@zgeoff/atc 2.12.0 → 2.14.0

package/src/daemon/build-execution-targets.ts

@@ -1,4 +1,5 @@
-import type { TargetConfig } from '../shared/collect-targets';
+import type { TargetConfig, TargetConfigError } from '../shared/collect-targets';
+import { buildImpProvider } from './build-imp-provider';
 import { buildTargetIdentity } from './build-target-identity';
 import type { ExecutionProvider } from './execution-provider';
 import { LocalPTYProvider } from './local-pty-provider';
@@ -19,16 +20,54 @@ export interface ExecutionTarget {
   readonly provider: ExecutionProvider | null;
 }
 
+/**
+ * The targets the daemon serves, and the problems with their entries that
+ * only the daemon's environment shows.
+ */
+export interface ExecutionTargetsBuild {
+  readonly targets: ExecutionTarget[];
+  readonly errors: TargetConfigError[];
+}
+
 /**
  * Builds one target per configured entry, in config order, each with a
- * provider of its kind when this daemon has one.
+ * provider of its kind when this daemon has one. An entry whose provider
+ * cannot start from `env` keeps no provider and adds a target error.
  */
-export function buildExecutionTargets(configs: readonly TargetConfig[]): ExecutionTarget[] {
-  return configs.map((config) => ({
-    id: config.id,
-    kind: config.provider,
-    options: config.options,
-    identity: buildTargetIdentity(config.provider, config.options),
-    provider: config.provider === 'local-pty' ? new LocalPTYProvider() : null,
-  }));
+export function buildExecutionTargets(
+  configs: readonly TargetConfig[],
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): ExecutionTargetsBuild {
+  const errors: TargetConfigError[] = [];
+
+  const targets = configs.map((config) => {
+    const built = buildProvider(config, env);
+
+    if (built.problem !== null) {
+      errors.push({ scope: 'target', target: config.id, problem: built.problem });
+    }
+
+    return {
+      id: config.id,
+      kind: config.provider,
+      options: config.options,
+      identity: buildTargetIdentity(config.provider, config.options),
+      provider: built.provider,
+    };
+  });
+
+  return { targets, errors };
+}
+
+function buildProvider(
+  config: TargetConfig,
+  env: Readonly<Record<string, string | undefined>>,
+): Readonly<{ provider: ExecutionProvider | null; problem: string | null }> {
+  if (config.provider === 'local-pty') {
+    return { provider: new LocalPTYProvider(), problem: null };
+  }
+
+  return config.provider === 'imp'
+    ? buildImpProvider(config.id, config.options, env)
+    : { provider: null, problem: null };
 }

package/src/daemon/build-imp-provider.ts

@@ -0,0 +1,68 @@
+import { ImpClientPort } from './imp-client-port';
+import { ImpProvider } from './imp-provider';
+
+/**
+ * The provider of an `imp` target, or the problem that keeps it from one.
+ * A problem never includes the token or any other environment value.
+ */
+export interface ImpProviderBuild {
+  readonly provider: ImpProvider | null;
+  readonly problem: string | null;
+}
+
+/**
+ * The provider of target `id` from its `imp` options: `url` is where impd
+ * listens, and `tokenEnv` holds the name of the daemon's environment
+ * variable that carries the token, so no credential sits in the config.
+ * `image`, `memoryMib`, `guestDir`, and `guestATC` pass through. No
+ * provider when `url` is missing, so the target lists and refuses every
+ * spawn. A `tokenEnv` that is not a non-empty string, or whose variable is
+ * unset or empty in `env`, is a problem and leaves no provider; a target
+ * without `tokenEnv` calls impd with no token.
+ */
+export function buildImpProvider(
+  id: string,
+  options: Readonly<Record<string, unknown>>,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): ImpProviderBuild {
+  const url = options['url'];
+  const tokenEnv = options['tokenEnv'];
+
+  if (typeof url !== 'string' || url === '') {
+    return { provider: null, problem: null };
+  }
+
+  if (tokenEnv !== undefined && (typeof tokenEnv !== 'string' || tokenEnv === '')) {
+    return {
+      provider: null,
+      problem: `target ${JSON.stringify(id)} must give tokenEnv as a non-empty string`,
+    };
+  }
+
+  const token = tokenEnv === undefined ? null : env[tokenEnv];
+
+  if (token === undefined || token === '') {
+    return {
+      provider: null,
+      problem: `target ${JSON.stringify(id)} reads its impd token from ${String(tokenEnv)}, which is unset or empty in the daemon's environment`,
+    };
+  }
+
+  const provider = new ImpProvider(new ImpClientPort({ url, token }), {
+    ...pickString(options, 'image'),
+    ...pickString(options, 'guestDir'),
+    ...pickString(options, 'guestATC'),
+    ...(typeof options['memoryMib'] === 'number' ? { memoryMib: options['memoryMib'] } : {}),
+  });
+
+  return { provider, problem: null };
+}
+
+function pickString(
+  options: Readonly<Record<string, unknown>>,
+  key: 'image' | 'guestDir' | 'guestATC',
+): Partial<Record<typeof key, string>> {
+  const value = options[key];
+
+  return typeof value === 'string' && value !== '' ? { [key]: value } : {};
+}

package/src/daemon/build-report-trail-entry.ts

@@ -5,14 +5,16 @@ import type { TrailEntry } from '../store/trail-entry';
 import type { NoteReport } from './parse-report';
 
 /**
- * The trail entry for one note a session reported, carrying its label and a
- * preview of its text.
+ * The trail entry for one note a session reported, carrying its label, its
+ * text and a preview of it, and the id its reporter gave it, when it gave
+ * one.
  */
 export function buildReportTrailEntry(
   sessionID: SessionID,
   agentSessionID: AgentSessionID | undefined,
   report: Readonly<NoteReport>,
   reportedAt: number,
+  reportID?: string,
 ): TrailEntry {
   return {
     at: reportedAt,
@@ -21,5 +23,7 @@ export function buildReportTrailEntry(
     kind: 'report',
     label: report.label,
     detail: truncateDetail(report.text),
+    text: report.text,
+    ...(reportID === undefined ? {} : { reportID }),
   };
 }

package/src/daemon/build-report-view.ts

@@ -0,0 +1,41 @@
+import { encodeCursor } from '../protocol/encode-cursor';
+import type { StoredReport } from '../store/state-store';
+import type { SessionDescriptor } from './sessions';
+
+/**
+ * One report as `report.get` returns it: the cursor of its event, when it
+ * arrived, the session that sent it and that session's name, its label, its
+ * text, and whether that text is whole.
+ */
+export interface ReportView {
+  readonly report: string;
+  readonly at: number;
+  readonly session: string;
+  readonly name: string | null;
+  readonly label: string;
+  readonly text: string;
+  readonly complete: boolean;
+}
+
+export function buildReportView(
+  stored: StoredReport,
+  sessions: readonly SessionDescriptor[],
+): ReportView {
+  // A row written before atc session ids stayed stable across restores
+  // carries an earlier atc id, so the agent session id links it.
+  const live =
+    (stored.agentSessionID === null
+      ? undefined
+      : sessions.find((s) => s.agentSessionID === stored.agentSessionID)) ??
+    sessions.find((s) => s.id === stored.atcID);
+
+  return {
+    report: encodeCursor({ kind: 'events', id: stored.id }),
+    at: stored.at,
+    session: live?.id ?? stored.atcID,
+    name: live?.name ?? null,
+    label: stored.label,
+    text: stored.text,
+    complete: stored.complete,
+  };
+}

package/src/daemon/build-scoped-context.ts

@@ -187,8 +187,11 @@ export function buildScopedContext(
     },
     writeSessionInput: (sessionID, data) =>
       canSee(sessionID) ? ctx.writeSessionInput(sessionID, data) : 'missing',
+    writeSessionLine: (sessionID, text) =>
+      canSee(sessionID) ? ctx.writeSessionLine(sessionID, text) : 'missing',
     ejectSession: (id, prompt) => (canSee(id) ? ctx.ejectSession(id, prompt) : 'missing'),
-    adoptSession: (id, cols, rows) => (canSee(id) ? ctx.adoptSession(id, cols, rows) : 'missing'),
+    adoptSession: (id, cols, rows) =>
+      canSee(id) ? ctx.adoptSession(id, cols, rows) : Promise.resolve('missing' as const),
     resizeSession: (client, sessionID, dims) =>
       canSee(sessionID) && ctx.resizeSession(client, sessionID, dims),
     readSessionRecord: (id) =>
@@ -200,6 +203,11 @@ export function buildScopedContext(
 
       return ctx.readEvents(afterID, limit, waitMs, sessionID, merged);
     },
+    readReport: (id, outer) => {
+      const merged = outer === null ? access : outer.merge(access);
+
+      return ctx.readReport(id, merged);
+    },
     writeSessionMessage: (sessionID, from, text, keyed) =>
       canSee(sessionID)
         ? ctx.writeSessionMessage(sessionID, from, text, buildPrincipalKey(keyed))

package/src/daemon/build-session-lifecycle.ts

@@ -0,0 +1,52 @@
+/**
+ * A session's lifecycle as four layers, each owned by one actor:
+ *
+ * - `desired`: what the operator asked for. `run` keeps the harness
+ *   running, `sleep` keeps its host asleep with the harness inside it, and
+ *   `stop` leaves the harness ended.
+ * - `vm`: the host the harness runs on. `none` is the daemon's own machine,
+ *   which has no lifecycle of its own; `awake`, `asleep`, and `unknown` are
+ *   the last state the daemon saw of a remote host.
+ * - `harness`: the agent process. `suspended` is a process kept inside a
+ *   sleeping host, which a revive brings back as it was.
+ * - `attachment`: the daemon's own connection to the harness's output.
+ *   `local` is a harness in the daemon's process tree; `attached`,
+ *   `reattaching`, and `detached` follow the connection to a remote one.
+ */
+export interface SessionLifecycle {
+  readonly desired: 'run' | 'sleep' | 'stop';
+  readonly vm: 'none' | 'awake' | 'asleep' | 'unknown';
+  readonly harness: 'running' | 'suspended' | 'exited';
+  readonly attachment: 'local' | 'attached' | 'reattaching' | 'detached';
+}
+
+// The session facts the layers derive from.
+interface LifecycleFacts {
+  readonly desired: SessionLifecycle['desired'];
+  readonly vm: SessionLifecycle['vm'];
+  readonly attachment: SessionLifecycle['attachment'];
+
+  // Whether the harness is kept inside a sleeping host.
+  readonly suspended: boolean;
+  readonly hasHarness: boolean;
+  readonly kind: 'pty' | 'headless';
+  readonly state: 'running' | 'needs_you' | 'done' | 'exited';
+}
+
+/**
+ * Builds the four layers from a session's facts. The harness runs while the
+ * session holds a terminal or a live headless run. A harness without one is
+ * suspended while it is kept inside a sleeping host, and exited otherwise.
+ */
+export function buildSessionLifecycle(facts: Readonly<LifecycleFacts>): SessionLifecycle {
+  const running = facts.hasHarness || (facts.kind === 'headless' && facts.state !== 'exited');
+  let harness: SessionLifecycle['harness'] = 'exited';
+
+  if (running) {
+    harness = 'running';
+  } else if (facts.suspended && facts.vm === 'asleep') {
+    harness = 'suspended';
+  }
+
+  return { desired: facts.desired, vm: facts.vm, harness, attachment: facts.attachment };
+}

package/src/daemon/build-tar-archive.ts

@@ -0,0 +1,85 @@
+/**
+ * One file in an archive: its path relative to the directory it unpacks
+ * into, its bytes, and its permission bits.
+ */
+export interface ArchiveFile {
+  readonly path: string;
+  readonly content: string | Uint8Array;
+  readonly mode?: number;
+}
+
+const BLOCK = 512;
+
+/**
+ * Packs files into a POSIX ustar archive that `tar -x` unpacks, each with
+ * its parent directories created on the way. A path longer than ustar
+ * holds is refused.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- file bytes have no readonly form
+export function buildTarArchive(files: readonly ArchiveFile[]): Uint8Array {
+  const encoder = new TextEncoder();
+
+  const blocks: Uint8Array[] = [];
+
+  for (const file of files) {
+    const content = typeof file.content === 'string' ? encoder.encode(file.content) : file.content;
+
+    blocks.push(
+      buildHeader(file.path, content.length, file.mode ?? 0o644),
+      content,
+      new Uint8Array((BLOCK - (content.length % BLOCK)) % BLOCK),
+    );
+  }
+
+  // Two empty blocks end the archive.
+  blocks.push(new Uint8Array(BLOCK * 2));
+
+  const archive = new Uint8Array(blocks.reduce((total, block) => total + block.length, 0));
+
+  let at = 0;
+
+  for (const block of blocks) {
+    archive.set(block, at);
+
+    at += block.length;
+  }
+
+  return archive;
+}
+
+function buildHeader(path: string, size: number, mode: number): Uint8Array {
+  const encoder = new TextEncoder();
+
+  const name = encoder.encode(path);
+
+  if (name.length > 100) {
+    throw new Error(`archive path is longer than 100 bytes: ${path}`);
+  }
+
+  const header = new Uint8Array(BLOCK);
+
+  header.set(name, 0);
+  header.set(encoder.encode(formatOctal(mode, 8)), 100);
+  header.set(encoder.encode(formatOctal(0, 8)), 108);
+  header.set(encoder.encode(formatOctal(0, 8)), 116);
+  header.set(encoder.encode(formatOctal(size, 12)), 124);
+  header.set(encoder.encode(formatOctal(0, 12)), 136);
+
+  // The checksum counts its own field as spaces.
+  header.set(encoder.encode('        '), 148);
+
+  header[156] = '0'.codePointAt(0) ?? 0;
+
+  header.set(encoder.encode('ustar\u000000'), 257);
+
+  const checksum = header.reduce((total, byte) => total + byte, 0);
+
+  header.set(encoder.encode(`${checksum.toString(8).padStart(6, '0')}\u0000 `), 148);
+
+  return header;
+}
+
+// An octal number padded to fill its field, ending in a NUL.
+function formatOctal(value: number, width: number): string {
+  return `${value.toString(8).padStart(width - 1, '0')}\u0000`;
+}

package/src/daemon/daemon-connection.ts

@@ -1,4 +1,4 @@
-import { basename } from 'node:path';
+import { basename, isAbsolute } from 'node:path';
 import type { AgentAdapter, AgentID, SpawnOptions, SpawnOverrides } from '../agents/agent-adapter';
 import { DaemonError } from '../protocol/daemon-error';
 import { DAEMON_FEATURES } from '../protocol/daemon-features';
@@ -15,6 +15,7 @@ import {
   encodeMessage,
 } from '../protocol/protocol';
 import type { ErrorCode, EventMsg, RequestMsg } from '../protocol/protocol';
+import type { SpawnWorkspaceSource } from '../protocol/request-param-schemas';
 import type { TargetConfigError } from '../shared/collect-targets';
 import type { DaemonID } from '../shared/daemon-id';
 import type { MessageID } from '../shared/message-id';
@@ -27,6 +28,7 @@ import type { Dims } from './attach-registry';
 import type { AgentEntry } from './build-agent-list';
 import type { FleetEvent } from './build-fleet-events';
 import { buildPayloadHash } from './build-payload-hash';
+import type { ReportView } from './build-report-view';
 import { buildScopedContext } from './build-scoped-context';
 import type { TargetEntry } from './build-target-list';
 import type { KeyedRequest } from './idempotency-ledger';
@@ -49,6 +51,10 @@ export interface SpawnParams {
   readonly parent: SessionID | null;
   readonly overrides: SpawnOverrides;
   readonly target: string;
+
+  // Where the session's working directory comes from; null runs the
+  // session in cwd as it stands.
+  readonly workspace: SpawnWorkspaceSource | null;
 }
 
 interface SessionRecord {
@@ -61,6 +67,15 @@ interface SessionRecord {
 
 // A transcript page with the file it came from, so a cursor into a replaced
 // transcript is distinguishable from one into a grown transcript.
+/**
+ * What `session.forget` answers: the token a forget that destroys a host
+ * must carry, with the time it stops being taken; or the forgotten session,
+ * with whether its host was destroyed.
+ */
+type ForgetResult =
+  | { readonly confirmToken: string; readonly expiresAt: number }
+  | { readonly forgotten: true; readonly destroyed: boolean };
+
 interface SessionTranscriptRead {
   readonly path: string;
   readonly page: TranscriptPage;
@@ -99,6 +114,10 @@ export interface DaemonContext {
   // without a target when the config gives no default.
   readonly resolveSpawnTarget: (requested: string | undefined) => string;
 
+  // Throws the refusal for a target that cannot materialize a workspace:
+  // one whose provider cannot both transfer an archive and run a command.
+  readonly requireWorkspaceTarget: (target: string) => void;
+
   // Runs the plan, which throws the refusal for a spawn it refuses, then
   // spawns. Answers with the `session.spawn` ok payload, which a keyed
   // retry replays as the first spawn answered it while the access, when
@@ -109,6 +128,13 @@ export interface DaemonContext {
     access: TargetAccess | null,
   ) => Promise<Readonly<Record<string, unknown>>>;
   readonly killSession: (id: SessionID) => Promise<boolean>;
+
+  // Forgets a session, or answers with the token a forget that destroys a
+  // host must carry. Throws the refusal for a token it does not take.
+  readonly forgetSession: (
+    id: SessionID,
+    confirmToken: string | undefined,
+  ) => Promise<ForgetResult | 'missing'>;
   readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean | 'child_pin';
   readonly quitDaemon: () => void;
   readonly ackSession: (id: SessionID) => boolean;
@@ -127,6 +153,13 @@ export interface DaemonContext {
     sessionID: SessionID,
     data: string,
   ) => 'busy' | 'ok' | 'missing' | 'dead';
+
+  // Types a line into the session and submits it the way the session's
+  // agent accepts a line, as opposed to the raw bytes the input write takes.
+  readonly writeSessionLine: (
+    sessionID: SessionID,
+    text: string,
+  ) => 'busy' | 'ok' | 'missing' | 'dead';
   readonly ejectSession: (
     id: SessionID,
     prompt: string,
@@ -135,7 +168,7 @@ export interface DaemonContext {
     id: SessionID,
     cols: number,
     rows: number,
-  ) => 'ok' | 'missing' | 'no_transcript';
+  ) => Promise<'ok' | 'missing' | 'no_transcript'>;
   readonly resizeSession: (client: OutputClient, sessionID: SessionID, dims: Dims) => boolean;
   readonly resyncClient: (sessionID: SessionID, client: OutputClient) => Promise<void>;
   readonly queueBytes?: number;
@@ -157,6 +190,11 @@ export interface DaemonContext {
     access: TargetAccess | null,
   ) => Promise<EventsPage>;
 
+  // One report by the trail id of its event, or null for a trail id that
+  // holds no report, or whose report's session is outside the access when
+  // there is one.
+  readonly readReport: (id: number, access: TargetAccess | null) => Promise<ReportView | null>;
+
   // Answers with the `session.message` ok payload, which a keyed retry
   // replays with the message's current status, or with the refusal.
   readonly writeSessionMessage: (
@@ -551,6 +589,27 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.forget': {
+        const parsed = parseRequestParams('session.forget', req.p);
+
+        if (!parsed.ok) {
+          this.sendErr(req.id, 'bad_args', parsed.message);
+
+          return;
+        }
+
+        const id = parsed.data.session;
+
+        const forgotten = await this.ctx.forgetSession(id, parsed.data.confirmToken);
+
+        if (forgotten === 'missing') {
+          this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
+        } else {
+          this.sendOk(req.id, { ...forgotten });
+        }
+
+        return;
+      }
       case 'session.resumeCommand': {
         const parsed = parseRequestParams('session.resumeCommand', req.p);
 
@@ -636,7 +695,8 @@ export class DaemonConnection {
         }
 
         const sessionID = parsed.data.session;
-        const adoptResult = ctx.adoptSession(sessionID, parsed.data.cols, parsed.data.rows);
+
+        const adoptResult = await ctx.adoptSession(sessionID, parsed.data.cols, parsed.data.rows);
 
         if (adoptResult === 'ok') {
           this.sendOk(req.id, {});
@@ -680,6 +740,11 @@ export class DaemonConnection {
 
         return;
       }
+      case 'session.submit': {
+        this.applySubmit(req, ctx);
+
+        return;
+      }
       case 'session.resize': {
         this.applyResize(req, ctx);
 
@@ -740,6 +805,11 @@ export class DaemonConnection {
 
         return;
       }
+      case 'report.get': {
+        await this.applyReportGet(req, ctx);
+
+        return;
+      }
       default: {
         this.sendErr(req.id, 'unknown_method', `unknown method '${req.m}'`);
       }
@@ -787,6 +857,18 @@ export class DaemonConnection {
         throw new DaemonError(overrides.code, overrides.message);
       }
 
+      // Checked before the spawn starts, so a target that cannot take a
+      // workspace refuses it before any git command runs.
+      if (data.workspace !== undefined) {
+        this.ctx.requireWorkspaceTarget(target);
+      }
+
+      // A workspace is materialized at cwd on the target, which only an
+      // absolute path names.
+      if (data.workspace !== undefined && !isAbsolute(data.cwd)) {
+        throw new DaemonError('bad_args', 'a spawn with a workspace requires an absolute cwd');
+      }
+
       let parent: SessionID | null = null;
 
       if (data.parent !== undefined) {
@@ -813,6 +895,7 @@ export class DaemonConnection {
         parent,
         overrides: overrides.overrides,
         target,
+        workspace: data.workspace ?? null,
       };
     };
 
@@ -869,8 +952,29 @@ export class DaemonConnection {
     }
 
     const sessionID = parsed.data.session;
-    const result = ctx.writeSessionInput(sessionID, parsed.data.d);
 
+    this.sendInputResult(req, sessionID, ctx.writeSessionInput(sessionID, parsed.data.d));
+  }
+
+  private applySubmit(req: RequestMsg, ctx: DaemonContext): void {
+    const parsed = parseRequestParams('session.submit', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const sessionID = parsed.data.session;
+
+    this.sendInputResult(req, sessionID, ctx.writeSessionLine(sessionID, parsed.data.text));
+  }
+
+  private sendInputResult(
+    req: RequestMsg,
+    sessionID: SessionID,
+    result: 'busy' | 'ok' | 'missing' | 'dead',
+  ): void {
     if (result === 'missing') {
       this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
 
@@ -1057,6 +1161,32 @@ export class DaemonConnection {
     });
   }
 
+  // A cursor that is not an events cursor, one at a row that holds no
+  // report, and one at a report outside the access all get one refusal, so
+  // the refusal is the same for a report out of reach and a missing one.
+  private async applyReportGet(req: RequestMsg, ctx: DaemonContext): Promise<void> {
+    const parsed = parseRequestParams('report.get', req.p);
+
+    if (!parsed.ok) {
+      this.sendErr(req.id, 'bad_args', parsed.message);
+
+      return;
+    }
+
+    const decoded = decodeCursor(parsed.data.report);
+
+    const view =
+      decoded === null || decoded.kind !== 'events' ? null : await ctx.readReport(decoded.id, null);
+
+    if (view === null) {
+      this.sendErr(req.id, 'bad_args', `no report '${parsed.data.report}'`);
+
+      return;
+    }
+
+    this.sendOk(req.id, { ...view });
+  }
+
   private async applySessionMessage(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('session.message', req.p);