@zgeoff/atc 2.10.4 → 2.12.0

package/src/mcp/mcp-tools.ts

@@ -1,6 +1,9 @@
 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({}));
 
@@ -16,14 +19,28 @@ 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.',
     ),
     detached: z
       .boolean()
@@ -31,6 +48,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' },
 );
@@ -54,8 +72,16 @@ const SESSION_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   { io: 'input' },
 );
 
+const WAIT_MS = z.number().int().min(0).max(30_000).optional();
+
 const EVENTS_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
+    session: z
+      .string()
+      .optional()
+      .describe(
+        "An atc session id; limits the read to that session's events. Cursors stay valid across filtered and unfiltered reads",
+      ),
     cursor: z
       .string()
       .optional()
@@ -69,19 +95,185 @@ const EVENTS_READ_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
       .max(200)
       .optional()
       .describe('Most events to return; defaults to 50'),
-    waitMs: z
-      .number()
-      .int()
-      .min(0)
-      .max(30_000)
-      .optional()
-      .describe(
-        'How long to wait for a new event when none is pending, in milliseconds; defaults to 0, capped at 30000. Keep it short.',
-      ),
+    waitMs: WAIT_MS.describe(
+      'How long to wait for a new event when none is pending, in milliseconds; defaults to 0, capped at 30000. Keep it short.',
+    ),
   }),
   { io: 'input' },
 );
 
+const MESSAGE_GET_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  z.strictObject({
+    message: z.string().describe('The message id atc_session_message returned'),
+    waitMs: WAIT_MS.describe(
+      'How long to hold the call until the message status changes from what it was when you called, in milliseconds; defaults to 0, capped at 30000',
+    ),
+  }),
+  { io: 'input' },
+);
+
+// Output schemas leave further properties open, so a field the daemon adds
+// later never fails a client that validates results against them.
+const MESSAGE_OUTPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {
+    message: { type: 'string' },
+    session: { type: 'string' },
+    from: { type: 'string' },
+    text: { type: 'string' },
+    status: { type: 'string', enum: ['accepted', 'delivered', 'answered'] },
+    answer: { type: 'string' },
+    turn: { type: ['string', 'null'] },
+    answeredWith: { type: 'array', items: { type: 'string' } },
+    sentAt: { type: 'number' },
+    deliveredAt: { type: 'number' },
+    answeredAt: { type: 'number' },
+  },
+  required: ['message', 'session', 'from', 'text', 'status', 'turn', 'answeredWith', 'sentAt'],
+};
+
+const MESSAGE_SENT_OUTPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {
+    message: { type: 'string' },
+    status: { type: 'string', enum: ['accepted', 'delivered', 'answered'] },
+  },
+  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: {
+    daemon: {
+      type: 'object',
+      properties: {
+        hostname: { type: 'string' },
+        platform: { type: 'string' },
+        arch: { type: 'string' },
+        build: { type: 'string' },
+      },
+      required: ['hostname', 'platform', 'arch', 'build'],
+    },
+    agents: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          label: { type: 'string' },
+          kind: { type: 'string' },
+          installed: { type: 'boolean' },
+          capabilities: {
+            type: 'object',
+            properties: {
+              spawn: { type: 'boolean' },
+              readTranscript: { type: 'boolean' },
+              message: { type: 'boolean' },
+              attach: { type: 'boolean' },
+              screen: { type: 'boolean' },
+              input: { type: 'boolean' },
+            },
+            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', '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'],
+      },
+    },
+  },
+  required: ['daemon', 'agents'],
+};
+
+const EVENTS_OUTPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {
+    events: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          cursor: { type: 'string' },
+          at: { type: 'number' },
+          session: { type: 'string' },
+          name: { type: ['string', 'null'] },
+          kind: { type: 'string' },
+          detail: { type: ['string', 'null'] },
+          message: { type: 'string' },
+          label: { type: 'string' },
+        },
+        required: ['cursor', 'at', 'session', 'name', 'kind', 'detail'],
+      },
+    },
+    cursor: { type: 'string' },
+    more: { type: 'boolean' },
+  },
+  required: ['events', 'cursor', 'more'],
+};
+
 interface MCPToolAnnotations {
   readonly readOnlyHint: boolean;
   readonly destructiveHint: boolean;
@@ -92,7 +284,19 @@ interface MCPToolDefinition {
   readonly name: string;
   readonly description: string;
   readonly inputSchema: Readonly<Record<string, unknown>>;
+
+  // The shape of the tool's structured result, for the tools that declare one.
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
   readonly annotations: MCPToolAnnotations;
+
+  // What the connected daemon has to announce for the tool to be listed at
+  // all, for its output schema to be declared, and for each listed input
+  // property to be offered. An older daemon gets the tool without them.
+  readonly requires?: {
+    readonly tool?: DaemonFeature;
+    readonly output?: DaemonFeature;
+    readonly inputs?: Readonly<Record<string, DaemonFeature>>;
+  };
   readonly scope: GrantScope;
 }
 
@@ -141,9 +345,16 @@ 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',
+      },
+    },
   },
   {
     name: 'atc_session_input',
@@ -215,6 +426,16 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     description: 'List directories sessions were previously spawned from, most recent first.',
     inputSchema: NO_INPUT,
   },
+  {
+    name: 'atc_agents_list',
+    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), 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', output: 'spawn.options' },
+  },
   {
     name: 'atc_session_get',
     annotations: READ_ONLY,
@@ -236,15 +457,17 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended), message events (message-accepted, message-delivered, message-answered), and reports (report) since a cursor, oldest first, each with the session id and name. A message event carries the message id; read the full message with atc_message_get. A report event carries its label. Without a cursor it returns the most recent events. Pass the returned cursor next time. waitMs holds the call open until an event arrives.',
+      'Catch up on the fleet: session events (started, prompt-submitted, needs-input, turn-done, ended), message events (message-accepted, message-delivered, message-answered), and reports (report) since a cursor, oldest first, each with the session id and name. A message event carries the message id; read the full message with atc_message_get. A report event carries its label. Without a cursor it returns the most recent events. Pass the returned cursor next time; more is true when the page stopped before the newest event, so read again at once. session limits the read to one session. waitMs holds the call open until an event arrives; pass it instead of polling in a tight loop.',
     inputSchema: EVENTS_READ_INPUT,
+    outputSchema: EVENTS_OUTPUT,
+    requires: { output: 'events.more', inputs: { session: 'events.session' } },
   },
   {
     name: 'atc_session_message',
     annotations: AGENT_FACING,
     scope: 'message',
     description:
-      "Send a session a message and get its id back. Follow up by polling atc_message_get with the id until its status is answered, which returns the session's final reply; don't read the session's screen or transcript to check on it. 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: {
@@ -255,24 +478,22 @@ 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',
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      'Read one message sent with atc_session_message: its id, session, from, text, status (accepted, delivered, or answered), the answer once answered, and the sentAt, deliveredAt, and answeredAt timestamps. Poll it until the status is answered.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        message: { type: 'string', description: 'The message id atc_session_message returned' },
-      },
-      required: ['message'],
-      additionalProperties: false,
-    },
+      'Read one message sent with atc_session_message: its id, session, from, text, status (accepted, delivered, or answered), the answer once answered, turn, answeredWith, and the sentAt, deliveredAt, and answeredAt timestamps. The answer is the final output of the session turn that carried the message, not a reply to that message alone: when one turn carries several messages, each gets the same answer. turn is that turn id, or null when the session reported none, and answeredWith lists the other messages the same turn answered. Pass waitMs to hold the call until the status changes from what it was when you called, up to 30000 ms, instead of polling in a tight loop; an answered message returns at once. Message ids and statuses persist, so after a call ends or times out, call again with the same id.',
+    inputSchema: MESSAGE_GET_INPUT,
+    outputSchema: MESSAGE_OUTPUT,
+    requires: { output: 'message.turn', inputs: { waitMs: 'message.wait' } },
   },
 ];

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,9 +1,14 @@
+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';
+import { requireDaemonFeatures } from './require-daemon-features';
 import type { FleetCaller } from './types';
 
 // The daemon requests the read-only tools send. Each only reads, so running
 // one twice is harmless.
 const RETRYABLE_METHODS: ReadonlySet<string> = new Set([
+  'agents.list',
   'dirs.list',
   'events.read',
   'message.get',
@@ -14,19 +19,35 @@ 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;
+  readonly features: ReadonlySet<DaemonFeature>;
+}
+
 /**
  * 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;
 
   private readonly build: string;
 
-  private client: Promise<DaemonClient> | null = null;
+  private client: Promise<DaemonConnection> | null = null;
 
   private readonly closed = new WeakSet<DaemonClient>();
 
@@ -35,25 +56,50 @@ export class ReconnectingCaller implements FleetCaller {
     this.build = build;
   }
 
+  // The required features are checked against each connection right before
+  // the request goes out on it, the retry's fresh connection included, since
+  // a restart can put an older daemon behind the same socket.
   async sendRequest(
     m: string,
     p?: Readonly<Record<string, unknown>>,
+    required: readonly DaemonFeature[] = [],
+    principal?: string,
   ): Promise<Readonly<Record<string, unknown>>> {
-    const client = await this.openClient();
+    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 client.sendRequest(m, p);
+      return await opened.client.sendRequest(m, params, principal);
     } catch (error) {
-      if (!this.closed.has(client) || !RETRYABLE_METHODS.has(m)) {
+      if (!this.closed.has(opened.client) || !(keyed || RETRYABLE_METHODS.has(m))) {
         throw error;
       }
 
       const fresh = await this.openClient();
 
-      return fresh.sendRequest(m, p);
+      // 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, params, principal);
     }
   }
 
+  // The features of the daemon the next request reaches, read from the
+  // handshake of the connection it rides.
+  async readFeatures(): Promise<ReadonlySet<DaemonFeature>> {
+    const opened = await this.openClient();
+
+    return opened.features;
+  }
+
   async stop(): Promise<void> {
     const current = this.client;
 
@@ -64,17 +110,19 @@ export class ReconnectingCaller implements FleetCaller {
     }
 
     try {
-      const client = await current;
+      const opened = await current;
 
-      client.stop();
+      opened.client.stop();
     } catch {
       // A connection that never opened has nothing to close.
     }
   }
 
-  private openClient(): Promise<DaemonClient> {
+  private openClient(): Promise<DaemonConnection> {
     if (this.client === null) {
-      const opening: Promise<DaemonClient> = this.openFreshClient(() => this.client === opening);
+      const opening: Promise<DaemonConnection> = this.openFreshClient(
+        () => this.client === opening,
+      );
 
       this.client = opening;
     }
@@ -85,7 +133,7 @@ export class ReconnectingCaller implements FleetCaller {
   // isCurrent returns true while this connection is still the one later requests
   // reuse: a connection that ends after a newer one replaced it must leave
   // the newer one in place.
-  private async openFreshClient(isCurrent: () => boolean): Promise<DaemonClient> {
+  private async openFreshClient(isCurrent: () => boolean): Promise<DaemonConnection> {
     const resetClient = () => {
       if (isCurrent()) {
         this.client = null;
@@ -107,8 +155,10 @@ export class ReconnectingCaller implements FleetCaller {
       resetClient();
     };
 
+    let hello: Readonly<Record<string, unknown>>;
+
     try {
-      await client.sendHello(this.build);
+      hello = await client.sendHello(this.build);
     } catch (error) {
       client.stop();
 
@@ -116,6 +166,18 @@ export class ReconnectingCaller implements FleetCaller {
       throw error;
     }
 
-    return client;
+    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

@@ -0,0 +1,40 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+
+// What each feature lets a tool call ask for, as an outdated-daemon refusal
+// 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.locator': "a session's locator",
+  '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',
+};
+
+/**
+ * Throws a `daemon_outdated` error when the daemon a request is about to
+ * reach lacks a feature the request depends on, rather than letting a daemon
+ * that would ignore the option answer as if it had honoured it. atc never
+ * restarts the daemon itself: a restart is the operator's call, because it
+ * respawns every session.
+ */
+export function requireDaemonFeatures(
+  features: ReadonlySet<DaemonFeature>,
+  required: readonly DaemonFeature[],
+): void {
+  const missing = required.find((feature) => !features.has(feature));
+
+  if (missing === undefined) {
+    return;
+  }
+
+  throw new Error(
+    `daemon_outdated: the running atc daemon is older than this atc and does not support ${FEATURE_USES[missing]}. Restart the daemon to use it: press u in the atc TUI, which restores every session. Until then, call without it.`,
+  );
+}