@zgeoff/atc 2.10.4 → 2.12.0

package/src/mcp/run-tool.ts

@@ -1,38 +1,73 @@
+import { createHash } from 'node:crypto';
 import { match } from 'ts-pattern';
 import { DaemonError } from '../protocol/daemon-error';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { isRecord } from '../shared/report';
+import { parseIdempotencyKey } from './parse-idempotency-key';
 import type { FleetCaller, ToolContext } from './types';
 
+/**
+ * A tool's result: the text every client reads, and for a tool whose result
+ * is data, that data as an object for clients that read structured content.
+ */
+interface ToolResult {
+  readonly text: string;
+  readonly structured: Readonly<Record<string, unknown>> | null;
+}
+
 export function runTool(
   caller: FleetCaller,
   name: string,
   args: Readonly<Record<string, unknown>>,
   ctx: ToolContext,
-): Promise<string> {
+): Promise<ToolResult> {
   return match(name)
     .with('atc_session_list', async () => {
       const ok = await caller.sendRequest('session.list');
 
-      return JSON.stringify(ok['sessions'], null, 2);
+      // The text stays the bare list older clients read; structured content
+      // has to be an object.
+      return {
+        text: JSON.stringify(ok['sessions'], null, 2),
+        structured: { sessions: ok['sessions'] },
+      };
     })
     .with('atc_session_spawn', async () => {
       const rawAgent = args['agent'];
       const nested = args['detached'] !== true && ctx.callerSessionID !== null;
+      const key = parseIdempotencyKey(args['idempotencyKey']);
 
       const params = {
         cwd: args['cwd'],
         ...(typeof args['name'] === 'string' ? { name: args['name'] } : {}),
         ...(typeof args['prompt'] === 'string' ? { prompt: args['prompt'] } : {}),
         ...(rawAgent === undefined ? {} : { agent: rawAgent }),
+        ...(args['model'] === undefined ? {} : { model: args['model'] }),
+        ...(args['effort'] === undefined ? {} : { effort: args['effort'] }),
+        ...(key === undefined ? {} : { idempotencyKey: key }),
+        ...(args['target'] === undefined ? {} : { target: args['target'] }),
         cols: 100,
         rows: 30,
       };
 
+      // A model, effort, key, or target needs a daemon that takes them; the check
+      // runs on every connection the spawn rides.
+      const optionFeatures: readonly DaemonFeature[] =
+        args['model'] === undefined && args['effort'] === undefined ? [] : ['spawn.options'];
+
+      const keyFeatures: readonly DaemonFeature[] = key === undefined ? [] : ['spawn.idempotency'];
+
+      const targetFeatures: readonly DaemonFeature[] =
+        args['target'] === undefined ? [] : ['spawn.target'];
+
+      const required = [...optionFeatures, ...keyFeatures, ...targetFeatures];
+
       const ok =
         nested && ctx.callerSessionID !== null
-          ? await sendNestedSpawn(caller, params, ctx.callerSessionID)
-          : await caller.sendRequest('session.spawn', params);
+          ? await sendNestedSpawn(caller, params, ctx.callerSessionID, required)
+          : await caller.sendRequest('session.spawn', params, required);
 
-      return JSON.stringify(ok['session'], null, 2);
+      return buildObjectResult(ok['session']);
     })
     .with('atc_session_input', async () => {
       await caller.sendRequest('session.input', {
@@ -40,12 +75,15 @@ export function runTool(
         d: `${typeof args['text'] === 'string' ? args['text'] : ''}\n`,
       });
 
-      return 'sent';
+      return { text: 'sent', structured: null };
     })
     .with('atc_session_screen', async () => {
       const ok = await caller.sendRequest('session.screen', { session: args['session'] });
 
-      return typeof ok['text'] === 'string' ? ok['text'] : JSON.stringify(ok);
+      return {
+        text: typeof ok['text'] === 'string' ? ok['text'] : JSON.stringify(ok),
+        structured: null,
+      };
     })
     .with('atc_session_update', async () => {
       await caller.sendRequest('session.update', {
@@ -54,32 +92,40 @@ export function runTool(
         ...(typeof args['pinned'] === 'boolean' ? { pinned: args['pinned'] } : {}),
       });
 
-      return 'updated';
+      return { text: 'updated', structured: null };
     })
     .with('atc_session_kill', async () => {
       await caller.sendRequest('session.kill', { session: args['session'] });
 
-      return 'killed';
+      return { text: 'killed', structured: null };
     })
     .with('atc_session_ack', async () => {
       await caller.sendRequest('session.ack', { session: args['session'] });
 
-      return 'acked';
+      return { text: 'acked', structured: null };
     })
     .with('atc_resume_command', async () => {
       const ok = await caller.sendRequest('session.resumeCommand', { session: args['session'] });
 
-      return typeof ok['command'] === 'string' ? ok['command'] : JSON.stringify(ok);
+      return {
+        text: typeof ok['command'] === 'string' ? ok['command'] : JSON.stringify(ok),
+        structured: null,
+      };
     })
     .with('atc_dirs_list', async () => {
       const ok = await caller.sendRequest('dirs.list');
 
-      return JSON.stringify(ok['dirs'], null, 2);
+      return { text: JSON.stringify(ok['dirs'], null, 2), structured: { dirs: ok['dirs'] } };
+    })
+    .with('atc_agents_list', async () => {
+      const ok = await caller.sendRequest('agents.list', {}, ['agents.list']);
+
+      return buildObjectResult(ok);
     })
     .with('atc_session_get', async () => {
       const ok = await caller.sendRequest('session.get', { session: args['session'] });
 
-      return JSON.stringify(ok, null, 2);
+      return buildObjectResult(ok);
     })
     .with('atc_session_read', async () => {
       const ok = await caller.sendRequest('session.read', {
@@ -88,16 +134,24 @@ export function runTool(
         ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
       });
 
-      return JSON.stringify(ok, null, 2);
+      return buildObjectResult(ok);
     })
     .with('atc_events_read', async () => {
-      const ok = await caller.sendRequest('events.read', {
-        ...(typeof args['cursor'] === 'string' ? { cursor: args['cursor'] } : {}),
-        ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
-        ...(typeof args['waitMs'] === 'number' ? { waitMs: args['waitMs'] } : {}),
-      });
-
-      return JSON.stringify(ok, null, 2);
+      const filtered = typeof args['session'] === 'string' && args['session'] !== '';
+      const required: DaemonFeature[] = filtered ? ['events.session'] : [];
+
+      const ok = await caller.sendRequest(
+        'events.read',
+        {
+          ...(typeof args['cursor'] === 'string' ? { cursor: args['cursor'] } : {}),
+          ...(typeof args['limit'] === 'number' ? { limit: args['limit'] } : {}),
+          ...(typeof args['waitMs'] === 'number' ? { waitMs: args['waitMs'] } : {}),
+          ...(typeof args['session'] === 'string' ? { session: args['session'] } : {}),
+        },
+        required,
+      );
+
+      return buildObjectResult(ok);
     })
     .with('atc_session_message', async () => {
       const given = args['from'];
@@ -107,37 +161,87 @@ export function runTool(
           ? given
           : ctx.sender.name;
 
-      const ok = await caller.sendRequest('session.message', {
-        session: args['session'],
-        text: args['text'],
-        from,
-      });
-
-      return JSON.stringify(ok, null, 2);
+      const key = parseIdempotencyKey(args['idempotencyKey']);
+      const required: DaemonFeature[] = key === undefined ? [] : ['message.idempotency'];
+
+      const ok = await caller.sendRequest(
+        'session.message',
+        {
+          session: args['session'],
+          text: args['text'],
+          from,
+          ...(key === undefined ? {} : { idempotencyKey: key }),
+        },
+        required,
+      );
+
+      return buildObjectResult(ok);
     })
     .with('atc_message_get', async () => {
-      const ok = await caller.sendRequest('message.get', { message: args['message'] });
-
-      return JSON.stringify(ok, null, 2);
+      const waits = typeof args['waitMs'] === 'number' && args['waitMs'] > 0;
+      const required: DaemonFeature[] = waits ? ['message.wait'] : [];
+
+      const ok = await caller.sendRequest(
+        'message.get',
+        {
+          message: args['message'],
+          ...(typeof args['waitMs'] === 'number' ? { waitMs: args['waitMs'] } : {}),
+        },
+        required,
+      );
+
+      return buildObjectResult(ok);
     })
     .otherwise(() => Promise.reject(new Error(`unknown tool '${name}'`)));
 }
 
+function buildObjectResult(value: unknown): ToolResult {
+  return {
+    text: JSON.stringify(value, null, 2),
+    structured: isRecord(value) ? value : null,
+  };
+}
+
 // The inherited id can point at a session another daemon hosts, or one
 // this daemon no longer lists; the spawn then lands top-level instead of
-// failing the tool call.
+// failing the tool call. The top-level spawn has a different payload, so it
+// runs under its own key, a fixed-length hash of the caller's: a retry of the
+// tool call derives the same key and replays it rather than conflicting with
+// the nested attempt's key, and the derived key fits the daemon's cap
+// whatever the caller's length. An answer
+// that holds an effect id is a keyed spawn that already ran, which a
+// top-level spawn would only duplicate.
 async function sendNestedSpawn(
   caller: FleetCaller,
   params: Readonly<Record<string, unknown>>,
   parent: string,
+  required: readonly DaemonFeature[],
 ): Promise<Readonly<Record<string, unknown>>> {
   try {
-    return await caller.sendRequest('session.spawn', { ...params, parent });
+    return await caller.sendRequest('session.spawn', { ...params, parent }, required);
   } catch (error) {
-    if (error instanceof DaemonError && error.code === 'no_such_session') {
-      return caller.sendRequest('session.spawn', params);
+    if (
+      error instanceof DaemonError &&
+      error.code === 'no_such_session' &&
+      error.data?.['effectRef'] === undefined
+    ) {
+      return caller.sendRequest('session.spawn', buildTopLevelParams(params), required);
     }
 
     throw error;
   }
 }
+
+function buildTopLevelParams(
+  params: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  const key = params['idempotencyKey'];
+
+  if (typeof key !== 'string') {
+    return params;
+  }
+
+  const digest = createHash('sha256').update(key).digest('hex');
+
+  return { ...params, idempotencyKey: `top-level:${digest}` };
+}

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

@@ -30,6 +30,9 @@ interface MCPHTTPServerOptions {
   readonly dbPath: string;
   readonly printApproval: (line: string) => void;
 
+  // Receives one line per request the server answers.
+  readonly printRequest: (line: string) => void;
+
   // How long a rotated refresh token still answers with its successor.
   readonly refreshReuseSeconds?: number;
 }
@@ -38,19 +41,24 @@ interface MCPHTTPServerOptions {
  * A running MCP HTTP server.
  */
 export interface MCPHTTPServer {
-  // The local address the server listens on.
+  // The loopback address the server answers on, for clients on this machine.
   readonly url: string;
 
+  // The address the server is bound to.
+  readonly listening: string;
+
   // The public origin: the OAuth issuer.
   readonly origin: string;
   readonly stop: () => Promise<void>;
 }
 
 /**
- * Serves atc's MCP tools over streamable HTTP at `/mcp`, with better-auth as
- * the OAuth 2.1 authorization server in the same process. Only the routes a
- * connector and the operator's browser need reach better-auth; every other
- * path is a 404. A request whose Host header is not the server's own is
+ * Serves atc's MCP tools over streamable HTTP at `/mcp` and `/`, with
+ * better-auth as the OAuth 2.1 authorization server in the same process. Only
+ * the routes a connector and the operator's browser need reach better-auth;
+ * every other path is a 404. Each answered request prints one line with its
+ * 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.
  */
@@ -81,23 +89,33 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
     idleTimeout: 60,
     maxRequestBodySize: MAX_LINE,
     fetch: async (request, bunServer) => {
+      const startedAt = performance.now();
       const state = holder.ready;
+      let rpc: RPCLabel | null = null;
+      let response: Response;
 
       if (state === null) {
-        return new Response(null, { status: 503 });
+        response = new Response(null, { status: 503 });
+      } else {
+        try {
+          response = await answerHTTPRequest(
+            state,
+            request,
+            bunServer.requestIP(request)?.address ?? null,
+            (label) => {
+              rpc = label;
+            },
+          );
+        } catch {
+          response = new Response(null, { status: 503 });
+        }
       }
 
-      try {
-        const answered = await answerHTTPRequest(
-          state,
-          request,
-          bunServer.requestIP(request)?.address ?? null,
-        );
+      options.printRequest(
+        formatRequestLine(request, rpc, response.status, performance.now() - startedAt),
+      );
 
-        return answered;
-      } catch {
-        return new Response(null, { status: 503 });
-      }
+      return response;
     },
   });
 
@@ -141,6 +159,7 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
 
   return {
     url: local,
+    listening: formatBindURL(options.host, port),
     origin,
     stop: async () => {
       await server.stop(true);
@@ -149,25 +168,101 @@ export async function startMCPHTTPServer(options: MCPHTTPServerOptions): Promise
   };
 }
 
+// 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;
+
+  return `http://${bracketed}:${port}`;
+}
+
 interface ServerState {
   readonly hosts: ReadonlySet<string>;
   readonly origins: ReadonlySet<string>;
   readonly ctx: HTTPServerContext;
 }
 
+// MCP answers at `/` as well as at `/mcp`, for a client configured with the
+// bare origin. Both are the one resource `<origin>/mcp`.
+const MCP_PATHS: ReadonlySet<string> = new Set(['/mcp', '/']);
+
+// The JSON-RPC method and tool name of an MCP request, for its request line.
+interface RPCLabel {
+  readonly method: string;
+  readonly tool: string | null;
+}
+
+function findRPCLabel(body: string): RPCLabel | null {
+  let message: unknown;
+
+  try {
+    message = JSON.parse(body);
+  } catch {
+    return null;
+  }
+
+  if (!isRecord(message) || typeof message['method'] !== 'string') {
+    return null;
+  }
+
+  const params = message['params'];
+
+  return {
+    method: message['method'],
+    tool: isRecord(params) && typeof params['name'] === 'string' ? params['name'] : null,
+  };
+}
+
+// Client-sent values in a request line are cut to this many characters.
+const LABEL_LENGTH = 64;
+
+// The line names the path without its query, which carries authorization
+// codes and signed state.
+function formatRequestLine(
+  request: Request,
+  rpc: RPCLabel | null,
+  status: number,
+  durationMs: number,
+): string {
+  const path = new URL(request.url).pathname;
+
+  const version = request.headers.get('mcp-protocol-version');
+
+  const fields = [
+    request.method,
+    toLogText(path, 128),
+    String(status),
+    `${Math.round(durationMs)}ms`,
+    ...(rpc === null ? [] : [`rpc=${toLogText(rpc.method, LABEL_LENGTH)}`]),
+    ...(rpc === null || rpc.tool === null ? [] : [`tool=${toLogText(rpc.tool, LABEL_LENGTH)}`]),
+    ...(version === null ? [] : [`mcp-protocol-version=${toLogText(version, LABEL_LENGTH)}`]),
+  ];
+
+  return fields.join(' ');
+}
+
+// Control and format characters are dropped, so a client cannot write
+// escape sequences into the operator's terminal.
+function toLogText(value: string, length: number): string {
+  return value.replaceAll(/[\p{Cc}\p{Cf}\s]/gu, '').slice(0, length);
+}
+
 // The better-auth routes a connector calls directly.
-const PASSED_THROUGH: ReadonlySet<string> = new Set([
+const PASSED_THROUGH: ReadonlySet<string> = new Set(['POST /oauth2/revoke']);
+
+// Both paths serve the protected resource metadata for `<origin>/mcp`.
+const RESOURCE_METADATA: ReadonlySet<string> = new Set([
   'GET /.well-known/oauth-protected-resource',
   'GET /.well-known/oauth-protected-resource/mcp',
-  'POST /oauth2/revoke',
 ]);
 
 // `socketAddress` is the peer the request arrived from: the requester, or the
-// proxy or tunnel in front of atc.
+// proxy or tunnel in front of atc. `onRPC` receives an accepted MCP request's
+// JSON-RPC method and tool, for its request line.
 async function answerHTTPRequest(
   state: ServerState,
   request: Request,
   socketAddress: string | null,
+  onRPC: (label: RPCLabel | null) => void,
 ): Promise<Response> {
   const host = request.headers.get('host');
 
@@ -187,7 +282,7 @@ async function answerHTTPRequest(
     return ctx.store.auth.handler(toPublicRequest(ctx, request, url));
   }
 
-  if (route === 'GET /.well-known/oauth-authorization-server') {
+  if (route === 'GET /.well-known/oauth-authorization-server' || RESOURCE_METADATA.has(route)) {
     return answerMetadataRequest(ctx, request, url);
   }
 
@@ -226,7 +321,7 @@ async function answerHTTPRequest(
         });
   }
 
-  if (url.pathname === '/mcp') {
+  if (MCP_PATHS.has(url.pathname)) {
     if (isForeignOrigin) {
       return new Response(null, { status: 403 });
     }
@@ -235,10 +330,14 @@ async function answerHTTPRequest(
       return new Response(null, { status: 405, headers: { allow: 'POST' } });
     }
 
+    const body = await request.text();
+
+    onRPC(findRPCLabel(body));
+
     return answerMCPRequest(ctx, {
       authorization: request.headers.get('authorization'),
       protocolVersion: request.headers.get('mcp-protocol-version'),
-      body: await request.text(),
+      body,
     });
   }
 
@@ -253,7 +352,8 @@ function toPublicRequest(ctx: HTTPServerContext, request: Request, url: URL): Re
 }
 
 // The metadata advertises only what atc's clients can use: public clients
-// with no client authentication, and no introspection endpoint.
+// with no client authentication, no introspection endpoint, and Bearer
+// tokens alone, so nothing about DPoP.
 async function answerMetadataRequest(
   ctx: HTTPServerContext,
   request: Request,
@@ -267,9 +367,15 @@ async function answerMetadataRequest(
   }
 
   const advertised = Object.fromEntries(
-    Object.entries(metadata).filter(([key]) => !key.startsWith('introspection_')),
+    Object.entries(metadata).filter(
+      ([key]) => !key.startsWith('introspection_') && !key.startsWith('dpop_'),
+    ),
   );
 
+  if (RESOURCE_METADATA.has(`${request.method} ${url.pathname}`)) {
+    return Response.json(advertised, { status: response.status });
+  }
+
   return Response.json({
     ...advertised,
     token_endpoint_auth_methods_supported: ['none'],

package/src/mcp/types.ts

@@ -1,12 +1,20 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
 import type { ApprovalState } from './approval-state';
 import type { openMCPAuth } from './open-mcp-auth';
 
-// The slice of the daemon client the tool handlers need.
+// 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
+// ride, every time it is sent, and refused unsent when that daemon lacks one.
+// A request with a principal acts as that principal.
 export interface FleetCaller {
   readonly sendRequest: (
     m: string,
     p?: Readonly<Record<string, unknown>>,
+    required?: readonly DaemonFeature[],
+    principal?: string,
   ) => Promise<Readonly<Record<string, unknown>>>;
+  readonly readFeatures: () => Promise<ReadonlySet<DaemonFeature>>;
 }
 
 export interface ToolContext {

package/src/mcp-http-server.ts

@@ -43,9 +43,14 @@ export async function runMCPHTTPServer(build: string, flags: MCPHTTPFlags): Prom
     printApproval: (line) => {
       console.log(line.replaceAll(/[\p{Cc}\p{Cf}]/gu, ''));
     },
+
+    // Request lines go to stderr, so stdout keeps the approval lines alone.
+    printRequest: (line) => {
+      console.error(line);
+    },
   });
 
-  console.log(`atc mcp --http: serving ${server.origin}/mcp, listening on ${server.url}`);
+  console.log(`atc mcp --http: serving ${server.origin}/mcp, listening on ${server.listening}`);
 
   const admin = await openMCPAuth({ dbPath: mcpAuthDBFile, origin: null });
   const clients = await collectClients(admin.db);

package/src/mcp-server.ts

@@ -1,5 +1,6 @@
 import { bootDaemonClient } from './client/boot-daemon';
 import { answerRPCRequest } from './mcp/answer-rpc-request';
+import { requireDaemonFeatures } from './mcp/require-daemon-features';
 import type { FleetCaller, ToolContext } from './mcp/types';
 
 /**
@@ -12,6 +13,17 @@ export async function runMCPServer(build: string): Promise<void> {
 
   const client = boot.client;
 
+  // The connection lives as long as the server, so the features its
+  // handshake announced hold for every call.
+  const caller: FleetCaller = {
+    sendRequest: (m, p, required = []) => {
+      requireDaemonFeatures(boot.features, required);
+
+      return client.sendRequest(m, p);
+    },
+    readFeatures: () => Promise.resolve(boot.features),
+  };
+
   // The server inherits the calling session's id from its environment, so a
   // spawn from inside a session nests under it by default.
   const inherited = process.env['ATC_SESSION_ID'];
@@ -48,7 +60,7 @@ export async function runMCPServer(build: string): Promise<void> {
 
       void (async () => {
         try {
-          await answerRPCLine(client, build, toolContext, line);
+          await answerRPCLine(caller, build, toolContext, line);
         } catch {
           // A failed line gets no response, the way a malformed one gets none.
         } finally {

package/src/protocol/daemon-error.ts

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

package/src/protocol/daemon-features.ts

@@ -0,0 +1,47 @@
+/**
+ * The request features a daemon announces in its `daemon.hello` answer. A
+ * daemon from before the list existed announces none, so a client that
+ * outlives an upgrade sees exactly what the running daemon serves.
+ */
+export const DAEMON_FEATURES = [
+  // `agents.list` exists.
+  'agents.list',
+
+  // `events.read` returns `more`.
+  'events.more',
+
+  // `events.read` takes a `session` filter.
+  'events.session',
+
+  // `message.get` returns `turn` and `answeredWith`.
+  'message.turn',
+
+  // `message.get` takes `waitMs`.
+  'message.wait',
+
+  // `session.spawn` takes `model` and `effort`, and `agents.list` returns
+  // `spawnOptions`.
+  'spawn.options',
+
+  // `daemon.hello` returns `daemonID`.
+  'daemon.id',
+
+  // Every session descriptor holds a `locator`.
+  'session.locator',
+
+  // `session.spawn` takes `idempotencyKey`.
+  'spawn.idempotency',
+
+  // `session.message` takes `idempotencyKey`.
+  'message.idempotency',
+
+  // `session.spawn` takes `target`, and `agents.list` returns `targets`,
+  // `spawnDefaults`, `configRevision`, and `targetErrors`.
+  'spawn.target',
+
+  // A request takes `as`, the principal it acts as, and `daemon.hello`
+  // takes `principal`, the principal the whole connection acts as.
+  'request.principal',
+] as const;
+
+export type DaemonFeature = (typeof DAEMON_FEATURES)[number];