@zgeoff/atc 2.20.0 → 2.22.0

package/src/mcp/mcp-tools.ts

@@ -1,9 +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';
+import type { FleetFeature } from './types';
 
 const NO_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(z.strictObject({}));
 
@@ -27,8 +27,23 @@ const { $schema: _, ...IDEMPOTENCY_KEY_INPUT } = z.toJSONSchema(IDEMPOTENCY_KEY_
   io: 'input',
 });
 
+// The daemon a call goes to, offered only by a caller that routes across
+// named daemons.
+const DAEMON_FIELD = z
+  .string()
+  .optional()
+  .describe(
+    'The atc daemon to run on, one of the names atc_daemons_list returns. Omit it to use the default daemon. A daemon that is down answers daemon_unavailable; atc never runs the call on another daemon instead.',
+  );
+
+const DIRS_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
+  z.strictObject({ daemon: DAEMON_FIELD }),
+  { io: 'input' },
+);
+
 const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
+    daemon: DAEMON_FIELD,
     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'),
@@ -117,7 +132,11 @@ const MESSAGE_GET_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
 
 const REPORT_GET_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
-    report: z.string().describe("The cursor of the report's event, from atc_events_read"),
+    report: z
+      .string()
+      .describe(
+        "The report handle of the report's event from atc_events_read, or the event's cursor when it carries no report handle",
+      ),
   }),
   { io: 'input' },
 );
@@ -316,10 +335,13 @@ interface MCPToolDefinition {
   // 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.
+  // `outputUnless` leaves the output schema out when the caller announces
+  // that feature, for a tool whose result takes another shape there.
   readonly requires?: {
-    readonly tool?: DaemonFeature;
-    readonly output?: DaemonFeature;
-    readonly inputs?: Readonly<Record<string, DaemonFeature>>;
+    readonly tool?: FleetFeature;
+    readonly output?: FleetFeature;
+    readonly outputUnless?: FleetFeature;
+    readonly inputs?: Readonly<Record<string, FleetFeature>>;
   };
   readonly scope: GrantScope;
 }
@@ -373,6 +395,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     inputSchema: SPAWN_INPUT,
     requires: {
       inputs: {
+        daemon: 'fleet.daemons',
         model: 'spawn.options',
         effort: 'spawn.options',
         idempotencyKey: 'spawn.idempotency',
@@ -452,7 +475,17 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description: 'List directories sessions were previously spawned from, most recent first.',
+    inputSchema: DIRS_INPUT,
+    requires: { inputs: { daemon: 'fleet.daemons' } },
+  },
+  {
+    name: 'atc_daemons_list',
+    annotations: READ_ONLY,
+    scope: 'read',
+    description:
+      "List the atc daemons this server routes to: each one's name, state (up, down, unauthorized, changed, or outdated), build, daemonID, and features, plus defaultDaemon, the daemon a spawn or directory listing without daemon goes to. Session and message ids start with the name of the daemon that holds them.",
     inputSchema: NO_INPUT,
+    requires: { tool: 'fleet.daemons' },
   },
   {
     name: 'atc_agents_list',
@@ -462,7 +495,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
       "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' },
+    requires: { tool: 'agents.list', output: 'spawn.options', outputUnless: 'fleet.daemons' },
   },
   {
     name: 'atc_session_get',
@@ -485,7 +518,7 @@ 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 and a preview of its text; read the full text with atc_report_get, passing the cursor of that event. 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.',
+      '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 and a preview of its text; read the full text with atc_report_get, passing the report handle of that event when it carries one, else its cursor. 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' } },
@@ -495,7 +528,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      "Read one report's full text without messaging the session that sent it. Pass the cursor of the report's event from atc_events_read. Returns the report cursor, at, the session id and name, the label, the text (up to 64 KiB, as the session sent it), and complete, which is false for a report recorded before atc kept full texts: its text is then only the preview the event held. A cursor of an event that is not a report answers as an unknown report.",
+      "Read one report's full text without messaging the session that sent it. Pass the report handle of the report's event from atc_events_read, or the event's cursor when it carries none. Returns the report cursor, at, the session id and name, the label, the text (up to 64 KiB, as the session sent it), and complete, which is false for a report recorded before atc kept full texts: its text is then only the preview the event held. A cursor of an event that is not a report answers as an unknown report.",
     inputSchema: REPORT_GET_INPUT,
     outputSchema: REPORT_OUTPUT,
     requires: { tool: 'report.get' },

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

@@ -21,6 +21,8 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'spawn.workspace': "atc_session_spawn's workspace",
   sources: 'sources.list and sources.interpret',
   'git.probe': 'git.probe',
+  'transport.tcp': 'a TCP connection to the daemon',
+  'idempotency.replayOnly': 'a resend that only replays a held idempotency key',
 };
 
 /**

package/src/mcp/run-tool.ts

@@ -25,6 +25,12 @@ export function runTool(
     .with('atc_session_list', async () => {
       const ok = await caller.sendRequest('session.list');
 
+      // A caller that routes across named daemons adds each daemon's state,
+      // so a daemon that is down never reads as one with no sessions.
+      if (ok['daemons'] !== undefined) {
+        return buildObjectResult({ sessions: ok['sessions'], daemons: ok['daemons'] });
+      }
+
       // The text stays the bare list older clients read; structured content
       // has to be an object.
       return {
@@ -38,6 +44,7 @@ export function runTool(
       const key = parseIdempotencyKey(args['idempotencyKey']);
 
       const params = {
+        ...(typeof args['daemon'] === 'string' ? { daemon: args['daemon'] } : {}),
         cwd: args['cwd'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
@@ -132,10 +139,17 @@ export function runTool(
       };
     })
     .with('atc_dirs_list', async () => {
-      const ok = await caller.sendRequest('dirs.list');
+      const params = typeof args['daemon'] === 'string' ? { daemon: args['daemon'] } : {};
+
+      const ok = await caller.sendRequest('dirs.list', params);
 
       return { text: JSON.stringify(ok['dirs'], null, 2), structured: { dirs: ok['dirs'] } };
     })
+    .with('atc_daemons_list', async () => {
+      const ok = await caller.sendRequest('daemons.list');
+
+      return buildObjectResult(ok);
+    })
     .with('atc_agents_list', async () => {
       const ok = await caller.sendRequest('agents.list', {}, ['agents.list']);
 

package/src/mcp/start-mcp-http-server.ts

@@ -35,6 +35,9 @@ interface MCPHTTPServerOptions {
 
   // How long a rotated refresh token still answers with its successor.
   readonly refreshReuseSeconds?: number;
+
+  // Serves `/healthz` and `/readyz` for an orchestrator's probes.
+  readonly probes?: boolean;
 }
 
 /**
@@ -60,7 +63,11 @@ export interface MCPHTTPServer {
  * method, path, JSON-RPC method and tool, status, duration, and MCP protocol
  * version, and never a body, query, credential, or address. A request whose Host header is not the server's own is
  * refused, so a DNS rebinding page cannot reach it through a browser, and a
- * browser form post from any other origin is refused too.
+ * browser form post from any other origin is refused too. With `probes`,
+ * `/healthz` answers 200 while the server serves and `/readyz` answers 200
+ * once the authorization server's database is open, else 503; both pass
+ * the Host check first and answer with an empty body, so they disclose
+ * nothing about the fleet.
  */
 export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise<MCPHTTPServer> {
   // Normalized before binding, so an invalid public URL throws with no port
@@ -79,7 +86,10 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
     );
   }
 
-  const holder: { ready: ServerState | null } = { ready: null };
+  const holder: { ready: ServerState | null; hosts: ReadonlySet<string> } = {
+    ready: null,
+    hosts: new Set(),
+  };
 
   const server = Bun.serve({
     hostname: options.host,
@@ -94,7 +104,11 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
       let rpc: RPCLabel | null = null;
       let response: Response;
 
-      if (state === null) {
+      const path = new URL(request.url).pathname;
+
+      if (options.probes === true && PROBE_PATHS.has(path)) {
+        response = answerProbeRequest(request, path, holder.hosts, state !== null);
+      } else if (state === null) {
         response = new Response(null, { status: 503 });
       } else {
         try {
@@ -122,6 +136,16 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
   const port = server.port ?? options.port;
   const local = `http://127.0.0.1:${port}`;
   const origin = publicOrigin ?? local;
+
+  const hosts = new Set([
+    new URL(origin).host,
+    `127.0.0.1:${port}`,
+    `localhost:${port}`,
+    ...options.allowedHosts,
+  ]);
+
+  holder.hosts = hosts;
+
   let store: HTTPServerContext['store'];
 
   try {
@@ -139,12 +163,7 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
   }
 
   holder.ready = {
-    hosts: new Set([
-      new URL(origin).host,
-      `127.0.0.1:${port}`,
-      `localhost:${port}`,
-      ...options.allowedHosts,
-    ]),
+    hosts,
     origins: new Set([origin, local, `http://localhost:${port}`]),
     ctx: {
       caller: options.caller,
@@ -168,6 +187,31 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
   };
 }
 
+const PROBE_PATHS: ReadonlySet<string> = new Set(['/healthz', '/readyz']);
+
+// A probe from a Host other than the server's own is refused like any other
+// request; `ready` is whether the authorization server's database is open.
+function answerProbeRequest(
+  request: Request,
+  path: string,
+  hosts: ReadonlySet<string>,
+  ready: boolean,
+): Response {
+  const host = request.headers.get('host');
+
+  if (host === null || !hosts.has(host)) {
+    return new Response(null, { status: 403 });
+  }
+
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return new Response(null, { status: 405, headers: { allow: 'GET, HEAD' } });
+  }
+
+  const isReady = path === '/healthz' || ready;
+
+  return new Response(null, { status: isReady ? 200 : 503 });
+}
+
 // An IPv6 address takes the brackets a URL puts around it.
 function formatBindURL(host: string, port: number): string {
   const bracketed = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;

package/src/mcp/types.ts

@@ -2,6 +2,13 @@ import type { DaemonFeature } from '../protocol/daemon-features';
 import type { ApprovalState } from './approval-state';
 import type { openMCPAuth } from './open-mcp-auth';
 
+/**
+ * A feature the tool list can depend on: one a daemon announces, or
+ * `fleet.daemons`, which only a caller that routes across named daemons
+ * announces, for the tools and inputs that pick a daemon.
+ */
+export type FleetFeature = DaemonFeature | 'fleet.daemons';
+
 // The slice of the daemon client the tool handlers need: requests, and the
 // features the connected daemon announced at its handshake. A request that
 // lists required features is checked against the connection it is about to
@@ -14,7 +21,7 @@ export interface FleetCaller {
     required?: readonly DaemonFeature[],
     principal?: string,
   ) => Promise<Readonly<Record<string, unknown>>>;
-  readonly readFeatures: () => Promise<ReadonlySet<DaemonFeature>>;
+  readonly readFeatures: () => Promise<ReadonlySet<FleetFeature>>;
 }
 
 export interface ToolContext {

package/src/protocol/daemon-features.ts

@@ -64,6 +64,15 @@ export const DAEMON_FEATURES = [
   // `git.probe` exists, and `session.spawn` takes a git workspace with both
   // `ref` and `sha`.
   'git.probe',
+
+  // The daemon can serve the client protocol on a TCP listener whose
+  // handshake takes a bearer token.
+  'transport.tcp',
+
+  // A keyed `session.spawn` or `session.message` takes `replayOnly`, which
+  // replays a key the daemon holds and refuses one it does not hold with
+  // `idempotency_key_unknown`, running nothing.
+  'idempotency.replayOnly',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/protocol.ts

@@ -57,6 +57,7 @@ const ERROR_CODES = [
   'stale_epoch',
   'idempotency_conflict',
   'outcome_unknown',
+  'idempotency_key_unknown',
   'internal',
 ] as const;
 

package/src/protocol/request-param-schemas.ts

@@ -23,6 +23,10 @@ const IDEMPOTENCY_KEY = z
   .max(200, 'idempotencyKey must be at most 200 characters')
   .optional();
 
+// With a key, only replays what the key already holds: a key the daemon
+// does not hold is refused and nothing runs.
+const REPLAY_ONLY = z.boolean({ error: 'replayOnly must be a boolean' }).optional();
+
 // A full commit id, SHA-1 or SHA-256.
 const COMMIT_ID = /^(?:[\da-f]{40}|[\da-f]{64})$/u;
 
@@ -168,6 +172,7 @@ export const REQUEST_PARAM_SCHEMAS = {
     // A retry carrying the same key replays the first spawn's answer instead
     // of spawning again.
     idempotencyKey: IDEMPOTENCY_KEY,
+    replayOnly: REPLAY_ONLY,
 
     // The execution target the session runs on; absent runs on the default
     // target, and a target the daemon cannot use refuses the spawn.
@@ -260,6 +265,7 @@ export const REQUEST_PARAM_SCHEMAS = {
     // A retry carrying the same key replays the first send's message
     // instead of sending another.
     idempotencyKey: IDEMPOTENCY_KEY,
+    replayOnly: REPLAY_ONLY,
   }).refine((v) => v.text !== '', { message: 'session.message requires text' }),
   'session.tap': SESSION_DEFAULTED,
   'message.get': z

package/src/run-daemon-id.ts

@@ -0,0 +1,52 @@
+import { DaemonClient } from './client/daemon-client';
+import { daemonRecordFile, daemonSocketPath } from './shared/config';
+import { findDaemonRecord } from './shared/find-daemon-record';
+
+/**
+ * Prints the running daemon's `daemonID`, the identity a gateway registry
+ * pins, read from the handshake over the owner's local socket: the one this
+ * environment computes, else the one the daemon recorded in the state
+ * directory. When no daemon answers, prints a hint to stderr and exits
+ * nonzero instead of booting one.
+ */
+export async function runDaemonID(build: string): Promise<void> {
+  const record = findDaemonRecord(daemonRecordFile);
+  const paths = [daemonSocketPath, ...(record === null ? [] : [record.socketPath])];
+
+  for (const path of new Set(paths)) {
+    const daemonID = await tryReadDaemonID(path, build);
+
+    if (daemonID !== null) {
+      console.log(daemonID);
+
+      return;
+    }
+  }
+
+  console.error(`atc daemon id: no daemon at ${daemonSocketPath} — start one first`);
+  process.exit(1);
+}
+
+// The daemonID the daemon at the socket returns, or null when nothing
+// answers there or the answer holds none.
+async function tryReadDaemonID(socketPath: string, build: string): Promise<string | null> {
+  let client: DaemonClient;
+
+  try {
+    client = await DaemonClient.open(socketPath);
+  } catch {
+    return null;
+  }
+
+  try {
+    const hello = await client.sendHello(build);
+
+    const daemonID = hello['daemonID'];
+
+    return typeof daemonID === 'string' ? daemonID : null;
+  } catch {
+    return null;
+  } finally {
+    client.stop();
+  }
+}

package/src/shared/find-daemon-record.ts

@@ -6,6 +6,9 @@ export interface DaemonRecord {
   readonly socketPath: string;
   readonly reporterSocketPath: string;
   readonly eventsSocketPath: string | null;
+
+  // The port the TCP listener bound, or null without one.
+  readonly listenPort: number | null;
 }
 
 const RECORD_SCHEMA = z.object({
@@ -13,12 +16,14 @@ const RECORD_SCHEMA = z.object({
   socketPath: z.string().min(1),
   reporterSocketPath: z.string().min(1),
   eventsSocketPath: z.string().min(1).nullable(),
+  listenPort: z.number().int().min(1).max(65_535).nullable().default(null),
 });
 
 /**
- * Reads the record a running daemon keeps in its state directory: its pid
- * and the socket paths it listens on, which a client whose environment
- * computes other socket paths uses to find it. A missing, torn, or
+ * Reads the record a running daemon keeps in its state directory: its pid,
+ * the socket paths it listens on, which a client whose environment
+ * computes other socket paths uses to find it, and the port its TCP
+ * listener bound. A missing, torn, or
  * malformed record reads as null; a record left by a crashed daemon still
  * parses, so a caller proves liveness by connecting.
  */

package/src/store/state-store.ts

@@ -785,6 +785,22 @@ export class StateStore {
     return toIdempotencyRecord(row);
   }
 
+  // The record a key holds under its principal and operation, or null when
+  // the ledger holds none.
+  async findIdempotencyKey(
+    id: Pick<IdempotencyRecord, 'principal' | 'operation' | 'key'>,
+  ): Promise<IdempotencyRecord | null> {
+    const row = await this.db
+      .selectFrom('idempotency')
+      .selectAll()
+      .where('principal', '=', id.principal)
+      .where('operation', '=', id.operation)
+      .where('key', '=', id.key)
+      .executeTakeFirst();
+
+    return row === undefined ? null : toIdempotencyRecord(row);
+  }
+
   async updateIdempotencyCompleted(
     record: Pick<IdempotencyRecord, 'principal' | 'operation' | 'key'>,
     result: string,