@zgeoff/atc 2.12.0 → 2.13.0

package/src/daemon/start-headless-turn.ts

@@ -44,10 +44,10 @@ export function startHeadlessTurn(
       cwd: s.cwd,
       prompt,
       ...(s.agentSessionID === undefined ? {} : { resume: s.agentSessionID }),
-      permissionMode: 'auto',
       sessionID,
       ...(s.model === undefined ? {} : { model: s.model }),
       ...(s.effort === undefined ? {} : { effort: s.effort }),
+      ...(s.withheldEnv.length === 0 ? {} : { withheldEnv: s.withheldEnv }),
     },
     {
       onOutput: (text) => {

package/src/daemon/start-session-bridge.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod';
+import type { EventMsg } from '../protocol/protocol';
+import type { MessageID } from '../shared/message-id';
+import type { SessionID } from '../shared/session-id';
+import { toMessageID } from '../shared/to-message-id';
+import type { MessageRecord } from '../store/message-record';
+import type { TapClient } from './daemon-connection';
+import type { HarnessRelay } from './execution-provider';
+import type { HookEvent } from './hooks';
+import { isBindingCurrent } from './is-binding-current';
+import type { BridgeBinding } from './is-binding-current';
+import { parseHookLine } from './parse-hook-line';
+
+/**
+ * The fields of a live session the bridge checks its binding against and
+ * reads the status from.
+ */
+export interface BridgeSession {
+  readonly id: SessionID;
+  readonly target: string;
+  readonly targetIdentity: string;
+  readonly hostKey: SessionID;
+  readonly bridgeEpoch: number;
+  readonly state: string;
+  readonly lastMsg: string;
+}
+
+/**
+ * What the bridge needs from the daemon. Each operation acts on the one
+ * session the caller names, which is always the bridge's own.
+ */
+export interface BridgeContext {
+  readonly findSession: (sessionID: SessionID) => BridgeSession | undefined;
+  readonly applyHookEvent: (e: HookEvent) => void;
+
+  // Applies a report under the id its reporter gave it, and settles once
+  // the report is recorded; false when the payload is no report.
+  readonly applyReport: (
+    sessionID: SessionID,
+    payload: Readonly<Record<string, unknown>>,
+    reportID: string,
+  ) => Promise<boolean>;
+  readonly attachTap: (client: TapClient, sessionID: SessionID) => 'ok' | 'missing' | 'unsupported';
+  readonly ackMessage: (
+    client: TapClient,
+    sessionID: SessionID,
+    messageID: MessageID,
+  ) => Promise<MessageRecord | 'not_tapping' | 'unknown'>;
+  readonly detachTap: (client: TapClient) => void;
+}
+
+const REQUEST_SCHEMA = z.looseObject({ v: z.literal(1), id: z.string().min(1), op: z.string() });
+
+const REPORT_SCHEMA = z.looseObject({
+  reportID: z.string().min(1).max(128),
+  payload: z.record(z.string(), z.unknown()),
+});
+
+const ACK_SCHEMA = z.looseObject({ message: z.string().min(1) });
+
+type BridgeRefusal = 'forbidden' | 'stale_binding' | 'not_tapping' | 'unknown_message';
+
+/**
+ * Serves one connection a remote harness's processes opened to the daemon:
+ * the session bridge. A line without an `op` is a hook line, as the local
+ * reporter socket takes it. A request line `{ v: 1, id, op }` gets one
+ * answer line `{ id, ok }`, and the bridge's own inbox events go out as
+ * protocol event lines.
+ *
+ * The bridge takes hooks, reports, its session's tap and acks, and its
+ * session's own status, for the one session it was bound to and nothing
+ * else: an unknown op, a malformed request, or a report or hook for any
+ * other session answers `forbidden` and closes the connection. Every line
+ * checks the binding against the live session first, and one that no
+ * longer matches answers `stale_binding` and closes.
+ *
+ * Trust: the binding holds no secret. A host serves the bridge's socket
+ * inside itself alone, so reaching the socket is the proof of being inside
+ * that host. One host is one trust domain: a sub-session in its parent's
+ * host runs as the same user and can reach the parent's socket too. The
+ * per-session socket and binding stop processes in the host from crossing
+ * sessions by accident, never a hostile process inside the same host.
+ */
+export function startSessionBridge(
+  relay: HarnessRelay,
+  binding: Readonly<BridgeBinding>,
+  ctx: BridgeContext,
+): void {
+  let closed = false;
+  let writing: Promise<void> = Promise.resolve();
+
+  // Lines go out one at a time, in the order they were written, and none
+  // after the bridge closed.
+  const writeLine = async (value: Readonly<Record<string, unknown>>) => {
+    const line = JSON.stringify(value);
+    const previous = writing;
+
+    writing = (async () => {
+      await previous;
+
+      if (!closed) {
+        try {
+          await relay.writeLine(line);
+        } catch {}
+      }
+    })();
+
+    await writing;
+  };
+
+  const stopBridge = () => {
+    if (closed) {
+      return;
+    }
+
+    closed = true;
+
+    ctx.detachTap(tap);
+    relay.close();
+  };
+
+  // Answers a refusal, then closes once the answer has gone out.
+  const answerRefusal = async (id: string | null, code: BridgeRefusal) => {
+    await writeLine({ id, ok: false, code });
+
+    stopBridge();
+  };
+
+  const tap: TapClient = {
+    sendEvent: (event: EventMsg) => {
+      void (async () => {
+        await writeLine(event);
+
+        if (event.ev === 'InboxClosed') {
+          stopBridge();
+        }
+      })();
+    },
+  };
+
+  const isCurrent = () => isBindingCurrent(binding, ctx.findSession(binding.sessionID));
+
+  const applyRequest = async (
+    request: Readonly<Record<string, unknown>>,
+    id: string,
+    op: string,
+  ) => {
+    if (op === 'report') {
+      const parsed = REPORT_SCHEMA.safeParse(request);
+
+      if (
+        !parsed.success ||
+        !(await ctx.applyReport(binding.sessionID, parsed.data.payload, parsed.data.reportID))
+      ) {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      void writeLine({ id, ok: true });
+
+      return;
+    }
+
+    if (op === 'tap.open') {
+      if (ctx.attachTap(tap, binding.sessionID) !== 'ok') {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      void writeLine({ id, ok: true });
+
+      return;
+    }
+
+    if (op === 'tap.ack') {
+      const parsed = ACK_SCHEMA.safeParse(request);
+
+      if (!parsed.success) {
+        void answerRefusal(id, 'forbidden');
+
+        return;
+      }
+
+      const acked = await ctx.ackMessage(tap, binding.sessionID, toMessageID(parsed.data.message));
+
+      if (acked === 'not_tapping' || acked === 'unknown') {
+        const code: BridgeRefusal = acked === 'unknown' ? 'unknown_message' : 'not_tapping';
+
+        void writeLine({ id, ok: false, code });
+
+        return;
+      }
+
+      void writeLine({ id, ok: true, status: acked.status });
+
+      return;
+    }
+
+    if (op === 'status.read') {
+      const s = ctx.findSession(binding.sessionID);
+
+      void writeLine({ id, ok: true, state: s?.state ?? 'exited', lastMsg: s?.lastMsg ?? '' });
+
+      return;
+    }
+
+    void answerRefusal(id, 'forbidden');
+  };
+
+  // Lines are applied one at a time, in the order they arrived.
+  let applying: Promise<void> = Promise.resolve();
+
+  const applyLine = async (line: string) => {
+    if (closed) {
+      return;
+    }
+
+    let parsed: unknown;
+
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      void answerRefusal(null, 'forbidden');
+
+      return;
+    }
+
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      void answerRefusal(null, 'forbidden');
+
+      return;
+    }
+
+    const record: Readonly<Record<string, unknown>> = Object.fromEntries(Object.entries(parsed));
+
+    if (!('op' in record)) {
+      const e = parseHookLine(line);
+
+      if (!isCurrent()) {
+        void answerRefusal(null, 'stale_binding');
+
+        return;
+      }
+
+      if (e === null || e.atcId !== binding.sessionID) {
+        void answerRefusal(null, 'forbidden');
+
+        return;
+      }
+
+      ctx.applyHookEvent(e);
+
+      return;
+    }
+
+    const request = REQUEST_SCHEMA.safeParse(record);
+
+    if (!request.success) {
+      const id = typeof record['id'] === 'string' ? record['id'] : null;
+
+      void answerRefusal(id, 'forbidden');
+
+      return;
+    }
+
+    if (!isCurrent()) {
+      void answerRefusal(request.data.id, 'stale_binding');
+
+      return;
+    }
+
+    await applyRequest(record, request.data.id, request.data.op);
+  };
+
+  relay.onLine((line) => {
+    const previous = applying;
+
+    applying = (async () => {
+      await previous;
+
+      try {
+        await applyLine(line);
+      } catch {}
+    })();
+  });
+
+  relay.onClose(() => {
+    closed = true;
+
+    ctx.detachTap(tap);
+  });
+}

package/src/mcp/mcp-tools.ts

@@ -42,6 +42,9 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
     target: SPAWN_SCHEMA.shape.target.describe(
       'Execution target for the new session, one of the target ids in atc_agents_list. Omit it to run on the default target (spawnDefaults.target). An unknown or unavailable target is refused; atc never runs the session on another target instead.',
     ),
+    workspace: SPAWN_SCHEMA.shape.workspace.describe(
+      "Where the session's working directory comes from. Omit it to run the session in cwd as it stands. With it, atc materializes a clean checkout into cwd on the target, which must not exist yet: {kind:'path', path, allowDirty?} checks out the pushed HEAD of a git checkout on the atc host, refusing uncommitted changes unless allowDirty is 'warn'; {kind:'git', url, ref or sha, credentialRef?} checks out a branch, tag, or full commit of a repository, with credentialRef {kind:'env', name} naming the atc daemon's environment variable that holds its token. A directory outside git runs in place only on a target on the atc host itself (provider local-pty), with cwd equal to its path. Submodules and Git LFS are refused, and so is a URL that carries a credential.",
+    ),
     detached: z
       .boolean()
       .optional()
@@ -353,6 +356,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
         effort: 'spawn.options',
         idempotencyKey: 'spawn.idempotency',
         target: 'spawn.target',
+        workspace: 'spawn.workspace',
       },
     },
   },
@@ -361,12 +365,15 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: AGENT_FACING_DESTRUCTIVE,
     scope: 'spawn',
     description:
-      'Type a line of text into a running session, as if the operator typed it and pressed enter. Use it to answer a session that is waiting on input.',
+      "Type a line of text into a running session and submit it, as if the operator typed it and pressed enter. atc submits the line the way the session's agent accepts one. Use it to answer a session that is waiting on input. A result of sent means atc wrote the line and its submit key to the session; it does not confirm that the agent took the line or answered it. Read the session's screen or events for that. The tool sends no raw keystrokes.",
     inputSchema: {
       type: 'object',
       properties: {
         session: { type: 'string', description: 'The atc session id' },
-        text: { type: 'string', description: 'The line to type; a newline is appended' },
+        text: {
+          type: 'string',
+          description: "The line to submit; atc adds the submit key the session's agent expects",
+        },
       },
       required: ['session', 'text'],
       additionalProperties: false,

package/src/mcp/require-daemon-features.ts

@@ -10,11 +10,14 @@ const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'message.idempotency': "atc_session_message's idempotencyKey",
   'message.turn': "atc_message_get's turn and answeredWith",
   'message.wait': "atc_message_get's waitMs",
+  'session.forget': 'session.forget',
   'session.locator': "a session's locator",
+  'session.submit': 'atc_session_input',
   'spawn.idempotency': "atc_session_spawn's idempotencyKey",
   'spawn.options': "atc_session_spawn's model and effort",
   'spawn.target': "atc_session_spawn's target",
   'request.principal': 'the target limits of a remote MCP client',
+  'spawn.workspace': "atc_session_spawn's workspace",
 };
 
 /**

package/src/mcp/run-tool.ts

@@ -46,12 +46,13 @@ export function runTool(
         ...(args['effort'] === undefined ? {} : { effort: args['effort'] }),
         ...(key === undefined ? {} : { idempotencyKey: key }),
         ...(args['target'] === undefined ? {} : { target: args['target'] }),
+        ...(args['workspace'] === undefined ? {} : { workspace: args['workspace'] }),
         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.
+      // A model, effort, key, target, or workspace 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'];
 
@@ -60,20 +61,38 @@ export function runTool(
       const targetFeatures: readonly DaemonFeature[] =
         args['target'] === undefined ? [] : ['spawn.target'];
 
-      const required = [...optionFeatures, ...keyFeatures, ...targetFeatures];
+      const workspaceFeatures: readonly DaemonFeature[] =
+        args['workspace'] === undefined ? [] : ['spawn.workspace'];
+
+      const required = [...optionFeatures, ...keyFeatures, ...targetFeatures, ...workspaceFeatures];
 
       const ok =
         nested && ctx.callerSessionID !== null
           ? await sendNestedSpawn(caller, params, ctx.callerSessionID, required)
           : await caller.sendRequest('session.spawn', params, required);
 
-      return buildObjectResult(ok['session']);
+      // A spawn whose workspace left changes behind returns its warnings
+      // beside the session's own fields.
+      const warnings = ok['warnings'];
+
+      const session =
+        warnings === undefined || !isRecord(ok['session'])
+          ? ok['session']
+          : { ...ok['session'], warnings };
+
+      return buildObjectResult(session);
     })
     .with('atc_session_input', async () => {
-      await caller.sendRequest('session.input', {
-        session: args['session'],
-        d: `${typeof args['text'] === 'string' ? args['text'] : ''}\n`,
-      });
+      // An older daemon would take the line as raw input, which some agents
+      // never submit.
+      await caller.sendRequest(
+        'session.submit',
+        {
+          session: args['session'],
+          text: typeof args['text'] === 'string' ? args['text'] : '',
+        },
+        ['session.submit'],
+      );
 
       return { text: 'sent', structured: null };
     })

package/src/protocol/daemon-features.ts

@@ -42,6 +42,17 @@ export const DAEMON_FEATURES = [
   // A request takes `as`, the principal it acts as, and `daemon.hello`
   // takes `principal`, the principal the whole connection acts as.
   'request.principal',
+
+  // `session.spawn` takes `workspace`, and a session descriptor holds the
+  // `workspace` its checkout was materialized from.
+  'spawn.workspace',
+
+  // `session.forget` exists, and a kill of a session asleep on a target that
+  // can destroy its host answers `confirmation_required`.
+  'session.forget',
+
+  // `session.submit` exists.
+  'session.submit',
 ] as const;
 
 export type DaemonFeature = (typeof DAEMON_FEATURES)[number];

package/src/protocol/protocol.ts

@@ -26,6 +26,29 @@ const ERROR_CODES = [
   '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',

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

@@ -23,6 +23,55 @@ const IDEMPOTENCY_KEY = z
   .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';
 
@@ -75,6 +124,11 @@ export const REQUEST_PARAM_SCHEMAS = {
       .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(
@@ -84,6 +138,15 @@ 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(),
@@ -96,6 +159,9 @@ export const REQUEST_PARAM_SCHEMAS = {
   'session.input': SESSION_DEFAULTED.extend({
     d: buildDefaultedString(''),
   }),
+  'session.submit': SESSION_DEFAULTED.extend({
+    text: buildDefaultedString(''),
+  }),
   'session.resize': SESSION_DEFAULTED.extend({
     cols: buildTerminalSize(0),
     rows: buildTerminalSize(0),

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,