chainlesschain 0.162.189 → 0.162.193

package/src/lib/cowork-mcp-tools.js

@@ -20,6 +20,7 @@
  * @module cowork-mcp-tools
  */
 import { validateMcpServerConfig } from "./skill-mcp.js";
+import { mcpEffectDescriptorFields } from "./mcp-effect-contract.js";
 
 export const _deps = {
   importMcpClient: async () => {
@@ -64,6 +65,10 @@ export function toAgentTool(serverName, tool) {
       source: "cowork-template-mcp",
       serverName,
       originalName: tool.name,
+      ...mcpEffectDescriptorFields(tool, {
+        sourceTrusted: false,
+        provenance: `cowork-template:${serverName}`,
+      }),
     },
     executor: {
       kind: "mcp",

package/src/lib/cowork-task-runner.js

@@ -7,22 +7,379 @@
  * @module cowork-task-runner
  */
 
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, appendFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { SubAgentContext } from "./sub-agent-context.js";
 import { getTemplate, setUserTemplates } from "./cowork-task-templates.js";
 import { mountTemplateMcpTools } from "./cowork-mcp-tools.js";
 import { listUserTemplates } from "./cowork-template-marketplace.js";
+import {
+  createMcpCallLedger,
+  McpEffect,
+  snapshotMcpJsonRpcInput,
+} from "./mcp-call-ledger.js";
+import {
+  createMcpRecoveryAdmissionController,
+  guardMcpLedgerForRecovery,
+} from "./mcp-ledger-recovery-admission.js";
+import {
+  assertMcpVerifiedProjectionAuthority,
+  createSessionMcpLedgerSink,
+  createMcpLedgerEventReducer,
+  formatMcpLedgerRecoveryNotice,
+  snapshotMcpLedgerRecoveryProjection,
+} from "./mcp-call-ledger-store.js";
+import {
+  appendAuthorityEvent as appendSessionEvent,
+  appendAuthorityEventIfHead as appendSessionEventIfHead,
+  isUnsafeSessionId,
+  readVerifiedEvents as readVerifiedSessionEvents,
+  readVerifiedProjection as readVerifiedSessionProjection,
+} from "../harness/jsonl-session-store.js";
 
 // ─── Dependencies (overridable for testing) ──────────────────────────────────
 
-export const _deps = { existsSync, mkdirSync, appendFileSync, readFileSync };
+export const _deps = {
+  existsSync,
+  mkdirSync,
+  appendFileSync,
+  readFileSync,
+  appendSessionEvent,
+  appendSessionEventIfHead,
+  readVerifiedSessionEvents,
+  readVerifiedSessionProjection,
+  randomUUID,
+};
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
 const DEFAULT_MAX_ITERATIONS = 50;
 const DEFAULT_TOKEN_BUDGET = 100_000;
 
+function resolveCoworkMcpSessionId(requested) {
+  if (requested != null) {
+    if (typeof requested !== "string" || isUnsafeSessionId(requested)) {
+      const error = new Error("Cowork MCP session id is invalid");
+      error.code = "CC_COWORK_MCP_SESSION_INVALID";
+      throw error;
+    }
+    return requested;
+  }
+  return `cowork-mcp-${_deps.randomUUID()}`;
+}
+
+function publicMcpRecoveryState(recovery, blockMode, readErrorCode = null) {
+  const unsettled = Array.isArray(recovery?.unsettled)
+    ? recovery.unsettled.slice(0, 20).map((record) =>
+        Object.freeze({
+          ledgerId: record.ledgerId,
+          serverName: record.serverName,
+          toolName: record.toolName,
+          effect: record.effectContract?.effect || McpEffect.UNKNOWN,
+        }),
+      )
+    : [];
+  const incidents = Array.isArray(recovery?.incidents)
+    ? recovery.incidents.slice(0, 20).map((incident) =>
+        Object.freeze({
+          code: incident.code,
+          ledgerId: incident.ledgerId || null,
+        }),
+      )
+    : [];
+  // Exact replay denies are active admission authority, not display samples.
+  // Never truncate this list: dropping one entry would re-enable that call.
+  const replayDenied = Array.isArray(recovery?.replayDenied)
+    ? recovery.replayDenied.map((entry) =>
+        Object.freeze({
+          ledgerId: entry.ledgerId,
+          serverName: entry.serverName,
+          toolName: entry.toolName,
+          inputBytes: entry.inputBytes,
+          replayDigest: entry.replayDigest,
+        }),
+      )
+    : [];
+  if (readErrorCode) {
+    incidents.push(Object.freeze({ code: readErrorCode, ledgerId: null }));
+  }
+  return Object.freeze({
+    blockMode,
+    unsettled: Object.freeze(unsettled),
+    incidents: Object.freeze(incidents),
+    replayDenied: Object.freeze(replayDenied),
+    headHash: recovery?.headHash || null,
+    recoveryDigest: recovery?.recoveryDigest || null,
+    remediation:
+      recovery?.remediation || (readErrorCode ? "inspect_transcript" : null),
+  });
+}
+
+function assertCoworkMcpSessionBindingEvent(event, templateId) {
+  if (event?.type !== "cowork_mcp_session") return;
+  const binding = event.data;
+  if (
+    binding?.schemaVersion !== 1 ||
+    typeof binding.taskId !== "string" ||
+    typeof binding.templateId !== "string"
+  ) {
+    const error = new Error("Cowork MCP session binding is malformed");
+    error.code = "CC_COWORK_MCP_SESSION_BIND_INVALID";
+    throw error;
+  }
+  if (binding.templateId !== templateId) {
+    const error = new Error(
+      `Cowork MCP session is already bound to template ${binding.templateId}`,
+    );
+    error.code = "CC_COWORK_MCP_SESSION_BIND_CONFLICT";
+    throw error;
+  }
+}
+
+function createCoworkMcpRecoveryProjection(sessionId, templateId, onFinish) {
+  const ledger = createMcpLedgerEventReducer({
+    sessionId,
+    verified: true,
+  });
+  let acceptedCount = 0;
+  let finished = false;
+  return Object.freeze({
+    accept(event) {
+      if (finished) {
+        const error = new Error("Cowork MCP projection accepted after finish");
+        error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+        throw error;
+      }
+      acceptedCount += 1;
+      assertCoworkMcpSessionBindingEvent(event, templateId);
+      ledger.accept(event);
+    },
+    finish(authority) {
+      if (finished) {
+        const error = new Error("Cowork MCP projection finished twice");
+        error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+        throw error;
+      }
+      finished = true;
+      const recovery = ledger.finish();
+      assertMcpVerifiedProjectionAuthority(authority, {
+        acceptedCount,
+        headHash: recovery.headHash,
+      });
+      const projected = Object.freeze({
+        schemaVersion: 1,
+        bindingAllowed: true,
+        expectedHeadHash: recovery.headHash,
+        recovery,
+      });
+      onFinish(projected);
+      return projected;
+    },
+  });
+}
+
+function snapshotCoworkMcpRecoveryProjection(sessionId, value) {
+  const snapshot = snapshotMcpJsonRpcInput(value);
+  const fields = Object.keys(snapshot || {})
+    .sort()
+    .join(",");
+  if (
+    fields !== "bindingAllowed,expectedHeadHash,recovery,schemaVersion" ||
+    snapshot.schemaVersion !== 1 ||
+    snapshot.bindingAllowed !== true
+  ) {
+    const error = new TypeError("Cowork MCP recovery projection is malformed");
+    error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+    throw error;
+  }
+  const recovery = snapshotMcpLedgerRecoveryProjection(
+    sessionId,
+    snapshot.recovery,
+  );
+  if (snapshot.expectedHeadHash !== recovery.headHash) {
+    const error = new TypeError(
+      "Cowork MCP recovery projection head is inconsistent",
+    );
+    error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+    throw error;
+  }
+  return Object.freeze({ ...snapshot, recovery });
+}
+
+function readCoworkMcpRecoveryProjection(sessionId, templateId) {
+  const hasCustomLegacyReader =
+    typeof _deps.readVerifiedSessionEvents === "function" &&
+    _deps.readVerifiedSessionEvents !== readVerifiedSessionEvents;
+  const readProjection = _deps.readVerifiedSessionProjection;
+  if (
+    typeof readProjection === "function" &&
+    (readProjection !== readVerifiedSessionProjection || !hasCustomLegacyReader)
+  ) {
+    let projectionCreated = false;
+    let finishedProjection;
+    const returnedProjection = readProjection(sessionId, () => {
+      if (projectionCreated) {
+        const error = new Error("Cowork MCP projection factory was reused");
+        error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+        throw error;
+      }
+      projectionCreated = true;
+      return createCoworkMcpRecoveryProjection(
+        sessionId,
+        templateId,
+        (value) => {
+          finishedProjection = value;
+        },
+      );
+    });
+    if (
+      !projectionCreated ||
+      finishedProjection === undefined ||
+      returnedProjection !== finishedProjection
+    ) {
+      const error = new Error(
+        "Cowork MCP projection reader bypassed its verified factory",
+      );
+      error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+      throw error;
+    }
+    return snapshotCoworkMcpRecoveryProjection(sessionId, returnedProjection);
+  }
+  if (!hasCustomLegacyReader) {
+    const error = new TypeError(
+      "Verified Cowork MCP projection reader is unavailable",
+    );
+    error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+    throw error;
+  }
+
+  const verifiedEvents = snapshotMcpJsonRpcInput(
+    _deps.readVerifiedSessionEvents(sessionId),
+  );
+  if (!Array.isArray(verifiedEvents)) {
+    const invalid = new TypeError(
+      "Verified Cowork MCP events must be returned synchronously as an array",
+    );
+    invalid.code = "CC_MCP_LEDGER_VERIFIED_EVENTS_INVALID";
+    throw invalid;
+  }
+  let finishedProjection;
+  const projection = createCoworkMcpRecoveryProjection(
+    sessionId,
+    templateId,
+    (value) => {
+      finishedProjection = value;
+    },
+  );
+  for (const event of verifiedEvents) projection.accept(event);
+  const returnedProjection = projection.finish(
+    Object.freeze({
+      headHash: verifiedEvents.at(-1)?.hash || null,
+      eventCount: verifiedEvents.length,
+      readMessages: () => [],
+    }),
+  );
+  if (returnedProjection !== finishedProjection) {
+    const error = new Error("Cowork MCP legacy projection did not finish");
+    error.code = "CC_COWORK_MCP_RECOVERY_PROJECTION_INVALID";
+    throw error;
+  }
+  return snapshotCoworkMcpRecoveryProjection(sessionId, returnedProjection);
+}
+
+/**
+ * Build one session-scoped durable ledger for every template MCP call. The
+ * returned ledger is handed to SubAgentContext, so agent-core must complete a
+ * durable started prewrite before invoking unknown/write/destructive tools.
+ */
+export function prepareCoworkMcpRuntime(mcp, options = {}) {
+  if (
+    !mcp?.mcpClient ||
+    !Array.isArray(mcp.extraToolDefinitions) ||
+    mcp.extraToolDefinitions.length === 0
+  ) {
+    return {
+      sessionId: null,
+      ledger: null,
+      recoveryNotice: null,
+      recoveryState: null,
+    };
+  }
+
+  const sessionId = resolveCoworkMcpSessionId(options.mcpSessionId);
+  if (typeof options.onProgress === "function") {
+    options.onProgress({ type: "mcp-session", sessionId });
+  }
+  let recoveryNotice = null;
+  let recoveryState = null;
+  let bindingAllowed = false;
+  let expectedHeadHash = null;
+  try {
+    const projected = readCoworkMcpRecoveryProjection(
+      sessionId,
+      String(options.templateId || "free"),
+    );
+    const recovery = projected.recovery;
+    expectedHeadHash = projected.expectedHeadHash;
+    bindingAllowed = projected.bindingAllowed;
+    recoveryNotice = formatMcpLedgerRecoveryNotice(recovery);
+    const blockMode =
+      recovery.incidents.length > 0
+        ? "all"
+        : recovery.unsettled.length > 0
+          ? "unsafe"
+          : null;
+    recoveryState = publicMcpRecoveryState(recovery, blockMode);
+    if (recoveryNotice && typeof options.onProgress === "function") {
+      options.onProgress({
+        type: "mcp-recovery",
+        sessionId,
+        unsettled: recovery.unsettled.length,
+        incidents: recovery.incidents.length,
+        recovery: recoveryState,
+      });
+    }
+  } catch (error) {
+    recoveryNotice =
+      "MCP recovery notice — the durable Cowork MCP ledger could not be read. " +
+      "Do not execute or retry MCP tools until the session transcript has " +
+      `been inspected (${error?.code || "CC_MCP_LEDGER_EVENT_READ_FAILED"}).`;
+    recoveryState = publicMcpRecoveryState(
+      null,
+      "all",
+      error?.code || "CC_MCP_LEDGER_EVENT_READ_FAILED",
+    );
+    if (typeof options.onProgress === "function") {
+      options.onProgress({
+        type: "mcp-recovery",
+        sessionId,
+        unsettled: 0,
+        incidents: 1,
+        recovery: recoveryState,
+      });
+    }
+  }
+
+  const sink = createSessionMcpLedgerSink(sessionId, {
+    appendEvent: _deps.appendSessionEvent,
+  });
+  const recoveryController =
+    createMcpRecoveryAdmissionController(recoveryState);
+  return {
+    sessionId,
+    recoveryNotice,
+    recoveryState,
+    bindingAllowed,
+    expectedHeadHash,
+    ledger: guardMcpLedgerForRecovery(
+      createMcpCallLedger({ sink }),
+      recoveryController,
+      { code: "CC_COWORK_MCP_RECOVERY_BLOCKED" },
+    ),
+  };
+}
+
 // ─── Runner ───────────────────────────────────────────────────────────────────
 
 /**
@@ -37,6 +394,7 @@ const DEFAULT_TOKEN_BUDGET = 100_000;
  * @param {object} [options.llmOptions] - LLM provider/model/key
  * @param {number} [options.maxIterations] - Override iteration limit
  * @param {number} [options.tokenBudget] - Override token budget
+ * @param {string} [options.mcpSessionId] - Stable MCP ledger session for resume
  * @returns {Promise<{ taskId: string, status: string, result: object }>}
  */
 export async function runCoworkTask(options = {}) {
@@ -51,6 +409,7 @@ export async function runCoworkTask(options = {}) {
     tokenBudget = DEFAULT_TOKEN_BUDGET,
     onProgress = null,
     signal = null,
+    mcpSessionId = null,
   } = options;
 
   if (!userMessage || typeof userMessage !== "string") {
@@ -95,7 +454,7 @@ export async function runCoworkTask(options = {}) {
     taskParts.push(`\n## 用户提供的文件\n${files.join("\n")}`);
   }
 
-  const task = taskParts.join("\n");
+  let task = taskParts.join("\n");
 
   // Mount template-declared MCP servers (best-effort, failures are tolerated)
   const mcp = await mountTemplateMcpTools(template, {
@@ -103,72 +462,108 @@ export async function runCoworkTask(options = {}) {
       if (onProgress) onProgress({ type: "mcp-warning", message: msg });
     },
   });
-  if (onProgress && (mcp.mounted.length > 0 || mcp.skipped.length > 0)) {
-    onProgress({
-      type: "mcp-mounted",
-      mounted: mcp.mounted,
-      skipped: mcp.skipped.map((s) => s.name),
-      toolCount: mcp.extraToolDefinitions.length,
+  try {
+    if (onProgress && (mcp.mounted.length > 0 || mcp.skipped.length > 0)) {
+      onProgress({
+        type: "mcp-mounted",
+        mounted: mcp.mounted,
+        skipped: mcp.skipped.map((s) => s.name),
+        toolCount: mcp.extraToolDefinitions.length,
+      });
+    }
+    const mcpRuntime = prepareCoworkMcpRuntime(mcp, {
+      mcpSessionId,
+      onProgress,
+      templateId: template.id,
     });
-  }
+    if (mcpRuntime.recoveryNotice) {
+      task += `\n\n## MCP Recovery Authority\n${mcpRuntime.recoveryNotice}`;
+    }
 
-  // Create isolated sub-agent context
-  const subAgent = SubAgentContext.create({
-    role: `cowork-${template.id}`,
-    task,
-    inheritedContext: null,
-    maxIterations,
-    tokenBudget,
-    db,
-    llmOptions,
-    cwd,
-    onProgress,
-    signal,
-    extraToolDefinitions: mcp.extraToolDefinitions,
-    externalToolDescriptors: mcp.externalToolDescriptors,
-    externalToolExecutors: mcp.externalToolExecutors,
-    mcpClient: mcp.mcpClient,
-  });
+    // Create isolated sub-agent context
+    const subAgent = SubAgentContext.create({
+      role: `cowork-${template.id}`,
+      task,
+      inheritedContext: null,
+      maxIterations,
+      tokenBudget,
+      db,
+      llmOptions,
+      cwd,
+      onProgress,
+      signal,
+      extraToolDefinitions: mcp.extraToolDefinitions,
+      externalToolDescriptors: mcp.externalToolDescriptors,
+      externalToolExecutors: mcp.externalToolExecutors,
+      mcpClient: mcp.mcpClient,
+      ...(mcpRuntime.ledger ? { mcpCallLedger: mcpRuntime.ledger } : {}),
+    });
 
-  const taskId = subAgent.id;
+    const taskId = subAgent.id;
 
-  // Build loop options — pass shell policy overrides if template declares them
-  const loopOptions = {};
-  if (
-    Array.isArray(template.shellPolicyOverrides) &&
-    template.shellPolicyOverrides.length
-  ) {
-    loopOptions.shellPolicyOverrides = template.shellPolicyOverrides;
-  }
+    if (mcpRuntime.sessionId && mcpRuntime.bindingAllowed) {
+      const mapped = await _deps.appendSessionEventIfHead(
+        mcpRuntime.sessionId,
+        "cowork_mcp_session",
+        {
+          schemaVersion: 1,
+          taskId,
+          templateId: template.id,
+        },
+        mcpRuntime.expectedHeadHash,
+      );
+      if (mapped === false) {
+        const error = new Error(
+          "Cowork MCP task/session binding was not persisted",
+        );
+        error.code = "CC_COWORK_MCP_SESSION_BIND_FAILED";
+        throw error;
+      }
+    }
 
-  // Run the agent with the user's message
-  try {
-    const result = await subAgent.run(userMessage, loopOptions);
-    const entry = {
-      taskId,
-      status: subAgent.status,
-      templateId: template.id,
-      templateName: template.name,
-      result,
-    };
-    _appendHistory(cwd, entry, userMessage);
-    return entry;
-  } catch (err) {
-    const entry = {
-      taskId,
-      status: "failed",
-      templateId: template.id,
-      templateName: template.name,
-      result: {
-        summary: `Task failed: ${err.message}`,
-        artifacts: [],
-        tokenCount: 0,
-        toolsUsed: [],
-        iterationCount: 0,
-      },
-    };
-    _appendHistory(cwd, entry, userMessage);
-    return entry;
+    // Build loop options — pass shell policy overrides if template declares them
+    const loopOptions =
+      mcpRuntime.sessionId && mcpRuntime.bindingAllowed
+        ? { sessionId: mcpRuntime.sessionId }
+        : {};
+    if (
+      Array.isArray(template.shellPolicyOverrides) &&
+      template.shellPolicyOverrides.length
+    ) {
+      loopOptions.shellPolicyOverrides = template.shellPolicyOverrides;
+    }
+
+    // Run the agent with the user's message
+    try {
+      const result = await subAgent.run(userMessage, loopOptions);
+      const entry = {
+        taskId,
+        status: subAgent.status,
+        templateId: template.id,
+        templateName: template.name,
+        ...(mcpRuntime.sessionId ? { mcpSessionId: mcpRuntime.sessionId } : {}),
+        result,
+      };
+      _appendHistory(cwd, entry, userMessage);
+      return entry;
+    } catch (err) {
+      const entry = {
+        taskId,
+        status: "failed",
+        templateId: template.id,
+        templateName: template.name,
+        ...(mcpRuntime.sessionId ? { mcpSessionId: mcpRuntime.sessionId } : {}),
+        result: {
+          summary: `Task failed: ${err.message}`,
+          artifacts: [],
+          tokenCount: 0,
+          toolsUsed: [],
+          iterationCount: 0,
+        },
+      };
+      _appendHistory(cwd, entry, userMessage);
+      return entry;
+    }
   } finally {
     await mcp.cleanup();
   }