Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import { type ReactNode, useEffect, useRef, useState } from "react";
import { TOKEN_HEADER_NAME, type ViewNode } from "../../cli/src/view/model.js";
import {
flowToMermaid,
parseFlow,
SHAPE_READING,
shapeKindsUsed,
shapePreview,
shapeState,
tableRows,
} from "../../cli/src/view/shape.js";
import { DiffView } from "./DiffView.js";
import { isLivePage, pageToken } from "./data.js";
import { HelpTip } from "./HelpTip.js";
import { MermaidDiagram } from "./MermaidDiagram.js";
/**
* Intent, Shape and Code (Story 13.6): the three layers of a message that
* landed commits, top to bottom, with 1/2/3 tabs. Opening on Shape shows what
* the change does first; Intent is the record, read but never rewritten here,
* and Code is the same diff the panel already shows.
*/
export type ShapeTab = "intent" | "shape" | "code";
/** The fields the three layers read; a message node or the panel's detail both fit. */
export interface ShapeNode {
title: string;
kind: ViewNode["kind"];
why?: string | undefined;
alternatives?: ViewNode["alternatives"];
agentDecisions?: ViewNode["agentDecisions"];
work?: ViewNode["work"];
decidedBy?: ViewNode["decidedBy"];
commits?: string[] | undefined;
commitTags?: ViewNode["commitTags"];
shape?: ViewNode["shape"];
/** The owning session and the message's id: what the Regenerate button posts. */
sessionId?: string | undefined;
nodeId?: string | undefined;
}
const TABS: { id: ShapeTab; number: string; label: string }[] = [
{ id: "intent", number: "1", label: "Intent" },
{ id: "shape", number: "2", label: "Shape" },
{ id: "code", number: "3", label: "Code" },
];
const DECIDED_LABEL = {
user: "You",
agent: "The agent, on its own",
agreed: "You, approving the agent's proposal",
} as const;
/** The record's Intent: the same fields the panel shows, in reading order. */
function IntentLayer({ node }: { node: ShapeNode }) {
const empty =
!node.why &&
!node.alternatives?.length &&
!node.agentDecisions?.length &&
!node.work?.length &&
!node.decidedBy;
if (empty) return <p className="muted">No reason was recorded for this message.</p>;
return (
<div className="shape-intent">
{node.why ? (
<section>
<h4>Why</h4>
<p>{node.why}</p>
</section>
) : null}
{node.alternatives?.length ? (
<section>
<h4>Considered and rejected</h4>
<ul>
{node.alternatives.map((alt) => (
<li key={alt.option}>
<strong>{alt.option}</strong>
{alt.why ? <> — {alt.why}</> : null}
</li>
))}
</ul>
</section>
) : null}
{node.agentDecisions?.length ? (
<section>
<h4>Decided by the agent on its own</h4>
<ul>
{node.agentDecisions.map((decision) => (
<li key={decision.title}>
<strong>{decision.title}</strong>
{decision.why ? <> — {decision.why}</> : null}
</li>
))}
</ul>
</section>
) : null}
{node.work?.length ? (
<section>
<h4>What the agent did</h4>
<ul>
{node.work.map((item) => (
<li key={item}>{item}</li>
))}
</ul>
</section>
) : null}
{node.decidedBy ? (
<p className="decided-by">Decided by: {DECIDED_LABEL[node.decidedBy]}</p>
) : null}
</div>
);
}
/** How a tool's output is named when it is shown as plain text. */
const TEXT_CAPTION: Record<string, string> = {
pseudo: "Steps",
example: "Example",
flow: "Flow source (not drawn)",
mermaid: "Flowchart source (not drawn)",
sequence: "Sequence source (not drawn)",
table: "Before / After (as written)",
interface: "Interface (as written)",
};
/**
* A tool's caption with a "?" that says how to read it. The kinds a Shape uses
* are already named in the legend above, so the bubble only explains the tool.
* `reading` swaps in another tool's explanation (an ordered Flow reads like a
* Sequence).
*/
function ToolCaption({ id, label, reading }: { id: string; label: string; reading: string }) {
const help = SHAPE_READING[reading];
if (!help)
return (
<figcaption className="shape-caption">
<span>{label}</span>
</figcaption>
);
return (
<figcaption className="shape-caption">
<span>{label}</span>
<HelpTip id={`shape-${id}`} label={`How to read the ${label}`}>
<span className="shape-reading">{help}</span>
</HelpTip>
</figcaption>
);
}
/** Tools Mermaid draws; a Flow is turned into Mermaid source first. */
const DIAGRAM_KINDS = new Set(["flow", "mermaid", "sequence"]);
/** A diagram tool's caption, distinct from the plain-text fallback caption. */
function diagramLabel(kind: string): string {
if (kind === "sequence") return "Sequence";
if (kind === "flow") return "Flow";
return "Flowchart";
}
/** The header of each table tool; the writer sends only the rows. */
const TABLE_COLUMNS: Record<string, readonly [string, string, string]> = {
table: ["Case", "Before", "After"],
interface: ["Item", "Before", "After"],
};
/** A three-column table: Before / After or Interface, one row per case or item. */
function ShapeTable({
columns,
rows,
}: {
columns: readonly [string, string, string];
rows: readonly (readonly [string, string, string])[];
}) {
return (
<table className="shape-table">
<thead>
<tr>
{columns.map((column) => (
<th key={column} scope="col">
{column}
</th>
))}
</tr>
</thead>
<tbody>
{rows.map(([what, before, after], index) => (
<tr key={`${index}-${what}`}>
<th scope="row">{what}</th>
<td>{before}</td>
<td>{after}</td>
</tr>
))}
</tbody>
</table>
);
}
/** The Shape layer: each tool's output; Mermaid drawn, the table laid out. */
function ShapeLayer({
node,
enabled,
renderMermaid,
}: {
node: ShapeNode;
enabled: boolean;
renderMermaid: (source: string) => ReactNode;
}) {
const state = shapeState(node.shape, enabled);
if (state === "off") {
return <p className="muted">Shapes are off. Turn them on in Settings → Recording.</p>;
}
if (state === "queued") {
return <p className="muted">This Shape is being prepared, or the message landed no commits.</p>;
}
if (state === "empty") {
return <p className="muted">Nothing to show: the change was too small to draw.</p>;
}
const tools = node.shape?.tools ?? [];
const kinds = shapeKindsUsed(tools);
return (
<div className="shape-tools">
{kinds.length > 0 ? (
<div className="shape-legend" aria-label="Kinds in this Shape">
{kinds.map((kind) => (
<span key={kind.id} className="shape-kind">
<span className="shape-kind-symbol">{kind.symbol}</span>
{kind.name}
</span>
))}
</div>
) : null}
{tools.map((tool, index) => {
const key = `${tool.kind}-${index}`;
const source = tool.kind === "flow" ? flowToMermaid(tool.text) : tool.text;
const orderedFlow = tool.kind === "flow" && parseFlow(tool.text)?.ordered === true;
if (DIAGRAM_KINDS.has(tool.kind) && tool.valid !== false && source !== undefined)
return (
<figure key={key} className="shape-figure">
{renderMermaid(source)}
<ToolCaption
id={key}
label={orderedFlow ? "Sequence" : diagramLabel(tool.kind)}
reading={orderedFlow ? "sequence" : tool.kind}
/>
</figure>
);
const columns = TABLE_COLUMNS[tool.kind];
const rows = columns && tool.valid !== false ? tableRows(tool.text) : undefined;
if (columns && rows !== undefined)
return (
<figure key={key} className="shape-figure">
<ShapeTable columns={columns} rows={rows} />
<ToolCaption
id={key}
label={tool.kind === "interface" ? "Interface" : "Before / After"}
reading={tool.kind}
/>
</figure>
);
return (
<figure key={key} className="shape-figure">
<pre className={`shape-source is-${tool.kind}`}>{tool.text}</pre>
<ToolCaption
id={key}
label={TEXT_CAPTION[tool.kind] ?? tool.kind}
reading={tool.kind}
/>
</figure>
);
})}
{node.shape?.by ? (
<p className="shape-by">
Written by {node.shape.by === "side" ? "the side model" : "the agent"}.
</p>
) : null}
</div>
);
}
/** What the Regenerate button posts: the message and the project it belongs to. */
export interface RegenerateRequest {
dir: string;
sessionId: string;
nodeId: string;
}
/** The POST the button makes; the token is the one the served page carries. */
async function requestShape(request: RegenerateRequest): Promise<void> {
const token = pageToken();
if (token === null) throw new Error("Open the map with `cogit open` to regenerate a Shape.");
const response = await fetch("/api/shape/regenerate", {
method: "POST",
headers: { "content-type": "application/json", [TOKEN_HEADER_NAME]: token },
body: JSON.stringify(request),
});
if (response.ok) return;
const text = (await response.text()).trim();
throw new Error(text === "" ? `the Shape was not written (${response.status})` : text);
}
/**
* Asks the side model to write this message's Shape again, for the answer a
* small model missed or one the reader wants differently. The server holds the
* request until the model answers and then rebuilds the open maps, so the layer
* swaps in the new Shape by itself; this only shows whether the ask is running.
*/
function RegenerateButton({ request }: { request: RegenerateRequest }) {
const [state, setState] = useState<"idle" | "running" | "done" | "error">("idle");
const [error, setError] = useState("");
const run = async (): Promise<void> => {
setState("running");
setError("");
try {
await requestShape(request);
setState("done");
} catch (err) {
setState("error");
setError(err instanceof Error ? err.message : String(err));
}
};
return (
<div className="shape-regenerate">
<button
type="button"
className="shape-regenerate-button"
title="Ask the side model to write this Shape again"
onClick={() => void run()}
disabled={state === "running"}
>
{state === "running" ? "Regenerating…" : "Regenerate"}
</button>
{state === "done" ? <span className="muted">Written again.</span> : null}
{state === "error" ? <span className="shape-regenerate-error">{error}</span> : null}
</div>
);
}
/** The Code layer: the message's commits and their patches. */
function CodeLayer({ node, root }: { node: ShapeNode; root: string }) {
const live = typeof document !== "undefined" && isLivePage();
const commits = node.commits ?? [];
if (commits.length === 0) return <p className="muted">No commit is linked to this message.</p>;
return (
<div className="shape-code">
{commits.map((commit) => (
<section key={commit}>
<h4>
<code>{commit.slice(0, 7)}</code>{" "}
{node.commitTags?.find((tag) => tag.hash === commit)?.subject ?? ""}
</h4>
{live ? <DiffView dir={root} commit={commit} /> : null}
</section>
))}
{live ? null : <p className="muted">Open with `cogit open` to see the diffs.</p>}
</div>
);
}
/**
* The three layers with their tabs. Presentational (no state, no effects) so a
* render test can check the layers and the pending states without a browser;
* `renderMermaid` lets that test stand in for the real renderer.
*/
export function ShapeLayers({
node,
root,
tab,
enabled,
onTab,
regenerate,
renderMermaid = (source) => <MermaidDiagram source={source} interactive />,
}: {
node: ShapeNode;
root: string;
tab: ShapeTab;
enabled: boolean;
onTab: (tab: ShapeTab) => void;
/** Set on a served page for a message that can be shaped again. */
regenerate?: RegenerateRequest | undefined;
renderMermaid?: (source: string) => ReactNode;
}) {
return (
<div className="shape-layers">
<div className="shape-tabs" role="tablist" aria-label="Intent, Shape and Code">
{TABS.map((entry) => (
<button
key={entry.id}
type="button"
role="tab"
aria-selected={tab === entry.id}
className={tab === entry.id ? "shape-tab is-active" : "shape-tab"}
onClick={() => onTab(entry.id)}
>
<span className="shape-tab-no">{entry.number}</span> {entry.label}
</button>
))}
</div>
<div
className="shape-layer"
role="tabpanel"
aria-label={TABS.find((entry) => entry.id === tab)?.label}
>
{tab === "intent" ? <IntentLayer node={node} /> : null}
{tab === "shape" ? (
<>
<ShapeLayer node={node} enabled={enabled} renderMermaid={renderMermaid} />
{regenerate === undefined ? null : <RegenerateButton request={regenerate} />}
</>
) : null}
{tab === "code" ? <CodeLayer node={node} root={root} /> : null}
</div>
</div>
);
}
/** The large modal, opened from the panel's code section. */
export function ShapeModal({
node,
root,
enabled,
regenerate,
onClose,
}: {
node: ShapeNode;
root: string;
enabled: boolean;
regenerate?: RegenerateRequest | undefined;
onClose: () => void;
}) {
const [tab, setTab] = useState<ShapeTab>("shape");
const box = useRef<HTMLDivElement>(null);
useEffect(() => {
box.current?.focus();
const onKey = (event: KeyboardEvent): void => {
if (event.key === "Escape") {
event.stopPropagation();
onClose();
} else if (event.key === "1") setTab("intent");
else if (event.key === "2") setTab("shape");
else if (event.key === "3") setTab("code");
};
window.addEventListener("keydown", onKey);
return () => window.removeEventListener("keydown", onKey);
}, [onClose]);
return (
<div className="shape-overlay" onClick={onClose}>
<div
ref={box}
className="shape-modal"
role="dialog"
aria-modal="true"
aria-label={`${node.title} — Intent, Shape and Code`}
tabIndex={-1}
onClick={(event) => event.stopPropagation()}
>
<header className="shape-head">
<div>
<span className="kind">message</span>
<h2>{node.title}</h2>
</div>
<button type="button" className="drilldown-close" aria-label="Close" onClick={onClose}>
×
</button>
</header>
<ShapeLayers
node={node}
root={root}
tab={tab}
enabled={enabled}
onTab={setTab}
regenerate={regenerate}
/>
</div>
</div>
);
}
/**
* The panel's code section entry (Story 13.6): a short preview of the Shape and
* an Open button that shows the three layers. With no Shape yet it still opens,
* and the Shape tab explains why (queued or off).
*/
export function ShapeSection({
node,
root,
enabled,
}: {
node: ShapeNode;
root: string;
enabled: boolean;
}) {
const [open, setOpen] = useState(false);
const state = shapeState(node.shape, enabled);
const preview = shapePreview(node.shape);
// Only a page the local server served can ask for a new Shape: over
// `file://` nothing would answer, and the button stays out.
const live = typeof document !== "undefined" && isLivePage();
const regenerate =
enabled && live && node.sessionId !== undefined && node.nodeId !== undefined
? { dir: root, sessionId: node.sessionId, nodeId: node.nodeId }
: undefined;
const diagram = node.shape?.tools.find(
(tool) => DIAGRAM_KINDS.has(tool.kind) && tool.valid !== false,
);
const diagramSource =
diagram === undefined
? undefined
: diagram.kind === "flow"
? flowToMermaid(diagram.text)
: diagram.text;
return (
<section className="shape-section">
<h3>Intent, Shape and Code</h3>
{state === "ready" ? (
// The diagram leads: a drawn Shape says more at a glance than three
// lines of steps, so it comes first and the steps follow it.
<>
{diagramSource === undefined ? null : (
<MermaidDiagram source={diagramSource} className="shape-preview-diagram" fit />
)}
{preview === undefined ? null : <pre className="shape-preview">{preview}</pre>}
</>
) : state === "off" ? (
<p className="muted">Shapes are off.</p>
) : state === "empty" ? (
<p className="muted">Nothing to show for this change.</p>
) : (
<p className="muted">Shape is being prepared.</p>
)}
<button type="button" className="shape-open" onClick={() => setOpen(true)}>
Open
</button>
{open ? (
<ShapeModal
node={node}
root={root}
enabled={enabled}
regenerate={regenerate}
onClose={() => setOpen(false)}
/>
) : null}
</section>
);
}