@zgeoff/atc 2.11.0 → 2.13.0

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,40 @@ const ERROR_CODES = [
   'no_such_session',
   'session_dead',
   'unsupported',
+  'unsupported_operation',
+  'unknown_target',
+  'target_unavailable',
+  'target_changed',
+  'target_config_invalid',
+  'target_forbidden',
+  'not_a_git_repo',
+  'no_commits',
+  'unreadable_tree',
+  'has_submodules',
+  'lfs_unsupported',
+  'workspace_dirty',
+  'no_origin',
+  'invalid_git_url',
+  'unpushed_head',
+  'credential_in_url',
+  'credential_missing',
+  'ref_not_found',
+  'clone_failed',
+  'sanitize_failed',
+  'tar_failed',
+  'workspace_exists',
+  'transfer_failed',
+  'workspace_mismatch',
+  'host_unavailable',
+  'auth_not_configured',
+  'host_leased',
+  'confirmation_required',
+  'confirm_token_invalid',
   'already_answered',
   'too_slow',
+  'stale_epoch',
+  'idempotency_conflict',
+  'outcome_unknown',
   'internal',
 ] as const;
 
@@ -30,6 +62,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 +72,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 +100,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 +127,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 +142,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 +169,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,72 @@ 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();
+
+// A full commit id, SHA-1 or SHA-256.
+const COMMIT_ID = /^(?:[\da-f]{40}|[\da-f]{64})$/u;
+
+// The daemon environment variable a git workspace's token is read from.
+const CREDENTIAL_REF = z.strictObject({
+  kind: z.literal('env'),
+  name: z.string().regex(/^[A-Za-z_]\w*$/u, 'a credentialRef names an environment variable'),
+});
+
+/**
+ * Where a spawn's working directory comes from, materialized as a clean
+ * checkout into the spawn's `cwd` on its execution target. A `path` source
+ * is a directory on the daemon's host, resolved to its origin URL and
+ * pushed HEAD; `allowDirty: 'warn'` resolves a tree with uncommitted
+ * changes to HEAD and leaves the changes behind with a warning. A `git`
+ * source is a repository URL with exactly one of a branch or tag `ref` or
+ * a full commit `sha`, and an optional `credentialRef` naming the daemon
+ * environment variable that holds its token.
+ */
+const WORKSPACE_SOURCE = z.discriminatedUnion('kind', [
+  z.strictObject({
+    kind: z.literal('path'),
+    path: z
+      .string({ error: 'a path workspace requires an absolute path' })
+      .startsWith('/', 'a path workspace requires an absolute path'),
+    allowDirty: z.enum(['refuse', 'warn']).optional(),
+  }),
+  z
+    .strictObject({
+      kind: z.literal('git'),
+      url: z
+        .string({ error: 'a git workspace requires a url' })
+        .min(1, 'a git workspace requires a url')
+        .refine((url) => !url.startsWith('-'), 'a git workspace url must not start with -'),
+      ref: z
+        .string()
+        .min(1, 'a git workspace ref must not be empty')
+        .refine((ref) => !ref.startsWith('-'), 'a git workspace ref must not start with -')
+        .optional(),
+      sha: z.string().regex(COMMIT_ID, 'a git workspace sha is a full commit id').optional(),
+      credentialRef: CREDENTIAL_REF.optional(),
+    })
+    .refine((source) => (source.ref === undefined) !== (source.sha === undefined), {
+      message: 'a git workspace takes exactly one of ref or sha',
+    }),
+]);
+
+export type SpawnWorkspaceSource = z.infer<typeof WORKSPACE_SOURCE>;
+
+// 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 +90,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 +108,27 @@ 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(),
+
+    // Where the session's working directory comes from: absent runs the
+    // session in cwd as it stands, and a source materializes a clean
+    // checkout into cwd first.
+    workspace: WORKSPACE_SOURCE.optional(),
+
     // The session the new one is a sub-session of; absent or empty spawns a
     // top-level session.
     parent: z.preprocess(
@@ -54,21 +138,33 @@ export const REQUEST_PARAM_SCHEMAS = {
   }),
   'session.kill': SESSION_DEFAULTED,
   'session.ack': SESSION_DEFAULTED,
+
+  // Without a token, a forget that destroys a host answers with one; the
+  // forget that carries it destroys the host.
+  'session.forget': SESSION_DEFAULTED.extend({
+    confirmToken: z
+      .string({ error: 'session.forget confirmToken must be a string' })
+      .min(1, 'session.forget confirmToken must not be empty')
+      .optional(),
+  }),
   'session.update': SESSION_DEFAULTED.extend({
     name: buildOptionalString(),
     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.submit': SESSION_DEFAULTED.extend({
+    text: 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 +174,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 +204,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 +225,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/report.ts

@@ -1,5 +1,9 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { sendReport } from './shared/report';
 import { REPORT_KINDS } from './shared/report-kinds';
+import { sendBridgeRequest } from './shared/send-bridge-request';
 
 interface ReportOptions {
   readonly message: string;
@@ -19,7 +23,8 @@ interface ReportOptions {
  * 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.
+ * given. Inside a remote host it goes to the session bridge instead. Always
+ * exits 0 so it never blocks the session it reports on.
  */
 export async function runReport(kind: string, options: ReportOptions): Promise<void> {
   try {
@@ -37,7 +42,9 @@ export async function runReport(kind: string, options: ReportOptions): Promise<v
 
       const payload = buildReportPayload(kind, options, stdin);
 
-      if (payload !== null) {
+      if (payload !== null && process.env['ATC_BRIDGE'] === '1') {
+        await sendBridgeReport(sock, process.env['ATC_OUTBOX'] ?? '', payload);
+      } else if (payload !== null) {
         const line = `${JSON.stringify({ atcId, event: 'Report', payload })}\n`;
 
         await sendReport(sock, line, 2000);
@@ -48,6 +55,34 @@ export async function runReport(kind: string, options: ReportOptions): Promise<v
   process.exit(0);
 }
 
+// Inside a remote host, a report goes to the session bridge under an id of
+// its own, and waits in the outbox until the bridge takes or refuses it, so
+// the session's tap sends it again after a dropped connection. A resent
+// report lands once, and a refused one is never resent.
+async function sendBridgeReport(
+  sock: string,
+  outbox: string,
+  payload: Readonly<Record<string, string | readonly string[]>>,
+): Promise<void> {
+  const reportID = randomUUID();
+  const file = outbox === '' ? null : join(outbox, `${reportID}.json`);
+
+  if (file !== null) {
+    try {
+      mkdirSync(outbox, { recursive: true });
+      writeFileSync(file, JSON.stringify({ reportID, payload }));
+    } catch {}
+  }
+
+  const answer = await sendBridgeRequest(sock, 'report', { reportID, payload }, 2000);
+
+  const isFinal = answer?.['ok'] === true || answer?.['code'] === 'forbidden';
+
+  if (isFinal && file !== null) {
+    rmSync(file, { force: true });
+  }
+}
+
 function buildReportPayload(
   kind: string,
   options: ReportOptions,

package/src/run-bridge-tap.ts

@@ -0,0 +1,241 @@
+import { readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { openBridgeSocket } from './shared/open-bridge-socket';
+import type { BridgeSocket } from './shared/open-bridge-socket';
+
+const INBOX_MESSAGE_SCHEMA = z.looseObject({
+  ev: z.literal('InboxMessage'),
+  message: z.string(),
+  from: z.string(),
+  text: z.string(),
+  sentAt: z.number(),
+});
+
+const OUTBOX_REPORT_SCHEMA = z.object({
+  reportID: z.string().min(1),
+  payload: z.record(z.string(), z.unknown()),
+});
+
+// The wait before the first reconnect, doubling up to the longest.
+const FIRST_RETRY_MS = 250;
+const LONGEST_RETRY_MS = 5000;
+
+// How many message ids the tap remembers having printed.
+const SEEN_LIMIT = 10_000;
+
+// How one connection to the bridge ended: the inbox closed for good, the
+// bridge refused the tap, or the connection dropped after or before it
+// opened the tap.
+type TapEnd = 'closed' | 'refused' | 'lost' | 'unreachable';
+
+/**
+ * Streams the session's inbox to stdout from inside a remote host, through
+ * the session bridge at the given socket. It prints each message once as
+ * one NDJSON line and acks it after the line is written. A dropped
+ * connection, as a host's sleep or a daemon restart leaves it, reconnects
+ * with a growing wait of at most 5 seconds and no end; each new connection
+ * replays the messages not yet acked, and one already printed is acked
+ * again and not printed twice. Each connection also sends the reports the
+ * outbox still holds. Exits 0 once the inbox closes and 1 when the bridge
+ * refuses the tap.
+ */
+export async function runBridgeTap(socketPath: string, outbox: string): Promise<void> {
+  const seen = new Set<string>();
+
+  let wait = FIRST_RETRY_MS;
+
+  for (;;) {
+    const end = await runTapConnection(socketPath, outbox, seen);
+
+    if (end === 'closed') {
+      process.exit(0);
+    }
+
+    if (end === 'refused') {
+      console.error('atc tap: the session bridge refused the tap');
+      process.exit(1);
+    }
+
+    if (end === 'lost') {
+      wait = FIRST_RETRY_MS;
+    }
+
+    await Bun.sleep(wait);
+
+    wait = Math.min(wait * 2, LONGEST_RETRY_MS);
+  }
+}
+
+async function runTapConnection(
+  socketPath: string,
+  outbox: string,
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- the ids the tap printed, which every connection adds to
+  seen: Set<string>,
+): Promise<TapEnd> {
+  const ended = Promise.withResolvers<TapEnd>();
+  let opened = false;
+  let printing: Promise<void> = Promise.resolve();
+  let socket: BridgeSocket;
+
+  // The outbox file behind each report this connection sent, by request id.
+  let sent = new Map<string, string>();
+
+  const onLine = (line: Readonly<Record<string, unknown>>) => {
+    if (line['ev'] === 'InboxClosed') {
+      ended.resolve('closed');
+
+      return;
+    }
+
+    if (line['id'] === 'tap.open') {
+      if (line['ok'] !== true) {
+        ended.resolve('refused');
+
+        return;
+      }
+
+      opened = true;
+      sent = sendOutboxReports(socket, outbox);
+
+      return;
+    }
+
+    // A report the bridge took, or one it refuses outright, leaves the
+    // outbox: no resend would change the answer. Only the file this
+    // connection sent under the answered id is removed.
+    if (typeof line['id'] === 'string' && line['id'].startsWith('report:')) {
+      const path = sent.get(line['id']);
+
+      if (path !== undefined && (line['ok'] === true || line['code'] === 'forbidden')) {
+        sent.delete(line['id']);
+
+        rmSync(path, { force: true });
+      }
+
+      return;
+    }
+
+    if (line['ok'] === false && line['code'] === 'stale_binding') {
+      ended.resolve('refused');
+
+      return;
+    }
+
+    const msg = INBOX_MESSAGE_SCHEMA.safeParse(line);
+
+    if (!msg.success) {
+      return;
+    }
+
+    const message = msg.data;
+    const previous = printing;
+
+    printing = (async () => {
+      await previous;
+
+      if (!seen.has(message.message)) {
+        const printed = `${JSON.stringify({ id: message.message, from: message.from, text: message.text, sentAt: message.sentAt })}\n`;
+
+        try {
+          await Bun.write(Bun.stdout, printed);
+        } catch {
+          process.exit(1);
+        }
+
+        updateSeenIDs(seen, message.message);
+      }
+
+      socket.writeLine({
+        v: 1,
+        id: `ack:${message.message}`,
+        op: 'tap.ack',
+        message: message.message,
+      });
+    })();
+  };
+
+  try {
+    socket = await openBridgeSocket(socketPath, onLine);
+  } catch {
+    return 'unreachable';
+  }
+
+  void (async () => {
+    await socket.closed;
+
+    const end: TapEnd = opened ? 'lost' : 'unreachable';
+
+    ended.resolve(end);
+  })();
+
+  socket.writeLine({ v: 1, id: 'tap.open', op: 'tap.open' });
+
+  const end = await ended.promise;
+
+  await printing.catch(() => {});
+
+  socket.end();
+
+  return end;
+}
+
+// Sends every report the outbox holds, and returns the file behind each
+// request id it sent; a file that is no report is removed, since no answer
+// would ever clear it.
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a socket is a live handle
+function sendOutboxReports(socket: BridgeSocket, outbox: string): Map<string, string> {
+  const sent = new Map<string, string>();
+
+  let files: string[];
+
+  try {
+    files = readdirSync(outbox).filter((file) => file.endsWith('.json'));
+  } catch {
+    return sent;
+  }
+
+  for (const file of files) {
+    const path = join(outbox, file);
+    let report: z.infer<typeof OUTBOX_REPORT_SCHEMA> | null = null;
+
+    try {
+      const parsed = OUTBOX_REPORT_SCHEMA.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+
+      report = parsed.success ? parsed.data : null;
+    } catch {}
+
+    if (report === null) {
+      rmSync(path, { force: true });
+      continue;
+    }
+
+    const id = `report:${report.reportID}`;
+
+    sent.set(id, path);
+
+    socket.writeLine({
+      v: 1,
+      id,
+      op: 'report',
+      reportID: report.reportID,
+      payload: report.payload,
+    });
+  }
+
+  return sent;
+}
+
+// oxlint-disable-next-line prefer-readonly-parameter-types -- the set grows in place
+function updateSeenIDs(seen: Set<string>, id: string): void {
+  seen.add(id);
+
+  for (const oldest of seen) {
+    if (seen.size <= SEEN_LIMIT) {
+      break;
+    }
+
+    seen.delete(oldest);
+  }
+}

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-clean-env.ts

@@ -3,14 +3,22 @@
  * scrubbed out. A child that inherits those variables behaves as part of
  * the parent session — Claude transcripts nest, and Grok joins the
  * parent's in-process dashboard — which breaks resume and isolation.
+ *
+ * Variables named in `withheld` are left out of what the child inherits,
+ * such as a workspace credential that only the daemon's own git commands
+ * may see. The extras the caller sets explicitly are added after, so one
+ * of them is kept even when it shares a withheld name.
  */
 export function collectCleanEnv(
   extra: Readonly<Record<string, string>> = {},
+  withheld: readonly string[] = [],
 ): Record<string, string> {
   const env: Record<string, string> = {};
 
+  const skipped = new Set(withheld);
+
   for (const [key, value] of Object.entries(process.env)) {
-    if (value === undefined || isParentSessionKey(key)) {
+    if (value === undefined || isParentSessionKey(key) || skipped.has(key)) {
       continue;
     }