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.

17.1 KB
Raw Blame
import type { BranchSummary, NodeKind } from "../schema/session.js";

/**
 * Serialized contract between `cogit build` and the HTML template. The
 * builder fills this shape, JSON-serializes it into the page's data element and
 * the React app in `packages/template` renders it. Keep this file free of runtime
 * dependencies so both sides can import it.
 */

/** Id of the `<script type="application/json">` that carries the model. */
export const DATA_ELEMENT_ID = "cogit-data";

/**
 * Meta tag the local map server injects into the pages it serves. The page
 * subscribes to rebuild events only when it is present, so a `file://` page or
 * the Vite dev server never tries to reach a server that is not there.
 */
export const LIVE_META_NAME = "cogit-live";

/**
 * Meta tag the local map server puts in every page it serves: a random token
 * for this server start that a settings read or write must echo. Other sites
 * cannot read it, so they cannot post a change even when the host check is
 * bypassed. A `file://` page has no token and its settings stay read-only.
 */
export const TOKEN_META_NAME = "cogit-token";

/** Request header that echoes {@link TOKEN_META_NAME} back on a write (a page cannot read it off another site). */
export const TOKEN_HEADER_NAME = "x-cogit-token";

/**
 * Settings the panel may change over the local server (Story 8.9). The rest are
 * setup-time or security-adjacent and stay on `cogit config set`.
 */
export const PANEL_EDITABLE_KEYS = [
  "recorder",
  "messageSummaries",
  "startupContext",
  "recordHeadless",
  "tryBeforeNotes",
  "shapes",
  "captures",
  "language",
  "shareConversations",
] as const;

export type PanelEditableKey = (typeof PANEL_EDITABLE_KEYS)[number];

export function isPanelEditableKey(key: string): key is PanelEditableKey {
  return (PANEL_EDITABLE_KEYS as readonly string[]).includes(key);
}

/** Version of the serialized view model (not the session schema). */
export const VIEW_SCHEMA = 1;

/** A code commit a message carries, with the subject read from git at build time. */
export interface ViewCommit {
  /** The hash as the record holds it (short or full). */
  hash: string;
  /** The commit's subject; absent when git no longer knows the commit. */
  subject?: string;
  /**
   * Project-relative files the commit changed (Story 10.5), so a file row can
   * ask for the diff of the commit that touched it. Absent on pages built
   * before 10.5 and for commits git no longer knows.
   */
  files?: string[];
}

/**
 * The code a message landed, from git (Story 10.3): lines added and removed
 * plus the number of distinct files its commits touched. Facts only — cogit
 * never reads the message to decide whether it looks big.
 */
export interface ViewChange {
  added: number;
  removed: number;
  files: number;
}

/** What a message's change does, between Intent and Code (Story 13.6). */
export interface ViewShapeTool {
  /** `pseudo`, `flow`, `table`, or a kind a newer CLI wrote (shown as text). */
  kind: string;
  text: string;
  /** False when the registry refused the output; the map shows it as text. */
  valid?: boolean | undefined;
}

export interface ViewShape {
  tools: ViewShapeTool[];
  /** Who wrote it: the main agent or the side model. */
  by?: "agent" | "side" | undefined;
  /** The message's commits this Shape covers. */
  commits: string[];
  at?: string | undefined;
}

export interface ViewNode {
  /** Stable id (`h…`); the key of the node, never shown to the user. */
  id: string;
  /** Display label (`m1`, `m2`, …) derived from send order (Story 8.5). */
  label?: string;
  kind: NodeKind;
  title: string;
  summary?: string;
  why?: string;
  at?: string;
  /**
   * The earlier message this one reacts to; `null` for a new root. Always set
   * on the messages the map draws (buildMessages falls back to the previous
   * message when a record points elsewhere).
   */
  parent?: string | null;
  /**
   * Set when the message hangs from a message of an earlier session (Story
   * 8.6): the map then draws a "continues …" mark and a root for the layout,
   * because the other session has its own graph.
   */
  continues?: ViewContinue;
  /** Earlier messages this one returns to or builds on besides its parent. */
  links?: string[];
  /** On a branch's first message: what that thread asked and what came of it. */
  branch?: BranchSummary;
  decidedBy?: "user" | "agent" | "agreed";
  alternatives?: { option: string; why: string }[];
  commits?: string[];
  /**
   * How much code landed after this message (Story 10.3), read from git's
   * numstat for the commits linked to it. Absent when no commit is linked: the
   * map shows nothing rather than a misleading zero.
   */
  change?: ViewChange;
  /**
   * `commits` with their subjects (Story 8.8); the map draws them as small tag
   * chips. A tag without a subject is a commit git no longer has, drawn greyed.
   */
  commitTags?: ViewCommit[];
  files?: string[];
  /** For a message: what the agent did about it. */
  work?: string[];
  /** For a message: choices the agent made on its own. */
  agentDecisions?: {
    title: string;
    why: string;
    alternatives?: { option: string; why: string }[] | undefined;
  }[];
  /** When the node was first added. */
  addedAt?: string;
  /** When the node was last added or changed; marks where the work left off. */
  touchedAt?: string;
  /**
   * For a message that landed commits: a small representation of what the
   * change does (Story 13.6). Missing means nobody wrote one (yet): the modal
   * says why (queued or off).
   */
  shape?: ViewShape;
  /** A user message the record does not hold yet: the row is not summarized. */
  unsummarized?: true;
}

/** The earlier session's message a first message continues (Story 8.6). */
export interface ViewContinue {
  sessionId: string;
  /** The other session's title, or its id when the record is gone. */
  sessionTitle: string;
  /** The id of the message in the other session. */
  id: string;
  /** Its `m67` label from that session, when the message is still there. */
  label?: string;
}

export interface ViewPendingItem {
  text: string;
  needsUser: boolean;
}

export interface ViewStatus {
  goal: string;
  done: string[];
  pending: ViewPendingItem[];
  next: string;
}

/** Status card at the top of the map (merged across sessions). */
export interface StatusCard extends ViewStatus {
  /** Time of the newest message across sessions, or null with no sessions. */
  lastActivity: string | null;
}

/** A user message the record does not hold yet, read from the transcript at build time. */
export interface ViewPendingMessage {
  /** The stable id the message will get as a node (`h…`). */
  id: string;
  /** The `m1`, `m2`, … label the user reads. */
  label?: string;
  at: string;
  /** The first words of the message, used as the card title. */
  title: string;
}

/** One user message and the agent's written answer, read from the transcript at build time. */
export interface ViewChatTurn {
  /** Same stable id as the message node it belongs to (`h…`). */
  id: string;
  /** The `m1`, `m2`, … label the user reads. */
  label?: string;
  at: string;
  /** The user's message as written, without injected reminders. */
  text: string;
  /** The agent's written replies until the next message; tool output is never included. */
  replies: string[];
  /** What the agent did with tools in that turn, counted, not shown. */
  tools: { commands: number; files: string[]; other: number };
}

export interface ViewSession {
  sessionId: string;
  agent: string;
  title: string;
  /** Who recorded the session (Story 9.3); absent on records written before it. */
  author?: string;
  /** Their git email, which tells people apart; absent on older records. */
  authorEmail?: string;
  startedAt: string;
  updatedAt: string;
  status: ViewStatus;
  /**
   * The session's user messages, flat and in the order they were sent. Older
   * records' topic nodes are not part of the map any more (Epic 8); every
   * message carries the id of the message it hangs from.
   */
  messages: ViewNode[];
  /** False when the Claude Code transcript is gone, so resume cannot work. */
  transcriptAvailable: boolean;
  /** The linked git worktree the session ran in, if any. */
  worktree?: { path: string; branch: string | null };
  /**
   * User messages the record does not hold yet, counted from the transcript at
   * build time. Only set while the SessionEnd catch-up is off.
   */
  unrecordedMessages?: number;
  /**
   * The conversation, for sessions that record messages and still have their
   * transcript. It lives only in the generated page, never in the session file.
   */
  chat?: ViewChatTurn[];
}

/**
 * One entry of the map's project switcher (Story 8.12): a registered project
 * with the line that says where its work left off.
 */
export interface ViewSwitcherProject {
  name: string;
  path: string;
  /** Time of the project's newest message across its sessions. */
  lastActivity: string | null;
  /** The newest session's `next`, or its last message title when `next` is empty. */
  leftOff: string;
  /** `file://` URL of the project's map. */
  lineageUrl: string;
  /** True for the project the page belongs to. */
  current: boolean;
}

/**
 * One row of the "your turn" inbox (Story 11.1): a session across the registered
 * projects whose transcript ends with the agent's turn, or whose record has
 * pending items flagged `needsUser`. The two signals stay apart: `signal` says
 * which put the row there, and a record-only row carries no `lastMessage`.
 */
export interface ViewInboxRow {
  projectName: string;
  projectPath: string;
  /** `file://` URL of the project's map; ignored by a page the server serves. */
  mapUrl: string;
  sessionId: string;
  /** The session's title, or its id when the record has none yet. */
  sessionTitle: string;
  /** `turn` when the transcript ends with the agent, `record` for `needsUser`. */
  signal: "turn" | "record" | "both";
  /** Newest signal time (ISO): the agent's last turn, else the record's activity. */
  at: string;
  /**
   * The agent's last written message as plain text (Markdown stripped), first
   * ~300 characters (Story 12.2).
   */
  lastMessage?: string;
  /** Where-were-we, as the record wrote it; the page labels it as the record's. */
  goal: string;
  lastDecision: string;
  pending: ViewPendingItem[];
  /** The session's newest message id, for opening the map at it. */
  messageId?: string;
  /** False when the transcript is gone, so resume cannot work. */
  transcriptAvailable: boolean;
}

export interface LineageViewModel {
  /** A shared project's first download failed, so an empty map does not mean an empty record. */
  recordDownloadFailed?: boolean;
  kind: "lineage";
  schema: typeof VIEW_SCHEMA;
  project: {
    name: string;
    path: string;
    generatedAt: string;
  };
  status: StatusCard;
  /** Every session, in start order. */
  sessions: ViewSession[];
  /**
   * Who is looking: the git identity of the machine that built the page, so the
   * map can tell your sessions from your teammates'. Absent when unknown.
   */
  viewer?: { author?: string; authorEmail?: string };
  /**
   * Every registered project, most recently active first, for the map's
   * switcher (Story 8.12). Missing directories are left out; older pages simply
   * have no switcher.
   */
  switcher?: ViewSwitcherProject[];
  /**
   * Which conversations touched which file (Story 8.15), most recently touched
   * first: the union of each message's `files` and the files of its commits,
   * read from git at build time. Absent on pages built before 8.15.
   */
  files?: ViewFile[];
  /**
   * Patches embedded at build time, by commit and then by file ("" for the
   * whole commit), so a saved map can show a diff without the local server.
   * A page built without them keeps saying the server is needed.
   */
  diffs?: Record<string, Record<string, string>>;
  /**
   * Settings embedded at build time (Story 8.13). The settings modal shows them
   * read-only over `file://`; over the local server it reads the live values
   * instead. Absent on pages built before 8.13.
   */
  settings?: PanelSettings;
  /**
   * How wide the user dragged each session's message rows, by session id, from
   * `.cogit/state/map.json` at build time. Local state like `read`. Absent on
   * pages built before it.
   */
  rowWidths?: Record<string, number>;
  /**
   * Sessions the user left open on the map, from `.cogit/state/map.json` at
   * build time, so a reload opens them again. Absent on pages built before it.
   */
  openSessions?: string[];
  /**
   * The "your turn" inbox for this project only (Story 11.1). Absent on pages
   * built before it; a project's map never carries another project's rows.
   */
  inbox?: ViewInboxRow[];
  /**
   * The curated captured-work list (Story 15.1), read from the local store at
   * build time. Absent on pages built before it.
   */
  captures?: ViewCapture[];
}

/**
 * One item of the curated captured-work list (Story 15.1), read from
 * `.cogit/state/captures.json` at build time. A side model drafts it from a
 * session's leftover work; the user accepts, dismisses or closes it. The store
 * is local and never committed, and it is not a plan: no assignment, no
 * priority, no tracker state.
 */
export interface ViewCapture {
  /** `c` + eight hex characters, minted once; never derived from the text. */
  id: string;
  text: string;
  /** `suggested` waits for the user; `open` is accepted; `dismissed` and `done` are closed. */
  state: "suggested" | "open" | "dismissed" | "done";
  /**
   * The recorded session the item came from. An item belongs to a whole session
   * (Story 15.2); the map anchors it on the session's first message.
   */
  source: { sessionId: string };
  createdAt: string;
  updatedAt: string;
  /** Set when the item became `done`. */
  closedAt?: string | undefined;
}

/**
 * One message that touched a file (Story 8.15): the file view's row on the map
 * and what `cogit log --file` prints. `commits` are the commits that
 * touched this file; a commit git no longer knows leaves an empty list.
 */
export interface ViewFileHit {
  sessionId: string;
  /** The session's title, or its id when the record has none yet. */
  sessionTitle: string;
  messageId: string;
  /** The message's `mN` label. */
  label: string;
  at?: string;
  title: string;
  /** The branch the message sits in, when a branch summary starts at or before it. */
  branch?: string;
  commits: string[];
}

/** A file recorded messages touched, most recently touched first. */
export interface ViewFile {
  /** Project-relative path (`src/app.ts`). */
  path: string;
  /** Messages that touched it, newest first. */
  hits: ViewFileHit[];
  count: number;
  /** Time of the newest hit. */
  lastAt?: string;
}

/** One project card in the global panel. */
export interface PanelProject {
  name: string;
  path: string;
  /** True when the registered directory no longer exists. */
  missing: boolean;
  /** `updatedAt` of the project's most recently updated session. */
  lastActivity: string | null;
  /** Pending items flagged `needsUser` after merging active sessions. */
  needsUserCount: number;
  /** `file://` URL of the project's map; null when the directory is gone. */
  lineageUrl: string | null;
}

/**
 * Global settings on the panel. `agents` is shown read-only;
 * the keys in `PANEL_EDITABLE_KEYS` are editable when the page comes from the
 * local server (over `file://` everything stays read-only).
 */
export interface PanelSettings {
  /** Who records: the main agent, both, or only a small side model (Story 12.1). */
  recorder: "agent" | "mixed" | "side";
  language: string;
  updateEveryTurns: number;
  /** How often the side model records, in turns (Story 12.1). */
  sideEveryTurns: number;
  sessionEndCatchUp: boolean;
  /** Model the side runs and the session-end catch-up use (Story 12.1). */
  sideModel: string;
  messageSummaries: boolean;
  startupContext: boolean;
  /** Whether `claude -p` and SDK sessions are recorded. */
  recordHeadless: boolean;
  /**
   * Whether the agent is told before editing a file about options earlier
   * thoughts considered and rejected (Story 10.4).
   */
  tryBeforeNotes: boolean;
  /**
   * Whether a message that landed commits gets a Shape (Story 13.6): a small
   * plain-language or diagram view of what the change does.
   */
  shapes: boolean;
  /**
   * Whether the side model distils each session's leftover work into a short
   * curated list (Story 15.1).
   */
  captures: boolean;
  shareConversations: boolean;
  agents: string[];
  /** A message whose linked commits crossed this many lines counts as big (10.3). */
  bigChangeLines: number;
}

/**
 * The subset `GET /api/config` returns and a settings modal may change
 * (Story 8.13). Everything else stays on `cogit config set`.
 */
export type PanelEditableSettings = Pick<PanelSettings, PanelEditableKey>;

export interface PanelViewModel {
  kind: "panel";
  schema: typeof VIEW_SCHEMA;
  generatedAt: string;
  settings: PanelSettings;
  /** Registry order. */
  projects: PanelProject[];
  /**
   * Every project's "your turn" rows, oldest first (Story 11.1). Absent on
   * pages built before it.
   */
  inbox?: ViewInboxRow[];
}

/** Either page the template can render; the embedded data decides which. */
export type PageModel = LineageViewModel | PanelViewModel;