Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,
};
}