Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

11.8 KB
Raw Blame
import { parseMessageRef } from "./common.js";
import {
  type LineageNode,
  type LineageNodeInput,
  MESSAGE_ID,
  SESSION_SCHEMA,
  type Session,
  type SessionInput,
} from "./session.js";

export interface MergeResult {
  session: Session;
  warnings: string[];
}

export interface MergeOptions {
  /**
   * Position in send order of every message the session knows, by its stable id
   * (`h…`). Without it, `m1`, `m2`, … define the order, as before 8.5.
   */
  order?: ReadonlyMap<string, number>;
  /** Stable id → display label, for warnings the agent reads. */
  labels?: ReadonlyMap<string, string>;
  /**
   * Cross-session references (`<sessionId>:<id>`) that were checked against the
   * project's records: the other session exists, holds that message, and started
   * earlier (Story 8.6). Anything else is refused like an unknown parent.
   */
  crossTargets?: ReadonlySet<string>;
  /** Who is writing (Story 12.1): the main agent (default) or the side model. */
  by?: "agent" | "side";
  /**
   * Messages whose latest parent event was written by the side model (Story
   * 12.1). The side model may correct only those parents, so an agent's
   * correction is never undone by a later side run.
   */
  sideOwnsParent?: ReadonlySet<string>;
  /**
   * The user asked for this Shape (the map's Regenerate button), so a side
   * write replaces `shape` even when the agent wrote it. Every other field
   * keeps the usual rule.
   */
  forceShape?: boolean;
}

/**
 * The fields the side model may fill (Story 12.1). Structure (parent, links) is
 * handled separately because an agent correction must survive the next side run.
 */
const SIDE_FIELDS = [
  "title",
  "summary",
  "why",
  "decidedBy",
  "alternatives",
  "commits",
  "files",
  "branch",
  "work",
  "agentDecisions",
  "shape",
] as const;

type SideField = (typeof SIDE_FIELDS)[number];

/** A field the side model may fill: missing, empty text or an empty list. */
function isEmptyValue(value: unknown): boolean {
  return (
    value === undefined ||
    value === null ||
    value === "" ||
    (Array.isArray(value) && value.length === 0)
  );
}

/**
 * Merges one side-model node into the stored one: a field is written only when
 * empty or already the side model's, so the agent's notes are never overwritten.
 */
function mergeSide(prev: LineageNode, input: LineageNodeInput, forceShape = false): LineageNode {
  const next: LineageNode = { ...prev };
  const marks: Record<string, "side"> = {};
  for (const field of SIDE_FIELDS) {
    const value = input[field];
    if (value === undefined) continue;
    const forced = forceShape && field === "shape";
    if (!forced && !isEmptyValue(prev[field]) && prev.by?.[field] !== "side") continue;
    (next as unknown as Record<SideField, unknown>)[field] = value;
    marks[field] = "side";
  }
  return Object.keys(marks).length === 0 ? prev : { ...next, by: { ...(prev.by ?? {}), ...marks } };
}

/** The agent wrote these fields now, so the side model may no longer replace them. */
function agentMarks(prev: LineageNode | undefined, input: LineageNodeInput): LineageNode["by"] {
  const marks = { ...(prev?.by ?? {}) };
  for (const field of SIDE_FIELDS) if (input[field] !== undefined) delete marks[field];
  return Object.keys(marks).length > 0 ? marks : undefined;
}

/** A new node from the side model: every field it sent is its own to correct. */
function sideMarks(input: LineageNodeInput): LineageNode["by"] {
  const marks: Record<string, "side"> = {};
  for (const field of SIDE_FIELDS) if (input[field] !== undefined) marks[field] = "side";
  return Object.keys(marks).length > 0 ? marks : undefined;
}

/**
 * Merges agent input into the stored session. Nodes are upserted by id and never
 * removed; status is replaced when sent; other fields change only when sent.
 */
export function mergeSession(
  existing: Session | undefined,
  input: SessionInput,
  now: string,
  opts: MergeOptions = {},
): MergeResult {
  if (existing && existing.sessionId !== input.sessionId) {
    throw new Error(`session id mismatch: ${existing.sessionId} vs ${input.sessionId}`);
  }
  const base: Session = existing ?? {
    schema: SESSION_SCHEMA,
    sessionId: input.sessionId,
    agent: "claude-code",
    title: "",
    startedAt: now,
    updatedAt: now,
    status: { goal: "", done: [], pending: [], next: "" },
    nodes: [],
  };

  const nodes = new Map<string, LineageNode>(base.nodes.map((n) => [n.id, n]));
  /**
   * Send-order position of every message the record holds or this write adds.
   * The table (stable ids) decides it; without one, `m1`, `m2`, … still do. A
   * parent must be one of these, so a message that has no node cannot be one.
   */
  const recorded = new Map<string, number>();
  for (const n of [...base.nodes, ...(input.nodes ?? [])]) {
    if (n.kind !== "message") continue;
    const fromTable = opts.order?.get(n.id);
    const number = messageNumber(n);
    const position = fromTable ?? (number === null ? null : number - 1);
    if (position !== null) recorded.set(n.id, position);
  }
  const label = (id: string): string => opts.labels?.get(id) ?? id;
  const messageWarnings: string[] = [];
  const side = opts.by === "side";
  for (const { parent, links, ...n } of input.nodes ?? []) {
    const prev = nodes.get(n.id);
    const own = n.kind === "message" ? (recorded.get(n.id) ?? null) : null;
    if (side && prev) {
      // The side model fills notes but never rewrites the agent's: it may only
      // correct a parent it wrote itself (Story 12.1).
      const merged = mergeSide(prev, n, opts.forceShape === true);
      const nextParent =
        parent !== undefined && own !== null && (opts.sideOwnsParent?.has(n.id) ?? false)
          ? checkParent(n.id, parent, own, recorded, messageWarnings, label, opts.crossTargets)
          : (prev.parent ?? null);
      const next: LineageNode = { ...merged, parent: nextParent };
      nodes.set(n.id, {
        ...next,
        addedAt: prev.addedAt,
        touchedAt: sameNode(prev, next) ? prev.touchedAt : now,
      });
      continue;
    }
    const nextParent =
      parent !== undefined && own !== null
        ? checkParent(n.id, parent, own, recorded, messageWarnings, label, opts.crossTargets)
        : parent === undefined
          ? (prev?.parent ?? null)
          : parent;
    const nextLinks =
      links !== undefined && own !== null
        ? checkLinks(n.id, links, own, recorded, messageWarnings, label, opts.crossTargets)
        : links;
    const next: LineageNode = {
      ...prev,
      ...n,
      parent: nextParent,
      ...(nextLinks === undefined ? {} : { links: nextLinks }),
    };
    const marks = side ? sideMarks(n) : agentMarks(prev, n);
    // Nodes recorded before these stamps existed keep no addedAt: their order stays as stored.
    const addedAt = prev ? prev.addedAt : now;
    nodes.set(n.id, {
      ...next,
      // An explicit undefined clears a previous side mark: the agent owns it now.
      by: marks,
      ...(addedAt === undefined ? {} : { addedAt }),
      touchedAt: prev && sameNode(prev, next) ? prev.touchedAt : now,
    });
  }

  const merged: Session = {
    ...base,
    agent: input.agent ?? base.agent,
    title: input.title ?? base.title,
    status: input.status ?? base.status,
    ...(input.leftOff === undefined && base.leftOff === undefined
      ? {}
      : { leftOff: input.leftOff ?? base.leftOff }),
    nodes: [...nodes.values()],
    updatedAt: now,
  };
  const warnings = [...messageWarnings, ...repairTree(merged.nodes)];
  return { session: merged, warnings };
}

/** The number in a message node's id (`m7` → 7), or null for any other node. */
function messageNumber(node: { id: string; kind: string }): number | null {
  if (node.kind !== "message" || !MESSAGE_ID.test(node.id)) return null;
  return Number(node.id.slice(1));
}

function isEarlierMessage(numbers: Map<string, number>, id: string, own: number): boolean {
  const number = numbers.get(id);
  return number !== undefined && number < own;
}

/** The recorded message just before `own` by position, or null when there is none. */
function previousMessage(numbers: Map<string, number>, own: number): string | null {
  let best: string | null = null;
  let bestNumber = -1;
  for (const [id, number] of numbers) {
    if (number < own && number > bestNumber) {
      best = id;
      bestNumber = number;
    }
  }
  return best;
}

/**
 * A message's parent is the earlier message it reacts to; anything else (a
 * forward reference, a self-parent, a removed message id) falls back to the
 * previous message so the chain stays in time order. Old records whose message
 * parents are phase ids are left alone: this only checks what the agent sends now.
 */
function checkParent(
  id: string,
  parent: string | null,
  own: number,
  numbers: Map<string, number>,
  warnings: string[],
  label: (id: string) => string,
  crossTargets: ReadonlySet<string> | undefined,
): string | null {
  if (parent === null || isEarlierMessage(numbers, parent, own)) return parent;
  if (isCrossTarget(parent, crossTargets)) return parent;
  const fallback = previousMessage(numbers, own);
  const cross = parseMessageRef(parent).sessionId !== null;
  warnings.push(
    fallback === null
      ? `message ${label(id)}: parent ${label(parent)} is not ${cross ? "a message of an earlier session in this project" : "an earlier message of this session"}, moved to root`
      : `message ${label(id)}: parent ${label(parent)} is not ${cross ? "a message of an earlier session in this project" : "an earlier message of this session"}, using ${label(fallback)}`,
  );
  return fallback;
}

/** A `<sessionId>:<id>` reference that was checked against the other record. */
function isCrossTarget(ref: string, crossTargets: ReadonlySet<string> | undefined): boolean {
  return parseMessageRef(ref).sessionId !== null && (crossTargets?.has(ref) ?? false);
}

/** Links point at earlier messages too; a forward or unknown one is dropped. */
function checkLinks(
  id: string,
  links: string[],
  own: number,
  numbers: Map<string, number>,
  warnings: string[],
  label: (id: string) => string,
  crossTargets: ReadonlySet<string> | undefined,
): string[] {
  return links.filter((link) => {
    if (isEarlierMessage(numbers, link, own) || isCrossTarget(link, crossTargets)) return true;
    const cross = parseMessageRef(link).sessionId !== null;
    warnings.push(
      `message ${label(id)}: link ${label(link)} is not ${cross ? "a message of an earlier session in this project" : "an earlier message of this session"}, dropped`,
    );
    return false;
  });
}

const NODE_FIELDS = [
  "parent",
  "kind",
  "title",
  "summary",
  "why",
  "at",
  "decidedBy",
  "alternatives",
  "commits",
  "files",
  "links",
  "branch",
  "work",
  "agentDecisions",
  "shape",
] as const;

/** A resent node that changed nothing keeps its touch time. */
function sameNode(a: LineageNode, b: LineageNode): boolean {
  return NODE_FIELDS.every((field) => JSON.stringify(a[field]) === JSON.stringify(b[field]));
}

/**
 * Re-roots nodes whose parent is missing or that sit on a cycle. Mutates in
 * place. A `<sessionId>:<id>` parent (Story 8.6) belongs to another session's
 * graph, so it is not looked up here and never re-rooted.
 */
export function repairTree(nodes: LineageNode[]): string[] {
  const warnings: string[] = [];
  const byId = new Map(nodes.map((n) => [n.id, n]));
  for (const n of nodes) {
    if (n.parent !== null && parseMessageRef(n.parent).sessionId === null && !byId.has(n.parent)) {
      warnings.push(`node ${n.id}: parent ${n.parent} not found, moved to root`);
      n.parent = null;
    }
  }
  for (const n of nodes) {
    const seen = new Set<string>([n.id]);
    let cur = n.parent;
    while (cur !== null) {
      if (seen.has(cur)) {
        warnings.push(`node ${n.id}: parent cycle, moved to root`);
        n.parent = null;
        break;
      }
      seen.add(cur);
      cur = byId.get(cur)?.parent ?? null;
    }
  }
  return warnings;
}