@zgeoff/atc 2.11.0 → 2.13.0

package/src/store/fleet-entry.ts

@@ -4,20 +4,29 @@ 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';
+import type { SessionWorkspace } from './workspace-materialization';
 
+// 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 +36,44 @@ 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;
+
+  // What the session's workspace was materialized from, for a session
+  // spawned with a workspace source; a fleet write leaves it to the
+  // materialization record that holds it.
+  readonly workspace?: SessionWorkspace;
+
+  // The environment variable names every harness the session starts goes
+  // without, held with its ready workspace; never their values.
+  readonly withheldEnv?: readonly string[];
+
+  // What the operator asked of the harness: absent keeps it running,
+  // `sleep` keeps its host asleep, and `stop` leaves it ended.
+  readonly desired?: 'sleep' | 'stop';
+
+  // The session whose host the harness runs on: its own id, or its
+  // parent's when the two share one host. A row without one runs on a host
+  // of its own.
+  readonly hostKey?: SessionID;
 }
 
 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 +83,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 +123,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/run-migrations.ts

@@ -1,21 +1,38 @@
+import { randomUUID } from 'node:crypto';
 import { sql } from 'kysely';
 import type { Generated, Kysely } from 'kysely';
 import { DEFAULT_MIGRATION_TABLE, Migrator } from 'kysely/migration';
 import type { Migration, MigrationProvider, MigrationResultSet } from 'kysely/migration';
+import type { IdempotencyState } from './idempotency-record';
 import type { MessageStatus } from './message-record';
+import type { MaterializationPhase } from './workspace-materialization';
 
 interface FleetTable {
-  agent_session_id: string;
+  session_id: string;
+  agent_session_id: string | null;
   name: string;
   cwd: string;
   pinned: number;
   last_attached: number | null;
   agent: string;
   exited: number;
-  parent: string | null;
+  parent_session_id: string | null;
   prompt: string | null;
   result: string | null;
   transcript_path: string | null;
+  model: string | null;
+  effort: string | null;
+  target: string | null;
+  target_identity: string | null;
+
+  // What the operator asked of the session's harness: null keeps it
+  // running, `sleep` keeps its host asleep, and `stop` leaves it ended.
+  desired: string | null;
+
+  // The session whose host this session's harness runs on: its own id, or
+  // its parent's when the two share one host. Null for a row from before
+  // hosts were recorded, which runs on its own.
+  host_key: string | null;
 }
 
 interface EventsTable {
@@ -27,6 +44,10 @@ interface EventsTable {
   session_id: string | null;
   kind: string | null;
   detail: string | null;
+
+  // The id a remote session's reporter gave a report row, unique so a
+  // resent report lands once; null on every other row.
+  report_id: string | null;
 }
 
 interface SpawnHistoryTable {
@@ -39,6 +60,58 @@ interface PrefsTable {
   value: string;
 }
 
+// Which daemon owns each persisted session, and under which ownership
+// epoch. A write from a daemon whose epoch is behind the stored one is
+// stale and rejected.
+interface SessionOwnerTable {
+  session_id: string;
+  daemon_id: string;
+  owner_epoch: Generated<number>;
+  updated_at: number;
+}
+
+// One idempotency key per principal and operation: the hash of the payload
+// it first arrived with, where the keyed effect stands, and the effect it
+// names. A key whose outcome is unknown never expires, so a retry of it can
+// never start a fresh effect.
+interface IdempotencyTable {
+  principal: string;
+  operation: string;
+  key: string;
+  payload_hash: string;
+  state: IdempotencyState;
+  effect_ref: string;
+  result: string | null;
+  created_at: number;
+  updated_at: number;
+
+  // The target, and its identity, the completed effect's session was bound
+  // to; null for a key completed without one.
+  effect_target: string | null;
+  effect_target_identity: string | null;
+}
+
+// One spawn's workspace on its way to the execution target, keyed by the
+// session it is for.
+interface WorkspaceMaterializationTable {
+  session_id: string;
+  target: string;
+  dir: string;
+  source_kind: 'path' | 'git';
+  phase: MaterializationPhase;
+  repo_url: string | null;
+  sha: string | null;
+  ref: string | null;
+  error_code: string | null;
+  started_at: number;
+  updated_at: number;
+  materialized_at: number | null;
+
+  // JSON array of the environment variable names every harness the session
+  // starts goes without; names only, never their values.
+  withheld_env: string | null;
+}
+
 interface MessagesTable {
   id: string;
   atc_id: string;
@@ -66,11 +139,15 @@ export interface StateStoreSchema {
   spawn_history: SpawnHistoryTable;
   prefs: PrefsTable;
   messages: MessagesTable;
+  session_owner: SessionOwnerTable;
+  idempotency: IdempotencyTable;
+  workspace_materialization: WorkspaceMaterializationTable;
 }
 
 // Every shape the fleet table has shipped with: the oldest carries only
 // agent_session_id under its Claude-era name plus name and cwd, and each
-// later step adds one column the daemon grew to depend on. events later gains
+// later step adds one column the daemon grew to depend on, until the
+// rebuild that keys the table by the atc session id. events later gains
 // columns of its own, as does messages, while spawn_history and prefs have
 // carried one shape since they were added.
 const MIGRATIONS: Record<string, Migration> = {
@@ -232,6 +309,134 @@ const MIGRATIONS: Record<string, Migration> = {
         .execute();
     },
   },
+  '014_add_fleet_model_effort': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('fleet').addColumn('model', 'text').execute();
+      await db.schema.alterTable('fleet').addColumn('effort', 'text').execute();
+    },
+  },
+  '015_rebuild_fleet_keyed_by_session_id': {
+    async up(db: Kysely<StateStoreSchema>) {
+      // The ledger records this step only after it returns, so a crash in
+      // between leaves a rebuilt table behind a ledger that still lacks it.
+      const columns = await collectFleetColumns(db);
+
+      if (columns.has('session_id')) {
+        return;
+      }
+
+      // SQLite takes this DDL inside a transaction even though kysely's
+      // adapter declines to open one for it, so the rebuild lands whole or
+      // not at all.
+      await sql`BEGIN IMMEDIATE`.execute(db);
+
+      try {
+        await updateFleetKeyToSessionID(db);
+
+        await sql`COMMIT`.execute(db);
+      } catch (error) {
+        await sql`ROLLBACK`.execute(db);
+
+        throw error;
+      }
+    },
+  },
+  '016_create_session_owner': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await sql`BEGIN IMMEDIATE`.execute(db);
+
+      try {
+        await createSessionOwners(db);
+
+        await sql`COMMIT`.execute(db);
+      } catch (error) {
+        await sql`ROLLBACK`.execute(db);
+
+        throw error;
+      }
+    },
+  },
+  '017_create_idempotency': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createTable('idempotency')
+        .ifNotExists()
+        .addColumn('principal', 'text', (c) => c.notNull())
+        .addColumn('operation', 'text', (c) => c.notNull())
+        .addColumn('key', 'text', (c) => c.notNull())
+        .addColumn('payload_hash', 'text', (c) => c.notNull())
+        .addColumn('state', 'text', (c) => c.notNull())
+        .addColumn('effect_ref', 'text', (c) => c.notNull())
+        .addColumn('result', 'text')
+        .addColumn('created_at', 'integer', (c) => c.notNull())
+        .addColumn('updated_at', 'integer', (c) => c.notNull())
+        .addPrimaryKeyConstraint('idempotency_pk', ['principal', 'operation', 'key'])
+        .execute();
+
+      await db.schema
+        .createIndex('idempotency_state_updated_at')
+        .ifNotExists()
+        .on('idempotency')
+        .columns(['state', 'updated_at'])
+        .execute();
+    },
+  },
+  '018_add_fleet_target': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('fleet').addColumn('target', 'text').execute();
+      await db.schema.alterTable('fleet').addColumn('target_identity', 'text').execute();
+    },
+  },
+  '019_add_idempotency_effect_target': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('idempotency').addColumn('effect_target', 'text').execute();
+
+      await db.schema
+        .alterTable('idempotency')
+        .addColumn('effect_target_identity', 'text')
+        .execute();
+    },
+  },
+  '020_create_workspace_materialization': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema
+        .createTable('workspace_materialization')
+        .ifNotExists()
+        .addColumn('session_id', 'text', (c) => c.primaryKey())
+        .addColumn('target', 'text', (c) => c.notNull())
+        .addColumn('dir', 'text', (c) => c.notNull())
+        .addColumn('source_kind', 'text', (c) => c.notNull())
+        .addColumn('phase', 'text', (c) => c.notNull())
+        .addColumn('repo_url', 'text')
+        .addColumn('sha', 'text')
+        .addColumn('ref', 'text')
+        .addColumn('error_code', 'text')
+        .addColumn('started_at', 'integer', (c) => c.notNull())
+        .addColumn('updated_at', 'integer', (c) => c.notNull())
+        .addColumn('materialized_at', 'integer')
+        .addColumn('withheld_env', 'text')
+        .execute();
+    },
+  },
+  '021_add_fleet_lifecycle': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('fleet').addColumn('desired', 'text').execute();
+      await db.schema.alterTable('fleet').addColumn('host_key', 'text').execute();
+    },
+  },
+  '022_add_events_report_id': {
+    async up(db: Kysely<StateStoreSchema>) {
+      await db.schema.alterTable('events').addColumn('report_id', 'text').execute();
+
+      await db.schema
+        .createIndex('events_report_id')
+        .ifNotExists()
+        .unique()
+        .on('events')
+        .column('report_id')
+        .execute();
+    },
+  },
 };
 
 const PROVIDER: MigrationProvider = {
@@ -243,8 +448,8 @@ const PROVIDER: MigrationProvider = {
  * `Migrator`, one additive step at a time. A database from before the
  * ladder existed is recognized at whichever shape it stopped at by a
  * baselining pass that records the steps its columns already satisfy, so
- * only what is genuinely missing runs. Nothing here ever drops a column or
- * a row.
+ * only what is genuinely missing runs. One step rebuilds the fleet table
+ * under a new key and carries every row across; no step drops a row.
  */
 export async function runMigrations(db: Kysely<StateStoreSchema>): Promise<void> {
   // A baselined step can land out of order relative to a step that turned
@@ -314,8 +519,128 @@ async function recordLegacyBaseline(db: Kysely<StateStoreSchema>): Promise<void>
   }
 }
 
+// Mints the store's daemon id when it has none, then records that daemon as
+// the owner of every fleet row, at the first ownership epoch.
+async function createSessionOwners(db: Kysely<StateStoreSchema>): Promise<void> {
+  await db.schema
+    .createTable('session_owner')
+    .ifNotExists()
+    .addColumn('session_id', 'text', (c) => c.primaryKey())
+    .addColumn('daemon_id', 'text', (c) => c.notNull())
+    .addColumn('owner_epoch', 'integer', (c) => c.notNull().defaultTo(1))
+    .addColumn('updated_at', 'integer', (c) => c.notNull())
+    .execute();
+
+  await db
+    .insertInto('prefs')
+    .values({ key: 'daemon_id', value: randomUUID() })
+    .onConflict((oc) => oc.column('key').doNothing())
+    .execute();
+
+  await sql`
+    INSERT OR IGNORE INTO session_owner (session_id, daemon_id, updated_at)
+    SELECT fleet.session_id, prefs.value, ${Date.now()}
+    FROM fleet JOIN prefs ON prefs.key = 'daemon_id'
+  `.execute(db);
+}
+
+interface LegacyFleetIDRow {
+  old_rowid: number;
+  agent_session_id: string | null;
+}
+
+// The columns the rebuild writes by name. Any other column a legacy table
+// carries moves across untouched, so the rebuild never loses data a step
+// outside this ladder added.
+const REBUILT_FLEET_COLUMNS: ReadonlySet<string> = new Set([
+  'agent_session_id',
+  'name',
+  'cwd',
+  'pinned',
+  'last_attached',
+  'agent',
+  'exited',
+  'parent',
+  'prompt',
+  'result',
+  'transcript_path',
+  'model',
+  'effort',
+]);
+
+// Gives every row a minted atc session id and moves the sub-session link
+// from the parent's agent session id to the parent's atc session id. A link
+// to an agent session id no row holds becomes no link.
+async function updateFleetKeyToSessionID(db: Kysely<StateStoreSchema>): Promise<void> {
+  const columns = await sql<ColumnInfoRow>`PRAGMA table_info(fleet)`.execute(db);
+
+  const extras = columns.rows.filter((column) => !REBUILT_FLEET_COLUMNS.has(column.name));
+
+  // Keyed by rowid: SQLite lets a text primary key hold NULL, so a legacy
+  // row can lack the agent session id the mapping would otherwise key on.
+  await sql`CREATE TEMP TABLE fleet_ids (old_rowid INTEGER PRIMARY KEY, agent_session_id TEXT, session_id TEXT NOT NULL)`.execute(
+    db,
+  );
+
+  const rows =
+    await sql<LegacyFleetIDRow>`SELECT rowid AS old_rowid, agent_session_id FROM fleet`.execute(db);
+
+  for (const row of rows.rows) {
+    await sql`INSERT INTO fleet_ids (old_rowid, agent_session_id, session_id) VALUES (${row.old_rowid}, ${row.agent_session_id}, ${randomUUID()})`.execute(
+      db,
+    );
+  }
+
+  const extraDefinitions = extras.map(
+    (column) => sql`, ${sql.ref(column.name)} ${sql.raw(column.type)}`,
+  );
+
+  const extraTargets = extras.map((column) => sql`, ${sql.ref(column.name)}`);
+  const extraSources = extras.map((column) => sql`, ${sql.ref(`f.${column.name}`)}`);
+
+  await sql`
+    CREATE TABLE fleet_rebuilt (
+      session_id TEXT PRIMARY KEY,
+      agent_session_id TEXT UNIQUE,
+      name TEXT NOT NULL,
+      cwd TEXT NOT NULL,
+      pinned INTEGER NOT NULL DEFAULT 0,
+      last_attached INTEGER,
+      agent TEXT NOT NULL DEFAULT 'claude',
+      exited INTEGER NOT NULL DEFAULT 0,
+      parent_session_id TEXT,
+      prompt TEXT,
+      result TEXT,
+      transcript_path TEXT,
+      model TEXT,
+      effort TEXT
+      ${sql.join(extraDefinitions, sql``)}
+    )
+  `.execute(db);
+
+  await sql`
+    INSERT INTO fleet_rebuilt (
+      session_id, agent_session_id, name, cwd, pinned, last_attached, agent, exited,
+      parent_session_id, prompt, result, transcript_path, model, effort
+      ${sql.join(extraTargets, sql``)}
+    )
+    SELECT
+      ids.session_id, f.agent_session_id, f.name, f.cwd, f.pinned, f.last_attached, f.agent,
+      f.exited, parents.session_id, f.prompt, f.result, f.transcript_path, f.model, f.effort
+      ${sql.join(extraSources, sql``)}
+    FROM fleet f
+    JOIN fleet_ids ids ON ids.old_rowid = f.rowid
+    LEFT JOIN fleet_ids parents ON parents.agent_session_id = f.parent
+  `.execute(db);
+
+  await sql`DROP TABLE fleet`.execute(db);
+  await sql`ALTER TABLE fleet_rebuilt RENAME TO fleet`.execute(db);
+  await sql`DROP TABLE fleet_ids`.execute(db);
+}
+
 interface ColumnInfoRow {
   name: string;
+  type: string;
 }
 
 async function collectFleetColumns(db: Kysely<StateStoreSchema>): Promise<ReadonlySet<string>> {