chainlesschain 0.166.46 → 0.166.48

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(),
+  );
 }
 
 /**

package/src/lib/app-server/cli-agent-kernel-adapter.js

@@ -2,6 +2,7 @@ import { PassThrough } from "node:stream";
 import { randomUUID } from "node:crypto";
 import {
   assertSandboxAvailable,
+  assertSandboxCapabilities,
   normalizeAgentSandboxMode,
 } from "../agent-sandbox.js";
 
@@ -127,6 +128,7 @@ export class CliAgentKernelAdapter {
         },
       },
     );
+    assertSandboxCapabilities(sandbox);
     assertSandboxAvailable(sandbox);
 
     const input = new PassThrough();
@@ -166,6 +168,26 @@ export class CliAgentKernelAdapter {
             binding: event.binding,
           });
         }
+        if (event.type === "question_request") {
+          const answerQuestion = async () => {
+            let answer = null;
+            try {
+              answer = await current.requestQuestion(event);
+            } catch {
+              // A missing/rejecting host is cancellation, never implicit consent.
+            }
+            writeLine(input, {
+              type: "answer",
+              id: event.id,
+              answer,
+              binding: event.binding,
+            });
+          };
+          // The Headless runtime owns blocking semantics and its timeout. Keep
+          // the transport event chain free so a timed-out question can emit
+          // question_resolved/result even while a slow host request is pending.
+          void answerQuestion().catch(() => {});
+        }
         if (event.type === "result") {
           session.current = null;
           current.resolve(event);
@@ -194,6 +216,7 @@ export class CliAgentKernelAdapter {
         permissionMode,
         sandbox,
         interactiveApprovals: true,
+        interactiveQuestions: turnOptions.interactiveQuestions === true,
         includePartialMessages: true,
         ephemeral: false,
         evolutionIngress:
@@ -263,6 +286,7 @@ export class CliAgentKernelAdapter {
     options = {},
     emit,
     requestApproval,
+    requestQuestion,
   }) {
     const session = await this._session(threadId, options);
     if (session.current) {
@@ -283,6 +307,10 @@ export class CliAgentKernelAdapter {
         turnId,
         emit,
         requestApproval,
+        requestQuestion:
+          typeof requestQuestion === "function"
+            ? requestQuestion
+            : async () => null,
         resolve,
         reject,
       };

package/src/lib/app-server/server.js

@@ -10,6 +10,7 @@ import { AppServerGraphRuntime } from "./graph-runtime.js";
 import { captureAgentSkillOutcomeIndex } from "../evolution/agent-evolution-runtime-composition-brand.js";
 import { captureSkillVectorAuthority } from "../skill-vector-authority.js";
 import { captureSkillRetrievalRevocationReader } from "../evolution/skill-retrieval-revocation-authority.js";
+import { sameInteractionBinding } from "../interaction-binding.js";
 import { compileGraphDefinition } from "../graph-kernel/compiler.js";
 import { createCliContextMemoryRuntime } from "../context-memory-kernel/runtime.js";
 import { isEvolutionWorkbenchCliHost } from "../evolution/evolution-workbench-cli-host.js";
@@ -882,6 +883,10 @@ export class CcAppServer {
         turnOptions.skillRetrievalRevocationReader =
           skillRetrievalRevocationReader;
       }
+      if (this.negotiated) {
+        turnOptions.interactiveQuestions =
+          this.negotiated.features.includes("deferred_questions");
+      }
       const result = await this.kernel.startTurn({
         threadId,
         turnId: attempt.id,
@@ -896,6 +901,7 @@ export class CcAppServer {
             event,
           }),
         requestApproval: (event) => this._requestApproval(turn, event),
+        requestQuestion: (event) => this._requestQuestion(turn, event),
       });
       const failed = result?.is_error === true || result?.subtype === "error";
       const output = typeof result?.result === "string" ? result.result : "";
@@ -1137,6 +1143,8 @@ export class CcAppServer {
         turnOptions.skillRetrievalRevocationReader =
           this.skillRetrievalRevocationReader;
       }
+      turnOptions.interactiveQuestions =
+        this.negotiated?.features.includes("deferred_questions") === true;
       const result = await this.kernel.startTurn({
         threadId: turn.threadId,
         turnId: turn.id,
@@ -1144,6 +1152,7 @@ export class CcAppServer {
         options: turnOptions,
         emit: (event) => this._emitKernelEvent(turn, event),
         requestApproval: (event) => this._requestApproval(turn, event),
+        requestQuestion: (event) => this._requestQuestion(turn, event),
       });
       if (turn.interruptRequested) {
         await this._completeTurn(turn, "interrupted", result);
@@ -1321,6 +1330,48 @@ export class CcAppServer {
       );
       return;
     }
+    if (event?.type === "question_request") {
+      if (!this.negotiated?.features.includes("deferred_questions")) return;
+      const blocking = event.blocking !== false && event.mode !== "deferred";
+      if (blocking) turn.status = "waiting_input";
+      turn.revision += 1;
+      await this._notify(
+        "question/requested",
+        { request: this._questionRequest(turn, event) },
+        {
+          threadId: turn.threadId,
+          turnId: turn.id,
+          itemId: `${turn.id}:question:${safeId(event.id, "question")}`,
+          traceId,
+          idempotencyKey: `question-requested:${turn.id}:${event.id}`,
+        },
+      );
+      return;
+    }
+    if (event?.type === "question_resolved") {
+      if (!this.negotiated?.features.includes("deferred_questions")) return;
+      if (event.blocking !== false && event.mode !== "deferred") {
+        turn.status = "running";
+      }
+      turn.revision += 1;
+      await this._notify(
+        "question/resolved",
+        {
+          threadId: turn.threadId,
+          turnId: turn.id,
+          questionId: safeId(event.id, `${turn.id}:question`),
+          mode: event.mode === "deferred" ? "deferred" : "blocking",
+          via: event.via || "unknown",
+        },
+        {
+          threadId: turn.threadId,
+          turnId: turn.id,
+          traceId,
+          idempotencyKey: `question-resolved:${turn.id}:${event.id}:${event.via}`,
+        },
+      );
+      return;
+    }
     if (event?.type === "plan_update") {
       await this._notify(
         "item/completed",
@@ -1394,6 +1445,48 @@ export class CcAppServer {
     return result;
   }
 
+  _questionRequest(turn, event) {
+    const id = safeId(event.id, `${turn.id}:question`);
+    return {
+      id,
+      threadId: turn.threadId,
+      turnId: turn.id,
+      binding: event.binding || null,
+      question: String(event.question || "").slice(0, 16_384),
+      options: Array.isArray(event.options)
+        ? event.options.slice(0, 128)
+        : null,
+      multiSelect: event.multiSelect === true,
+      mode: event.mode === "deferred" ? "deferred" : "blocking",
+      blocking: event.blocking !== false && event.mode !== "deferred",
+      purpose: event.purpose || "decision",
+      contextRevision: Number.isSafeInteger(event.context_revision)
+        ? event.context_revision
+        : null,
+      expiresAt: new Date(this.now() + this.requestTimeoutMs).toISOString(),
+    };
+  }
+
+  async _requestQuestion(turn, event) {
+    if (!this.negotiated?.features.includes("deferred_questions")) return null;
+    const request = this._questionRequest(turn, event);
+    const result = requireObject(
+      await this._requestClient("question/answer", { request }),
+      "question answer",
+    );
+    if (
+      result.questionId !== request.id ||
+      !request.binding ||
+      !sameInteractionBinding(request.binding, result.binding)
+    ) {
+      throw new JsonRpcError(
+        JSON_RPC_ERROR.INVALID_PARAMS,
+        "client returned an invalid or stale question answer",
+      );
+    }
+    return Object.hasOwn(result, "answer") ? result.answer : null;
+  }
+
   async _requestHumanTask({ task }) {
     const result = await this._requestClient("humanTask/decide", { task });
     const response = requireObject(result, "humanTask decision");

package/src/lib/background-agent-keeper-client.js

@@ -4,6 +4,7 @@ import { createNdjsonReader } from "./background-session-transport.js";
 import {
   BACKGROUND_AGENT_KEEPER_ARM,
   BACKGROUND_AGENT_KEEPER_ARMED,
+  BACKGROUND_AGENT_KEEPER_ARM_TIMEOUT_MS,
   BACKGROUND_AGENT_KEEPER_HELLO,
   BACKGROUND_AGENT_KEEPER_HEARTBEAT,
   BACKGROUND_AGENT_KEEPER_HEARTBEAT_INTERVAL_MS,
@@ -244,6 +245,7 @@ export async function connectBackgroundAgentKeeper(options = {}) {
         BACKGROUND_AGENT_KEEPER_ARM,
         BACKGROUND_AGENT_KEEPER_ARMED,
         normalized,
+        BACKGROUND_AGENT_KEEPER_ARM_TIMEOUT_MS,
       );
       activeTurn = normalized;
       return normalized;

package/src/lib/background-agent-keeper-protocol.js

@@ -50,6 +50,13 @@ export const BACKGROUND_AGENT_KEEPER_IDENTITY_PROBE_TIMEOUT_MS =
 export const BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS = 5_000;
 export const BACKGROUND_AGENT_KEEPER_PERSIST_RETRY_TIMEOUT_MS =
   3 * BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS;
+// ARM durably binds a newly spawned turn. It can contend with a strict state
+// lock and, on Windows, an incumbent identity probe. Keep this deadline
+// independent from short HELLO requests and long destructive RETIRE cleanup.
+export const BACKGROUND_AGENT_KEEPER_ARM_TIMEOUT_MS =
+  BACKGROUND_AGENT_KEEPER_IDENTITY_PROBE_TIMEOUT_MS +
+  BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS +
+  10_000;
 // A 20-Agent macOS formal run can leave successfully SIGKILLed process groups
 // observable for several seconds while launchd reaps their orphaned leaders.
 // Two seconds made that bounded kernel/reaper delay look like an escaped tree.