@zgeoff/atc 2.10.4 → 2.12.0

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/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,25 +16,40 @@ 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({}),
   'session.list': z.object({}),
   'dirs.list': z.object({}),
+  '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,
@@ -44,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(
@@ -58,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',
   }),
@@ -77,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({
@@ -96,15 +127,28 @@ 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'),
     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
-    .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),
@@ -115,10 +159,32 @@ 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));
 }
 
+// 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/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 };
+}