@zgeoff/atc 2.10.4 → 2.12.0

package/src/shared/config.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { buildOptionalString } from './build-optional-string';
 import { buildOptionalStringArray } from './build-optional-string-array';
@@ -8,6 +8,11 @@ import { collectGateways } from './collect-gateways';
 import type { GatewayConfig } from './collect-gateways';
 import { collectHooks } from './collect-hooks';
 import type { HooksConfig } from './collect-hooks';
+import { collectPrincipals } from './collect-principals';
+import { collectTargets } from './collect-targets';
+import type { TargetConfig, TargetConfigError } from './collect-targets';
+import { formatJSONKind } from './format-json-kind';
+import { isRecord } from './report';
 import { resolveHomeDir } from './resolve-home-dir';
 
 export interface Config {
@@ -21,6 +26,20 @@ export interface Config {
   gateways: GatewayConfig[];
   hooks: HooksConfig;
   leader: LeaderKey;
+
+  // Where sessions run, and the one a spawn without a target runs on: null
+  // when the config gives none it can use.
+  targets: readonly TargetConfig[];
+  defaultTarget: string | null;
+
+  // The target config problems that leave a target, or every target,
+  // unusable.
+  targetErrors: readonly TargetConfigError[];
+
+  // The targets each principal may use: null when the config has no
+  // principals, which leaves every principal the implicit local target.
+  principals: ReadonlyMap<string, readonly string[]> | null;
+  principalErrors: readonly string[];
 }
 
 /**
@@ -47,6 +66,11 @@ const DEFAULTS: Config = {
   gateways: [],
   hooks: {},
   leader: { code: 0, label: '^Space' },
+  targets: [{ id: 'local', provider: 'local-pty', options: {} }],
+  defaultTarget: 'local',
+  targetErrors: [],
+  principals: null,
+  principalErrors: [],
 };
 
 const configDir = join(resolveHomeDir(), '.config', 'atc');
@@ -80,38 +104,132 @@ const CONFIG_SCHEMA = z.object({
   gateways: z.unknown().optional(),
   hooks: z.unknown().optional(),
   leader: buildOptionalString(),
+  targets: z.unknown().optional(),
+  defaultTarget: z.unknown().optional(),
+  principals: z.unknown().optional(),
 });
 
-export function loadConfig(): Config {
-  mkdirSync(configDir, { recursive: true });
-  mkdirSync(stateDir, { recursive: true });
+/**
+ * Reads and parses config.json. Only an absent file means every default,
+ * the implicit `local` target included, and a first run writes those
+ * defaults out. A file that exists but cannot be read or parsed loads as
+ * unusable: every default but the targets, which it leaves empty with the
+ * problem as the one target error, so nothing runs until the file is fixed.
+ * Never throws.
+ */
+export function loadConfig(file: string = configFile): Config {
+  // Every atc process writes under the state directory; a failure here
+  // comes back from the first write into it.
+  try {
+    mkdirSync(stateDir, { recursive: true });
+  } catch {}
+
+  let text: string;
+
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch (error) {
+    const code: unknown = error instanceof Error ? Reflect.get(error, 'code') : undefined;
+
+    if (code !== 'ENOENT') {
+      const detail = typeof code === 'string' ? code : 'the file could not be read';
 
-  const file = configFile;
+      return buildUnusableConfig('config_unreadable', file, detail);
+    }
 
-  if (!existsSync(file)) {
-    writeFileSync(file, `${JSON.stringify(DEFAULTS, null, 2)}\n`);
+    tryWriteDefaultConfig(file);
 
     return { ...DEFAULTS };
   }
 
+  let raw: unknown;
+
   try {
-    return parseConfig(JSON.parse(readFileSync(file, 'utf8')));
+    raw = JSON.parse(text);
   } catch {
-    return { ...DEFAULTS };
+    // The parser's own message can quote the file's text, so the detail is
+    // a fixed phrase instead.
+    return buildUnusableConfig('config_malformed', file, 'the file is not valid JSON');
   }
+
+  return parseConfig(raw, file);
+}
+
+/**
+ * A config for a file that exists but cannot be used: every default but the
+ * targets, which are empty, with no default target and the file's problem
+ * as the one target error, and the principals, which get no target, since
+ * the file's own principals cannot be read.
+ */
+function buildUnusableConfig(
+  problem: 'config_malformed' | 'config_unreadable',
+  path: string,
+  detail: string,
+): Config {
+  return {
+    ...DEFAULTS,
+    targets: [],
+    defaultTarget: null,
+    targetErrors: [{ scope: 'config', problem, path, detail }],
+    principals: new Map(),
+  };
+}
+
+/**
+ * Writes the first-run config, never over a file that appeared since the
+ * read. A failure leaves the defaults in effect for this run, so it is not
+ * an error.
+ */
+function tryWriteDefaultConfig(file: string): void {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, renderDefaultConfig(), { flag: 'wx' });
+  } catch {}
+}
+
+/**
+ * The config.json text a first run writes. It leaves out the targets and
+ * principals, so the file holds the one implicit `local` target and no
+ * principals until the user sets their own, and the errors a parse
+ * reports, which belong to no file.
+ */
+export function renderDefaultConfig(): string {
+  const {
+    targets: _targets,
+    defaultTarget: _default,
+    targetErrors: _errors,
+    principals: _principals,
+    principalErrors: _principalErrors,
+    ...written
+  } = DEFAULTS;
+
+  return `${JSON.stringify(written, null, 2)}\n`;
 }
 
 /**
  * Parses a user-written config.json's already-decoded JSON value into a
  * Config, applying every default a malformed or absent field falls back to.
- * Total: no shape of `raw` throws, so a hand-edited config never stops atc
- * starting.
+ * A root that is not an object leaves the config unusable, with no targets,
+ * and `file` is the path its error holds. Total: no shape of `raw` throws,
+ * so a hand-edited config never stops atc starting.
  */
-export function parseConfig(raw: unknown): Config {
+export function parseConfig(raw: unknown, file: string = configFile): Config {
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return buildUnusableConfig(
+      'config_malformed',
+      file,
+      `the root is ${formatJSONKind(raw)}, not an object`,
+    );
+  }
+
   const parsed = CONFIG_SCHEMA.safeParse(raw);
 
   if (!parsed.success) {
-    return { ...DEFAULTS };
+    return buildUnusableConfig(
+      'config_malformed',
+      file,
+      'the file does not match the config schema',
+    );
   }
 
   const claudeBin = parsed.data.claudeBin ?? DEFAULTS.claudeBin;
@@ -123,6 +241,8 @@ export function parseConfig(raw: unknown): Config {
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
   const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
   const hooks = collectHooks(parsed.data.hooks);
+  const targets = collectTargets(parsed.data.targets, parsed.data.defaultTarget);
+  const principals = collectPrincipals(parsed.data.principals);
 
   const leader =
     (parsed.data.leader === undefined ? null : decodeLeader(parsed.data.leader)) ?? DEFAULTS.leader;
@@ -138,6 +258,11 @@ export function parseConfig(raw: unknown): Config {
     gateways,
     hooks,
     leader,
+    targets: targets.targets,
+    defaultTarget: targets.defaultTarget,
+    targetErrors: targets.errors,
+    principals: principals.principals,
+    principalErrors: principals.errors,
   };
 }
 

package/src/shared/daemon-id.ts

@@ -0,0 +1,8 @@
+import type { Tagged } from 'type-fest';
+
+/**
+ * The id a daemon holds for its whole life, minted once into its state
+ * store. It names the daemon in `daemon.hello`, in every session locator,
+ * and in the ownership row of each session the daemon persists.
+ */
+export type DaemonID = Tagged<string, 'DaemonID'>;

package/src/shared/format-json-kind.ts

@@ -0,0 +1,21 @@
+/**
+ * The kind of a decoded JSON value, as an error detail: "null", "an array",
+ * "an object", "a string", "a number", or "a boolean". It never includes
+ * the value itself, so a config diagnostic built from it holds nothing the
+ * file holds.
+ */
+export function formatJSONKind(raw: unknown): string {
+  if (raw === null) {
+    return 'null';
+  }
+
+  if (Array.isArray(raw)) {
+    return 'an array';
+  }
+
+  if (typeof raw === 'object') {
+    return 'an object';
+  }
+
+  return `a ${typeof raw}`;
+}

package/src/shared/sort-json-keys.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns a JSON value with every object's keys in sorted order, at every
+ * depth, so two values that differ only in key order serialize the same.
+ */
+export function sortJSONKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJSONKeys(item));
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .toSorted(([a], [b]) => a.localeCompare(b))
+        .map(([key, item]) => [key, sortJSONKeys(item)]),
+    );
+  }
+
+  return value;
+}

package/src/shared/to-daemon-id.ts

@@ -0,0 +1,11 @@
+import type { DaemonID } from './daemon-id';
+
+/**
+ * Trusts a string as a daemon id. This is the one point in the codebase
+ * where a plain string becomes a `DaemonID`, and it adds no runtime check:
+ * the caller asserts the string is the id a daemon minted for itself.
+ */
+export function toDaemonID(id: string): DaemonID {
+  // oxlint-disable-next-line no-unsafe-type-assertion -- the one point where a string is trusted as a DaemonID
+  return id as DaemonID;
+}

package/src/store/fleet-entry.ts

@@ -4,20 +4,28 @@ import type { AgentID } from '../agents/agent-adapter';
 import type { AgentSessionID } from '../shared/agent-session-id';
 import { buildOptionalBoolean } from '../shared/build-optional-boolean';
 import { buildOptionalString } from '../shared/build-optional-string';
+import type { DaemonID } from '../shared/daemon-id';
 import { isRecord } from '../shared/report';
+import type { SessionID } from '../shared/session-id';
 import { toAgentSessionID } from '../shared/to-agent-session-id';
 
+// One fleet row. The atc session id keys it and stays the same for the
+// session's whole life, across daemon restarts and fleet restores.
 export interface FleetEntry {
+  readonly sessionID: SessionID;
   readonly name: string;
   readonly cwd: string;
-  readonly agentSessionID: AgentSessionID;
+
+  // Absent until the agent reports its own session id; a row without one
+  // restores as an exited session, since there is nothing to resume.
+  readonly agentSessionID?: AgentSessionID;
   readonly agent: AgentID;
   readonly pinned?: boolean;
   readonly lastAttachedAt?: number;
   readonly exited?: boolean;
 
-  // The agent session id of the session this one is a sub-session of.
-  readonly parent?: AgentSessionID;
+  // The atc session id of the session this one is a sub-session of.
+  readonly parent?: SessionID;
 
   // The prompt the session was spawned with.
   readonly prompt?: string;
@@ -27,15 +35,26 @@ export interface FleetEntry {
 
   // The transcript file the agent's hooks last reported for the session.
   readonly transcriptPath?: string;
+
+  // The model and effort the session was spawned with; absent for a session
+  // that runs on the agent's configured default.
+  readonly model?: string;
+  readonly effort?: string;
+
+  // The execution target the session runs on; a row without one restores
+  // on the `local` target.
+  readonly target?: string;
+
+  // The identity the target had when the session started on it; a row
+  // without one is bound to the implicit `local` target's identity.
+  readonly targetIdentity?: string;
 }
 
 export interface FleetStore {
+  readonly daemonID: DaemonID;
   readonly loadFleet: () => Promise<FleetEntry[]>;
   readonly writeFleet: (entries: readonly FleetEntry[]) => Promise<void>;
-  readonly updateFleetEntry: (
-    agentSessionID: AgentSessionID,
-    fields: FleetEntryUpdate,
-  ) => Promise<void>;
+  readonly updateFleetEntry: (sessionID: SessionID, fields: FleetEntryUpdate) => Promise<void>;
 }
 
 // The fields a session rewrites on its own row while it runs, without
@@ -45,7 +64,21 @@ export interface FleetEntryUpdate {
   readonly transcriptPath?: string;
 }
 
-// A stored fleet row's keys. name, cwd, and the resolved agentSessionID are
+// One entry of a legacy fleet.json, from before the fleet moved into the
+// state store: keyed by the agent session id, with the parent link held as
+// the parent's agent session id.
+export interface LegacyFleetEntry {
+  readonly name: string;
+  readonly cwd: string;
+  readonly agentSessionID: AgentSessionID;
+  readonly agent: AgentID;
+  readonly pinned?: boolean;
+  readonly lastAttachedAt?: number;
+  readonly exited?: boolean;
+  readonly parent?: AgentSessionID;
+}
+
+// A legacy fleet.json entry's keys. name, cwd, and the resolved agentSessionID are
 // required: a row missing any of them cannot restore a session, so the whole
 // row parses to undefined rather than a half-built entry. Fleet files
 // written before the id key was agent-neutral carry it under its Claude-era
@@ -71,7 +104,7 @@ const FLEET_ENTRY_SCHEMA = z.preprocess(
   }),
 );
 
-export function parseFleetEntry(raw: unknown): FleetEntry | undefined {
+export function parseFleetEntry(raw: unknown): LegacyFleetEntry | undefined {
   const parsed = FLEET_ENTRY_SCHEMA.safeParse(raw);
 
   if (!parsed.success) {

package/src/store/idempotency-record.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a keyed effect stands. `in_progress` holds while the daemon that
+ * claimed the key runs the effect; `completed` once the effect is durable;
+ * `outcome_unknown` when a daemon stopped mid-effect and its start-up
+ * reconciliation found no trace of the effect.
+ */
+export type IdempotencyState = 'in_progress' | 'completed' | 'outcome_unknown';
+
+// One idempotency key and the effect it names.
+export interface IdempotencyRecord {
+  readonly principal: string;
+  readonly operation: string;
+  readonly key: string;
+  readonly payloadHash: string;
+  readonly state: IdempotencyState;
+
+  // The id the effect was minted before it ran: the session a spawn
+  // created, or the message a send wrote.
+  readonly effectRef: string;
+
+  // The effect's answer as JSON, once completed by the daemon that ran it.
+  readonly result: string | null;
+
+  // The target the completed effect's session was bound to, as it stood
+  // then; null for a key completed without one.
+  readonly effectTarget: EffectTarget | null;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+/**
+ * A target name and the identity it held, which a replay of the key is
+ * authorized against.
+ */
+export interface EffectTarget {
+  readonly target: string;
+  readonly targetIdentity: string;
+}
+
+// The claim a keyed request makes before its effect runs.
+export interface IdempotencyClaim {
+  readonly principal: string;
+  readonly operation: string;
+  readonly key: string;
+  readonly payloadHash: string;
+  readonly effectRef: string;
+  readonly at: number;
+}

package/src/store/message-owner.ts

@@ -2,7 +2,7 @@ import type { AgentSessionID } from '../shared/agent-session-id';
 import type { SessionID } from '../shared/session-id';
 
 // Which session a message belongs to: the atc id it was sent to, or the
-// agent session id that survives a restore's re-minted atc id.
+// agent session id, which links rows written under an earlier atc id.
 export interface MessageOwner {
   readonly atcID: SessionID;
   readonly agentSessionID?: AgentSessionID;

package/src/store/message-record.ts

@@ -15,4 +15,7 @@ export interface MessageRecord {
   readonly deliveredAt?: number;
   readonly answeredAt?: number;
   readonly answer?: string;
+
+  // The turn whose final reply the answer is, when the reporter gave one.
+  readonly turn?: string;
 }