@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

package/src/global/integrations/sdd-evidence.js

@@ -16,6 +16,7 @@ export const SDD_FILE_OUTCOMES = Object.freeze({
 
 export const SDD_HEALTH = Object.freeze({
   CONFIGURED: "configured",
+  ADOPTED: "adopted",
   MISSING: "missing",
   DRIFTED: "drifted",
   CONFLICT: "conflict"
@@ -23,13 +24,16 @@ export const SDD_HEALTH = Object.freeze({
 
 /**
  * Classify one destination file against canonical bytes and optional tracked hash.
- * Untracked or user-modified files are conflicts and must never be overwritten.
+ * Untracked or user-modified files are conflicts and must never be overwritten
+ * unless overwriteConflicts is requested at apply time.
+ * adoptedHash (disk content accepted as-is) yields NOOP without claiming managed.
  */
 export function classifySddSkillFile({
   exists,
   canonicalHash,
   diskHash = null,
-  trackedHash = null
+  trackedHash = null,
+  adoptedHash = null
 } = {}) {
   if (!exists) {
     return {
@@ -38,6 +42,13 @@ export function classifySddSkillFile({
     };
   }
 
+  if (adoptedHash != null && adoptedHash === diskHash) {
+    return {
+      action: SDD_PLAN_ACTIONS.NOOP,
+      reason: "Adopted disk bytes; preserving byte-for-byte."
+    };
+  }
+
   if (trackedHash == null) {
     return {
       action: SDD_PLAN_ACTIONS.CONFLICT,
@@ -70,11 +81,19 @@ export function classifySddVerifyHealth({
   exists,
   canonicalHash,
   diskHash = null,
-  trackedHash = null
+  trackedHash = null,
+  adoptedHash = null
 } = {}) {
   if (!exists) {
     return { status: SDD_HEALTH.MISSING, drift: null, reason: "Destination missing on disk." };
   }
+  if (adoptedHash != null && adoptedHash === diskHash) {
+    return {
+      status: SDD_HEALTH.ADOPTED,
+      drift: null,
+      reason: "Disk matches adopted hash (not Kairo-managed)."
+    };
+  }
   if (trackedHash == null) {
     return { status: SDD_HEALTH.CONFLICT, drift: null, reason: "Pre-existing untracked file." };
   }

package/src/global/integrations/sdd-plan.js

@@ -25,6 +25,8 @@ export async function planSddConfigure({
   persona = "off",
   personaAgentIds = [],
   trackedFiles = {},
+  adoptedFiles = {},
+  overwriteConflicts = false,
   preservePersona = false,
   dryRun = true,
   exists = existsSync,
@@ -50,16 +52,31 @@ export async function planSddConfigure({
       for (const group of destinationGroups) {
         const destinationPath = join(group.root, skillId, ...file.relativePath.split("/"));
         const trackedHash = trackedFiles[destinationPath] ?? null;
+        const adoptedHash = adoptedFiles[destinationPath] ?? null;
         const fileExists = exists(destinationPath);
         const diskHash = fileExists ? hashBuffer(await readFileImpl(destinationPath)) : null;
-        const classification = classifySddSkillFile({
-          exists: fileExists, canonicalHash, diskHash, trackedHash
+        let classification = classifySddSkillFile({
+          exists: fileExists, canonicalHash, diskHash, trackedHash, adoptedHash
         });
+        let overwrote = false;
+        if (
+          overwriteConflicts
+          && classification.action === SDD_PLAN_ACTIONS.CONFLICT
+          && fileExists
+        ) {
+          classification = {
+            action: SDD_PLAN_ACTIONS.UPDATE,
+            reason: "Overwrite conflicts requested; backup then replace with canonical."
+          };
+          overwrote = true;
+        }
         actions.push({
           skillId, relativePath: file.relativePath, destinationPath,
           agentIds: [...group.agentIds], kind: group.kind,
           action: classification.action, reason: classification.reason,
-          canonicalHash, skillHash, diskHash, trackedHash, writes: false, executes: false
+          canonicalHash, skillHash, diskHash, trackedHash, adoptedHash,
+          overwrote, overwriteConflicts: Boolean(overwriteConflicts),
+          writes: false, executes: false
         });
       }
     }
@@ -78,6 +95,7 @@ export async function planSddConfigure({
   return {
     provider: "sdd-core", componentId: "sdd-core", dryRun: Boolean(dryRun),
     executes: false, writes: false, requestedPersona: persona, preservePersona,
+    overwriteConflicts: Boolean(overwriteConflicts),
     persona: personaTransition.persona,
     personaPath: resolveCanonicalTeachingPersonaPath(packageRoot),
     personaActive: personaTransition.after.length > 0, personaTransition, agentIds, actions,

package/src/global/integrations/sdd-resolutions.js

@@ -0,0 +1,73 @@
+import { formatCliCommand } from "../brand/cli.js";
+import { resolution, RESOLUTION_KIND, RESOLUTION_SAFETY } from "../check-resolutions.js";
+import { SDD_HEALTH } from "./sdd-evidence.js";
+
+/**
+ * Build panel/CLI resolution buttons for sdd-core:skills from verify findings.
+ * Agent list is derived from conflict/drifted findings so buttons scope correctly.
+ */
+export function buildSddSkillResolutions(verification = {}) {
+  const summary = verification.summary ?? {};
+  const conflictCount = summary.conflict ?? 0;
+  const driftedCount = summary.drifted ?? 0;
+  if (conflictCount === 0 && driftedCount === 0) return [];
+
+  const agentIds = conflictAgentIds(verification.findings ?? []);
+  const agentsFlag = agentIds.length ? ` --agents ${agentIds.join(",")}` : "";
+
+  return [
+    resolution(
+      "sdd-diff",
+      "Ver diff",
+      formatCliCommand(`components diff sdd-core${agentsFlag}`),
+      {
+        kind: RESOLUTION_KIND.RUN,
+        safety: RESOLUTION_SAFETY.READ_ONLY,
+        detail: "Read-only: canonical Kairo skills vs disk."
+      }
+    ),
+    resolution(
+      "sdd-adopt",
+      "Conservar el mío",
+      formatCliCommand(`components adopt sdd-core${agentsFlag} --yes`),
+      {
+        kind: RESOLUTION_KIND.CONFIGURE,
+        safety: RESOLUTION_SAFETY.CONSENT,
+        detail: "Adopt disk bytes into Kairo state without overwriting files. Button click is consent."
+      }
+    ),
+    resolution(
+      "sdd-overwrite",
+      "Usar versión Kairo",
+      formatCliCommand(`components configure sdd-core${agentsFlag} --overwrite-conflicts --yes`),
+      {
+        kind: RESOLUTION_KIND.CONFIGURE,
+        safety: RESOLUTION_SAFETY.DESTRUCTIVE,
+        detail: "Backup then replace conflicting files with canonical Kairo skills."
+      }
+    ),
+    resolution(
+      "doctor",
+      "Doctor",
+      formatCliCommand("doctor"),
+      { kind: RESOLUTION_KIND.RUN, safety: RESOLUTION_SAFETY.READ_ONLY }
+    ),
+    resolution(
+      "refresh",
+      "Refresh",
+      null,
+      { kind: RESOLUTION_KIND.REFRESH, safety: RESOLUTION_SAFETY.READ_ONLY }
+    )
+  ];
+}
+
+function conflictAgentIds(findings) {
+  const ids = new Set();
+  for (const finding of findings) {
+    if (finding?.status !== SDD_HEALTH.CONFLICT && finding?.status !== SDD_HEALTH.DRIFTED) {
+      continue;
+    }
+    for (const id of finding.agentIds ?? []) ids.add(id);
+  }
+  return [...ids].sort();
+}

package/src/global/integrations/sdd-state.js

@@ -8,6 +8,7 @@ export function defaultSddState() {
     personaAgentIds: [],
     agentIds: [],
     files: [],
+    adopted: [],
     lastReceiptId: null,
     updatedAt: null
   };
@@ -25,6 +26,7 @@ export function normalizeSddState(raw) {
     personaAgentIds,
     agentIds: Array.isArray(raw.agentIds) ? [...raw.agentIds] : [],
     files: Array.isArray(raw.files) ? raw.files.map(normalizeSddFile) : [],
+    adopted: Array.isArray(raw.adopted) ? raw.adopted.map(normalizeAdoptedFile).filter(Boolean) : [],
     lastReceiptId: typeof raw.lastReceiptId === "string" ? raw.lastReceiptId : null,
     updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : null
   };
@@ -42,6 +44,72 @@ function normalizeSddFile(entry) {
   };
 }
 
+function normalizeAdoptedFile(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  if (typeof entry.destinationPath !== "string" || !entry.destinationPath) return null;
+  if (typeof entry.hash !== "string" || !entry.hash) return null;
+  return {
+    destinationPath: entry.destinationPath,
+    hash: entry.hash,
+    skillId: typeof entry.skillId === "string" ? entry.skillId : null,
+    agentIds: Array.isArray(entry.agentIds) ? [...entry.agentIds] : [],
+    relativePath: typeof entry.relativePath === "string" ? entry.relativePath : "SKILL.md",
+    adoptedAt: typeof entry.adoptedAt === "string" ? entry.adoptedAt : null,
+    reason: typeof entry.reason === "string" ? entry.reason : null
+  };
+}
+
+/** Map destinationPath → adopted hash for verify/plan. */
+export function adoptedHashesFromState(sdd) {
+  const adopted = normalizeSddState(sdd).adopted;
+  return Object.fromEntries(adopted.map((entry) => [entry.destinationPath, entry.hash]));
+}
+
+/** Record conflict findings as adopted disk hashes (no file writes). */
+export function recordSddAdoptions(state, {
+  adoptions = [],
+  now = () => new Date().toISOString()
+} = {}) {
+  const current = normalizeSddState(state?.sdd);
+  const byPath = new Map(current.adopted.map((entry) => [entry.destinationPath, entry]));
+  for (const entry of adoptions) {
+    const normalized = normalizeAdoptedFile({
+      ...entry,
+      adoptedAt: entry.adoptedAt ?? now()
+    });
+    if (!normalized) continue;
+    byPath.set(normalized.destinationPath, normalized);
+  }
+  const adopted = [...byPath.values()].sort((a, b) =>
+    a.destinationPath.localeCompare(b.destinationPath)
+  );
+  return {
+    ...(state ?? {}),
+    sdd: {
+      ...current,
+      adopted,
+      updatedAt: now()
+    }
+  };
+}
+
+/** Drop adopted entries for paths that become Kairo-managed (overwrite/apply). */
+export function clearSddAdoptionsForPaths(state, paths = [], {
+  now = () => new Date().toISOString()
+} = {}) {
+  const current = normalizeSddState(state?.sdd);
+  const drop = new Set(paths);
+  const adopted = current.adopted.filter((entry) => !drop.has(entry.destinationPath));
+  return {
+    ...(state ?? {}),
+    sdd: {
+      ...current,
+      adopted,
+      updatedAt: now()
+    }
+  };
+}
+
 function verifiedNoopHash(file) {
   const disk = file.afterHash ?? file.diskHash ?? file.beforeHash ?? null;
   if (disk == null || file.canonicalHash == null || disk !== file.canonicalHash) return null;
@@ -116,6 +184,7 @@ export function recordSddMaterialization(state, { receipt, now = () => new Date(
       personaAgentIds,
       agentIds: collectAgentIds(files),
       files,
+      adopted: current.adopted,
       lastReceiptId: receipt.id ?? current.lastReceiptId,
       updatedAt: now()
     }

package/src/global/integrations/sdd-verify.js

@@ -26,6 +26,7 @@ export async function verifySddConfigure({
   homeDir,
   packageRoot,
   trackedFiles = {},
+  adoptedFiles = {},
   personaAgentIds = [],
   exists = existsSync,
   readFileImpl = readFile
@@ -49,14 +50,15 @@ export async function verifySddConfigure({
         const fileExists = exists(destinationPath);
         const diskHash = fileExists ? hashBuffer(await readFileImpl(destinationPath)) : null;
         const trackedHash = trackedFiles[destinationPath] ?? null;
+        const adoptedHash = adoptedFiles[destinationPath] ?? null;
         const health = classifySddVerifyHealth({
-          exists: fileExists, canonicalHash, diskHash, trackedHash
+          exists: fileExists, canonicalHash, diskHash, trackedHash, adoptedHash
         });
         findings.push({
           skillId, relativePath: file.relativePath, destinationPath,
           agentIds: [...group.agentIds], kind: group.kind,
           status: health.status, drift: health.drift, reason: health.reason,
-          canonicalHash, skillHash, diskHash, trackedHash
+          canonicalHash, skillHash, diskHash, trackedHash, adoptedHash
         });
       }
     }
@@ -66,13 +68,15 @@ export async function verifySddConfigure({
     || compareSkillPaths(a.relativePath, b.relativePath)
     || compareSkillPaths(a.destinationPath, b.destinationPath));
 
-  const summary = { configured: 0, missing: 0, drifted: 0, conflict: 0 };
+  const summary = { configured: 0, adopted: 0, missing: 0, drifted: 0, conflict: 0 };
   for (const entry of findings) summary[entry.status] += 1;
 
   const consumers = normalizePersonaAgentIds(personaAgentIds);
   const incompleteAgentIds = consumers.filter((id) => {
     const mine = findings.filter((e) => e.agentIds.includes(id));
-    return !mine.length || mine.some((e) => e.status !== SDD_HEALTH.CONFIGURED);
+    return !mine.length || mine.some((e) =>
+      e.status !== SDD_HEALTH.CONFIGURED && e.status !== SDD_HEALTH.ADOPTED
+    );
   });
   let gatePresent = true;
   for (const id of consumers) {
@@ -100,6 +104,7 @@ export function summarizeSddHealth(summary) {
   if (summary.conflict > 0) return SDD_HEALTH.CONFLICT;
   if (summary.missing > 0) return SDD_HEALTH.MISSING;
   if (summary.drifted > 0) return SDD_HEALTH.DRIFTED;
+  if ((summary.adopted ?? 0) > 0 && (summary.configured ?? 0) === 0) return SDD_HEALTH.ADOPTED;
   return SDD_HEALTH.CONFIGURED;
 }
 

package/src/global/mcp/kairo-mcp.js

@@ -12,10 +12,20 @@ import { runGraphifyOp } from "../observability/graphify-ops.js";
 import { resolveGitHeadSha } from "../observability/graphify-probe.js";
 import { runPassiveObservabilitySnapshot } from "../observability/passive-snapshot-flight.js";
 import { inspectEngramIntegration } from "../integrations/engram-evidence.js";
+import { buildFleetReport } from "../observability/fleet-probe.js";
+import {
+  createPublishWorkSnapshotHandler,
+  workSnapshotPublishSchema
+} from "./work-snapshot-tool.js";
+import { resolveMcpWorkspaceCwd } from "./resolve-mcp-workspace.js";
+
+/** Sole MCP write tool for companion snapshots. */
+export const KAIRO_MCP_WRITE_TOOLS = Object.freeze(["kairo_publish_work_snapshot"]);
 
 export const KAIRO_MCP_TOOLS = Object.freeze([
   "kairo_status", "kairo_runs", "kairo_alerts", "kairo_gentle_status",
-  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary"
+  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary", "kairo_fleet",
+  ...KAIRO_MCP_WRITE_TOOLS
 ]);
 
 const empty = z.object({});
@@ -30,7 +40,8 @@ export const mcpSchemas = Object.freeze({
     graph: z.string().min(1), question: z.string().min(1),
     budget: z.number().int().min(1).max(8000).default(2000)
   }),
-  graphPath: z.object({ graph: z.string().min(1), from: z.string().min(1), to: z.string().min(1) })
+  graphPath: z.object({ graph: z.string().min(1), from: z.string().min(1), to: z.string().min(1) }),
+  workSnapshotPublish: workSnapshotPublishSchema
 });
 
 const CODE_RE = /^(?:[a-z][a-z0-9_]{0,48}|status=\d+)$/;
@@ -94,7 +105,11 @@ function graphEnvelope(result) {
 
 export function createToolHandlers(deps = {}) {
   const homeDir = deps.homeDir ?? resolveHomeDir();
-  const cwd = deps.cwd ?? process.cwd();
+  // Cursor may spawn MCP under $HOME; prefer VSCODE_CWD / WORKSPACE_FOLDER_PATHS.
+  const cwd = resolveMcpWorkspaceCwd({
+    cwd: deps.cwd,
+    env: deps.env ?? process.env
+  });
   const listRuns = deps.listRuns ?? ((o) => listRunRecords(homeDir, o));
   const listAlertRows = deps.listAlerts ?? ((o) => listAlerts({ homeDir, ...o }));
   const listReviews = deps.listReviews ?? (() => listReviewReceipts({ homeDir, limit: 20 }));
@@ -117,6 +132,7 @@ export function createToolHandlers(deps = {}) {
     observabilityContext: { cwd, homeDir, workspaceRoot: cwd, headSha: requestHead() }
   }));
   const gentleProbe = deps.probeGentle ?? ((ctx) => probeGentle(ctx));
+  const fleetProbe = deps.buildFleet ?? ((ctx) => buildFleetReport(ctx));
   const graphOp = deps.runGraphifyOp ?? runGraphifyOp;
   const gOpts = () => ({
     cwd, workspaceRoot: cwd, headSha: requestHead(), whichCommand: deps.whichCommand,
@@ -200,7 +216,36 @@ export function createToolHandlers(deps = {}) {
       } catch {
         return soft("degraded", { signals: null, engram: null, links: [], alertsCount: null, nextSafeAction: null });
       }
-    }
+    },
+    async kairo_fleet() {
+      try {
+        const report = await fleetProbe({ homeDir });
+        return mcpResult({
+          ok: true,
+          code: "ok",
+          data: {
+            kind: report?.kind ?? "declared",
+            note: report?.note ?? null,
+            orchestratorAuthority: report?.orchestratorAuthority ?? null,
+            fleets: Array.isArray(report?.fleets) ? report.fleets : [],
+            activity: report?.activity ?? null,
+            generatedAt: report?.generatedAt ?? null
+          }
+        });
+      } catch {
+        return soft("degraded", {
+          kind: "declared", fleets: [], activity: null, note: null, orchestratorAuthority: null
+        });
+      }
+    },
+    kairo_publish_work_snapshot: createPublishWorkSnapshotHandler({
+      homeDir,
+      cwd,
+      now: deps.now,
+      writeAtomic: deps.writeAtomic,
+      publishWorkSnapshot: deps.publishWorkSnapshot,
+      mcpResult
+    })
   };
 }
 
@@ -213,7 +258,13 @@ export function registerKairoMcpTools(registerTool, deps = {}) {
     ["kairo_gentle_status", "Gentle probe / companion gentle signal", empty],
     ["kairo_graph_query", "Read-only Graphify query", mcpSchemas.graphQuery],
     ["kairo_graph_path", "Read-only Graphify path", mcpSchemas.graphPath],
-    ["kairo_context_summary", "Companion + soft links + alerts count", empty]
+    ["kairo_context_summary", "Companion + soft links + alerts count", empty],
+    ["kairo_fleet", "Declared fleet topology + OpenCode live activity", empty],
+    [
+      "kairo_publish_work_snapshot",
+      "Publish kairo.work-snapshot/v1 for the runtime workspace (enrolls conversation)",
+      mcpSchemas.workSnapshotPublish
+    ]
   ]) registerTool(name, { description, inputSchema }, h[name]);
   return h;
 }

package/src/global/mcp/resolve-mcp-workspace.js

@@ -0,0 +1,51 @@
+/**
+ * Resolve the workspace path for Kairo MCP identity.
+ *
+ * Cursor IDE launches global `mcpServers.kairo` with process cwd = $HOME even
+ * when the entry sets `cwd: "."`. It does inject the open folder via
+ * VSCODE_CWD / WORKSPACE_FOLDER_PATHS — prefer those over process.cwd().
+ */
+import { resolve } from "node:path";
+import { canonicalizeProjectPath } from "../next/project-key.js";
+
+function firstNonEmpty(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * Parse Cursor/VS Code workspace folder env into an ordered path list.
+ * WORKSPACE_FOLDER_PATHS uses commas when Cursor opens multiple roots.
+ */
+export function parseWorkspaceFolderPaths(raw) {
+  const text = firstNonEmpty(raw);
+  if (!text) return [];
+  return text
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {{ cwd?: string, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {string} absolute workspace path
+ */
+export function resolveMcpWorkspaceCwd({
+  cwd,
+  env = process.env
+} = {}) {
+  let chosen;
+  if (typeof cwd === "string" && cwd.trim()) {
+    chosen = resolve(cwd.trim());
+  } else {
+    const fromFolders = parseWorkspaceFolderPaths(env.WORKSPACE_FOLDER_PATHS);
+    if (fromFolders.length > 0) {
+      chosen = resolve(fromFolders[0]);
+    } else {
+      const vscodeCwd = firstNonEmpty(env.VSCODE_CWD);
+      chosen = vscodeCwd ? resolve(vscodeCwd) : resolve(process.cwd());
+    }
+  }
+  return canonicalizeProjectPath(chosen);
+}

package/src/global/mcp/work-snapshot-rule.js

@@ -0,0 +1,89 @@
+/**
+ * Managed Cursor rule: instruct agents to publish kairo.work-snapshot/v1.
+ */
+import { mkdir, readFile, writeFile, rename, copyFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+export const WORK_SNAPSHOT_RULE_FILENAME = "kairo-work-snapshot.mdc";
+
+export function resolveCursorRulesDir(homeDir = homedir()) {
+  return join(homeDir, ".cursor", "rules");
+}
+
+export function resolveWorkSnapshotRulePath(homeDir = homedir()) {
+  return join(resolveCursorRulesDir(homeDir), WORK_SNAPSHOT_RULE_FILENAME);
+}
+
+export const WORK_SNAPSHOT_RULE_BODY = `# Kairo work snapshot
+
+After each significant turn, publish the true work state with MCP \`kairo_publish_work_snapshot\`:
+
+- Required: \`conversationId\`, \`provider\` (\`cursor\`), \`goal\`, \`now\`, \`next\`
+- Optional: \`progress\` (≤3), \`blockers\`, \`delegations\` (only real ones)
+- Workspace identity is derived by Kairo from the runtime — never send \`projectKey\`, paths, or \`cwd\`
+- Never invent work. Never send prompts, transcripts, or tool dumps
+- Reuse the same \`conversationId\` for later turns in this chat
+`;
+
+export function buildWorkSnapshotRuleFile() {
+  return `---
+description: Publish Kairo work snapshot after significant Cursor turns
+alwaysApply: true
+---
+
+${WORK_SNAPSHOT_RULE_BODY}
+`;
+}
+
+async function writeAtomicText(targetPath, text, deps = {}) {
+  const write = deps.writeFileFn ?? writeFile;
+  const renameFn = deps.renameFn ?? rename;
+  const tempPath = join(
+    dirname(targetPath),
+    `.${WORK_SNAPSHOT_RULE_FILENAME}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`
+  );
+  await write(tempPath, text, "utf8");
+  await renameFn(tempPath, targetPath);
+}
+
+/**
+ * Plan or apply the managed work-snapshot rule under ~/.cursor/rules/.
+ */
+export async function ensureWorkSnapshotRule({
+  homeDir = homedir(),
+  apply = false,
+  now = () => Date.now(),
+  readFileFn = readFile,
+  mkdirFn = mkdir,
+  copyFileFn = copyFile,
+  writeFileFn = writeFile,
+  renameFn = rename
+} = {}) {
+  const path = resolveWorkSnapshotRulePath(homeDir);
+  const desired = buildWorkSnapshotRuleFile();
+  let existing = null;
+  try {
+    existing = await readFileFn(path, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const wouldWrite = existing !== desired;
+  const backupPath = wouldWrite && existing != null
+    ? `${path}.kairo-backup.${now()}`
+    : null;
+
+  if (!apply) {
+    return { path, wouldWrite, wrote: false, backupPath: null };
+  }
+
+  await mkdirFn(dirname(path), { recursive: true });
+  if (wouldWrite && existing != null) {
+    await copyFileFn(path, backupPath);
+  }
+  if (wouldWrite) {
+    await writeAtomicText(path, desired, { writeFileFn, renameFn });
+  }
+  return { path, wouldWrite, wrote: wouldWrite, backupPath };
+}

package/src/global/mcp/work-snapshot-tool.js

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import { publishWorkSnapshot } from "../next/publish-work-snapshot.js";
+
+export const workSnapshotPublishSchema = z.object({
+  conversationId: z.string().min(1).max(160),
+  provider: z.enum(["cursor", "codex", "claude", "opencode", "pi", "other"]),
+  goal: z.string().min(1).max(160),
+  now: z.string().min(1).max(240),
+  next: z.string().min(1).max(240),
+  progress: z.array(z.string().max(160)).max(3).optional(),
+  blockers: z.array(z.string().max(200)).max(12).optional(),
+  delegations: z.array(z.object({
+    workId: z.string().max(64).optional(),
+    title: z.string().max(160).optional(),
+    role: z.enum(["orchestrator", "worker"]).optional(),
+    state: z.enum(["assigned", "working", "blocked", "completed", "failed"]).optional()
+  }).strict()).max(12).optional()
+}).strict();
+
+export function createPublishWorkSnapshotHandler(deps = {}) {
+  const publishSnapshot = deps.publishWorkSnapshot ?? ((input) => publishWorkSnapshot(input, {
+    homeDir: deps.homeDir,
+    cwd: deps.cwd,
+    now: deps.now,
+    writeAtomic: deps.writeAtomic
+  }));
+  const toResult = deps.mcpResult;
+  if (typeof toResult !== "function") {
+    throw new Error("mcpResult dependency is required");
+  }
+
+  return async function kairo_publish_work_snapshot(args = {}) {
+    try {
+      const result = await publishSnapshot(args);
+      return toResult({
+        ok: Boolean(result?.ok),
+        code: result?.code ?? "publish_failed",
+        data: result?.data ?? null,
+        diagnostics: result?.diagnostics ?? [],
+        isError: !result?.ok
+      });
+    } catch {
+      return toResult({
+        ok: false, code: "publish_failed", data: null,
+        diagnostics: ["publish_failed"], isError: true
+      });
+    }
+  };
+}