@zgeoff/atc 2.10.3 → 2.11.0

package/src/mcp/run-tool.ts

@@ -1,18 +1,34 @@
 import { match } from 'ts-pattern';
 import { DaemonError } from '../protocol/daemon-error';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { isRecord } from '../shared/report';
 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'];
@@ -32,7 +48,7 @@ export function runTool(
           ? await sendNestedSpawn(caller, params, ctx.callerSessionID)
           : await caller.sendRequest('session.spawn', params);
 
-      return JSON.stringify(ok['session'], null, 2);
+      return buildObjectResult(ok['session']);
     })
     .with('atc_session_input', async () => {
       await caller.sendRequest('session.input', {
@@ -40,12 +56,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 +73,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 +115,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'];
@@ -113,16 +148,33 @@ export function runTool(
         from,
       });
 
-      return JSON.stringify(ok, null, 2);
+      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.

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,18 @@
+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.
 export interface FleetCaller {
   readonly sendRequest: (
     m: string,
     p?: Readonly<Record<string, unknown>>,
+    required?: readonly DaemonFeature[],
   ) => 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-features.ts

@@ -0,0 +1,23 @@
+/**
+ * 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',
+] as const;
+
+export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/parse-daemon-features.ts

@@ -0,0 +1,19 @@
+import type { DaemonFeature } from './daemon-features';
+import { DAEMON_FEATURES } from './daemon-features';
+
+/**
+ * Reads the features a `daemon.hello` answer announces. A missing or
+ * malformed list, which an older daemon sends, is no features, and a name
+ * this build does not know is dropped.
+ */
+export function parseDaemonFeatures(
+  hello: Readonly<Record<string, unknown>>,
+): ReadonlySet<DaemonFeature> {
+  const announced = hello['features'];
+
+  if (!Array.isArray(announced)) {
+    return new Set();
+  }
+
+  return new Set(DAEMON_FEATURES.filter((feature) => announced.includes(feature)));
+}

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

@@ -24,6 +24,7 @@ export const REQUEST_PARAM_SCHEMAS = {
   'daemon.quit': z.object({}),
   'session.list': z.object({}),
   'dirs.list': z.object({}),
+  'agents.list': z.object({}),
   'fleet.list': z.object({}),
   'fleet.restore': z.object({
     cols: buildDefaultedNumber(80),
@@ -96,7 +97,13 @@ export const REQUEST_PARAM_SCHEMAS = {
   'events.read': z.object({
     cursor: buildOptionalCursor(),
     limit: buildDefaultedNumber(50).transform((v) => Math.min(Math.max(Math.trunc(v), 1), 200)),
-    waitMs: buildDefaultedNumber(0).transform((v) => Math.min(Math.max(Math.trunc(v), 0), 30_000)),
+    waitMs: buildDefaultedWait(),
+
+    // Limits the read to one session's events; absent or empty reads the whole fleet.
+    session: z.preprocess(
+      (v) => (typeof v === 'string' && v !== '' ? v : undefined),
+      z.string().transform(toSessionID).optional(),
+    ),
   }),
   'session.message': SESSION_DEFAULTED.extend({
     from: buildDefaultedNonEmptyString('unknown'),
@@ -104,7 +111,10 @@ export const REQUEST_PARAM_SCHEMAS = {
   }).refine((v) => v.text !== '', { message: 'session.message requires text' }),
   'session.tap': SESSION_DEFAULTED,
   'message.get': z
-    .object({ message: buildDefaultedString('').transform(toMessageID) })
+    .object({
+      message: buildDefaultedString('').transform(toMessageID),
+      waitMs: buildDefaultedWait(),
+    })
     .refine((v) => v.message !== '', { message: 'message.get requires a message' }),
   'message.ack': SESSION_DEFAULTED.extend({
     message: buildDefaultedString('').transform(toMessageID),
@@ -119,6 +129,12 @@ function buildDefaultedNumber(fallback: number) {
   return z.preprocess((v) => (typeof v === 'number' ? v : undefined), z.number().default(fallback));
 }
 
+// How long a read may hold its request open, in milliseconds: 0 when absent,
+// clamped to 0–30000.
+function buildDefaultedWait() {
+  return buildDefaultedNumber(0).transform((v) => Math.min(Math.max(Math.trunc(v), 0), 30_000));
+}
+
 function buildDefaultedBooleanOrString(fallback: boolean | string) {
   return z.preprocess(
     (v) => (typeof v === 'boolean' || typeof v === 'string' ? v : undefined),

package/src/report.ts

@@ -3,13 +3,21 @@ import { REPORT_KINDS } from './shared/report-kinds';
 
 interface ReportOptions {
   readonly message: string;
+
+  // Comma-separated ids of every message one turn answered, reported together.
+  readonly messages: string;
   readonly label: string;
+
+  // The turn whose final reply an `answered` report carries; empty when unknown.
+  readonly turn: string;
 }
 
 /**
  * Runs inside wrangled sessions: reads stdin verbatim and forwards it to the
  * atc socket as a Report envelope of the given kind. An `answered` report
- * carries stdin as the final text for the given message; a `note` carries
+ * carries stdin as the final reply of the turn that carried the given
+ * message, or every given message at once, plus that turn's id when one is
+ * given; a `note` carries
  * it as text for the user under the given label, `progress` when none is
  * given. Always exits 0 so it never blocks the session it reports on.
  */
@@ -44,9 +52,18 @@ function buildReportPayload(
   kind: string,
   options: ReportOptions,
   stdin: string,
-): Record<string, string> | null {
+): Record<string, string | readonly string[]> | null {
   if (kind === 'answered') {
-    return options.message === '' ? null : { kind, message: options.message, answer: stdin };
+    const messages = options.messages.split(',').filter((id) => id !== '');
+    const turn = options.turn === '' ? {} : { turn: options.turn };
+
+    if (messages.length > 0) {
+      return { kind, messages, answer: stdin, ...turn };
+    }
+
+    return options.message === ''
+      ? null
+      : { kind, message: options.message, answer: stdin, ...turn };
   }
 
   if (kind === 'note') {

package/src/store/message-record.ts

@@ -15,4 +15,7 @@ export interface MessageRecord {
   readonly deliveredAt?: number;
   readonly answeredAt?: number;
   readonly answer?: string;
+
+  // The turn whose final reply the answer is, when the reporter gave one.
+  readonly turn?: string;
 }