@zgeoff/atc 2.11.0 → 2.13.0

package/src/mcp/mcp-tools.ts

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { REQUEST_PARAM_SCHEMAS } from '../protocol/request-param-schemas';
 import type { GrantScope } from '../shared/grant-scope';
+import { buildSpawnDescriptions } from './build-spawn-descriptions';
+import { IDEMPOTENCY_KEY_FIELD } from './parse-idempotency-key';
 
 const NO_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(z.strictObject({}));
 
@@ -17,14 +19,31 @@ const SESSION_ID_BASE = z.object({
 
 const SESSION_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(SESSION_ID_BASE.strict());
 const SPAWN_SCHEMA = REQUEST_PARAM_SCHEMAS['session.spawn'];
+const SPAWN_AGENT_DESCRIPTION = buildSpawnDescriptions(null).agent;
+
+// The key as a plain JSON Schema property, for an input schema written out
+// by hand.
+const { $schema: _, ...IDEMPOTENCY_KEY_INPUT } = z.toJSONSchema(IDEMPOTENCY_KEY_FIELD, {
+  io: 'input',
+});
 
 const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
     cwd: SPAWN_SCHEMA.shape.cwd.describe('Absolute path of the working directory'),
     name: SPAWN_SCHEMA.shape.name.describe('Session name; defaults to the directory basename'),
     prompt: SPAWN_SCHEMA.shape.prompt.describe('First message for the session'),
-    agent: SPAWN_SCHEMA.shape.agent.describe(
-      'Which registered agent id to spawn; defaults to claude',
+    agent: SPAWN_SCHEMA.shape.agent.describe(SPAWN_AGENT_DESCRIPTION),
+    model: SPAWN_SCHEMA.shape.model.describe(
+      "Model for the new session: an alias or a full model name, at most 200 characters, never starting with '-'. It reaches the agent CLI as its own argument. Refused when the agent takes no model; spawnOptions.model in atc_agents_list holds each agent's support, default, and examples. Omit it to keep the agent's configured default.",
+    ),
+    effort: SPAWN_SCHEMA.shape.effort.describe(
+      "Effort level for the new session, one of the agent's spawnOptions.effort.values in atc_agents_list. Refused when the agent takes no effort. Omit it to keep the agent's configured default.",
+    ),
+    target: SPAWN_SCHEMA.shape.target.describe(
+      'Execution target for the new session, one of the target ids in atc_agents_list. Omit it to run on the default target (spawnDefaults.target). An unknown or unavailable target is refused; atc never runs the session on another target instead.',
+    ),
+    workspace: SPAWN_SCHEMA.shape.workspace.describe(
+      "Where the session's working directory comes from. Omit it to run the session in cwd as it stands. With it, atc materializes a clean checkout into cwd on the target, which must not exist yet: {kind:'path', path, allowDirty?} checks out the pushed HEAD of a git checkout on the atc host, refusing uncommitted changes unless allowDirty is 'warn'; {kind:'git', url, ref or sha, credentialRef?} checks out a branch, tag, or full commit of a repository, with credentialRef {kind:'env', name} naming the atc daemon's environment variable that holds its token. A directory outside git runs in place only on a target on the atc host itself (provider local-pty), with cwd equal to its path. Submodules and Git LFS are refused, and so is a URL that carries a credential.",
     ),
     detached: z
       .boolean()
@@ -32,6 +51,7 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
       .describe(
         'Spawn a top-level session. By default a spawn from inside an atc session becomes a sub-session of it: listed under it, pinned with it, killed with it.',
       ),
+    idempotencyKey: IDEMPOTENCY_KEY_FIELD,
   }),
   { io: 'input' },
 );
@@ -124,6 +144,27 @@ const MESSAGE_SENT_OUTPUT: Readonly<Record<string, unknown>> = {
   required: ['message', 'status'],
 };
 
+const SPAWN_OPTION_OUTPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {
+    supported: { type: 'boolean' },
+    available: { type: 'boolean' },
+    values: { type: ['array', 'null'], items: { type: 'string' } },
+    examples: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { value: { type: 'string' }, resolvesTo: { type: ['string', 'null'] } },
+        required: ['value', 'resolvesTo'],
+      },
+    },
+    default: { type: ['string', 'null'] },
+    backendEffect: { type: ['string', 'null'], enum: ['applied', 'unverified', null] },
+    note: { type: ['string', 'null'] },
+  },
+  required: ['supported', 'available', 'values', 'examples', 'default', 'backendEffect', 'note'],
+};
+
 const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
   type: 'object',
   properties: {
@@ -159,8 +200,51 @@ const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
             required: ['spawn', 'readTranscript', 'message', 'attach', 'screen', 'input'],
           },
           models: { type: ['object', 'null'], additionalProperties: { type: 'string' } },
+          spawnOptions: {
+            type: 'object',
+            properties: { model: SPAWN_OPTION_OUTPUT, effort: SPAWN_OPTION_OUTPUT },
+            required: ['model', 'effort'],
+          },
+        },
+        required: ['id', 'label', 'kind', 'installed', 'capabilities', 'models', 'spawnOptions'],
+      },
+    },
+    targets: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          provider: { type: 'string' },
+          identity: { type: 'string' },
+          available: { type: 'boolean' },
+          default: { type: 'boolean' },
+          capabilities: {
+            type: 'object',
+            additionalProperties: { type: 'boolean' },
+          },
         },
-        required: ['id', 'label', 'kind', 'installed', 'capabilities', 'models'],
+        required: ['id', 'provider', 'identity', 'available', 'default', 'capabilities'],
+      },
+    },
+    spawnDefaults: {
+      type: 'object',
+      properties: { agent: { type: 'string' }, target: { type: ['string', 'null'] } },
+      required: ['agent', 'target'],
+    },
+    configRevision: { type: 'string' },
+    targetErrors: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          scope: { type: 'string', enum: ['config', 'targets', 'target', 'defaultTarget'] },
+          target: { type: 'string' },
+          problem: { type: 'string' },
+          path: { type: 'string' },
+          detail: { type: 'string' },
+        },
+        required: ['scope', 'problem'],
       },
     },
   },
@@ -264,21 +348,32 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     name: 'atc_session_spawn',
     annotations: AGENT_FACING,
     scope: 'spawn',
-    description:
-      'Spawn a new session in a directory. Optional agent is an agent id the daemon has registered, such as claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. An unregistered id is rejected. 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.',
+    description: buildSpawnDescriptions(null).tool,
     inputSchema: SPAWN_INPUT,
+    requires: {
+      inputs: {
+        model: 'spawn.options',
+        effort: 'spawn.options',
+        idempotencyKey: 'spawn.idempotency',
+        target: 'spawn.target',
+        workspace: 'spawn.workspace',
+      },
+    },
   },
   {
     name: 'atc_session_input',
     annotations: AGENT_FACING_DESTRUCTIVE,
     scope: 'spawn',
     description:
-      'Type a line of text into a running session, as if the operator typed it and pressed enter. Use it to answer a session that is waiting on input.',
+      "Type a line of text into a running session and submit it, as if the operator typed it and pressed enter. atc submits the line the way the session's agent accepts one. Use it to answer a session that is waiting on input. A result of sent means atc wrote the line and its submit key to the session; it does not confirm that the agent took the line or answered it. Read the session's screen or events for that. The tool sends no raw keystrokes.",
     inputSchema: {
       type: 'object',
       properties: {
         session: { type: 'string', description: 'The atc session id' },
-        text: { type: 'string', description: 'The line to type; a newline is appended' },
+        text: {
+          type: 'string',
+          description: "The line to submit; atc adds the submit key the session's agent expects",
+        },
       },
       required: ['session', 'text'],
       additionalProperties: false,
@@ -343,10 +438,10 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      "List the agents this atc host can run sessions under, plus the host itself (daemon: hostname, platform, arch, build). Each agent has its id (pass it as atc_session_spawn's agent), label, kind (the agent CLI family it runs), installed (whether its binary resolves on this host; a registered agent that is not installed cannot spawn), capabilities (spawn, readTranscript, message, attach, screen, input), and models: the model names the config sets for it, or null. It never includes credentials, environment values, or endpoints, and holds nothing about which plans or subscriptions an agent's account has.",
+      "List the agents this atc host can run sessions under, plus the host itself (daemon: hostname, platform, arch, build). Each agent has its id (pass it as atc_session_spawn's agent), label, kind (the agent CLI family it runs), installed (whether its binary resolves on this host; a registered agent that is not installed cannot spawn), capabilities (spawn, readTranscript, message, attach, screen, input), models (the model names the config sets for it, or null), and spawnOptions when the daemon supports spawn options. spawnOptions holds model and effort, each with supported (whether atc passes it to the agent CLI), available (whether a spawn on this host can pass it now), values (the accepted set, or null for any alias or model name), examples (each with the provider model it resolves to, when the config maps one), default (the configured value, or null for the CLI's own), backendEffect (applied, or unverified when the backend may ignore it), and a note. atc_session_spawn accepts exactly the available options. When the daemon supports targets, it also returns targets (each with its id, provider kind, identity, available, default, and capabilities), spawnDefaults (the agent and target a spawn without either runs with; a null target means such a spawn is refused), configRevision (a digest that changes whenever the target config does), and targetErrors (config problems that leave a target, or every target, unusable; a config file that exists but cannot be read or parsed is scope config, problem config_malformed or config_unreadable, with its path and detail, and refuses every spawn, local included). It never includes credentials, environment values, or endpoints, and holds nothing about which plans or subscriptions an agent's account has.",
     inputSchema: NO_INPUT,
     outputSchema: AGENTS_OUTPUT,
-    requires: { tool: 'agents.list' },
+    requires: { tool: 'agents.list', output: 'spawn.options' },
   },
   {
     name: 'atc_session_get',
@@ -379,7 +474,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: AGENT_FACING,
     scope: 'message',
     description:
-      "Send a session a message and get its id back. Follow up with atc_message_get, passing waitMs so each call waits for the next status change instead of polling in a tight loop, until its status is answered; don't read the session's screen or transcript to check on it. The answer is the final output of the session turn that carried the message, and one turn can carry several messages. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (Grok, Codex), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
+      "Send a session a message and get its id back. Follow up with atc_message_get, passing waitMs so each call waits for the next status change instead of polling in a tight loop, until its status is answered; don't read the session's screen or transcript to check on it. The answer is the final output of the session turn that carried the message, and one turn can carry several messages. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (capabilities.message is false in atc_agents_list), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -390,11 +485,13 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
           description:
             'Who the message is from; defaults to the calling session id, or mcp outside a session. Ignored for a remote client, whose messages are always from its own name',
         },
+        idempotencyKey: IDEMPOTENCY_KEY_INPUT,
       },
       required: ['session', 'text'],
       additionalProperties: false,
     },
     outputSchema: MESSAGE_SENT_OUTPUT,
+    requires: { inputs: { idempotencyKey: 'message.idempotency' } },
   },
   {
     name: 'atc_message_get',

package/src/mcp/parse-idempotency-key.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { DaemonError } from '../protocol/daemon-error';
+
+/**
+ * The idempotency key a spawn or message tool call may carry, as its input
+ * schema lists it.
+ */
+export const IDEMPOTENCY_KEY_FIELD = z
+  .string()
+  .min(1)
+  .max(180)
+  .optional()
+  .describe(
+    'A key, unique to this call, that makes a retry safe: retrying with the same key and arguments returns the first answer instead of acting again, and the same key with different arguments is refused as idempotency_conflict. A call interrupted mid-way is refused as outcome_unknown, with the id it acted under in data.effectRef. At most 180 characters',
+  );
+
+/**
+ * Reads a tool call's idempotency key, refusing one outside the input
+ * schema as `bad_args` before the call reaches the daemon.
+ */
+export function parseIdempotencyKey(value: unknown): string | undefined {
+  const parsed = IDEMPOTENCY_KEY_FIELD.safeParse(value);
+
+  if (!parsed.success) {
+    throw new DaemonError('bad_args', 'idempotencyKey must be a string of 1 to 180 characters');
+  }
+
+  return parsed.data;
+}

package/src/mcp/reconnecting-caller.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { DaemonClient } from '../client/daemon-client';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { parseDaemonFeatures } from '../protocol/parse-daemon-features';
@@ -18,6 +19,14 @@ const RETRYABLE_METHODS: ReadonlySet<string> = new Set([
   'session.screen',
 ]);
 
+// The effectful requests a daemon takes under an idempotency key, and the
+// feature it announces when it does. Under a key, a retry replays the first
+// answer instead of running the effect again.
+const KEYED_METHODS: ReadonlyMap<string, DaemonFeature> = new Map<string, DaemonFeature>([
+  ['session.spawn', 'spawn.idempotency'],
+  ['session.message', 'message.idempotency'],
+]);
+
 // One handshaken connection and the features its daemon announced.
 interface DaemonConnection {
   readonly client: DaemonClient;
@@ -27,9 +36,11 @@ interface DaemonConnection {
 /**
  * A daemon caller that survives a daemon restart: once the connection ends,
  * the next request opens and handshakes a fresh one. A request that was in
- * flight when the connection ended is retried once on a fresh connection only
- * when it is read-only; any other fails, because a spawn or a message must not
- * run twice.
+ * flight when the connection ended is retried once on a fresh connection when
+ * it is read-only, or when it is a spawn or a message the daemon takes under an
+ * idempotency key: the request keeps its key, minted here when the caller
+ * passed none, so the daemon runs it at most once. Any other request fails,
+ * because a spawn or a message must not run twice.
  */
 export class ReconnectingCaller implements FleetCaller {
   private readonly socketPath: string;
@@ -52,23 +63,32 @@ export class ReconnectingCaller implements FleetCaller {
     m: string,
     p?: Readonly<Record<string, unknown>>,
     required: readonly DaemonFeature[] = [],
+    principal?: string,
   ): Promise<Readonly<Record<string, unknown>>> {
     const opened = await this.openClient();
 
     requireDaemonFeatures(opened.features, required);
 
+    const keyFeature = KEYED_METHODS.get(m);
+    const keyed = keyFeature !== undefined && opened.features.has(keyFeature);
+    const params = keyed ? buildKeyedParams(p) : p;
+
     try {
-      return await opened.client.sendRequest(m, p);
+      return await opened.client.sendRequest(m, params, principal);
     } catch (error) {
-      if (!this.closed.has(opened.client) || !RETRYABLE_METHODS.has(m)) {
+      if (!this.closed.has(opened.client) || !(keyed || RETRYABLE_METHODS.has(m))) {
         throw error;
       }
 
       const fresh = await this.openClient();
 
-      requireDaemonFeatures(fresh.features, required);
+      // The fresh daemon has to take the key too, or the retry could run the
+      // effect a second time.
+      const retryRequired = keyed ? [...required, keyFeature] : required;
+
+      requireDaemonFeatures(fresh.features, retryRequired);
 
-      return fresh.client.sendRequest(m, p);
+      return fresh.client.sendRequest(m, params, principal);
     }
   }
 
@@ -149,3 +169,15 @@ export class ReconnectingCaller implements FleetCaller {
     return { client, features: parseDaemonFeatures(hello) };
   }
 }
+
+// The request's params with its idempotency key, minting one when the caller
+// passed none.
+function buildKeyedParams(
+  p: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> {
+  if (typeof p?.['idempotencyKey'] === 'string') {
+    return p;
+  }
+
+  return { ...p, idempotencyKey: randomUUID() };
+}

package/src/mcp/require-daemon-features.ts

@@ -4,10 +4,20 @@ import type { DaemonFeature } from '../protocol/daemon-features';
 // states it.
 const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'agents.list': 'atc_agents_list',
+  'daemon.id': "the daemon's persisted identity",
   'events.more': "atc_events_read's more flag",
   'events.session': "atc_events_read's session filter",
+  'message.idempotency': "atc_session_message's idempotencyKey",
   'message.turn': "atc_message_get's turn and answeredWith",
   'message.wait': "atc_message_get's waitMs",
+  'session.forget': 'session.forget',
+  'session.locator': "a session's locator",
+  'session.submit': 'atc_session_input',
+  'spawn.idempotency': "atc_session_spawn's idempotencyKey",
+  'spawn.options': "atc_session_spawn's model and effort",
+  'spawn.target': "atc_session_spawn's target",
+  'request.principal': 'the target limits of a remote MCP client',
+  'spawn.workspace': "atc_session_spawn's workspace",
 };
 
 /**

package/src/mcp/run-tool.ts

@@ -1,7 +1,9 @@
+import { createHash } from 'node:crypto';
 import { match } from 'ts-pattern';
 import { DaemonError } from '../protocol/daemon-error';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { isRecord } from '../shared/report';
+import { parseIdempotencyKey } from './parse-idempotency-key';
 import type { FleetCaller, ToolContext } from './types';
 
 /**
@@ -33,28 +35,64 @@ export function runTool(
     .with('atc_session_spawn', async () => {
       const rawAgent = args['agent'];
       const nested = args['detached'] !== true && ctx.callerSessionID !== null;
+      const key = parseIdempotencyKey(args['idempotencyKey']);
 
       const params = {
         cwd: args['cwd'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
         ...(rawAgent === undefined ? {} : { agent: rawAgent }),
+        ...(args['model'] === undefined ? {} : { model: args['model'] }),
+        ...(args['effort'] === undefined ? {} : { effort: args['effort'] }),
+        ...(key === undefined ? {} : { idempotencyKey: key }),
+        ...(args['target'] === undefined ? {} : { target: args['target'] }),
+        ...(args['workspace'] === undefined ? {} : { workspace: args['workspace'] }),
         cols: 100,
         rows: 30,
       };
 
+      // A model, effort, key, target, or workspace needs a daemon that takes
+      // them; the check runs on every connection the spawn rides.
+      const optionFeatures: readonly DaemonFeature[] =
+        args['model'] === undefined && args['effort'] === undefined ? [] : ['spawn.options'];
+
+      const keyFeatures: readonly DaemonFeature[] = key === undefined ? [] : ['spawn.idempotency'];
+
+      const targetFeatures: readonly DaemonFeature[] =
+        args['target'] === undefined ? [] : ['spawn.target'];
+
+      const workspaceFeatures: readonly DaemonFeature[] =
+        args['workspace'] === undefined ? [] : ['spawn.workspace'];
+
+      const required = [...optionFeatures, ...keyFeatures, ...targetFeatures, ...workspaceFeatures];
+
       const ok =
         nested && ctx.callerSessionID !== null
-          ? await sendNestedSpawn(caller, params, ctx.callerSessionID)
-          : await caller.sendRequest('session.spawn', params);
+          ? await sendNestedSpawn(caller, params, ctx.callerSessionID, required)
+          : await caller.sendRequest('session.spawn', params, required);
+
+      // A spawn whose workspace left changes behind returns its warnings
+      // beside the session's own fields.
+      const warnings = ok['warnings'];
+
+      const session =
+        warnings === undefined || !isRecord(ok['session'])
+          ? ok['session']
+          : { ...ok['session'], warnings };
 
-      return buildObjectResult(ok['session']);
+      return buildObjectResult(session);
     })
     .with('atc_session_input', async () => {
-      await caller.sendRequest('session.input', {
-        session: args['session'],
-        d: `${typeof args['text'] === 'string' ? args['text'] : ''}\n`,
-      });
+      // An older daemon would take the line as raw input, which some agents
+      // never submit.
+      await caller.sendRequest(
+        'session.submit',
+        {
+          session: args['session'],
+          text: typeof args['text'] === 'string' ? args['text'] : '',
+        },
+        ['session.submit'],
+      );
 
       return { text: 'sent', structured: null };
     })
@@ -142,11 +180,19 @@ export function runTool(
           ? given
           : ctx.sender.name;
 
-      const ok = await caller.sendRequest('session.message', {
-        session: args['session'],
-        text: args['text'],
-        from,
-      });
+      const key = parseIdempotencyKey(args['idempotencyKey']);
+      const required: DaemonFeature[] = key === undefined ? [] : ['message.idempotency'];
+
+      const ok = await caller.sendRequest(
+        'session.message',
+        {
+          session: args['session'],
+          text: args['text'],
+          from,
+          ...(key === undefined ? {} : { idempotencyKey: key }),
+        },
+        required,
+      );
 
       return buildObjectResult(ok);
     })
@@ -177,19 +223,44 @@ function buildObjectResult(value: unknown): ToolResult {
 
 // The inherited id can point at a session another daemon hosts, or one
 // this daemon no longer lists; the spawn then lands top-level instead of
-// failing the tool call.
+// failing the tool call. The top-level spawn has a different payload, so it
+// runs under its own key, a fixed-length hash of the caller's: a retry of the
+// tool call derives the same key and replays it rather than conflicting with
+// the nested attempt's key, and the derived key fits the daemon's cap
+// whatever the caller's length. An answer
+// that holds an effect id is a keyed spawn that already ran, which a
+// top-level spawn would only duplicate.
 async function sendNestedSpawn(
   caller: FleetCaller,
   params: Readonly<Record<string, unknown>>,
   parent: string,
+  required: readonly DaemonFeature[],
 ): Promise<Readonly<Record<string, unknown>>> {
   try {
-    return await caller.sendRequest('session.spawn', { ...params, parent });
+    return await caller.sendRequest('session.spawn', { ...params, parent }, required);
   } catch (error) {
-    if (error instanceof DaemonError && error.code === 'no_such_session') {
-      return caller.sendRequest('session.spawn', params);
+    if (
+      error instanceof DaemonError &&
+      error.code === 'no_such_session' &&
+      error.data?.['effectRef'] === undefined
+    ) {
+      return caller.sendRequest('session.spawn', buildTopLevelParams(params), required);
     }
 
     throw error;
   }
 }
+
+function buildTopLevelParams(
+  params: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  const key = params['idempotencyKey'];
+
+  if (typeof key !== 'string') {
+    return params;
+  }
+
+  const digest = createHash('sha256').update(key).digest('hex');
+
+  return { ...params, idempotencyKey: `top-level:${digest}` };
+}

package/src/mcp/types.ts

@@ -6,11 +6,13 @@ import type { openMCPAuth } from './open-mcp-auth';
 // features the connected daemon announced at its handshake. A request that
 // lists required features is checked against the connection it is about to
 // ride, every time it is sent, and refused unsent when that daemon lacks one.
+// A request with a principal acts as that principal.
 export interface FleetCaller {
   readonly sendRequest: (
     m: string,
     p?: Readonly<Record<string, unknown>>,
     required?: readonly DaemonFeature[],
+    principal?: string,
   ) => Promise<Readonly<Record<string, unknown>>>;
   readonly readFeatures: () => Promise<ReadonlySet<DaemonFeature>>;
 }

package/src/protocol/daemon-error.ts

@@ -7,10 +7,14 @@ import type { ErrorCode } from './protocol';
 export class DaemonError extends Error {
   readonly code: ErrorCode;
 
-  constructor(code: ErrorCode, msg: string) {
+  // Structured detail the error code defines for itself, sent as `err.data`.
+  readonly data: Readonly<Record<string, unknown>> | undefined;
+
+  constructor(code: ErrorCode, msg: string, data?: Readonly<Record<string, unknown>>) {
     super(msg);
 
     this.code = code;
+    this.data = data;
     this.name = 'DaemonError';
   }
 }

package/src/protocol/daemon-features.ts

@@ -18,6 +18,41 @@ export const DAEMON_FEATURES = [
 
   // `message.get` takes `waitMs`.
   'message.wait',
+
+  // `session.spawn` takes `model` and `effort`, and `agents.list` returns
+  // `spawnOptions`.
+  'spawn.options',
+
+  // `daemon.hello` returns `daemonID`.
+  'daemon.id',
+
+  // Every session descriptor holds a `locator`.
+  'session.locator',
+
+  // `session.spawn` takes `idempotencyKey`.
+  'spawn.idempotency',
+
+  // `session.message` takes `idempotencyKey`.
+  'message.idempotency',
+
+  // `session.spawn` takes `target`, and `agents.list` returns `targets`,
+  // `spawnDefaults`, `configRevision`, and `targetErrors`.
+  'spawn.target',
+
+  // A request takes `as`, the principal it acts as, and `daemon.hello`
+  // takes `principal`, the principal the whole connection acts as.
+  'request.principal',
+
+  // `session.spawn` takes `workspace`, and a session descriptor holds the
+  // `workspace` its checkout was materialized from.
+  'spawn.workspace',
+
+  // `session.forget` exists, and a kill of a session asleep on a target that
+  // can destroy its host answers `confirmation_required`.
+  'session.forget',
+
+  // `session.submit` exists.
+  'session.submit',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];