@zgeoff/atc 2.10.3 → 2.11.0

package/src/daemon/parse-report.ts

@@ -4,8 +4,14 @@ import { toMessageID } from '../shared/to-message-id';
 
 interface AnsweredReport {
   readonly kind: 'answered';
-  readonly message: MessageID;
+
+  // Every message the turn answered, recorded together.
+  readonly messages: readonly MessageID[];
   readonly answer: string;
+
+  // The turn whose final reply the answer is; null from a reporter that
+  // sends none.
+  readonly turn: string | null;
 }
 
 export interface NoteReport {
@@ -16,8 +22,27 @@ export interface NoteReport {
 
 export type Report = AnsweredReport | NoteReport;
 
+// Optional, so a report from an older bridge still parses; a missing, empty,
+// or wrong-typed turn reads as unknown.
+const TURN_SCHEMA = z.preprocess(
+  (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+  z.string().optional(),
+);
+
+const MESSAGE_IDS_SCHEMA = z.array(z.string().min(1)).min(1).optional();
+
 const REPORT_SCHEMA = z.discriminatedUnion('kind', [
-  z.object({ kind: z.literal('answered'), message: z.string().min(1), answer: z.string() }),
+  z
+    .object({
+      kind: z.literal('answered'),
+
+      // One message, or every message one turn answered.
+      message: z.string().min(1).optional(),
+      messages: MESSAGE_IDS_SCHEMA,
+      answer: z.string(),
+      turn: TURN_SCHEMA,
+    })
+    .refine((v) => (v.message === undefined) !== (v.messages === undefined)),
   z.object({ kind: z.literal('note'), label: z.string().min(1).max(64), text: z.string().min(1) }),
 ]);
 
@@ -38,7 +63,8 @@ export function parseReport(payload: Readonly<Record<string, unknown>>): Report
 
   return {
     kind: 'answered',
-    message: toMessageID(parsed.data.message),
+    messages: (parsed.data.messages ?? [parsed.data.message ?? '']).map((id) => toMessageID(id)),
     answer: parsed.data.answer,
+    turn: parsed.data.turn ?? null,
   };
 }

package/src/daemon/sessions.ts

@@ -134,6 +134,11 @@ export class SessionManager {
     return this.adapters[id] ?? null;
   }
 
+  // Every registered adapter, one per id, in registration order.
+  collectAdapters(): AgentAdapter[] {
+    return Object.values(this.adapters);
+  }
+
   // Hands a live terminal session off to a headless run: the terminal dies,
   // the record lives on as a headless session and keeps its screen history.
   yankHeadless(id: SessionID): Session | null {

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

@@ -57,10 +57,14 @@ export async function answerRPCRequest(message: unknown, deps: RPCDeps): Promise
       }),
     }))
     .with('ping', () => ({ kind: 'reply' as const, body: buildRPCResult(id, {}) }))
-    .with('tools/list', () => ({
-      kind: 'reply' as const,
-      body: buildRPCResult(id, { tools: buildToolList() }),
-    }))
+    .with('tools/list', async () => {
+      const features = await deps.caller.readFeatures();
+
+      return {
+        kind: 'reply' as const,
+        body: buildRPCResult(id, { tools: buildToolList(features) }),
+      };
+    })
     .with('tools/call', async () => {
       const result = await answerToolCall(deps, params);
 
@@ -101,9 +105,12 @@ async function answerToolCall(
   const args = isRecord(params['arguments']) ? params['arguments'] : {};
 
   try {
-    const text = await runTool(deps.caller, name, args, deps.toolContext);
+    const result = await runTool(deps.caller, name, args, deps.toolContext);
 
-    return { content: [{ type: 'text', text }] };
+    return {
+      content: [{ type: 'text', text: result.text }],
+      ...(result.structured === null ? {} : { structuredContent: result.structured }),
+    };
   } catch (error) {
     return { content: [{ type: 'text', text: formatToolError(error) }], isError: true };
   }

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

@@ -1,9 +1,12 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { isRecord } from '../shared/report';
 import { MCP_TOOLS } from './mcp-tools';
 
 interface MCPTool {
   readonly name: string;
   readonly description: string;
   readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
   readonly annotations: {
     readonly readOnlyHint: boolean;
     readonly destructiveHint: boolean;
@@ -11,11 +14,61 @@ interface MCPTool {
   };
 }
 
-export function buildToolList(): readonly MCPTool[] {
-  return MCP_TOOLS.map((tool) => ({
-    name: tool.name,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
-    annotations: tool.annotations,
-  }));
+/**
+ * The tools `tools/list` returns for a daemon announcing the given
+ * 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.
+ */
+export function buildToolList(features: ReadonlySet<DaemonFeature>): readonly MCPTool[] {
+  return MCP_TOOLS.flatMap((tool) => {
+    const requires = tool.requires ?? {};
+
+    if (requires.tool !== undefined && !features.has(requires.tool)) {
+      return [];
+    }
+
+    const inputSchema = buildInputSchema(tool.inputSchema, requires.inputs ?? {}, features);
+
+    return [
+      tool.outputSchema === undefined ||
+      (requires.output !== undefined && !features.has(requires.output))
+        ? {
+            name: tool.name,
+            description: tool.description,
+            inputSchema,
+            annotations: tool.annotations,
+          }
+        : {
+            name: tool.name,
+            description: tool.description,
+            inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: tool.annotations,
+          },
+    ];
+  });
+}
+
+function buildInputSchema(
+  schema: Readonly<Record<string, unknown>>,
+  inputs: Readonly<Record<string, DaemonFeature>>,
+  features: ReadonlySet<DaemonFeature>,
+): Readonly<Record<string, unknown>> {
+  const withheld = Object.entries(inputs).flatMap(([name, feature]) =>
+    features.has(feature) ? [] : [name],
+  );
+
+  const properties = schema['properties'];
+
+  if (withheld.length === 0 || !isRecord(properties)) {
+    return schema;
+  }
+
+  return {
+    ...schema,
+    properties: Object.fromEntries(
+      Object.entries(properties).filter(([name]) => !withheld.includes(name)),
+    ),
+  };
 }

package/src/mcp/mcp-tools.ts

@@ -1,4 +1,5 @@
 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';
 
@@ -54,8 +55,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 +78,121 @@ 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 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' } },
+        },
+        required: ['id', 'label', 'kind', 'installed', 'capabilities', 'models'],
+      },
+    },
+  },
+  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 +203,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;
 }
 
@@ -215,6 +338,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), 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.",
+    inputSchema: NO_INPUT,
+    outputSchema: AGENTS_OUTPUT,
+    requires: { tool: 'agents.list' },
+  },
   {
     name: 'atc_session_get',
     annotations: READ_ONLY,
@@ -236,15 +369,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 (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.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -259,20 +394,16 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
       required: ['session', 'text'],
       additionalProperties: false,
     },
+    outputSchema: MESSAGE_SENT_OUTPUT,
   },
   {
     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/reconnecting-caller.ts

@@ -1,9 +1,13 @@
 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,6 +18,12 @@ const RETRYABLE_METHODS: ReadonlySet<string> = new Set([
   'session.screen',
 ]);
 
+// 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
@@ -26,7 +36,7 @@ export class ReconnectingCaller implements FleetCaller {
 
   private readonly build: string;
 
-  private client: Promise<DaemonClient> | null = null;
+  private client: Promise<DaemonConnection> | null = null;
 
   private readonly closed = new WeakSet<DaemonClient>();
 
@@ -35,25 +45,41 @@ 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[] = [],
   ): Promise<Readonly<Record<string, unknown>>> {
-    const client = await this.openClient();
+    const opened = await this.openClient();
+
+    requireDaemonFeatures(opened.features, required);
 
     try {
-      return await client.sendRequest(m, p);
+      return await opened.client.sendRequest(m, p);
     } catch (error) {
-      if (!this.closed.has(client) || !RETRYABLE_METHODS.has(m)) {
+      if (!this.closed.has(opened.client) || !RETRYABLE_METHODS.has(m)) {
         throw error;
       }
 
       const fresh = await this.openClient();
 
-      return fresh.sendRequest(m, p);
+      requireDaemonFeatures(fresh.features, required);
+
+      return fresh.client.sendRequest(m, p);
     }
   }
 
+  // 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 +90,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 +113,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 +135,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 +146,6 @@ export class ReconnectingCaller implements FleetCaller {
       throw error;
     }
 
-    return client;
+    return { client, features: parseDaemonFeatures(hello) };
   }
 }

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

@@ -0,0 +1,33 @@
+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',
+  'events.more': "atc_events_read's more flag",
+  'events.session': "atc_events_read's session filter",
+  'message.turn': "atc_message_get's turn and answeredWith",
+  'message.wait': "atc_message_get's waitMs",
+};
+
+/**
+ * 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.`,
+  );
+}