src/agents-archive.ts

Functions

Imports

It imports src/store-guards.ts. Imported by src/controls-plan.ts, src/tools/agents.ts, src/watcher.ts.

Source

1import { auditStatement } from "./store-guards";
2
3// Revoked agents leave the live inventory and keep their history (job_24e460427d6c;
4// Dustin, 2026-10-02 and 2026-10-10: archive and hide, never delete an agent with
5// history). migrations/0038_agents_archive.sql says what moves and why.
6//
7// Every row that records what an agent did carries the actor string agent:<name>
8// itself, so moving the agents row breaks no join a reader of history needs. Three
9// things still need the old row, and read it from here: the name stays reserved
10// (mintAgent), the key's digest is still refused rather than tried as an operator key
11// (resolveAgent), and a reviewer's past verdict is judged on the scopes it held
12// (src/review.ts). Archived means revoked to every other reader.
13
14// A revoked agent moves this long after revocation, so a revocation made by mistake can
15// still be read in place for a week.
16export const ARCHIVE_AFTER_DAYS = 7;
17
18type ArchiveReason = "revoked-7-days" | "runner-job-ended";
19
20// How many agents one pass moves. A pass is not the place to drain a backlog of
21// hundreds; the next pass takes the rest.
22const MAX_PER_PASS = 20;
23
24// The audit identity of the pass that moves them.
25const ARCHIVE_ACTION = "agents.archive";
26
27export interface ArchivedAgent {
28  id: string;
29  name: string;
30  kind: string;
31  key_hash: string;
32  scopes: string;
33  created_by: string;
34  created_at: string;
35  revoked_at: string;
36  last_seen: string | null;
37  job_id: string | null;
38  reason: ArchiveReason;
39  audit_rows: number;
40  jobs: number;
41  archived_at: string;
42}
43
44interface DueRow {
45  id: string;
46  name: string;
47  reason: ArchiveReason;
48}
49
50/** The revoked agents due to move: 7 days after revocation, or a one-job key row
51 *  (job_id set, an old runner key) whose job has ended (done, failed or superseded). Oldest revocation first. */
52async function archiveDue(db: D1Database, now: Date): Promise<DueRow[]> {
53  const { results } = await db
54    .prepare(
55      `SELECT a.id AS id, a.name AS name,
56              CASE WHEN a.job_id IS NOT NULL AND j.status IN ('done', 'failed', 'superseded') THEN 'runner-job-ended' ELSE 'revoked-7-days' END AS reason
57         FROM agents a LEFT JOIN jobs j ON j.id = a.job_id
58        WHERE a.revoked_at IS NOT NULL
59          AND (datetime(a.revoked_at) <= datetime(?1, ?3)
60               OR (a.job_id IS NOT NULL AND j.status IN ('done', 'failed', 'superseded')))
61        ORDER BY a.revoked_at, a.name
62        LIMIT ?2`
63    )
64    .bind(now.toISOString(), MAX_PER_PASS, `-${ARCHIVE_AFTER_DAYS} days`)
65    .all<DueRow>();
66  return results ?? [];
67}
68
69/** The move of one agent, as one batch: copy it with its counts, delete it from agents,
70 *  and write the audit row. Both data statements are guarded on the row still being
71 *  revoked, so a row that changed between the read and the batch moves nothing. */
72function archiveStatements(db: D1Database, actor: string, due: DueRow): D1PreparedStatement[] {
73  const agentActor = `agent:${due.name}`;
74  return [
75    db
76      .prepare(
77        `INSERT INTO agents_archive (id, name, kind, key_hash, scopes, created_by, created_at, revoked_at, last_seen, job_id, reason, audit_rows, jobs)
78         SELECT id, name, kind, key_hash, scopes, created_by, created_at, revoked_at, last_seen, job_id, ?2,
79                (SELECT COUNT(*) FROM audit_log WHERE actor = ?3),
80                (SELECT COUNT(*) FROM (
81                   SELECT id FROM jobs WHERE posted_by = ?3 OR claimed_by = ?3
82                   UNION SELECT job_id FROM job_outcomes WHERE agent = ?3
83                   UNION SELECT job_id FROM job_claims WHERE agent = ?3))
84           FROM agents WHERE id = ?1 AND revoked_at IS NOT NULL`
85      )
86      .bind(due.id, due.reason, agentActor),
87    db.prepare("DELETE FROM agents WHERE id = ?1 AND revoked_at IS NOT NULL AND EXISTS (SELECT 1 FROM agents_archive WHERE id = ?1)").bind(due.id),
88    auditStatement(db, actor, ARCHIVE_ACTION, "agents", due.name, { reason: due.reason, id: due.id }),
89  ];
90}
91
92export interface ArchivePass {
93  archived: Array<{ name: string; reason: ArchiveReason }>;
94  // Due, and moved nothing: the row changed between the read and the batch.
95  skipped: string[];
96}
97
98/** The watcher pass's archive step. Each agent moves in its own batch, so one that
99 *  fails leaves the rest moved and says which. */
100export async function archiveRevokedAgents(db: D1Database, actor: string, now: Date): Promise<ArchivePass> {
101  const out: ArchivePass = { archived: [], skipped: [] };
102  for (const due of await archiveDue(db, now)) {
103    const results = await db.batch(archiveStatements(db, actor, due));
104    // The DELETE is what takes the row out of the live table, so its count is the move.
105    // agents has no trigger to inflate it.
106    if ((results[1]?.meta?.changes ?? 0) === 1) out.archived.push({ name: due.name, reason: due.reason });
107    else out.skipped.push(due.name);
108  }
109  return out;
110}
111
112/** Archived agents, newest move first. The stored verifier never leaves this module:
113 *  readers get its first twelve hex, the fingerprint agents list shows. */
114export async function listArchivedAgents(db: D1Database, limit = 200): Promise<Array<Omit<ArchivedAgent, "key_hash"> & { fingerprint: string }>> {
115  const { results } = await db.prepare("SELECT * FROM agents_archive ORDER BY archived_at DESC, name LIMIT ?1").bind(limit).all<ArchivedAgent>();
116  return (results ?? []).map(({ key_hash, ...row }) => ({ ...row, fingerprint: key_hash.slice(0, 12) }));
117}
118
119/** An archived agent by name, or null. */
120export async function archivedAgentByName(db: D1Database, name: string): Promise<ArchivedAgent | null> {
121  return db.prepare("SELECT * FROM agents_archive WHERE name = ?1").bind(name).first<ArchivedAgent>();
122}