@zgeoff/atc 2.19.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

@@ -48,6 +48,7 @@ const ERROR_CODES = [
   'github_unavailable',
   'host_unavailable',
   'auth_not_configured',
+  'auth_target_unsupported',
   'host_leased',
   'confirmation_required',
   'confirm_token_invalid',
@@ -56,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/collect-auth-profiles.ts

@@ -0,0 +1,122 @@
+import { isRecord } from './report';
+
+/**
+ * A named reference to a credential impd holds: the secret's name, never
+ * its value, and the rule impd applies when a request reaches the host,
+ * plus the profiles a session selecting this one needs beside it. Only
+ * the `custom` kind and the `bearer` scheme are bound.
+ */
+export interface AuthProfile {
+  readonly name: string;
+  readonly secret: string;
+  readonly kind: 'custom';
+  readonly host: string;
+  readonly header: string;
+  readonly scheme: 'bearer';
+  readonly dependencies: readonly string[];
+}
+
+interface AuthProfiles {
+  readonly profiles: ReadonlyMap<string, AuthProfile>;
+  readonly errors: readonly string[];
+}
+
+/**
+ * Reads the `authProfiles` map under impd's own rules for secret names,
+ * broker hosts and header names. A profile that breaks a rule is left out
+ * with an error, so a gateway that selects it is refused rather than bound
+ * to a rule impd would reject or apply differently. Dependencies are
+ * names only here; whether they resolve is a property of each selection.
+ */
+export function collectAuthProfiles(raw: unknown): AuthProfiles {
+  if (raw === undefined) {
+    return { profiles: new Map(), errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return { profiles: new Map(), errors: ['authProfiles must be an object of named profiles'] };
+  }
+
+  const profiles = new Map<string, AuthProfile>();
+
+  const errors: string[] = [];
+
+  for (const [name, entry] of Object.entries(raw)) {
+    const parsed = parseAuthProfile(name, entry);
+
+    if (typeof parsed === 'string') {
+      errors.push(`authProfiles.${name}: ${parsed}`);
+    } else {
+      profiles.set(name, parsed);
+    }
+  }
+
+  return { profiles, errors };
+}
+
+// impd's secret name rule: an imp name's form, so a secret name is never a
+// path or a flag.
+const SECRET_NAME = /^[a-z][a-z0-9-]{0,30}$/;
+
+// impd's broker host rule: a lowercase hostname as a CONNECT carries it, with
+// no port and no wildcard, whose last label starts with a letter so an IP
+// address never matches.
+const BROKER_HOST = /^(?:[a-z0-9][a-z0-9-]{0,62}\.)+[a-z][a-z0-9-]{0,62}$/;
+const BROKER_HOST_MAX = 253;
+
+// impd's header name rule.
+const HEADER_NAME = /^[a-z0-9-]{1,64}$/;
+
+// The profile an entry holds, or the first rule it breaks.
+function parseAuthProfile(name: string, entry: unknown): AuthProfile | string {
+  if (!isRecord(entry) || Array.isArray(entry)) {
+    return 'a profile must be an object';
+  }
+
+  const secret = entry['secret'];
+  const host = entry['host'];
+  const header = entry['header'];
+  const scheme = entry['scheme'];
+  const dependencies = entry['dependencies'];
+
+  if (entry['kind'] !== undefined && entry['kind'] !== 'custom') {
+    return 'kind must be custom, the one kind atc binds';
+  }
+
+  if (typeof secret !== 'string' || !SECRET_NAME.test(secret)) {
+    return 'secret must be a lowercase letter followed by up to 30 lowercase letters, digits or hyphens';
+  }
+
+  if (typeof host !== 'string' || host.length > BROKER_HOST_MAX || !BROKER_HOST.test(host)) {
+    return 'host must be a lowercase hostname such as api.example.com';
+  }
+
+  if (typeof header !== 'string' || !HEADER_NAME.test(header)) {
+    return 'header must be a lowercase header name such as authorization';
+  }
+
+  if (scheme !== 'bearer') {
+    return 'scheme must be bearer, the one scheme atc binds';
+  }
+
+  if (entry['user'] !== undefined) {
+    return 'user pairs only with the basic scheme, which atc does not bind';
+  }
+
+  if (
+    dependencies !== undefined &&
+    (!Array.isArray(dependencies) || !dependencies.every((dep) => typeof dep === 'string'))
+  ) {
+    return 'dependencies must be an array of profile names';
+  }
+
+  return {
+    name,
+    secret,
+    kind: 'custom',
+    host,
+    header,
+    scheme,
+    dependencies: dependencies ?? [],
+  };
+}