@cairnkeep/cli 2.3.0 → 2.4.0

package/opencode/plugins/memory-capture.ts

@@ -25,6 +25,8 @@ import path from "node:path"
 // degraded outcome, not a retry loop (Pitfall 3).
 
 const SERVER_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/index.js"
+const TRAJECTORY_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/trajectory-cli.js"
+const ARTIFACT_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/artifact-cli.js"
 const MAX_CHARS = 12000
 const RETENTION_CAP = 5
 
@@ -43,9 +45,9 @@ type SessionMessage = {
 // phase). Async/non-blocking so a slow extraction call never freezes a live
 // interactive session; bounded by `timeoutMs` and resolves (never rejects)
 // so the caller's existing fail-open handling is unchanged.
-function runExtract(
-  serverEntry: string,
-  model: string,
+function runNode(
+  entry: string,
+  args: string[],
   input: string,
   timeoutMs = 120000,
 ): Promise<{ stdout: string; stderr: string }> {
@@ -60,12 +62,12 @@ function runExtract(
       resolvePromise({ stdout, stderr })
     }
 
-    const child = spawn("node", [serverEntry, "extract", model], {
+    const child = spawn("node", [entry, ...args], {
       stdio: ["pipe", "pipe", "pipe"],
     })
     const timer = setTimeout(() => {
       try {
-        child.kill("SIGTERM")
+        child.kill("SIGKILL")
       } catch {
         // best-effort kill only
       }
@@ -79,12 +81,23 @@ function runExtract(
     })
     child.on("close", finish)
     child.on("error", finish)
+    child.stdin.on("error", () => {
+      // EPIPE after a failed/terminated child is part of the fail-open path.
+    })
 
     child.stdin.write(input)
     child.stdin.end()
   })
 }
 
+function trajectoryCaptureEnabled(): boolean {
+  return /^(1|true|yes|on)$/i.test(process.env.CAIRN_TRAJECTORY_CAPTURE ?? "")
+}
+
+function compactionCaptureEnabled(): boolean {
+  return /^(1|true|yes|on)$/i.test(process.env.CAIRN_COMPACTION_CAPTURE ?? "")
+}
+
 // Reimplements scripts/transcript-to-text.mjs's behavior (skip tool/reasoning/
 // file noise, join user/assistant text in order, cap total length keeping the
 // most recent turns) against OpenCode's { info, parts } message shape rather
@@ -113,6 +126,31 @@ export const MemoryCapturePlugin: Plugin = async ({ client, directory }) => {
   return {
     event: async ({ event }) => {
       try {
+        if (event.type === "session.compacted") {
+          if (!compactionCaptureEnabled()) return
+          const sessionID = event.properties?.sessionID
+          if (!sessionID) return
+
+          const sessionRes = await client.session.get({ path: { id: sessionID } })
+          const session = (sessionRes as { data?: { id?: string; parentID?: string; version?: string } })?.data
+          if (!session || session.parentID) return
+
+          const messagesRes = await client.session.messages({ path: { id: sessionID } })
+          const messages = ((messagesRes as { data?: unknown[] })?.data ?? []) as unknown[]
+          if (!fs.existsSync(ARTIFACT_ENTRY)) return
+
+          const capture = await runNode(
+            ARTIFACT_ENTRY,
+            ["capture-opencode", directory],
+            JSON.stringify({ event, session, messages, harness_version: "1.17.20" }),
+            3000,
+          )
+          if (capture.stderr.trim()) {
+            console.warn("cairn compaction capture skipped: local capture failed")
+          }
+          return
+        }
+
         if (event.type !== "session.idle") return
         const sessionID = event.properties?.sessionID
         if (!sessionID) return
@@ -122,19 +160,24 @@ export const MemoryCapturePlugin: Plugin = async ({ client, directory }) => {
 
         const repo = directory
         const agentfsDb = path.join(repo, ".agentfs", "project.db")
-        if (!fs.existsSync(agentfsDb)) return
-        if (!fs.existsSync(SERVER_ENTRY)) return
+        const trajectoryEnabled = trajectoryCaptureEnabled()
 
+        // Preserve the original disabled path: all pre-existing guards run
+        // before any SDK request or subprocess when trajectory capture is off.
+        if (!trajectoryEnabled) {
+          if (!fs.existsSync(agentfsDb)) return
+          if (!fs.existsSync(SERVER_ENTRY)) return
+        }
         const apiKey = process.env.CAIRN_LLM_API_KEY
         const model = process.env.CAIRN_LLM_EXTRACTION_MODEL
-        if (!apiKey || !model) return
+        if (!trajectoryEnabled && (!apiKey || !model)) return
 
         // session.idle's event payload only carries sessionID (no parentID) —
         // fetch the full session record to filter out subagent subsessions
         // (Pitfall 2: subagent tool calls also idle and would otherwise
         // over-stage past the 5-session retention cap's intent).
         const sessionRes = await client.session.get({ path: { id: sessionID } })
-        const session = (sessionRes as { data?: { parentID?: string } })?.data
+        const session = (sessionRes as { data?: { id?: string; parentID?: string; time?: unknown } })?.data
         if (session?.parentID) return
 
         // Mark processed before doing the (possibly slow) extract call so a
@@ -144,13 +187,36 @@ export const MemoryCapturePlugin: Plugin = async ({ client, directory }) => {
 
         const messagesRes = await client.session.messages({ path: { id: sessionID } })
         const messages = ((messagesRes as { data?: SessionMessage[] })?.data ?? []) as SessionMessage[]
+
+        if (trajectoryEnabled && fs.existsSync(TRAJECTORY_ENTRY)) {
+          const payload = JSON.stringify({
+            session: { ...session, id: session?.id ?? sessionID },
+            messages,
+          })
+          const capture = await runNode(
+            TRAJECTORY_ENTRY,
+            ["capture-opencode", repo],
+            payload,
+            3000,
+          )
+          if (capture.stderr.trim()) {
+            console.warn("cairn trajectory capture skipped: local capture failed")
+          }
+        }
+
+        // Durable-memory extraction retains its independent project/model
+        // gates and behavior when trajectory capture is enabled.
+        if (!fs.existsSync(agentfsDb)) return
+        if (!fs.existsSync(SERVER_ENTRY)) return
+        if (!apiKey || !model) return
+
         const text = messagesToText(messages)
         if (!text) return
 
         // Pipe the session text into the shared `extract` subcommand via
         // stdin (T-04-01 mitigation) — never string-interpolate arbitrary
         // session/message content into the shell command.
-        const res = await runExtract(SERVER_ENTRY, model, text)
+        const res = await runNode(SERVER_ENTRY, ["extract", model], text)
         const candidatesJson = String(res.stdout ?? "").trim()
         if (!candidatesJson) return
 

package/opencode/plugins/memory-wakeup.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from "@opencode-ai/plugin"
+import { spawn } from "node:child_process"
 import fs from "node:fs"
 import path from "node:path"
 
@@ -19,6 +20,47 @@ import path from "node:path"
 // session.
 
 const SERVER_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/index.js"
+const ARTIFACT_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/artifact-cli.js"
+
+function compactionCaptureEnabled(): boolean {
+  return /^(1|true|yes|on)$/i.test(process.env.CAIRN_COMPACTION_CAPTURE ?? "")
+}
+
+function runNode(entry: string, args: string[], timeoutMs = 3000): Promise<string> {
+  return new Promise((resolvePromise) => {
+    let stdout = ""
+    let settled = false
+    const finish = () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise(stdout)
+    }
+    const child = spawn("node", [entry, ...args], {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL")
+      } catch {
+        // best-effort kill only
+      }
+    }, timeoutMs)
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8")
+      if (stdout.length > 262144) {
+        stdout = ""
+        try {
+          child.kill("SIGKILL")
+        } catch {
+          // best-effort kill only
+        }
+      }
+    })
+    child.on("close", finish)
+    child.on("error", finish)
+  })
+}
 
 export const MemoryWakeupPlugin: Plugin = async ({ $, directory }) => {
   return {
@@ -37,7 +79,8 @@ export const MemoryWakeupPlugin: Plugin = async ({ $, directory }) => {
         const wikiIndex = path.join(repo, ".planning", "wiki", "index.md")
         const hasAgentfs = fs.existsSync(agentfsDb)
         const hasWiki = fs.existsSync(wikiIndex)
-        if (!hasAgentfs && !hasWiki) return
+        const compactionEnabled = compactionCaptureEnabled()
+        if (!hasAgentfs && !hasWiki && !compactionEnabled) return
 
         const sections: string[] = []
 
@@ -88,12 +131,21 @@ export const MemoryWakeupPlugin: Plugin = async ({ $, directory }) => {
           }
         }
 
-        if (sections.length === 0) return
+        if (sections.length > 0) {
+          output.system.push(
+            "Session-start context (auto-surfaced by the memory-wakeup plugin — use it; do not ask the user to recall anything it contains):",
+          )
+          output.system.push(sections.join("\n\n"))
+        }
 
-        output.system.push(
-          "Session-start context (auto-surfaced by the memory-wakeup plugin — use it; do not ask the user to recall anything it contains):",
-        )
-        output.system.push(sections.join("\n\n"))
+        if (compactionEnabled && fs.existsSync(ARTIFACT_ENTRY)) {
+          const args = ["recover", repo]
+          if (typeof input.sessionID === "string" && input.sessionID) {
+            args.push("--session-ref", `opencode:${input.sessionID}`)
+          }
+          const recovery = (await runNode(ARTIFACT_ENTRY, args, 3000)).trim()
+          if (recovery) output.system.push(recovery)
+        }
       } catch {
         // Fail open — never block a session because context surfacing failed.
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.3.0",
-  "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
+  "version": "2.4.0",
+  "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode, Pi).",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {
@@ -17,8 +17,10 @@
     "templates/",
     "claude/",
     "opencode/",
+    "pi/",
     "examples/anythingllm/",
     "examples/overlay-distribution/",
+    "examples/eval/",
     "containers/",
     "schemas/",
     "docs/",
@@ -26,6 +28,7 @@
     "CONTRIBUTING.md",
     "SECURITY.md",
     "mcp-memory-server/dist/",
+    "mcp-memory-server/scripts/fixtures/compaction-*.json",
     "mcp-memory-server/package.json",
     "AGENTS.md"
   ],
@@ -33,7 +36,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "agentfs-sdk": "^0.6.4",
     "zod": "^4.4.3"
   },
@@ -42,7 +45,8 @@
     "fix:perms": "git ls-files -s | awk '$1==\"100755\"{print $4}' | xargs chmod 755",
     "prepack": "npm run build:server && npm run fix:perms",
     "test": "for test in scripts/test-*.sh; do \"$test\" || exit 1; done",
-    "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm run build:server && npm test",
+    "audit:runtime": "node scripts/verify-dependency-security.mjs && npm audit --omit=dev --audit-level=high && npm --prefix mcp-memory-server audit --omit=dev --audit-level=high",
+    "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm run audit:runtime && npm run build:server && npm test",
     "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server test --global=false --dry-run=false"
   },
   "repository": {
@@ -59,6 +63,7 @@
     "agent",
     "claude-code",
     "opencode",
+    "pi-coding-agent",
     "context",
     "rag"
   ]

package/pi/extensions/cairnkeep-trajectory.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { spawn } from "node:child_process";
+
+const TRAJECTORY_ENTRY = "@@INFRA_ROOT@@/mcp-memory-server/dist/trajectory-cli.js";
+const CAPTURE_TIMEOUT_MS = 3000;
+
+function captureEnabled(): boolean {
+    return /^(?:1|true|yes|on)$/i.test(process.env.CAIRN_TRAJECTORY_CAPTURE?.trim() ?? "");
+}
+
+function submitTrajectory(projectRoot: string, payload: string): Promise<void> {
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        const finish = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise();
+        };
+        const child = spawn(process.execPath, [TRAJECTORY_ENTRY, "capture-pi", projectRoot], {
+            stdio: ["pipe", "ignore", "ignore"],
+        });
+        const timer = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            } catch {
+                // Best-effort timeout; capture always fails open.
+            }
+            finish();
+        }, CAPTURE_TIMEOUT_MS);
+
+        child.on("close", finish);
+        child.on("error", finish);
+        child.stdin.on("error", () => {
+            // EPIPE is expected when validation or timeout closes the child.
+        });
+        child.stdin.end(payload);
+    });
+}
+
+export default function cairnTrajectoryExtension(pi: ExtensionAPI): void {
+    pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
+        if (!captureEnabled()) return;
+        try {
+            const id = ctx.sessionManager.getSessionId();
+            const entries = ctx.sessionManager.getBranch();
+            if (!id) return;
+            await submitTrajectory(ctx.cwd, JSON.stringify({
+                session: { id, version: 3, cwd: ctx.cwd, entries },
+            }));
+        } catch {
+            // Local trajectory capture must never block or fail a Pi shutdown.
+        }
+    });
+}

package/schemas/artifact.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/artifact.schema.json",
+  "title": "Cairnkeep artifact contract",
+  "oneOf": [
+    { "$ref": "#/$defs/writeInput" },
+    { "$ref": "#/$defs/envelope" },
+    { "$ref": "#/$defs/listOutput" },
+    { "$ref": "#/$defs/doctorOutput" }
+  ],
+  "$defs": {
+    "kind": { "enum": ["compaction_summary", "diff", "test_output", "generated_file"] },
+    "artifactId": { "type": "string", "pattern": "^art_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" },
+    "sessionRef": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
+    "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "nodeRef": {
+      "type": "object", "additionalProperties": false,
+      "required": ["scope", "address_space", "key"],
+      "properties": {
+        "scope": { "type": "string", "minLength": 1, "maxLength": 256, "not": { "const": "all" } },
+        "address_space": { "enum": ["memory", "project-notes", "shared-notes"] },
+        "key": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^(?!/)(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*//)(?!.*\\\\)(?!__)(?!\\.cairnkeep)(?!.*[\\u0000-\\u001f\\u007f]).+(?<!/)$" }
+      }
+    },
+    "provenance": {
+      "type": "object", "additionalProperties": false, "required": ["producer"],
+      "properties": {
+        "producer": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" },
+        "source_event": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "harness": { "enum": ["claude-code", "opencode", "pi"] },
+        "harness_version": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "native_id": { "type": "string", "minLength": 1, "maxLength": 256 }
+      }
+    },
+    "completeness": {
+      "type": "object", "additionalProperties": false,
+      "required": ["task_goals", "decisions_made", "open_todos", "critical_error_traces"],
+      "properties": {
+        "task_goals": { "enum": ["complete", "partial", "missing"] },
+        "decisions_made": { "enum": ["complete", "partial", "missing"] },
+        "open_todos": { "enum": ["complete", "partial", "missing"] },
+        "critical_error_traces": { "enum": ["complete", "partial", "missing"] }
+      }
+    },
+    "compactionInputContent": {
+      "type": "object", "additionalProperties": false,
+      "required": ["raw_summary", "task_goals", "decisions_made", "open_todos", "critical_error_traces", "completeness", "trigger"],
+      "properties": {
+        "raw_summary": { "type": "string", "maxLength": 67108864 },
+        "task_goals": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "decisions_made": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "open_todos": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "critical_error_traces": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "completeness": { "$ref": "#/$defs/completeness" },
+        "trigger": { "type": "string", "minLength": 1, "maxLength": 128 }
+      }
+    },
+    "compactionContent": {
+      "type": "object", "additionalProperties": false,
+      "required": ["raw_summary", "task_goals", "decisions_made", "open_todos", "critical_error_traces", "completeness", "trigger", "revision"],
+      "properties": {
+        "raw_summary": { "type": "string", "maxLength": 67108864 },
+        "task_goals": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "decisions_made": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "open_todos": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "critical_error_traces": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 67108864 } },
+        "completeness": { "$ref": "#/$defs/completeness" },
+        "trigger": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "revision": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "diffContent": { "type": "object", "additionalProperties": false, "required": ["text"], "properties": { "text": { "type": "string", "maxLength": 67108864 } } },
+    "testOutputContent": {
+      "type": "object", "additionalProperties": false, "required": ["text"],
+      "properties": { "text": { "type": "string", "maxLength": 67108864 }, "exit_code": { "type": "integer" }, "status": { "enum": ["passed", "failed", "unknown"] } }
+    },
+    "generatedFileInputContent": {
+      "type": "object", "additionalProperties": false, "required": ["path_label", "file_digest", "logical_bytes", "binary"],
+      "properties": {
+        "path_label": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^(?!/)(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*//)(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f]).+(?<!/)$" },
+        "file_digest": { "$ref": "#/$defs/digest" }, "logical_bytes": { "type": "integer", "minimum": 0 }, "binary": { "type": "boolean" }, "snapshot": { "type": "string", "maxLength": 67108864 }
+      }
+    },
+    "generatedFileContent": {
+      "type": "object", "additionalProperties": false, "required": ["path_label", "file_digest", "logical_bytes", "binary"],
+      "properties": {
+        "path_label": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^(?!/)(?!.*(?:^|/)(?:\\.|\\.\\.)(?:/|$))(?!.*//)(?!.*\\\\)(?!.*[\\u0000-\\u001f\\u007f]).+(?<!/)$" },
+        "file_digest": { "$ref": "#/$defs/digest" }, "logical_bytes": { "type": "integer", "minimum": 0 }, "binary": { "type": "boolean" }, "snapshot": { "type": "string", "maxLength": 67108864 }, "metadata_only": { "type": "boolean" }
+      }
+    },
+    "writeInput": {
+      "oneOf": [
+        { "$ref": "#/$defs/writeCompaction" }, { "$ref": "#/$defs/writeDiff" }, { "$ref": "#/$defs/writeTestOutput" }, { "$ref": "#/$defs/writeGeneratedFile" }
+      ]
+    },
+    "writeBase": {
+      "type": "object", "additionalProperties": false,
+      "required": ["kind", "session_ref", "media_type", "provenance", "content"],
+      "properties": {
+        "kind": { "$ref": "#/$defs/kind" }, "session_ref": { "$ref": "#/$defs/sessionRef" }, "node_ref": { "$ref": "#/$defs/nodeRef" },
+        "media_type": { "type": "string", "minLength": 1, "maxLength": 255 }, "provenance": { "$ref": "#/$defs/provenance" }, "supersedes": { "$ref": "#/$defs/artifactId" }, "content": {}
+      }
+    },
+    "writeCompaction": { "allOf": [{ "$ref": "#/$defs/writeBase" }, { "properties": { "kind": { "const": "compaction_summary" }, "content": { "$ref": "#/$defs/compactionInputContent" } } }] },
+    "writeDiff": { "allOf": [{ "$ref": "#/$defs/writeBase" }, { "properties": { "kind": { "const": "diff" }, "content": { "$ref": "#/$defs/diffContent" } } }] },
+    "writeTestOutput": { "allOf": [{ "$ref": "#/$defs/writeBase" }, { "properties": { "kind": { "const": "test_output" }, "content": { "$ref": "#/$defs/testOutputContent" } } }] },
+    "writeGeneratedFile": { "allOf": [{ "$ref": "#/$defs/writeBase" }, { "properties": { "kind": { "const": "generated_file" }, "content": { "$ref": "#/$defs/generatedFileInputContent" } } }] },
+    "envelope": {
+      "oneOf": [
+        { "$ref": "#/$defs/envelopeCompaction" }, { "$ref": "#/$defs/envelopeDiff" }, { "$ref": "#/$defs/envelopeTestOutput" }, { "$ref": "#/$defs/envelopeGeneratedFile" }
+      ]
+    },
+    "envelopeBase": {
+      "type": "object", "additionalProperties": false,
+      "required": ["schema_version", "artifact_id", "kind", "created_at", "session_ref", "media_type", "logical_bytes", "stored_bytes", "content_digest", "provenance", "redaction", "truncation", "content"],
+      "properties": {
+        "schema_version": { "const": 1 }, "artifact_id": { "$ref": "#/$defs/artifactId" }, "kind": { "$ref": "#/$defs/kind" }, "created_at": { "type": "string", "format": "date-time" },
+        "session_ref": { "$ref": "#/$defs/sessionRef" }, "node_ref": { "$ref": "#/$defs/nodeRef" }, "media_type": { "type": "string", "minLength": 1, "maxLength": 255 },
+        "logical_bytes": { "type": "integer", "minimum": 0 }, "stored_bytes": { "type": "integer", "minimum": 0 }, "content_digest": { "$ref": "#/$defs/digest" },
+        "provenance": { "$ref": "#/$defs/provenance" }, "redaction": { "type": "object", "additionalProperties": false, "required": ["applied", "replacement_count"], "properties": { "applied": { "type": "boolean" }, "replacement_count": { "type": "integer", "minimum": 0 } } },
+        "truncation": { "type": "object", "additionalProperties": false, "required": ["truncated", "original_bytes", "stored_bytes"], "properties": { "truncated": { "type": "boolean" }, "reason": { "enum": ["artifact_limit", "generated_file_metadata_only"] }, "original_bytes": { "type": "integer", "minimum": 0 }, "stored_bytes": { "type": "integer", "minimum": 0 } } },
+        "supersedes": { "$ref": "#/$defs/artifactId" }, "content": {}
+      }
+    },
+    "envelopeCompaction": { "allOf": [{ "$ref": "#/$defs/envelopeBase" }, { "properties": { "kind": { "const": "compaction_summary" }, "content": { "$ref": "#/$defs/compactionContent" } } }] },
+    "envelopeDiff": { "allOf": [{ "$ref": "#/$defs/envelopeBase" }, { "properties": { "kind": { "const": "diff" }, "content": { "$ref": "#/$defs/diffContent" } } }] },
+    "envelopeTestOutput": { "allOf": [{ "$ref": "#/$defs/envelopeBase" }, { "properties": { "kind": { "const": "test_output" }, "content": { "$ref": "#/$defs/testOutputContent" } } }] },
+    "envelopeGeneratedFile": { "allOf": [{ "$ref": "#/$defs/envelopeBase" }, { "properties": { "kind": { "const": "generated_file" }, "content": { "$ref": "#/$defs/generatedFileContent" } } }] },
+    "listOutput": { "type": "object", "additionalProperties": false, "required": ["schema_version", "artifacts", "logical_bytes"], "properties": { "schema_version": { "const": 1 }, "artifacts": { "type": "array", "items": { "$ref": "#/$defs/envelope" } }, "logical_bytes": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": "string" } } },
+    "doctorOutput": { "type": "object", "additionalProperties": false, "required": ["schema_version", "ok", "repaired", "integrity", "issues"], "properties": { "schema_version": { "const": 1 }, "ok": { "type": "boolean" }, "repaired": { "type": "boolean" }, "integrity": { "enum": ["ok", "failed"] }, "issues": { "type": "array", "items": { "type": "string" } } }
+  }
+}
+}

package/schemas/capability-callback.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/capability-callback.schema.json",
+  "title": "Cairnkeep capability callback record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "capability_id",
+    "invocation_id",
+    "correlation_id",
+    "harness",
+    "source",
+    "transport",
+    "started_at",
+    "finished_at",
+    "duration_ms",
+    "outcome",
+    "state_source",
+    "configuration_digest"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "capability_id": {
+      "enum": [
+        "memory.write",
+        "memory.search",
+        "notes.distill",
+        "wiki",
+        "graph",
+        "security.audit",
+        "route.check",
+        "context.explore"
+      ]
+    },
+    "invocation_id": {
+      "type": "string",
+      "pattern": "^cap:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "correlation_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^(?!unknown$)(?:cairn:)?[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$"
+    },
+    "harness": { "enum": ["claude-code", "opencode", "pi", "other"] },
+    "source": { "enum": ["mcp", "notes-cli", "audit-timer", "operating-command", "operating-workflow"] },
+    "transport": { "enum": ["stdio", "http", "local-process", "harness-command"] },
+    "started_at": { "type": "string", "format": "date-time" },
+    "finished_at": { "type": "string", "format": "date-time" },
+    "duration_ms": { "type": "number", "minimum": 0 },
+    "outcome": { "enum": ["success", "error", "timeout", "disabled"] },
+    "error_code": { "enum": ["callback-error", "callback-timeout", "result-error", "result-timeout", "capability-disabled"] },
+    "state_source": { "enum": ["environment", "project", "compatibility"] },
+    "configuration_digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "outcome": { "const": "success" } }, "required": ["outcome"] },
+      "then": { "not": { "required": ["error_code"] } },
+      "else": { "required": ["error_code"] }
+    },
+    {
+      "if": { "properties": { "outcome": { "const": "disabled" } }, "required": ["outcome"] },
+      "then": { "properties": { "error_code": { "const": "capability-disabled" } } }
+    }
+  ]
+}