@zgeoff/atc 2.11.0 → 2.12.0

package/src/mcp/run-tool.ts

@@ -1,7 +1,9 @@
+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';
 
 /**
@@ -33,20 +35,37 @@ export function runTool(
     .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 buildObjectResult(ok['session']);
     })
@@ -142,11 +161,19 @@ export function runTool(
           ? given
           : ctx.sender.name;
 
-      const ok = await caller.sendRequest('session.message', {
-        session: args['session'],
-        text: args['text'],
-        from,
-      });
+      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);
     })
@@ -177,19 +204,44 @@ function buildObjectResult(value: unknown): ToolResult {
 
 // 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/types.ts

@@ -6,11 +6,13 @@ import type { openMCPAuth } from './open-mcp-auth';
 // 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>>;
 }

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

@@ -18,6 +18,30 @@ export const DAEMON_FEATURES = [
 
   // `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];

package/src/protocol/protocol.ts

@@ -5,7 +5,7 @@ import { isRecord } from '../shared/report';
  * per line. Three message kinds, distinguished by which fields are present —
  * request (id + m), response (id + ok or err), event (ev).
  */
-export const PROTOCOL_V = 3;
+export const PROTOCOL_V = 4;
 
 // Control lines are capped before buffering; PTY output is split into chunks
 // so a queued response is delayed by at most one chunk.
@@ -20,8 +20,17 @@ const ERROR_CODES = [
   'no_such_session',
   'session_dead',
   'unsupported',
+  'unsupported_operation',
+  'unknown_target',
+  'target_unavailable',
+  'target_changed',
+  'target_config_invalid',
+  'target_forbidden',
   'already_answered',
   'too_slow',
+  'stale_epoch',
+  'idempotency_conflict',
+  'outcome_unknown',
   'internal',
 ] as const;
 
@@ -30,6 +39,9 @@ export type ErrorCode = (typeof ERROR_CODES)[number];
 interface ProtocolError {
   readonly code: ErrorCode;
   readonly msg: string;
+
+  // Structured detail an error code defines for itself.
+  readonly data?: Readonly<Record<string, unknown>>;
 }
 
 export interface RequestMsg {
@@ -37,6 +49,10 @@ export interface RequestMsg {
   readonly id: number;
   readonly m: string;
   readonly p?: Readonly<Record<string, unknown>>;
+
+  // The principal the request acts as, which narrows what the connection
+  // may reach for this request alone.
+  readonly as?: string;
 }
 
 export interface ResponseMsg {
@@ -61,7 +77,9 @@ export type DecodedMsg =
 /**
  * Classifies one NDJSON line. Unknown fields pass through untouched so
  * additive evolution never breaks a peer; a line that parses but fits no
- * message kind is malformed, and the caller closes the connection.
+ * message kind is malformed, and the caller closes the connection. An error
+ * code this build does not know decodes as `internal` with its message
+ * kept, so a peer that adds a code never breaks one that predates it.
  */
 export function decodeMessage(line: string): DecodedMsg {
   let parsed: unknown;
@@ -86,6 +104,13 @@ export function decodeMessage(line: string): DecodedMsg {
 
   if (typeof parsed['m'] === 'string') {
     const p = parsed['p'];
+    const as = parsed['as'];
+
+    // A principal that is not a string would otherwise drop out and leave the
+    // request with the connection's whole reach.
+    if (as !== undefined && (typeof as !== 'string' || as === '')) {
+      return { kind: 'malformed', reason: 'as must be a non-empty string' };
+    }
 
     return {
       kind: 'request',
@@ -94,21 +119,22 @@ export function decodeMessage(line: string): DecodedMsg {
         id: parsed['id'],
         m: parsed['m'],
         ...(isRecord(p) ? { p } : {}),
+        ...(as === undefined ? {} : { as }),
       },
     };
   }
 
   const ok = parsed['ok'];
-  const err = parsed['err'];
+  const err = parseProtocolError(parsed['err']);
 
-  if (isRecord(ok) || isProtocolError(err)) {
+  if (isRecord(ok) || err !== null) {
     return {
       kind: 'response',
       msg: {
         v: parsed['v'],
         id: parsed['id'],
         ...(isRecord(ok) ? { ok } : {}),
-        ...(isProtocolError(err) ? { err } : {}),
+        ...(err === null ? {} : { err }),
       },
     };
   }
@@ -120,10 +146,17 @@ export function encodeMessage(msg: EventMsg | RequestMsg | ResponseMsg): string
   return `${JSON.stringify(msg)}\n`;
 }
 
-function isProtocolError(value: unknown): value is ProtocolError {
-  return (
-    isRecord(value) &&
-    typeof value['msg'] === 'string' &&
-    ERROR_CODES.some((code) => code === value['code'])
-  );
+function parseProtocolError(value: unknown): ProtocolError | null {
+  if (!isRecord(value) || typeof value['msg'] !== 'string' || typeof value['code'] !== 'string') {
+    return null;
+  }
+
+  const raw = value['code'];
+  const data = value['data'];
+
+  return {
+    code: ERROR_CODES.find((code) => code === raw) ?? 'internal',
+    msg: value['msg'],
+    ...(isRecord(data) ? { data } : {}),
+  };
 }

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

@@ -16,9 +16,23 @@ const SESSION_DEFAULTED = z.object({
   session: buildDefaultedString('').transform(toSessionID),
 });
 
+// The idempotency key a spawn or message may carry, at most 200 characters.
+const IDEMPOTENCY_KEY = z
+  .string({ error: 'idempotencyKey must be a string' })
+  .min(1, 'idempotencyKey must not be empty')
+  .max(200, 'idempotencyKey must be at most 200 characters')
+  .optional();
+
+// The refusal of a terminal size outside the range a terminal takes.
+const TERMINAL_SIZE_ERROR = 'cols and rows must be whole numbers from 1 to 4096';
+
 export const REQUEST_PARAM_SCHEMAS = {
   'daemon.hello': z.object({
     client: buildDefaultedString('unknown client'),
+    principal: z
+      .string({ error: 'daemon.hello principal must be a non-empty string' })
+      .min(1, 'daemon.hello principal must be a non-empty string')
+      .optional(),
   }),
   'daemon.ping': z.object({}),
   'daemon.quit': z.object({}),
@@ -27,15 +41,15 @@ export const REQUEST_PARAM_SCHEMAS = {
   'agents.list': z.object({}),
   'fleet.list': z.object({}),
   'fleet.restore': z.object({
-    cols: buildDefaultedNumber(80),
-    rows: buildDefaultedNumber(24),
+    cols: buildTerminalSize(80),
+    rows: buildTerminalSize(24),
   }),
   'session.spawn': z.object({
     cwd: z.string({ error: 'session.spawn requires a cwd' }).min(1, 'session.spawn requires a cwd'),
     name: buildDefaultedString(''),
     prompt: buildDefaultedString(''),
-    cols: buildDefaultedNumber(80),
-    rows: buildDefaultedNumber(24),
+    cols: buildTerminalSize(80),
+    rows: buildTerminalSize(24),
 
     resume: buildDefaultedBooleanOrString(false).transform((v) =>
       typeof v === 'string' ? toAgentSessionID(v) : v,
@@ -45,6 +59,22 @@ export const REQUEST_PARAM_SCHEMAS = {
       .min(1, 'session.spawn agent must be a non-empty agent id')
       .optional(),
 
+    // Per-session overrides; the daemon checks each against what the agent
+    // advertises before anything spawns.
+    model: z.string({ error: 'session.spawn model must be a string' }).optional(),
+    effort: z.string({ error: 'session.spawn effort must be a string' }).optional(),
+
+    // A retry carrying the same key replays the first spawn's answer instead
+    // of spawning again.
+    idempotencyKey: IDEMPOTENCY_KEY,
+
+    // The execution target the session runs on; absent runs on the default
+    // target, and a target the daemon cannot use refuses the spawn.
+    target: z
+      .string({ error: 'session.spawn target must be a non-empty target id' })
+      .min(1, 'session.spawn target must be a non-empty target id')
+      .optional(),
+
     // The session the new one is a sub-session of; absent or empty spawns a
     // top-level session.
     parent: z.preprocess(
@@ -59,16 +89,16 @@ export const REQUEST_PARAM_SCHEMAS = {
     pinned: buildOptionalBoolean(),
   }),
   'session.attach': SESSION_DEFAULTED.extend({
-    cols: buildDefaultedNumber(80),
-    rows: buildDefaultedNumber(24),
+    cols: buildTerminalSize(80),
+    rows: buildTerminalSize(24),
   }),
   'session.detach': SESSION_DEFAULTED,
   'session.input': SESSION_DEFAULTED.extend({
     d: buildDefaultedString(''),
   }),
   'session.resize': SESSION_DEFAULTED.extend({
-    cols: buildDefaultedNumber(0),
-    rows: buildDefaultedNumber(0),
+    cols: buildTerminalSize(0),
+    rows: buildTerminalSize(0),
   }).refine((v) => v.cols >= 1 && v.rows >= 1, {
     message: 'session.resize requires positive cols and rows',
   }),
@@ -78,8 +108,8 @@ export const REQUEST_PARAM_SCHEMAS = {
     prompt: buildDefaultedNonEmptyString(EJECT_DEFAULT_PROMPT),
   }),
   'session.adopt': SESSION_DEFAULTED.extend({
-    cols: buildDefaultedNumber(80),
-    rows: buildDefaultedNumber(24),
+    cols: buildTerminalSize(80),
+    rows: buildTerminalSize(24),
   }),
   'permission.respond': z
     .object({
@@ -108,6 +138,10 @@ export const REQUEST_PARAM_SCHEMAS = {
   'session.message': SESSION_DEFAULTED.extend({
     from: buildDefaultedNonEmptyString('unknown'),
     text: buildDefaultedString(''),
+
+    // A retry carrying the same key replays the first send's message
+    // instead of sending another.
+    idempotencyKey: IDEMPOTENCY_KEY,
   }).refine((v) => v.text !== '', { message: 'session.message requires text' }),
   'session.tap': SESSION_DEFAULTED,
   'message.get': z
@@ -125,6 +159,22 @@ function buildDefaultedString(fallback: string) {
   return z.preprocess((v) => (typeof v === 'string' ? v : undefined), z.string().default(fallback));
 }
 
+// A terminal dimension: absent or not a number takes the fallback, and a
+// number must be a whole number in range, since the terminal emulator and
+// the PTY both assume one and a fractional size throws only after the
+// process starts.
+function buildTerminalSize(fallback: number) {
+  return z.preprocess(
+    (v) => (typeof v === 'number' ? v : undefined),
+    z
+      .number({ error: TERMINAL_SIZE_ERROR })
+      .int(TERMINAL_SIZE_ERROR)
+      .min(1, TERMINAL_SIZE_ERROR)
+      .max(4096, TERMINAL_SIZE_ERROR)
+      .default(fallback),
+  );
+}
+
 function buildDefaultedNumber(fallback: number) {
   return z.preprocess((v) => (typeof v === 'number' ? v : undefined), z.number().default(fallback));
 }

package/src/shared/agent-session-id.ts

@@ -3,6 +3,6 @@ import type { Tagged } from 'type-fest';
 /**
  * The session id an agent CLI issues for its own resume mechanism — what
  * `claude --resume <id>` takes. Adapters mint it from a hook payload or a
- * stored fleet row, and the fleet table keys on it.
+ * stored fleet row, and a fleet row holds at most one.
  */
 export type AgentSessionID = Tagged<string, 'AgentSessionID'>;

package/src/shared/collect-principals.ts

@@ -0,0 +1,51 @@
+import { isRecord } from './report';
+
+interface PrincipalsConfig {
+  // The targets each principal may use, by principal; null when the config
+  // has no `principals` key.
+  readonly principals: ReadonlyMap<string, readonly string[]> | null;
+  readonly errors: readonly string[];
+}
+
+/**
+ * Reads the `principals` map: each principal's id to the names of the
+ * targets it may use. No `principals` key is null. Otherwise the config
+ * fails closed: a malformed map grants nothing to anyone, and a malformed
+ * entry grants nothing to its principal. Each problem is an error.
+ */
+export function collectPrincipals(raw: unknown): PrincipalsConfig {
+  if (raw === undefined) {
+    return { principals: null, errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return {
+      principals: new Map(),
+      errors: ['principals must be an object of principal ids, so no principal gets a target'],
+    };
+  }
+
+  const principals = new Map<string, readonly string[]>();
+
+  const errors: string[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    const targets = isRecord(entry) ? entry['targets'] : undefined;
+
+    if (
+      id === '' ||
+      !Array.isArray(targets) ||
+      !targets.every((target) => typeof target === 'string' && target !== '')
+    ) {
+      errors.push(
+        `principal ${JSON.stringify(id)} must be an object whose targets is an array of target names, so it gets no target`,
+      );
+
+      continue;
+    }
+
+    principals.set(id, targets);
+  }
+
+  return { principals, errors };
+}

package/src/shared/collect-targets.ts

@@ -0,0 +1,144 @@
+import { formatJSONKind } from './format-json-kind';
+import { isRecord } from './report';
+
+/**
+ * A named place sessions run: the execution provider kind that serves it,
+ * and the options that kind takes.
+ */
+export interface TargetConfig {
+  readonly id: string;
+  readonly provider: string;
+  readonly options: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A config problem that leaves a target, or every target, unusable: the
+ * config file as a whole, the `targets` map, one entry of it, or
+ * `defaultTarget`.
+ */
+export type TargetConfigError = TargetSectionError | ConfigFileError;
+
+interface TargetSectionError {
+  readonly scope: 'targets' | 'target' | 'defaultTarget';
+
+  // The entry the problem is in; present only for an entry's problem.
+  readonly target?: string;
+  readonly problem: string;
+}
+
+/**
+ * A config file that exists but cannot be used, so no target in it can be
+ * trusted: `config_malformed` when its text is not JSON or its root is not
+ * an object, `config_unreadable` when reading it fails for any reason but
+ * its absence. `detail` holds the parse message, the root's kind, or the
+ * read's error code.
+ */
+interface ConfigFileError {
+  readonly scope: 'config';
+  readonly problem: 'config_malformed' | 'config_unreadable';
+  readonly path: string;
+  readonly detail: string;
+}
+
+interface TargetsConfig {
+  // Every well-formed entry, in config order.
+  readonly targets: readonly TargetConfig[];
+
+  // The target a spawn without a target runs on, or null when the config
+  // gives none it can use.
+  readonly defaultTarget: string | null;
+  readonly errors: readonly TargetConfigError[];
+}
+
+// The target a config holds when it sets no targets of its own: the
+// daemon's own machine.
+const LOCAL_TARGET: TargetConfig = { id: 'local', provider: 'local-pty', options: {} };
+
+/**
+ * Reads the `targets` map and `defaultTarget`. No `targets` key holds the
+ * one implicit `local` target as the default. Otherwise the config fails
+ * closed: a malformed map holds no targets, a malformed entry is left out,
+ * and a `defaultTarget` that is not a string or matches no well-formed
+ * entry leaves no default. Each problem is an error, so a spawn that
+ * resolves through it fails with that error instead of running on `local`.
+ * Without `defaultTarget`, the default is the `local` entry when the map
+ * holds a well-formed one, and none otherwise.
+ */
+export function collectTargets(rawTargets: unknown, rawDefault: unknown): TargetsConfig {
+  if (rawTargets === undefined && rawDefault === undefined) {
+    return { targets: [LOCAL_TARGET], defaultTarget: 'local', errors: [] };
+  }
+
+  const collected = collectTargetEntries(rawTargets);
+
+  const ids = new Set(collected.targets.map((target) => target.id));
+
+  if (rawDefault === undefined) {
+    return {
+      targets: collected.targets,
+      defaultTarget: ids.has('local') ? 'local' : null,
+      errors: collected.errors,
+    };
+  }
+
+  if (typeof rawDefault === 'string' && ids.has(rawDefault)) {
+    return { targets: collected.targets, defaultTarget: rawDefault, errors: collected.errors };
+  }
+
+  // The problem gives the value's kind, never the value: a wrongly typed
+  // defaultTarget can hold anything the file holds.
+  const problem =
+    typeof rawDefault === 'string'
+      ? 'defaultTarget: matches no well-formed target in targets'
+      : `defaultTarget: expected a string, got ${formatJSONKind(rawDefault)}`;
+
+  return {
+    targets: collected.targets,
+    defaultTarget: null,
+    errors: [...collected.errors, { scope: 'defaultTarget', problem }],
+  };
+}
+
+interface TargetEntries {
+  readonly targets: readonly TargetConfig[];
+  readonly errors: readonly TargetSectionError[];
+}
+
+function collectTargetEntries(raw: unknown): TargetEntries {
+  // A defaultTarget without a targets map names one of the implicit targets.
+  if (raw === undefined) {
+    return { targets: [LOCAL_TARGET], errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw) || Object.keys(raw).length === 0) {
+    return {
+      targets: [],
+      errors: [
+        { scope: 'targets', problem: 'targets must be a non-empty object of named targets' },
+      ],
+    };
+  }
+
+  const targets: TargetConfig[] = [];
+  const errors: TargetSectionError[] = [];
+
+  for (const [id, entry] of Object.entries(raw)) {
+    const provider = isRecord(entry) ? entry['provider'] : undefined;
+
+    if (id === '' || !isRecord(entry) || typeof provider !== 'string' || provider === '') {
+      errors.push({
+        scope: 'target',
+        target: id,
+        problem: `target ${JSON.stringify(id)} must be an object with a non-empty string provider`,
+      });
+
+      continue;
+    }
+
+    const { provider: _, ...options } = entry;
+
+    targets.push({ id, provider, options });
+  }
+
+  return { targets, errors };
+}