chainlesschain 0.162.143 → 0.162.148

package/src/harness/remote-session-registry.js

@@ -0,0 +1,420 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "crypto";
+
+export const REMOTE_SESSION_PROTOCOL_VERSION = "1.0";
+export const REMOTE_SESSION_SCOPES = Object.freeze([
+  "observe",
+  "prompt",
+  "approve",
+  "interrupt",
+]);
+
+const DEFAULT_TOKEN_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
+
+function hashToken(token) {
+  return createHash("sha256").update(String(token), "utf8").digest();
+}
+
+function tokensMatch(token, digest) {
+  const candidate = hashToken(token);
+  return (
+    candidate.length === digest.length && timingSafeEqual(candidate, digest)
+  );
+}
+
+function normalizeScopes(scopes) {
+  const requested = scopes || REMOTE_SESSION_SCOPES;
+  if (!Array.isArray(requested) || requested.length === 0) {
+    throw new TypeError("Remote session scopes must be a non-empty array");
+  }
+  const unique = [...new Set(requested)];
+  for (const scope of unique) {
+    if (!REMOTE_SESSION_SCOPES.includes(scope)) {
+      throw new Error(`Unsupported remote session scope: ${scope}`);
+    }
+  }
+  return unique;
+}
+
+/**
+ * Org-level constraints an administrator can impose on Remote Sessions. Lives
+ * next to the registry (its single enforcement point) so both the direct WS
+ * join and the relay pairing path go through the same checks. Permissive by
+ * default — an unconfigured policy is a no-op.
+ */
+export class RemoteSessionPolicy {
+  constructor({
+    allowedScopes = null,
+    maxDevices = null,
+    maxSessionTtlMs = null,
+    maxTokenTtlMs = null,
+    allowRelayPairing = true,
+  } = {}) {
+    this.allowedScopes = allowedScopes ? [...new Set(allowedScopes)] : null;
+    if (this.allowedScopes) {
+      if (this.allowedScopes.length === 0) {
+        throw new Error("allowedScopes cannot be empty");
+      }
+      for (const scope of this.allowedScopes) {
+        if (!REMOTE_SESSION_SCOPES.includes(scope)) {
+          throw new Error(`Unknown scope in org policy: ${scope}`);
+        }
+      }
+    }
+    this.maxDevices =
+      maxDevices == null ? null : Math.max(0, Math.floor(maxDevices));
+    this.maxSessionTtlMs =
+      maxSessionTtlMs == null ? null : Math.max(1, Math.floor(maxSessionTtlMs));
+    this.maxTokenTtlMs =
+      maxTokenTtlMs == null ? null : Math.max(1, Math.floor(maxTokenTtlMs));
+    this.allowRelayPairing = allowRelayPairing !== false;
+  }
+
+  /**
+   * Narrow requested scopes to the org-allowed set. Throws only when the request
+   * and the allow-list are wholly disjoint (i.e. nothing could be granted).
+   */
+  applyScopes(requestedScopes) {
+    if (!this.allowedScopes) {
+      return { scopes: requestedScopes || null, narrowed: false };
+    }
+    const requested =
+      requestedScopes && requestedScopes.length
+        ? [...new Set(requestedScopes)]
+        : [...REMOTE_SESSION_SCOPES];
+    const granted = requested.filter((scope) =>
+      this.allowedScopes.includes(scope),
+    );
+    if (granted.length === 0) {
+      throw new Error("Remote session scopes are not permitted by org policy");
+    }
+    return { scopes: granted, narrowed: granted.length !== requested.length };
+  }
+
+  capSessionTtl(ttlMs) {
+    return this.maxSessionTtlMs == null
+      ? ttlMs
+      : Math.min(ttlMs, this.maxSessionTtlMs);
+  }
+
+  capTokenTtl(ttlMs) {
+    return this.maxTokenTtlMs == null
+      ? ttlMs
+      : Math.min(ttlMs, this.maxTokenTtlMs);
+  }
+
+  enforceJoin({ deviceCount, via } = {}) {
+    if (via === "relay" && !this.allowRelayPairing) {
+      throw new Error("Relay pairing is disabled by org policy");
+    }
+    if (this.maxDevices != null && deviceCount >= this.maxDevices) {
+      throw new Error("Org policy device limit reached");
+    }
+  }
+
+  describe() {
+    return {
+      allowedScopes: this.allowedScopes,
+      maxDevices: this.maxDevices,
+      maxSessionTtlMs: this.maxSessionTtlMs,
+      maxTokenTtlMs: this.maxTokenTtlMs,
+      allowRelayPairing: this.allowRelayPairing,
+    };
+  }
+
+  static fromEnv(env = {}) {
+    const options = {};
+    const scopes = env.CHAINLESSCHAIN_REMOTE_SESSION_ALLOWED_SCOPES;
+    if (scopes) {
+      options.allowedScopes = scopes
+        .split(",")
+        .map((scope) => scope.trim())
+        .filter(Boolean);
+    }
+    const num = (value) => {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    };
+    if (env.CHAINLESSCHAIN_REMOTE_SESSION_MAX_DEVICES != null) {
+      options.maxDevices = num(env.CHAINLESSCHAIN_REMOTE_SESSION_MAX_DEVICES);
+    }
+    if (env.CHAINLESSCHAIN_REMOTE_SESSION_MAX_SESSION_TTL_MS != null) {
+      options.maxSessionTtlMs = num(
+        env.CHAINLESSCHAIN_REMOTE_SESSION_MAX_SESSION_TTL_MS,
+      );
+    }
+    if (env.CHAINLESSCHAIN_REMOTE_SESSION_MAX_TOKEN_TTL_MS != null) {
+      options.maxTokenTtlMs = num(
+        env.CHAINLESSCHAIN_REMOTE_SESSION_MAX_TOKEN_TTL_MS,
+      );
+    }
+    if (env.CHAINLESSCHAIN_REMOTE_SESSION_ALLOW_RELAY != null) {
+      options.allowRelayPairing = !/^(0|false|no|off)$/i.test(
+        String(env.CHAINLESSCHAIN_REMOTE_SESSION_ALLOW_RELAY).trim(),
+      );
+    }
+    return new RemoteSessionPolicy(options);
+  }
+}
+
+function publicSession(session) {
+  return {
+    protocolVersion: REMOTE_SESSION_PROTOCOL_VERSION,
+    sessionId: session.sessionId,
+    agentSessionId: session.agentSessionId,
+    name: session.name,
+    hostClientId: session.hostClientId,
+    createdAt: session.createdAt,
+    expiresAt: session.expiresAt,
+    memberCount: session.members.size,
+  };
+}
+
+/** In-memory authorization state for one local CLI process. */
+export class RemoteSessionRegistry {
+  constructor(options = {}) {
+    this.now = options.now || Date.now;
+    this.tokenTtlMs = options.tokenTtlMs || DEFAULT_TOKEN_TTL_MS;
+    this.sessionTtlMs = options.sessionTtlMs || DEFAULT_SESSION_TTL_MS;
+    this.policy = options.policy || new RemoteSessionPolicy();
+    this.sessions = new Map();
+    this.tokens = new Map();
+  }
+
+  create({ hostClientId, agentSessionId, name, scopes } = {}) {
+    if (!hostClientId) throw new Error("hostClientId is required");
+    if (!agentSessionId) throw new Error("agentSessionId is required");
+    const now = this.now();
+    const session = {
+      sessionId: randomUUID(),
+      agentSessionId,
+      name: name || agentSessionId,
+      hostClientId,
+      createdAt: now,
+      expiresAt: now + this.policy.capSessionTtl(this.sessionTtlMs),
+      members: new Map([
+        [
+          hostClientId,
+          {
+            clientId: hostClientId,
+            scopes: REMOTE_SESSION_SCOPES,
+            joinedAt: now,
+          },
+        ],
+      ]),
+    };
+    this.sessions.set(session.sessionId, session);
+    return {
+      session: publicSession(session),
+      pairing: this.issuePairingToken(session.sessionId, { scopes }),
+    };
+  }
+
+  issuePairingToken(sessionId, { scopes } = {}) {
+    const session = this.requireSession(sessionId);
+    const token = randomBytes(32).toString("base64url");
+    const now = this.now();
+    const { scopes: applied, narrowed } = this.policy.applyScopes(scopes);
+    const grantedScopes = normalizeScopes(applied);
+    this.tokens.set(sessionId, {
+      digest: hashToken(token),
+      scopes: grantedScopes,
+      createdAt: now,
+      expiresAt: Math.min(
+        now + this.policy.capTokenTtl(this.tokenTtlMs),
+        session.expiresAt,
+      ),
+    });
+    return {
+      token,
+      expiresAt: this.tokens.get(sessionId).expiresAt,
+      scopes: grantedScopes,
+      policyNarrowed: narrowed,
+    };
+  }
+
+  join({
+    sessionId,
+    clientId,
+    token,
+    via = "direct",
+    pushToken = null,
+    pushProvider = null,
+  } = {}) {
+    if (!clientId) throw new Error("clientId is required");
+    const session = this.requireSession(sessionId);
+    const pairing = this.tokens.get(sessionId);
+    if (!pairing || pairing.expiresAt <= this.now()) {
+      this.tokens.delete(sessionId);
+      throw new Error("Pairing token is missing or expired");
+    }
+    if (!tokensMatch(token, pairing.digest)) {
+      throw new Error("Invalid pairing token");
+    }
+    // Org policy is enforced only after the token proves the caller is invited,
+    // so a device-limit / relay-disabled message never leaks to unauthenticated
+    // probes. Existing (non-host) devices count against the limit.
+    const deviceCount = [...session.members.values()].filter(
+      (member) => member.clientId !== session.hostClientId,
+    ).length;
+    this.policy.enforceJoin({ deviceCount, via });
+    // Pairing credentials are deliberately one-time. The host must explicitly
+    // issue another token for each additional device.
+    this.tokens.delete(sessionId);
+    const member = {
+      clientId,
+      scopes: pairing.scopes,
+      joinedAt: this.now(),
+      pushToken: pushToken || null,
+      pushProvider: pushToken ? pushProvider || null : null,
+    };
+    session.members.set(clientId, member);
+    return { session: publicSession(session), member: { ...member } };
+  }
+
+  /**
+   * A device registers (or refreshes / clears) its own vendor push token after
+   * pairing — e.g. once FCM assigns one. Only an existing member may set its own
+   * token. A null token clears push for that device.
+   */
+  registerPush(sessionId, clientId, { token = null, provider = null } = {}) {
+    const session = this.requireSession(sessionId);
+    const member = session.members.get(clientId);
+    if (!member) {
+      throw new Error("Device is not paired with this remote session");
+    }
+    member.pushToken = token || null;
+    member.pushProvider = token ? provider || null : null;
+    return {
+      clientId,
+      hasPush: Boolean(member.pushToken),
+      provider: member.pushProvider,
+    };
+  }
+
+  /** Non-host members that carry a push token, for wake-up dispatch. */
+  pushTargets(sessionId, { excludeClientId } = {}) {
+    const session = this.requireSession(sessionId);
+    const targets = [];
+    for (const member of session.members.values()) {
+      if (member.clientId === session.hostClientId) continue;
+      if (member.clientId === excludeClientId) continue;
+      if (!member.pushToken) continue;
+      targets.push({
+        clientId: member.clientId,
+        pushToken: member.pushToken,
+        pushProvider: member.pushProvider,
+      });
+    }
+    return targets;
+  }
+
+  authorize(sessionId, clientId, scope) {
+    const session = this.requireSession(sessionId);
+    const member = session.members.get(clientId);
+    if (!member)
+      throw new Error("Client is not paired with this remote session");
+    if (!member.scopes.includes(scope)) {
+      throw new Error(`Remote session scope required: ${scope}`);
+    }
+    return { session, member };
+  }
+
+  members(sessionId) {
+    const session = this.requireSession(sessionId);
+    return [...session.members.values()].map((member) => ({ ...member }));
+  }
+
+  /**
+   * Host-only view of every paired device on a session. The host flag lets the
+   * UI keep the host row un-revocable and label it distinctly.
+   */
+  listDevices(sessionId, hostClientId) {
+    const session = this.requireSession(sessionId);
+    if (hostClientId && session.hostClientId !== hostClientId) {
+      throw new Error("Only the host can list paired devices");
+    }
+    return {
+      session: publicSession(session),
+      devices: [...session.members.values()].map((member) => ({
+        clientId: member.clientId,
+        scopes: [...member.scopes],
+        joinedAt: member.joinedAt,
+        isHost: member.clientId === session.hostClientId,
+        hasPush: Boolean(member.pushToken),
+        pushProvider: member.pushProvider || null,
+      })),
+    };
+  }
+
+  /**
+   * Host-initiated revocation of a single paired device. The host cannot revoke
+   * itself (use close() to end the whole session). Returns the removed member so
+   * callers can push a revocation notice to that device.
+   */
+  revokeMember(sessionId, hostClientId, clientId) {
+    if (!clientId) throw new Error("clientId is required");
+    const session = this.requireSession(sessionId);
+    if (session.hostClientId !== hostClientId) {
+      throw new Error("Only the host can revoke devices");
+    }
+    if (clientId === session.hostClientId) {
+      throw new Error("Cannot revoke the host device");
+    }
+    const member = session.members.get(clientId);
+    if (!member)
+      throw new Error("Device is not paired with this remote session");
+    session.members.delete(clientId);
+    return { session: publicSession(session), member: { ...member } };
+  }
+
+  findHosted(agentSessionId, hostClientId) {
+    const matches = [];
+    for (const session of this.sessions.values()) {
+      if (
+        session.agentSessionId === agentSessionId &&
+        session.hostClientId === hostClientId &&
+        session.expiresAt > this.now()
+      ) {
+        matches.push(session);
+      }
+    }
+    return matches;
+  }
+
+  removeClient(clientId) {
+    const affected = [];
+    for (const [sessionId, session] of this.sessions) {
+      if (!session.members.delete(clientId)) continue;
+      if (session.hostClientId === clientId) {
+        this.sessions.delete(sessionId);
+        this.tokens.delete(sessionId);
+        affected.push({ sessionId, closed: true });
+      } else {
+        affected.push({ sessionId, closed: false });
+      }
+    }
+    return affected;
+  }
+
+  close(sessionId, clientId) {
+    const session = this.requireSession(sessionId);
+    if (session.hostClientId !== clientId) {
+      throw new Error("Only the host can close a Remote Session");
+    }
+    this.sessions.delete(sessionId);
+    this.tokens.delete(sessionId);
+    return publicSession(session);
+  }
+
+  requireSession(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error("Remote session not found");
+    if (session.expiresAt <= this.now()) {
+      this.sessions.delete(sessionId);
+      this.tokens.delete(sessionId);
+      throw new Error("Remote session expired");
+    }
+    return session;
+  }
+}

package/src/lib/agent-sandbox.js

@@ -0,0 +1,72 @@
+/** OS-isolated shell execution for the coding agent. */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+export const DEFAULT_SANDBOX_IMAGE = "node:22-bookworm-slim";
+export const _deps = { spawnSync };
+
+export function normalizeAgentSandbox(value, options = {}) {
+  if (!value) return null;
+  const image =
+    typeof value === "string" && value.trim() && value !== "true"
+      ? value.trim()
+      : DEFAULT_SANDBOX_IMAGE;
+  return {
+    engine: "docker",
+    image,
+    cwd: path.resolve(options.cwd || process.cwd()),
+    network: options.network === true,
+  };
+}
+
+export function executeSandboxedShell(command, sandbox, options = {}) {
+  if (!sandbox || sandbox.engine !== "docker") {
+    throw new Error("A supported agent sandbox configuration is required");
+  }
+  const hostCwd = path.resolve(options.cwd || sandbox.cwd);
+  const args = ["run", "--rm", "--init"];
+  if (!sandbox.network) args.push("--network", "none");
+  args.push("--mount", `type=bind,source=${hostCwd},target=/workspace`);
+  args.push("--workdir", "/workspace");
+  if (process.platform !== "win32" && process.getuid && process.getgid) {
+    args.push("--user", `${process.getuid()}:${process.getgid()}`);
+  }
+  const env = options.env || {};
+  for (const key of ["CLAUDECODE", "CC_SESSION_ID", "CLAUDE_CODE_SESSION_ID"]) {
+    if (env[key] != null) args.push("--env", `${key}=${env[key]}`);
+  }
+  args.push(sandbox.image, "sh", "-lc", String(command || ""));
+  const result = _deps.spawnSync("docker", args, {
+    encoding: "utf8",
+    timeout: options.timeout,
+    maxBuffer: options.maxBuffer,
+    windowsHide: true,
+  });
+  if (result.error) {
+    return {
+      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,
+    };
+  }
+  return {
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    exitCode: typeof result.status === "number" ? result.status : 1,
+    signal: result.signal || null,
+  };
+}
+
+export function sandboxSummary(sandbox) {
+  if (!sandbox) return null;
+  return {
+    engine: sandbox.engine,
+    image: sandbox.image,
+    network: sandbox.network ? "enabled" : "disabled",
+    workspace: "read-write",
+  };
+}

package/src/lib/background-agent-supervisor.js

@@ -0,0 +1,197 @@
+import { spawn, spawnSync } from "node:child_process";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getHomeDir } from "./paths.js";
+
+export const _deps = { spawn, spawnSync };
+
+export function backgroundAgentsDir() {
+  const dir =
+    process.env.CC_BACKGROUND_AGENTS_DIR ||
+    join(getHomeDir(), "background-agents");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function createBackgroundAgentId() {
+  return `bg-${Date.now()}-${randomBytes(3).toString("hex")}`;
+}
+
+function safeId(id) {
+  if (!/^bg-[a-zA-Z0-9-]+$/.test(String(id || ""))) {
+    throw new Error(`Invalid background agent id: ${id}`);
+  }
+  return String(id);
+}
+
+export function statePath(id) {
+  return join(backgroundAgentsDir(), `${safeId(id)}.json`);
+}
+
+export function logPath(id) {
+  return join(backgroundAgentsDir(), `${safeId(id)}.log`);
+}
+
+export function writeBackgroundAgentState(state) {
+  const target = statePath(state.id);
+  const tmp = `${target}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  renameSync(tmp, target);
+  return state;
+}
+
+export function readBackgroundAgentState(id) {
+  const file = statePath(id);
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return false;
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "EPERM") return true;
+    return false;
+  }
+}
+
+export function effectiveBackgroundAgentState(state) {
+  if (!state) return null;
+  if (state.status === "running" && !isProcessAlive(state.pid)) {
+    return { ...state, status: "lost", endedAt: state.endedAt || Date.now() };
+  }
+  return state;
+}
+
+export function listBackgroundAgents(options = {}) {
+  return readdirSync(backgroundAgentsDir())
+    .filter((name) => name.endsWith(".json") && !name.includes(".job."))
+    .map((name) => readBackgroundAgentState(name.slice(0, -5)))
+    .filter(Boolean)
+    .map(effectiveBackgroundAgentState)
+    .filter((state) => options.all || state.status === "running")
+    .sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0));
+}
+
+export function launchBackgroundAgent({
+  argv,
+  cwd,
+  sessionId,
+  title,
+  cliEntry,
+}) {
+  const id = createBackgroundAgentId();
+  const dir = backgroundAgentsDir();
+  const jobFile = join(dir, `${id}.job.${process.pid}.json`);
+  const worker = fileURLToPath(
+    new URL("../workers/background-agent-worker.js", import.meta.url),
+  );
+  const job = {
+    id,
+    argv,
+    cwd,
+    sessionId,
+    title: title || "Background agent",
+    cliEntry: cliEntry || process.argv[1],
+    logFile: logPath(id),
+  };
+  writeFileSync(jobFile, JSON.stringify(job), { mode: 0o600 });
+  let child;
+  try {
+    child = _deps.spawn(process.execPath, [worker, jobFile], {
+      cwd,
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+  } catch (error) {
+    rmSync(jobFile, { force: true });
+    throw error;
+  }
+  child.unref();
+  const state = {
+    id,
+    sessionId,
+    title: job.title,
+    cwd,
+    pid: child.pid,
+    status: "running",
+    startedAt: Date.now(),
+    endedAt: null,
+    exitCode: null,
+    logFile: job.logFile,
+  };
+  writeBackgroundAgentState(state);
+  return state;
+}
+
+export function readBackgroundAgentLog(id, options = {}) {
+  const file = logPath(id);
+  if (!existsSync(file)) return "";
+  const text = readFileSync(file, "utf8");
+  const lines = text.split(/\r?\n/);
+  const limit = Math.max(1, Number(options.lines) || 100);
+  return lines.slice(-limit).join("\n");
+}
+
+export function stopBackgroundAgent(id) {
+  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id));
+  if (!state) throw new Error(`Background agent not found: ${id}`);
+  if (state.status !== "running") return { ...state, stopped: false };
+  if (process.platform === "win32") {
+    const killed = _deps.spawnSync(
+      "taskkill",
+      ["/PID", String(state.pid), "/T", "/F"],
+      {
+        windowsHide: true,
+        encoding: "utf8",
+      },
+    );
+    if (killed.error || (killed.status !== 0 && isProcessAlive(state.pid))) {
+      throw new Error(
+        `Failed to stop background agent ${id}: ${killed.error?.message || killed.stderr || `taskkill exited ${killed.status}`}`,
+      );
+    }
+  } else {
+    try {
+      process.kill(-Number(state.pid), "SIGTERM");
+    } catch {
+      process.kill(Number(state.pid), "SIGTERM");
+    }
+  }
+  const next = {
+    ...state,
+    status: "stopped",
+    endedAt: Date.now(),
+    stoppedByUser: true,
+  };
+  writeBackgroundAgentState(next);
+  return { ...next, stopped: true };
+}
+
+export function openBackgroundLogFile(id) {
+  const fd = openSync(logPath(id), "a", 0o600);
+  return { fd, close: () => closeSync(fd) };
+}
+
+export function removeJobFile(file) {
+  rmSync(file, { force: true });
+}