Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
fix(mcp): make ix_context structured output cache-stable by omitting generatedAt (HR-04A) (#823)
Ian Hock0880396ea7ed
diff --git a/ix-cli/src/cli/__tests__/context-from-issue-bundle.test.ts b/ix-cli/src/cli/__tests__/context-from-issue-bundle.test.tsindex 735c6da3..edea2406 100644--- a/ix-cli/src/cli/__tests__/context-from-issue-bundle.test.ts+++ b/ix-cli/src/cli/__tests__/context-from-issue-bundle.test.ts@@ -155,4 +155,17 @@ describe("ix context --from-issue bundle", () => {expect(b.issue).toBeUndefined();expect(contextBundleSchema.safeParse(JSON.parse(JSON.stringify(b))).success).toBe(true);});++ it("accepts a bundle with and without generatedAt, and keeps the key when present", () => {+ const b = JSON.parse(JSON.stringify(build(issue())));+ expect(typeof b.generatedAt).toBe("string");+ const withKey = contextBundleSchema.safeParse(b);+ expect(withKey.success).toBe(true);+ expect(withKey.data?.generatedAt).toBe(b.generatedAt);++ const { generatedAt: _omit, ...without } = b;+ const parsed = contextBundleSchema.safeParse(without);+ expect(parsed.success).toBe(true);+ expect(parsed.data && "generatedAt" in parsed.data).toBe(false);+ });});diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.tsindex 2b99e49f..51473f07 100644--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@ -224,6 +224,28 @@ describe("ix context investigation state", () => {expect(loaded?.bundle.evidence).toEqual(bundle.evidence);});+ it("keeps generatedAt in the saved file, and resumes it", () => {+ const bundle = bundleWith([makeClaim("renders to DOM", 0.9)]);+ saveInvestigation("widget-check", bundle);++ const onDisk = JSON.parse(readFileSync(join(investigationsDir(), "widget-check.json"), "utf8"));+ expect(typeof bundle.generatedAt).toBe("string");+ expect(onDisk.bundle.generatedAt).toBe(bundle.generatedAt);+ expect(loadInvestigation("widget-check")?.bundle.generatedAt).toBe(bundle.generatedAt);+ });++ it("loads and renders a saved bundle that lacks generatedAt", () => {+ const { generatedAt: _omit, ...bundle } = bundleWith([makeClaim("renders to DOM", 0.9)]);+ writeState("no-stamp", envelope("no-stamp", bundle));++ expect(loadInvestigation("no-stamp")?.bundle.target.name).toBe("Widget");+ for (const format of ["json", "llm"] as const) {+ const lines = captureLog(() => renderSavedInvestigation("no-stamp", format));+ expect(lines.length).toBeGreaterThan(0);+ }+ expect(process.exitCode).toBe(priorExitCode);+ });+it("round-trips the format the budget was sized for, and loads a save without one", () => {const sized = bundleWith([makeClaim("renders to DOM", 0.9)]);sized.budgets = { ...sized.budgets, format: "llm" };diff --git a/ix-cli/src/cli/__tests__/mcp.test.ts b/ix-cli/src/cli/__tests__/mcp.test.tsindex 47c2591b..a3bc12c9 100644--- a/ix-cli/src/cli/__tests__/mcp.test.ts+++ b/ix-cli/src/cli/__tests__/mcp.test.ts@@ -250,8 +250,44 @@ describe("ix mcp", () => {const result = await client.callTool({ name: "ix_context", arguments: { target: "Widget", structured: true } });expect(calls).toEqual([["context", "--format=json", "--", "Widget"]]);- expect(result.structuredContent).toEqual(bundle);- expect(result.content).toEqual([{ type: "text", text: JSON.stringify(bundle) }]);+ const { generatedAt: _volatile, ...stable } = bundle;+ expect(result.structuredContent).toEqual(stable);+ expect(result.content).toEqual([{ type: "text", text: JSON.stringify(stable) }]);+ });++ it("two structured ix_context renders of the same input are byte-identical", async () => {+ const stamps = ["2026-01-01T00:00:00Z", "2026-01-01T00:00:05Z"];+ let n = 0;+ const client = await connect(async () => ({+ ok: true,+ stdout: JSON.stringify({ ...contextBundle(), generatedAt: stamps[n++] }),+ stderr: "",+ }));++ const args = { name: "ix_context", arguments: { target: "Widget", structured: true } };+ const r1 = await client.callTool(args);+ const r2 = await client.callTool(args);++ expect(JSON.stringify(r1)).toBe(JSON.stringify(r2));+ expect("generatedAt" in (r1.structuredContent as object)).toBe(false);+ expect(JSON.stringify(r1.content)).not.toContain("generatedAt");+ });++ it("keeps the structured text twin stable when stdout has a leading notice", async () => {+ const bundle = contextBundle();+ const outs = [+ `notice: update available\n${JSON.stringify({ ...bundle, generatedAt: "2026-01-01T00:00:00Z" })}`,+ JSON.stringify({ ...bundle, generatedAt: "2026-01-01T00:00:05Z" }),+ ];+ let n = 0;+ const client = await connect(async () => ({ ok: true, stdout: outs[n++], stderr: "" }));++ const args = { name: "ix_context", arguments: { target: "Widget", structured: true } };+ const r1 = await client.callTool(args);+ const r2 = await client.callTool(args);++ expect(r1.isError).toBeFalsy();+ expect(JSON.stringify(r1)).toBe(JSON.stringify(r2));});it("marks an unparseable bundle as an MCP error, on the structured path", async () => {diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex fa5e0277..eed12c1e 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -268,8 +268,11 @@ interface EvidenceItem {interface ContextBundle {schema: typeof BUNDLE_SCHEMA;- /** The one explicitly declared time-dependent field. */- generatedAt: string;+ /**+ * The one explicitly declared time-dependent field. Absent from the MCP+ * structured copy so identical calls are byte-identical.+ */+ generatedAt?: string;target: { id: string; name: string; kind: string; resolutionMode: string; path?: string };/*** Where an issue's bundle starts, and what in the issue did not resolve.diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.tsindex e9fda972..e3da9963 100644--- a/ix-cli/src/cli/context-bundle-schema.ts+++ b/ix-cli/src/cli/context-bundle-schema.ts@@ -25,11 +25,10 @@ function buildSchemas(z: typeof Zod.z) {* Versioned contract for the deterministic context bundle produced by* `ix context` (schema `ix-context-bundle/1`).*- * This is the single source of truth for the bundle's shape. The MCP server- * uses it as the `ix_context` output schema so agents get a structured- * contract, and the CLI validates every bundle with it on the way to disk- * (investigation save and `--out`) and on the way back off it- * (`loadInvestigation`), so a malformed or unexpected payload can never be+ * This is the single source of truth for the bundle's shape. The CLI+ * validates every bundle with it on the way to disk (investigation save and+ * `--out`) and on the way back off it (`loadInvestigation`), so a malformed+ * or unexpected payload can never be* written as if it were a valid bundle, nor honoured when read back.** The shapes below mirror the `ContextBundle` and `EvidenceItem` interfaces in@@ -46,7 +45,10 @@ function buildSchemas(z: typeof Zod.z) {*/const contextBundleSchema = z.object({schema: z.literal(BUNDLE_SCHEMA),- generatedAt: z.string(),+ // Optional on the way in: the MCP structured copy leaves it out so identical+ // calls are byte-identical. Still declared, because zod strips an undeclared+ // key and `--save` / `--out` files must keep it.+ generatedAt: z.string().optional(),target: z.object({id: z.string(),name: z.string(),diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.tsindex be85d57a..a3ebcceb 100644--- a/ix-cli/src/mcp/server.ts+++ b/ix-cli/src/mcp/server.ts@@ -927,7 +927,9 @@ function declaresOutputSchema(tool: string): boolean {* its own versioned schema (`ix-context-bundle/1`), so the structured copy is* stable across releases; when the output does not parse into a usable object* we omit structured content and keep the text result authoritative rather- * than throwing.+ * than throwing. The copy leaves out `generatedAt`, the bundle's one per-call+ * field, so identical calls return identical bytes and a prompt cache or dedup+ * can match; `--save` / `--out` files and CLI stdout keep it.*/async function runJsonStructured(runIx: IxRunner,@@ -948,9 +950,10 @@ async function runJsonStructured(if (!isRecord(parsed) || Object.keys(parsed).length === 0) {return textResult(text || JSON.stringify({ error: `${argv.command} produced no parseable JSON`, tool }), true);}+ const { generatedAt: _perCall, ...stable } = parsed;return {- content: [{ type: "text", text }],- structuredContent: parsed,+ content: [{ type: "text", text: JSON.stringify(stable) }],+ structuredContent: stable,};}