@zgeoff/atc 2.11.0 → 2.13.0

package/src/daemon/start-headless-turn.ts

@@ -10,8 +10,9 @@ import { truncateSummary } from './truncate-summary';
  * runner, wires the run's output and completion into the session manager,
  * passes the turn's start and end to the event trail the way a terminal
  * turn's hooks do, and records the live handle on the session's runtime. Returns false
- * without starting anything when the session is unknown, its agent has no
- * headless runner, or a turn is already running.
+ * without starting anything when the session is unknown or exited, its
+ * agent has no headless runner, its target does not serve headless turns,
+ * or a turn is already running.
  */
 export function startHeadlessTurn(
   mgr: SessionManager,
@@ -28,6 +29,12 @@ export function startHeadlessTurn(
     return false;
   }
 
+  // The runner runs on the daemon's own host, so a session whose target
+  // does not serve headless turns never reaches it.
+  if (s.state === 'exited' || mgr.findExecutionRefusal(s, 'headless') !== null) {
+    return false;
+  }
+
   mgr.updateSurfaceState(sessionID, 'running', 'headless turn running');
 
   recordTurnEvent(sessionID, { kind: 'prompt-submitted', detail: truncateDetail(prompt) });
@@ -37,8 +44,10 @@ export function startHeadlessTurn(
       cwd: s.cwd,
       prompt,
       ...(s.agentSessionID === undefined ? {} : { resume: s.agentSessionID }),
-      permissionMode: 'auto',
       sessionID,
+      ...(s.model === undefined ? {} : { model: s.model }),
+      ...(s.effort === undefined ? {} : { effort: s.effort }),
+      ...(s.withheldEnv.length === 0 ? {} : { withheldEnv: s.withheldEnv }),
     },
     {
       onOutput: (text) => {

package/src/daemon/start-session-bridge.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod';
+import type { EventMsg } from '../protocol/protocol';
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
+import { toMessageID } from '../shared/to-message-id';
+import type { MessageRecord } from '../store/message-record';
+import type { TapClient } from './daemon-connection';
+import type { HarnessRelay } from './execution-provider';
+import type { HookEvent } from './hooks';
+import { isBindingCurrent } from './is-binding-current';
+import type { BridgeBinding } from './is-binding-current';
+import { parseHookLine } from './parse-hook-line';
+
+/**
+ * The fields of a live session the bridge checks its binding against and
+ * reads the status from.
+ */
+export interface BridgeSession {
+  readonly id: SessionID;
+  readonly target: string;
+  readonly targetIdentity: string;
+  readonly hostKey: SessionID;
+  readonly bridgeEpoch: number;
+  readonly state: string;
+  readonly lastMsg: string;
+}
+
+/**
+ * What the bridge needs from the daemon. Each operation acts on the one
+ * session the caller names, which is always the bridge's own.
+ */
+export interface BridgeContext {
+  readonly findSession: (sessionID: SessionID) => BridgeSession | undefined;
+  readonly applyHookEvent: (e: HookEvent) => void;
+
+  // Applies a report under the id its reporter gave it, and settles once
+  // the report is recorded; false when the payload is no report.
+  readonly applyReport: (
+    sessionID: SessionID,
+    payload: Readonly<Record<string, unknown>>,
+    reportID: string,
+  ) => Promise<boolean>;
+  readonly attachTap: (client: TapClient, sessionID: SessionID) => 'ok' | 'missing' | 'unsupported';
+  readonly ackMessage: (
+    client: TapClient,
+    sessionID: SessionID,
+    messageID: MessageID,
+  ) => Promise<MessageRecord | 'not_tapping' | 'unknown'>;
+  readonly detachTap: (client: TapClient) => void;
+}
+
+const REQUEST_SCHEMA = z.looseObject({ v: z.literal(1), id: z.string().min(1), op: z.string() });
+
+const REPORT_SCHEMA = z.looseObject({
+  reportID: z.string().min(1).max(128),
+  payload: z.record(z.string(), z.unknown()),
+});
+
+const ACK_SCHEMA = z.looseObject({ message: z.string().min(1) });
+
+type BridgeRefusal = 'forbidden' | 'stale_binding' | 'not_tapping' | 'unknown_message';
+
+/**
+ * Serves one connection a remote harness's processes opened to the daemon:
+ * the session bridge. A line without an `op` is a hook line, as the local
+ * reporter socket takes it. A request line `{ v: 1, id, op }` gets one
+ * answer line `{ id, ok }`, and the bridge's own inbox events go out as
+ * protocol event lines.
+ *
+ * The bridge takes hooks, reports, its session's tap and acks, and its
+ * session's own status, for the one session it was bound to and nothing
+ * else: an unknown op, a malformed request, or a report or hook for any
+ * other session answers `forbidden` and closes the connection. Every line
+ * checks the binding against the live session first, and one that no
+ * longer matches answers `stale_binding` and closes.
+ *
+ * Trust: the binding holds no secret. A host serves the bridge's socket
+ * inside itself alone, so reaching the socket is the proof of being inside
+ * that host. One host is one trust domain: a sub-session in its parent's
+ * host runs as the same user and can reach the parent's socket too. The
+ * per-session socket and binding stop processes in the host from crossing
+ * sessions by accident, never a hostile process inside the same host.
+ */
+export function startSessionBridge(
+  relay: HarnessRelay,
+  binding: Readonly<BridgeBinding>,
+  ctx: BridgeContext,
+): void {
+  let closed = false;
+  let writing: Promise<void> = Promise.resolve();
+
+  // Lines go out one at a time, in the order they were written, and none
+  // after the bridge closed.
+  const writeLine = async (value: Readonly<Record<string, unknown>>) => {
+    const line = JSON.stringify(value);
+    const previous = writing;
+
+    writing = (async () => {
+      await previous;
+
+      if (!closed) {
+        try {
+          await relay.writeLine(line);
+        } catch {}
+      }
+    })();
+
+    await writing;
+  };
+
+  const stopBridge = () => {
+    if (closed) {
+      return;
+    }
+
+    closed = true;
+
+    ctx.detachTap(tap);
+    relay.close();
+  };
+
+  // Answers a refusal, then closes once the answer has gone out.
+  const answerRefusal = async (id: string | null, code: BridgeRefusal) => {
+    await writeLine({ id, ok: false, code });
+
+    stopBridge();
+  };
+
+  const tap: TapClient = {
+    sendEvent: (event: EventMsg) => {
+      void (async () => {
+        await writeLine(event);
+
+        if (event.ev === 'InboxClosed') {
+          stopBridge();
+        }
+      })();
+    },
+  };
+
+  const isCurrent = () => isBindingCurrent(binding, ctx.findSession(binding.sessionID));
+
+  const applyRequest = async (
+    request: Readonly<Record<string, unknown>>,
+    id: string,
+    op: string,
+  ) => {
+    if (op === 'report') {
+      const parsed = REPORT_SCHEMA.safeParse(request);
+
+      if (
+        !parsed.success ||
+        !(await ctx.applyReport(binding.sessionID, parsed.data.payload, parsed.data.reportID))
+      ) {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      void writeLine({ id, ok: true });
+
+      return;
+    }
+
+    if (op === 'tap.open') {
+      if (ctx.attachTap(tap, binding.sessionID) !== 'ok') {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      void writeLine({ id, ok: true });
+
+      return;
+    }
+
+    if (op === 'tap.ack') {
+      const parsed = ACK_SCHEMA.safeParse(request);
+
+      if (!parsed.success) {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      const acked = await ctx.ackMessage(tap, binding.sessionID, toMessageID(parsed.data.message));
+
+      if (acked === 'not_tapping' || acked === 'unknown') {
+        const code: BridgeRefusal = acked === 'unknown' ? 'unknown_message' : 'not_tapping';
+
+        void writeLine({ id, ok: false, code });
+
+        return;
+      }
+
+      void writeLine({ id, ok: true, status: acked.status });
+
+      return;
+    }
+
+    if (op === 'status.read') {
+      const s = ctx.findSession(binding.sessionID);
+
+      void writeLine({ id, ok: true, state: s?.state ?? 'exited', lastMsg: s?.lastMsg ?? '' });
+
+      return;
+    }
+
+    void answerRefusal(id, 'forbidden');
+  };
+
+  // Lines are applied one at a time, in the order they arrived.
+  let applying: Promise<void> = Promise.resolve();
+
+  const applyLine = async (line: string) => {
+    if (closed) {
+      return;
+    }
+
+    let parsed: unknown;
+
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      void answerRefusal(null, 'forbidden');
+
+      return;
+    }
+
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      void answerRefusal(null, 'forbidden');
+
+      return;
+    }
+
+    const record: Readonly<Record<string, unknown>> = Object.fromEntries(Object.entries(parsed));
+
+    if (!('op' in record)) {
+      const e = parseHookLine(line);
+
+      if (!isCurrent()) {
+        void answerRefusal(null, 'stale_binding');
+
+        return;
+      }
+
+      if (e === null || e.atcId !== binding.sessionID) {
+        void answerRefusal(null, 'forbidden');
+
+        return;
+      }
+
+      ctx.applyHookEvent(e);
+
+      return;
+    }
+
+    const request = REQUEST_SCHEMA.safeParse(record);
+
+    if (!request.success) {
+      const id = typeof record['id'] === 'string' ? record['id'] : null;
+
+      void answerRefusal(id, 'forbidden');
+
+      return;
+    }
+
+    if (!isCurrent()) {
+      void answerRefusal(request.data.id, 'stale_binding');
+
+      return;
+    }
+
+    await applyRequest(record, request.data.id, request.data.op);
+  };
+
+  relay.onLine((line) => {
+    const previous = applying;
+
+    applying = (async () => {
+      await previous;
+
+      try {
+        await applyLine(line);
+      } catch {}
+    })();
+  });
+
+  relay.onClose(() => {
+    closed = true;
+
+    ctx.detachTap(tap);
+  });
+}

package/src/daemon/target-access.ts

@@ -0,0 +1,36 @@
+/**
+ * A target a session runs on, as the name it holds and the identity the
+ * session is bound to there.
+ */
+export interface TargetGrant {
+  readonly target: string;
+  readonly targetIdentity: string;
+}
+
+/**
+ * The targets a principal may use, each as a name and an identity: a
+ * session on a granted name whose identity differs is outside the grant.
+ */
+export class TargetAccess {
+  private readonly grants: ReadonlyMap<string, TargetGrant>;
+
+  constructor(grants: readonly TargetGrant[]) {
+    this.grants = new Map(grants.map((grant) => [buildGrantKey(grant), grant]));
+  }
+
+  canUse(grant: TargetGrant): boolean {
+    return this.grants.has(buildGrantKey(grant));
+  }
+
+  /**
+   * The grants both accesses hold, so a principal on a narrowed connection
+   * never reaches past the connection.
+   */
+  merge(other: TargetAccess): TargetAccess {
+    return new TargetAccess([...this.grants.values()].filter((grant) => other.canUse(grant)));
+  }
+}
+
+function buildGrantKey(grant: TargetGrant): string {
+  return JSON.stringify([grant.target, grant.targetIdentity]);
+}

package/src/mcp/answer-mcp-request.ts

@@ -4,6 +4,7 @@ import type { GrantScope } from '../shared/grant-scope';
 import { normalizeClientName } from '../shared/normalize-client-name';
 import { isRecord } from '../shared/report';
 import { answerRPCRequest } from './answer-rpc-request';
+import { buildPrincipalCaller } from './build-principal-caller';
 import { deriveTokenHash } from './derive-token-hash';
 import { findClientName } from './find-client-name';
 import { isSupportedProtocolVersion } from './is-supported-protocol-version';
@@ -21,7 +22,8 @@ interface MCPHTTPRequest {
  * database, so a revoked grant loses access at once, and a token bound to any
  * other resource is refused. A tool call outside the token's scopes is a 403
  * that names the missing scope. A message the client sends is always from the
- * client's own name.
+ * client's own name, and every request acts as the client's id, so the
+ * daemon limits it to the targets that principal may use.
  */
 export async function answerMCPRequest(
   ctx: HTTPServerContext,
@@ -65,7 +67,7 @@ export async function answerMCPRequest(
   }
 
   const outcome = await answerRPCRequest(message, {
-    caller: ctx.caller,
+    caller: buildPrincipalCaller(ctx.caller, access.clientID),
     build: ctx.build,
     toolContext: { callerSessionID: null, sender: { kind: 'fixed', name: access.clientName } },
     scopes: access.scopes,
@@ -95,12 +97,13 @@ export async function answerMCPRequest(
 }
 
 interface VerifiedAccess {
+  readonly clientID: string;
   readonly clientName: string;
   readonly scopes: readonly GrantScope[];
 }
 
-// An inactive, unknown, or revoked token, or one bound to another resource,
-// verifies to null. Verifying stamps when the token's grant was last used.
+// An inactive, unknown, or revoked token, one bound to another resource, or
+// one without a client id verifies to null. Verifying stamps when the token's grant was last used.
 async function verifyAccessToken(
   ctx: HTTPServerContext,
   token: string,
@@ -124,11 +127,16 @@ async function verifyAccessToken(
   const granted = typeof payload['scope'] === 'string' ? payload['scope'].split(' ') : [];
   const clientID = typeof payload['client_id'] === 'string' ? payload['client_id'] : '';
 
+  if (clientID === '') {
+    return null;
+  }
+
   await upsertGrantUse(ctx, token);
 
   const storedName = await findClientName(ctx.store.db, clientID);
 
   return {
+    clientID,
     clientName: normalizeClientName(storedName, 'remote'),
     scopes: GRANT_SCOPES.filter((scope) => granted.includes(scope)),
   };

package/src/mcp/answer-rpc-request.ts

@@ -1,7 +1,9 @@
 import { match } from 'ts-pattern';
+import { z } from 'zod';
 import { DaemonError } from '../protocol/daemon-error';
 import type { GrantScope } from '../shared/grant-scope';
 import { isRecord } from '../shared/report';
+import type { RegisteredAgent } from './build-spawn-descriptions';
 import { buildToolList } from './build-tool-list';
 import { MCP_TOOLS } from './mcp-tools';
 import { pickProtocolVersion } from './pick-protocol-version';
@@ -60,9 +62,11 @@ export async function answerRPCRequest(message: unknown, deps: RPCDeps): Promise
     .with('tools/list', async () => {
       const features = await deps.caller.readFeatures();
 
+      const agents = features.has('agents.list') ? await tryReadAgents(deps) : null;
+
       return {
         kind: 'reply' as const,
-        body: buildRPCResult(id, { tools: buildToolList(features) }),
+        body: buildRPCResult(id, { tools: buildToolList(features, agents) }),
       };
     })
     .with('tools/call', async () => {
@@ -97,6 +101,29 @@ function findMissingScope(
   return scopes.includes(needed) ? null : needed;
 }
 
+// The part of an agents.list answer the spawn descriptions read.
+const ROSTER_AGENT_SCHEMA = z.object({ id: z.string(), installed: z.boolean() });
+const AGENT_ROSTER_SCHEMA = z.object({ agents: z.array(ROSTER_AGENT_SCHEMA) });
+
+// The registered agents, or null when the daemon cannot answer, so the tool
+// list still builds with descriptions that name no agent. A caller without
+// the read scope gets null too, since listing agents is a read.
+async function tryReadAgents(deps: RPCDeps): Promise<RegisteredAgent[] | null> {
+  if (deps.scopes !== undefined && !deps.scopes.includes('read')) {
+    return null;
+  }
+
+  try {
+    const answer = await deps.caller.sendRequest('agents.list');
+
+    const parsed = AGENT_ROSTER_SCHEMA.safeParse(answer);
+
+    return parsed.success ? parsed.data.agents : null;
+  } catch {
+    return null;
+  }
+}
+
 async function answerToolCall(
   deps: RPCDeps,
   params: Readonly<Record<string, unknown>>,

package/src/mcp/build-principal-caller.ts

@@ -0,0 +1,15 @@
+import type { FleetCaller } from './types';
+
+/**
+ * The caller every request of one remote MCP client rides: each request acts
+ * as the client's principal, whatever principal it asked for, and goes only
+ * to a daemon that limits a request to its principal's targets, so a daemon
+ * that would ignore the principal never answers it with the owner's reach.
+ */
+export function buildPrincipalCaller(caller: FleetCaller, principal: string): FleetCaller {
+  return {
+    sendRequest: (m, p, required = []) =>
+      caller.sendRequest(m, p, [...required, 'request.principal'], principal),
+    readFeatures: () => caller.readFeatures(),
+  };
+}

package/src/mcp/build-spawn-descriptions.ts

@@ -0,0 +1,45 @@
+/**
+ * One agent as the spawn descriptions list it: its id and whether its binary
+ * resolves on the daemon's host.
+ */
+export interface RegisteredAgent {
+  readonly id: string;
+  readonly installed: boolean;
+}
+
+interface SpawnDescriptions {
+  readonly tool: string;
+  readonly agent: string;
+}
+
+/**
+ * The `atc_session_spawn` description and its `agent` field description,
+ * naming the agents the daemon registered when the tool list was built. Only
+ * a registered id appears, and a registered agent whose binary is missing is
+ * marked not installed. null leaves every agent unnamed, for a tool list
+ * built while the daemon could not answer. Both point at `atc_agents_list`
+ * for the current list.
+ */
+export function buildSpawnDescriptions(
+  agents: readonly RegisteredAgent[] | null,
+): SpawnDescriptions {
+  const roster =
+    agents === null
+      ? ''
+      : ` When this tool list was built, the host registered: ${formatRoster(agents)}.`;
+
+  return {
+    tool: `Spawn a new session in a directory. Optional agent is a registered agent id; omitted agent is always Claude, never the TUI last-used value.${roster} atc_agents_list returns the current agents, whether each is installed, and the model and effort each takes. An unregistered agent, a registered agent that is not installed, and a model or effort the agent does not take are refused before anything spawns. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.`,
+    agent: `Registered agent id to spawn; defaults to claude.${roster} atc_agents_list returns the current list.`,
+  };
+}
+
+function formatRoster(agents: readonly RegisteredAgent[]): string {
+  if (agents.length === 0) {
+    return 'no agents';
+  }
+
+  return agents
+    .map((agent) => (agent.installed ? agent.id : `${agent.id} (not installed)`))
+    .join(', ');
+}

package/src/mcp/build-tool-list.ts

@@ -1,5 +1,7 @@
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { isRecord } from '../shared/report';
+import { buildSpawnDescriptions } from './build-spawn-descriptions';
+import type { RegisteredAgent } from './build-spawn-descriptions';
 import { MCP_TOOLS } from './mcp-tools';
 
 interface MCPTool {
@@ -19,8 +21,16 @@ interface MCPTool {
  * features. A tool the daemon cannot serve is left out, and a tool it serves
  * in an older form is listed without the output schema and input properties
  * that form lacks, so a client never sees an option the daemon would ignore.
+ * The spawn tool's description and its agent field's description name the
+ * registered agents; null leaves them unnamed. No schema depends on which
+ * agents the host registers or installs.
  */
-export function buildToolList(features: ReadonlySet<DaemonFeature>): readonly MCPTool[] {
+export function buildToolList(
+  features: ReadonlySet<DaemonFeature>,
+  agents: readonly RegisteredAgent[] | null,
+): readonly MCPTool[] {
+  const spawn = buildSpawnDescriptions(agents);
+
   return MCP_TOOLS.flatMap((tool) => {
     const requires = tool.requires ?? {};
 
@@ -28,20 +38,23 @@ export function buildToolList(features: ReadonlySet<DaemonFeature>): readonly MC
       return [];
     }
 
-    const inputSchema = buildInputSchema(tool.inputSchema, requires.inputs ?? {}, features);
+    const gated = buildInputSchema(tool.inputSchema, requires.inputs ?? {}, features);
+    const isSpawn = tool.name === 'atc_session_spawn';
+    const description = isSpawn ? spawn.tool : tool.description;
+    const inputSchema = isSpawn ? buildAgentFieldSchema(gated, spawn.agent) : gated;
 
     return [
       tool.outputSchema === undefined ||
       (requires.output !== undefined && !features.has(requires.output))
         ? {
             name: tool.name,
-            description: tool.description,
+            description,
             inputSchema,
             annotations: tool.annotations,
           }
         : {
             name: tool.name,
-            description: tool.description,
+            description,
             inputSchema,
             outputSchema: tool.outputSchema,
             annotations: tool.annotations,
@@ -72,3 +85,18 @@ function buildInputSchema(
     ),
   };
 }
+
+// The input schema with only the agent field's description replaced.
+function buildAgentFieldSchema(
+  schema: Readonly<Record<string, unknown>>,
+  description: string,
+): Readonly<Record<string, unknown>> {
+  const properties = schema['properties'];
+  const agent = isRecord(properties) ? properties['agent'] : undefined;
+
+  if (!isRecord(properties) || !isRecord(agent)) {
+    return schema;
+  }
+
+  return { ...schema, properties: { ...properties, agent: { ...agent, description } } };
+}