chainlesschain 0.164.0 → 0.165.2

package/src/lib/background-session-transport.js

@@ -25,15 +25,18 @@
 
 import net from "node:net";
 import { unlinkSync } from "node:fs";
-import { join } from "node:path";
+import {
+  backgroundAgentSessionPipePath,
+  cleanupBackgroundAgentLocalPipeDirectory,
+  prepareBackgroundAgentLocalPipePath,
+} from "./background-agent-keeper-protocol.js";
 
 const HELLO_TIMEOUT_MS = 5000;
 const MAX_LINE_BYTES = 1024 * 1024;
 
 /** Pipe endpoint for a session id (Windows named pipe / POSIX socket file). */
-export function transportPipePath(id, dir) {
-  if (process.platform === "win32") return `\\\\.\\pipe\\cc-bg-${id}`;
-  return join(dir, `${id}.sock`);
+export function transportPipePath(id, dir, options = {}) {
+  return backgroundAgentSessionPipePath(id, dir, options);
 }
 
 /**
@@ -106,6 +109,7 @@ export function startBackgroundSessionServer(opts) {
     getStatus,
   } = opts;
   const pipePath = opts.pipePath || transportPipePath(id, dir);
+  prepareBackgroundAgentLocalPipePath(pipePath);
   if (process.platform !== "win32") {
     try {
       unlinkSync(pipePath); // stale socket from a crashed prior worker
@@ -259,9 +263,17 @@ export function startBackgroundSessionServer(opts) {
   });
 
   return new Promise((resolve, reject) => {
-    server.once("error", reject);
+    const rejectListen = (error) => {
+      try {
+        cleanupBackgroundAgentLocalPipeDirectory(pipePath);
+      } catch {
+        /* preserve the original listen error */
+      }
+      reject(error);
+    };
+    server.once("error", rejectListen);
     server.listen(pipePath, () => {
-      server.removeListener("error", reject);
+      server.removeListener("error", rejectListen);
       server.on("error", () => {
         /* post-listen errors must not crash the worker */
       });
@@ -299,6 +311,11 @@ export function startBackgroundSessionServer(opts) {
                 } catch {
                   /* already gone */
                 }
+                try {
+                  cleanupBackgroundAgentLocalPipeDirectory(pipePath);
+                } catch {
+                  /* best-effort cleanup after the server has closed */
+                }
               }
               done();
             });

package/src/lib/background-turn-bootstrap-protocol.js

@@ -124,3 +124,67 @@ export function clearBackgroundTurnBootstrapEnvironment(environment) {
     delete environment[key];
   }
 }
+
+/**
+ * Freeze a released POSIX turn in its detached process group when its worker
+ * disappears. The worker's detached-spawn contract makes the positive current
+ * PID the group ID; using its negative form fails with ESRCH if that invariant
+ * is ever broken instead of stopping an unrelated worker/runner group.
+ *
+ * Register the SIGCONT fail-safe before SIGSTOP because Node's process.kill()
+ * can return to JavaScript before the stop is delivered. If the group is ever
+ * resumed, immediately SIGKILL it instead of letting the Agent or one of its
+ * descendants continue without supervision.
+ */
+export function containReleasedBackgroundTurnDisconnect(options = {}) {
+  const released = options.released === true;
+  const platform = options.platform || process.platform;
+  const currentPid = Number(options.currentPid ?? process.pid);
+  const signalProcessGroup =
+    options.signalProcessGroup || process.kill.bind(process);
+  const resumeSignalTarget = options.resumeSignalTarget || process;
+  const onResumedKillFailure =
+    options.onResumedKillFailure || (() => process.exit(1));
+  if (
+    !released ||
+    platform === "win32" ||
+    !Number.isSafeInteger(currentPid) ||
+    currentPid <= 0
+  ) {
+    return false;
+  }
+  const groupPid = -currentPid;
+  const killAfterResume = () => {
+    try {
+      signalProcessGroup(groupPid, "SIGKILL");
+    } catch {
+      onResumedKillFailure();
+    }
+  };
+  try {
+    resumeSignalTarget.once("SIGCONT", killAfterResume);
+  } catch {
+    try {
+      signalProcessGroup(groupPid, "SIGKILL");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  try {
+    signalProcessGroup(groupPid, "SIGSTOP");
+    return true;
+  } catch {
+    try {
+      resumeSignalTarget.removeListener("SIGCONT", killAfterResume);
+    } catch {
+      // The same group SIGKILL below remains the containment fallback.
+    }
+    try {
+      signalProcessGroup(groupPid, "SIGKILL");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

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

@@ -58,6 +58,7 @@ export const _deps = {
 
 const DEFAULT_MAX_ITERATIONS = 50;
 const DEFAULT_TOKEN_BUDGET = 100_000;
+const WORKFLOW_EFFECT_ID_RE = /^sha256:[a-f0-9]{64}$/;
 const COWORK_MCP_CALL_LEDGER_UNSUPPORTED =
   "CC_COWORK_MCP_CALL_LEDGER_UNSUPPORTED";
 const COWORK_MCP_SESSION_UNVERIFIED = "CC_COWORK_MCP_SESSION_UNVERIFIED";
@@ -74,6 +75,44 @@ function coworkMcpAdmissionError(code, message, sessionId, cause = null) {
   return error;
 }
 
+function assertWorkflowEffectId(value) {
+  if (value == null) return;
+  if (typeof value !== "string" || !WORKFLOW_EFFECT_ID_RE.test(value)) {
+    const error = new TypeError(
+      "workflowEffectId must be a canonical sha256 identity",
+    );
+    error.code = "CC_COWORK_WORKFLOW_EFFECT_ID_INVALID";
+    throw error;
+  }
+}
+
+function workflowEffectEvidence(subAgent, workflowEffectId) {
+  if (!workflowEffectId) return {};
+  const attempts =
+    typeof subAgent?.providerRequestAttempts === "function"
+      ? subAgent.providerRequestAttempts()
+      : [];
+  const receipts =
+    typeof subAgent?.providerRequestReceipts === "function"
+      ? subAgent.providerRequestReceipts()
+      : [];
+  const nestedEffectAttempts =
+    typeof subAgent?.nestedEffectAttempts === "function"
+      ? subAgent.nestedEffectAttempts()
+      : [];
+  const nestedEffectSettlements =
+    typeof subAgent?.nestedEffectSettlements === "function"
+      ? subAgent.nestedEffectSettlements()
+      : [];
+  return {
+    workflowEffectId,
+    providerRequestAttempts: attempts,
+    providerRequestReceipts: receipts,
+    nestedEffectAttempts,
+    nestedEffectSettlements,
+  };
+}
+
 function assertCoworkMcpEventUsageAdmission(event, sessionId) {
   if (event?.type !== "session_start") return;
   const data =
@@ -477,6 +516,12 @@ export function prepareCoworkMcpRuntime(mcp, options = {}) {
  * @param {number} [options.maxIterations] - Override iteration limit
  * @param {number} [options.tokenBudget] - Override token budget
  * @param {string} [options.mcpSessionId] - Stable MCP ledger session for resume
+ * @param {string} [options.workflowEffectId] - Canonical durable workflow effect
+ * @param {boolean} [options.strictUsageTelemetry] - Require synchronous durable call observers
+ * @param {function} [options.onUsageBoundary] - Provider-call durable start observer
+ * @param {function} [options.onUsageSettlement] - Provider-call durable settlement observer
+ * @param {function} [options.onToolCallBoundary] - Tool-call durable start observer
+ * @param {function} [options.onToolCallSettlement] - Tool-call durable settlement observer
  * @param {(request: object) => boolean|Promise<boolean>} [options.approveMcpLocalCodeExecution]
  * @returns {Promise<{ taskId: string, status: string, result: object }>}
  */
@@ -493,12 +538,19 @@ export async function runCoworkTask(options = {}) {
     onProgress = null,
     signal = null,
     mcpSessionId = null,
+    workflowEffectId = null,
+    strictUsageTelemetry = false,
+    onUsageBoundary = null,
+    onUsageSettlement = null,
+    onToolCallBoundary = null,
+    onToolCallSettlement = null,
     approveMcpLocalCodeExecution = null,
   } = options;
 
   if (!userMessage || typeof userMessage !== "string") {
     throw new Error("userMessage is required");
   }
+  assertWorkflowEffectId(workflowEffectId);
 
   // An explicit canonical authority must be admitted before mounting local MCP
   // servers, constructing a child context, or making any provider call.
@@ -582,6 +634,16 @@ export async function runCoworkTask(options = {}) {
       cwd,
       onProgress,
       signal,
+      ...(workflowEffectId ? { workflowEffectId } : {}),
+      ...(strictUsageTelemetry
+        ? {
+            strictUsageTelemetry: true,
+            onUsageBoundary,
+            onUsageSettlement,
+            onToolCallBoundary,
+            onToolCallSettlement,
+          }
+        : {}),
       extraToolDefinitions: mcp.extraToolDefinitions,
       externalToolDescriptors: mcp.externalToolDescriptors,
       externalToolExecutors: mcp.externalToolExecutors,
@@ -632,17 +694,25 @@ export async function runCoworkTask(options = {}) {
         templateId: template.id,
         templateName: template.name,
         ...(mcpRuntime.sessionId ? { mcpSessionId: mcpRuntime.sessionId } : {}),
+        ...workflowEffectEvidence(subAgent, workflowEffectId),
         result,
       };
       _appendHistory(cwd, entry, userMessage);
       return entry;
     } catch (err) {
+      // A durable workflow already marked this outer effect as dispatched.
+      // Converting a child/provider exception into an ordinary failed result
+      // would authorize the step retry path even though the physical provider
+      // outcome may be unknown. Propagate so the runtime keeps it pending and
+      // requires reconciliation.
+      if (workflowEffectId) throw err;
       const entry = {
         taskId,
         status: "failed",
         templateId: template.id,
         templateName: template.name,
         ...(mcpRuntime.sessionId ? { mcpSessionId: mcpRuntime.sessionId } : {}),
+        ...workflowEffectEvidence(subAgent, workflowEffectId),
         result: {
           summary: `Task failed: ${err.message}`,
           artifacts: [],