chainlesschain 0.166.46 → 0.166.47

package/src/gateways/ws/ws-session-state.js

@@ -16,6 +16,7 @@ export const DEFAULT_WS_SESSION_STATE_MAX_EVENTS = 64;
 
 const RUN_STATUSES = new Set(["idle", "running", "interrupted"]);
 const APPROVAL_STATUSES = new Set(["pending", "interrupted"]);
+const MAX_DEFERRED_QUESTIONS = 32;
 
 function own(object, key) {
   return Object.prototype.hasOwnProperty.call(object || {}, key);
@@ -112,12 +113,87 @@ function normalizeRun(value) {
   };
 }
 
+function normalizeDeferredRecord(value, resolved = false) {
+  if (!value || typeof value !== "object") return null;
+  const requestId =
+    typeof value.requestId === "string" && value.requestId.length > 0
+      ? value.requestId
+      : null;
+  if (!requestId || !value.binding || typeof value.binding !== "object") {
+    return null;
+  }
+  const binding = cloneJson(value.binding);
+  if (
+    binding.sessionId == null ||
+    !Number.isSafeInteger(binding.sequence) ||
+    binding.sequence <= 0
+  ) {
+    return null;
+  }
+  let answer = "";
+  if (resolved) {
+    if (typeof value.answer === "string") answer = value.answer;
+    else {
+      try {
+        answer = JSON.stringify(value.answer);
+      } catch {
+        answer = String(value.answer ?? "");
+      }
+    }
+    if (typeof answer !== "string") answer = String(value.answer ?? "");
+    answer = answer.slice(0, 16384);
+  }
+  return {
+    requestId,
+    question:
+      typeof value.question === "string" ? value.question.slice(0, 2048) : "",
+    binding,
+    requestedRevision: nonNegativeRevision(
+      value.requestedRevision ?? value.contextRevision,
+    ),
+    ...(resolved
+      ? {
+          answer,
+          resolvedRevision: nonNegativeRevision(value.resolvedRevision),
+        }
+      : {
+          options: Array.isArray(value.options)
+            ? cloneJson(value.options.slice(0, 32), [])
+            : null,
+          multiSelect: value.multiSelect === true,
+          purpose:
+            value.purpose === "preference" ? "preference" : "information",
+          contextRevision: nonNegativeRevision(value.contextRevision),
+        }),
+  };
+}
+
+function upsertBounded(list, record) {
+  if (!record) return list;
+  const next = list.filter((item) => item.requestId !== record.requestId);
+  next.push(record);
+  return next.slice(-MAX_DEFERRED_QUESTIONS);
+}
+
 function normalizeSnapshot(value = {}, options = {}) {
   const source = value && typeof value === "object" ? value : {};
   const snapshot = {
     revision: nonNegativeRevision(source.revision),
     todo: normalizeTodoSnapshot(source.todo),
     pendingApproval: normalizePendingApproval(source.pendingApproval),
+    contextRevision: nonNegativeRevision(source.contextRevision),
+    deferredQuestions: Array.isArray(source.deferredQuestions)
+      ? source.deferredQuestions
+          .map((value) => normalizeDeferredRecord(value, false))
+          .filter(Boolean)
+          .slice(-MAX_DEFERRED_QUESTIONS)
+      : [],
+    deferredAnswers: Array.isArray(source.deferredAnswers)
+      ? source.deferredAnswers
+          .map((value) => normalizeDeferredRecord(value, true))
+          .filter(Boolean)
+          .slice(-MAX_DEFERRED_QUESTIONS)
+      : [],
     run: normalizeRun(source.run),
   };
 
@@ -183,6 +259,58 @@ function applyEvent(snapshot, event) {
       }
       break;
 
+    case "question.context.revision":
+      next.contextRevision = Math.max(
+        next.contextRevision,
+        nonNegativeRevision(payload.contextRevision),
+      );
+      break;
+
+    case "question.deferred.requested": {
+      const question = normalizeDeferredRecord(payload, false);
+      if (
+        question &&
+        question.binding.sessionId === payload.binding?.sessionId
+      ) {
+        next.deferredQuestions = upsertBounded(
+          next.deferredQuestions,
+          question,
+        );
+      }
+      break;
+    }
+
+    case "question.deferred.resolved": {
+      const answer = normalizeDeferredRecord(payload, true);
+      if (answer) {
+        const pending = next.deferredQuestions.find(
+          (item) => item.requestId === answer.requestId,
+        );
+        if (
+          pending &&
+          JSON.stringify(pending.binding) === JSON.stringify(answer.binding)
+        ) {
+          next.deferredQuestions = next.deferredQuestions.filter(
+            (item) => item.requestId !== answer.requestId,
+          );
+          next.deferredAnswers = upsertBounded(next.deferredAnswers, answer);
+        }
+      }
+      break;
+    }
+
+    case "question.deferred.consumed": {
+      const ids = new Set(
+        Array.isArray(payload.questionIds)
+          ? payload.questionIds.filter((id) => typeof id === "string")
+          : [],
+      );
+      next.deferredAnswers = next.deferredAnswers.filter(
+        (item) => !ids.has(item.requestId),
+      );
+      break;
+    }
+
     case "run.started":
       next.run = normalizeRun({
         status: "running",
@@ -302,6 +430,9 @@ export function createWsSessionState(options = {}) {
         revision: 0,
         todo: normalizeTodoSnapshot(options.todo),
         pendingApproval: null,
+        contextRevision: 0,
+        deferredQuestions: [],
+        deferredAnswers: [],
         run: normalizeRun(),
         ...(hasPlanSnapshot
           ? { planSnapshot: cloneJson(options.planSnapshot) }

package/src/generated/cc-agent-protocol.schema.json

@@ -18,6 +18,7 @@
       "agent_stream_events",
       "agent_stream_payloads",
       "unified_policy_decision",
+      "deferred_questions",
       "context_memory_kernel"
     ],
     "contextMemory": {
@@ -3832,6 +3833,7 @@
         "method": {
           "enum": [
             "approval/decide",
+            "question/answer",
             "humanTask/decide"
           ]
         },
@@ -3862,6 +3864,8 @@
             "item/completed",
             "approval/requested",
             "approval/resolved",
+            "question/requested",
+            "question/resolved",
             "tool/requested",
             "tool/result",
             "subagent/started",

package/src/lazy-dispatch.js

@@ -814,7 +814,14 @@ export function isFastReadOnlyInvocation(argv, env = process.env) {
     commandLocation?.token === "session" &&
     argv[commandLocation.index + 1] === "show" &&
     !explicitOtlp;
-  return quickStatus || sessionShow;
+  // Capability inspection is a deliberately static, read-only diagnostic.
+  // Keep it ahead of observability initialization even when an OTLP endpoint
+  // is configured; otherwise merely inspecting a profile creates a queue and
+  // contradicts the command's no-network/no-write contract.
+  const llmCapabilities =
+    commandLocation?.token === "llm" &&
+    argv[commandLocation.index + 1] === "capabilities";
+  return quickStatus || sessionShow || llmCapabilities;
 }
 
 let processHandlersInstalled = false;

package/src/lib/agent-sandbox.js

@@ -1,5 +1,6 @@
 /** OS-isolated shell execution for the coding agent. */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { proxyEnv } from "./sandbox-egress-proxy.js";
 import executionBroker from "./process-execution-broker/index.js";
@@ -10,8 +11,15 @@ export const AGENT_SANDBOX_MODES = Object.freeze([
   "workspace-write",
   "strict",
 ]);
+export const AGENT_SANDBOX_CAPABILITY_SCHEMA =
+  "chainlesschain.agent-sandbox-capabilities/v1";
 export const _deps = {
   spawnSync: (...args) => executionBroker.spawnSync(...args),
+  host: () => ({
+    platform: process.platform,
+    release: os.release(),
+    arch: process.arch,
+  }),
 };
 
 function stringList(value) {
@@ -322,46 +330,298 @@ export function enforceSandboxFailClosed(sandbox, reason = "safe") {
   };
 }
 
+function capability(id, details = {}) {
+  return { id, ...details };
+}
+
+function addUniqueCapability(target, entry) {
+  if (!target.some((candidate) => candidate.id === entry.id)) {
+    target.push(entry);
+  }
+}
+
+/**
+ * Describe the exact legacy agent-shell sandbox request without claiming that
+ * a command has run. `enforceable` is backend capability; `applied` is only
+ * populated after a child was successfully started through that backend.
+ */
+export function assessAgentSandboxCapabilities(sandbox, options = {}) {
+  const host = options.host || {
+    platform: process.platform,
+    release: os.release(),
+    arch: process.arch,
+  };
+  const execution = options.execution || null;
+  const availability = options.availability || null;
+  const requested = [];
+  const enforceable = [];
+  const unsupported = [];
+
+  if (!sandbox) {
+    return {
+      schema: AGENT_SANDBOX_CAPABILITY_SCHEMA,
+      host: {
+        platform: String(host.platform),
+        release: String(host.release),
+        arch: String(host.arch),
+      },
+      backend: {
+        engine: null,
+        isolationLevel: "policy-only",
+        availabilityChecked: false,
+        available: null,
+        reason: null,
+      },
+      status: "disabled",
+      execution: {
+        observed: false,
+        attempted: false,
+        started: false,
+      },
+      requested,
+      enforceable,
+      applied: [],
+      unsupported,
+    };
+  }
+
+  const engine = String(sandbox.engine || "");
+  const policy = sandbox.policy || normalizeSandboxPolicy({}, sandbox.cwd);
+  const supportedEngine = engine === "docker" || engine === "bubblewrap";
+  const supportedPlatform =
+    engine !== "bubblewrap" || host.platform === "linux";
+  const isolationCapability =
+    engine === "docker"
+      ? "isolation.container"
+      : engine === "bubblewrap"
+        ? "isolation.linux-namespace"
+        : "isolation.unknown";
+  const networkCapability = sandbox.network
+    ? "network.unrestricted"
+    : "network.none";
+
+  addUniqueCapability(requested, capability(isolationCapability));
+  addUniqueCapability(requested, capability("filesystem.workspace-read-write"));
+  addUniqueCapability(requested, capability(networkCapability));
+
+  const filesystemRequests = [
+    ["filesystem.additional-read", policy.allowRead],
+    ["filesystem.deny-read", policy.denyRead],
+    ["filesystem.additional-write", policy.allowWrite],
+    ["filesystem.deny-write", policy.denyWrite],
+  ];
+  for (const [id, values] of filesystemRequests) {
+    if (values?.length) {
+      addUniqueCapability(
+        requested,
+        capability(id, { entries: values.length }),
+      );
+    }
+  }
+  const domainRuleCount =
+    (policy.allowedDomains?.length || 0) + (policy.deniedDomains?.length || 0);
+  if (domainRuleCount > 0) {
+    addUniqueCapability(
+      requested,
+      capability("network.domain-policy", { entries: domainRuleCount }),
+    );
+  }
+
+  if (!supportedEngine) {
+    unsupported.push(
+      capability("backend.engine", {
+        reason: "unsupported_engine",
+        message: `Unsupported agent sandbox engine: ${engine || "<empty>"}`,
+        remediation: "Use engine=docker or engine=bubblewrap.",
+      }),
+    );
+  } else if (!supportedPlatform) {
+    unsupported.push(
+      capability("backend.platform", {
+        reason: "bubblewrap_requires_linux",
+        message: `bubblewrap is only supported on Linux; host platform is ${host.platform}`,
+        remediation: "Use Docker on this host or run bubblewrap on Linux.",
+      }),
+    );
+  } else {
+    addUniqueCapability(
+      enforceable,
+      capability(isolationCapability, {
+        enforcement:
+          engine === "docker" ? "docker-container" : "bubblewrap-namespaces",
+      }),
+    );
+    addUniqueCapability(
+      enforceable,
+      capability("filesystem.workspace-read-write", {
+        enforcement:
+          engine === "docker" ? "docker-bind-mount" : "bubblewrap-bind-mount",
+      }),
+    );
+    addUniqueCapability(
+      enforceable,
+      capability(networkCapability, {
+        enforcement:
+          engine === "docker"
+            ? sandbox.network
+              ? "docker-default-network"
+              : "docker-network-none"
+            : sandbox.network
+              ? "bubblewrap-share-net"
+              : "bubblewrap-unshared-network-namespace",
+      }),
+    );
+
+    for (const [id, values] of filesystemRequests) {
+      if (!values?.length) continue;
+      if (engine === "docker") {
+        unsupported.push(
+          capability(id, {
+            reason: "docker_fine_grained_filesystem_unsupported",
+            message:
+              "The Docker sandbox backend cannot enforce fine-grained filesystem policy; use engine=bubblewrap",
+            remediation:
+              "Use engine=bubblewrap on Linux or remove the fine-grained rule.",
+          }),
+        );
+      } else if (id === "filesystem.additional-read") {
+        unsupported.push(
+          capability(id, {
+            reason: "bubblewrap_additional_read_not_isolated",
+            message:
+              "The bubblewrap agent-shell backend exposes the host root read-only and cannot make allowRead an exclusive read boundary",
+            remediation:
+              "Remove allowRead or use the attested ProcessExecutionBroker sandbox for a supported execution contract.",
+          }),
+        );
+      } else {
+        addUniqueCapability(
+          enforceable,
+          capability(id, {
+            entries: values.length,
+            enforcement: `bubblewrap-${id.replace("filesystem.", "")}-mount`,
+          }),
+        );
+      }
+    }
+
+    if (domainRuleCount > 0) {
+      unsupported.push(
+        capability("network.domain-policy", {
+          reason: "domain_policy_has_no_non_bypassable_backend",
+          message:
+            "Domain-restricted sandbox networking has no non-bypassable backend enforcement; refusing unrestricted network access",
+          remediation:
+            "Disable sandbox networking or use a separately attested dependency-fetch service.",
+        }),
+      );
+    }
+  }
+
+  const executionObserved = execution !== null;
+  const executionAttempted = execution?.attempted === true;
+  const executionStarted = execution?.started === true;
+  const availabilityChecked = availability !== null || executionStarted;
+  const available = executionStarted
+    ? true
+    : availability === null
+      ? null
+      : availability.available === true;
+  const availabilityReason = executionStarted
+    ? null
+    : availability?.reason || null;
+  let status = "ready";
+  if (unsupported.length > 0) status = "unsupported";
+  else if (executionStarted) status = "applied";
+  else if (executionAttempted) status = "failed-to-start";
+  else if (availabilityChecked && !available) status = "unavailable";
+
+  return {
+    schema: AGENT_SANDBOX_CAPABILITY_SCHEMA,
+    host: {
+      platform: String(host.platform),
+      release: String(host.release),
+      arch: String(host.arch),
+    },
+    backend: {
+      engine,
+      isolationLevel: isolationLevel(sandbox),
+      availabilityChecked,
+      available,
+      reason: availabilityReason,
+    },
+    status,
+    execution: {
+      observed: executionObserved,
+      attempted: executionAttempted,
+      started: executionStarted,
+    },
+    requested,
+    enforceable,
+    applied: executionStarted ? enforceable.map((entry) => ({ ...entry })) : [],
+    unsupported,
+  };
+}
+
+export function assertSandboxCapabilities(sandbox, options = {}) {
+  const report = assessAgentSandboxCapabilities(sandbox, options);
+  if (report.unsupported.length === 0) return report;
+  const error = new Error(
+    `Unsupported sandbox capability request: ${report.unsupported
+      .map((entry) => `${entry.id} (${entry.message})`)
+      .join("; ")}`,
+  );
+  error.code = "CONFIG_SANDBOX_CAPABILITY_UNSUPPORTED";
+  error.capabilityReport = report;
+  throw error;
+}
+
+function attachSandboxCapabilityReport(
+  result,
+  sandbox,
+  execution,
+  availability,
+  host,
+) {
+  return {
+    ...result,
+    sandboxCapabilities: assessAgentSandboxCapabilities(sandbox, {
+      execution,
+      availability,
+      host,
+    }),
+  };
+}
+
 export function executeSandboxedShell(command, sandbox, options = {}) {
   if (!sandbox || !["docker", "bubblewrap"].includes(sandbox.engine)) {
     throw new Error("A supported agent sandbox configuration is required");
   }
   const hostCwd = path.resolve(options.cwd || sandbox.cwd);
   const policy = sandbox.policy || normalizeSandboxPolicy({}, hostCwd);
-  // Proxy environment variables are advisory: a child can clear them or open a
-  // raw socket. Until a backend can enforce egress below the process layer,
-  // domain-restricted networking must fail closed instead of granting the
-  // sandbox an unrestricted network namespace.
-  const egress = options.egressProxy || null;
-  if (
-    (policy.allowedDomains.length || policy.deniedDomains.length) &&
-    sandbox.network
-  ) {
+  const capabilityHost = _deps.host();
+  const capabilityReport = assessAgentSandboxCapabilities(sandbox, {
+    host: capabilityHost,
+  });
+  if (capabilityReport.unsupported.length > 0) {
     return {
       stdout: "",
-      stderr:
-        "Domain-restricted sandbox networking has no non-bypassable backend enforcement; refusing unrestricted network access",
+      stderr: capabilityReport.unsupported
+        .map((entry) => entry.message)
+        .join("; "),
       exitCode: 1,
       failedToStart: true,
+      sandboxCapabilities: capabilityReport,
     };
   }
+  // Proxy environment variables are advisory: a child can clear them or open a
+  // raw socket. Until a backend can enforce egress below the process layer,
+  // domain-restricted networking must fail closed instead of granting the
+  // sandbox an unrestricted network namespace.
+  const egress = options.egressProxy || null;
   if (sandbox.engine === "bubblewrap") {
     return executeBubblewrapShell(command, sandbox, options, hostCwd, policy);
   }
-  if (
-    policy.allowRead.length ||
-    policy.denyRead.length ||
-    policy.allowWrite.length ||
-    policy.denyWrite.length
-  ) {
-    return {
-      stdout: "",
-      stderr:
-        "The Docker sandbox backend cannot enforce fine-grained filesystem policy; use engine=bubblewrap",
-      exitCode: 1,
-      failedToStart: true,
-    };
-  }
   const args = ["run", "--rm", "--init"];
   if (!sandbox.network) args.push("--network", "none");
   args.push("--mount", `type=bind,source=${hostCwd},target=/workspace`);
@@ -397,22 +657,34 @@ export function executeSandboxedShell(command, sandbox, options = {}) {
     auditContext: options.auditContext,
   });
   if (result.error) {
-    return {
+    return attachSandboxCapabilityReport(
+      {
+        stdout: result.stdout || "",
+        stderr:
+          result.error.code === "ENOENT"
+            ? "Docker is not installed"
+            : result.error.message,
+        exitCode: typeof result.status === "number" ? result.status : 1,
+        failedToStart: true,
+      },
+      sandbox,
+      { attempted: true, started: false },
+      { available: false, reason: result.error.message },
+      capabilityHost,
+    );
+  }
+  return attachSandboxCapabilityReport(
+    {
       stdout: result.stdout || "",
-      stderr:
-        result.error.code === "ENOENT"
-          ? "Docker is not installed"
-          : result.error.message,
+      stderr: result.stderr || "",
       exitCode: typeof result.status === "number" ? result.status : 1,
-      failedToStart: true,
-    };
-  }
-  return {
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-    exitCode: typeof result.status === "number" ? result.status : 1,
-    signal: result.signal || null,
-  };
+      signal: result.signal || null,
+    },
+    sandbox,
+    { attempted: true, started: true },
+    { available: true, reason: null },
+    capabilityHost,
+  );
 }
 
 function executeBubblewrapShell(command, sandbox, options, hostCwd, policy) {
@@ -469,22 +741,34 @@ function executeBubblewrapShell(command, sandbox, options, hostCwd, policy) {
     auditContext: options.auditContext,
   });
   if (result.error) {
-    return {
+    return attachSandboxCapabilityReport(
+      {
+        stdout: result.stdout || "",
+        stderr:
+          result.error.code === "ENOENT"
+            ? "bubblewrap is not installed"
+            : result.error.message,
+        exitCode: typeof result.status === "number" ? result.status : 1,
+        failedToStart: true,
+      },
+      sandbox,
+      { attempted: true, started: false },
+      { available: false, reason: result.error.message },
+      _deps.host(),
+    );
+  }
+  return attachSandboxCapabilityReport(
+    {
       stdout: result.stdout || "",
-      stderr:
-        result.error.code === "ENOENT"
-          ? "bubblewrap is not installed"
-          : result.error.message,
+      stderr: result.stderr || "",
       exitCode: typeof result.status === "number" ? result.status : 1,
-      failedToStart: true,
-    };
-  }
-  return {
-    stdout: result.stdout || "",
-    stderr: result.stderr || "",
-    exitCode: typeof result.status === "number" ? result.status : 1,
-    signal: result.signal || null,
-  };
+      signal: result.signal || null,
+    },
+    sandbox,
+    { attempted: true, started: true },
+    { available: true, reason: null },
+    _deps.host(),
+  );
 }
 
 /**