src/status.ts

Functions

Imports

It imports src/agent-record.ts, src/agents-schema.ts, src/auto-merge-policy.ts, src/auto-merge-tick.ts, src/canon.ts, src/env.ts, src/gate-policy.ts, src/inbox.ts, src/job-breaker.ts, src/jobs.ts, src/maintenance.ts, src/merge-safety.ts, src/ops-types/feed.ts, src/overnight.ts, src/provenance.ts, src/roster.ts, src/truth-report.ts. Imported by src/ops-feed.ts, src/portal-actions.ts, src/tools/status.ts, src/watcher-detect.ts, src/watcher-gather.ts.

Source

1import { overnightState, type OvernightState } from "./overnight";
2import type { Env } from "./env";
3import { APP_ROSTER } from "./roster";
4import { pendingProposals, servedCanonPaths, type PendingProposal } from "./canon";
5import { loadGatePolicy } from "./gate-policy";
6import { loadMergePolicy } from "./auto-merge-policy";
7import { breakerState, type BreakerState } from "./job-breaker";
8import { SCOPE_FLAGS, parseScopes } from "./agents-schema";
9import { loadAgentRecords, type AgentRecord } from "./agent-record";
10import { jobsSummary, type JobsSummary } from "./jobs";
11import { integrityOf, REPORTS_PREFIX } from "./truth-report";
12import { AWAITING_SEAT_KEY, type AwaitingSeat } from "./auto-merge-tick";
13import { gatherInbox, type InboxApp } from "./inbox";
14import { readSafetyReport } from "./merge-safety";
15import type { OpsMergeSafety } from "./ops-types/feed";
16import { externalFence } from "./provenance";
17import { readMaintenance, type MaintenanceItem } from "./maintenance";
18
19// Capsid's status as a driver and the Portal read it (capsid_run_improve action status,
20// GET /portal/api/namespaces): per namespace the queue, the breaker, what waits on the
21// seat and the maintenance list, and across them the signed policies, the overnight
22// switch, the merge safety meter and, for the admin, the credential inventory. The
23// tool keeps the improve loop's name, which it was served under before the loop was
24// removed (Dustin, 2026-10-19), so no credential's tools list has to change.
25
26interface NamespaceStatus {
27  namespace: string;
28  // The queue's circuit breaker (src/job-breaker.ts): open when the namespace's drivers
29  // failed the threshold of jobs in 24 hours, until the seat or Dustin resets it.
30  breaker: BreakerState;
31  // The latest `capsid_lint_namespace` report document under reports/. null means no report was ever
32  // run here, which is not an integrity of zero.
33  latest_report: { path: string; integrity: number | null; generated: string } | null;
34  // Counts for the open states and today's moves, plus the blocked jobs themselves with
35  // the command each waits on, because a count alone tells nobody what to run.
36  jobs: JobsSummary;
37  // Pull requests the auto-merge policy declined, each with the refusing check. The
38  // tick rewrites the whole list, so it needs no expiry. Empty when the policy is off.
39  awaiting_seat: AwaitingSeat[];
40  // The daily maintenance pass's list for this namespace (src/maintenance.ts): stale or
41  // mislabelled jobs, what was resumed for the seat, green driver pull requests waiting,
42  // pull requests red for days, and merged or old branches. Empty before the first pass.
43  maintenance: MaintenanceItem[];
44  // Open pull requests that pass read in this namespace, so an empty pull request list can
45  // be told from one that read nothing. null when the pass did not read them (never ran,
46  // not a roster namespace, or the read failed and a prs-not-checked item says why).
47  maintenance_prs_read: number | null;
48  // Branches that pass read in this namespace, the same way: null when it read none.
49  maintenance_branches_read: number | null;
50  // What needs Dustin in this namespace's app (src/inbox.ts): blocked jobs and questions,
51  // pull requests auto-merge declined, a failing CI run, a site that is down. The same
52  // answer GET /ops/inbox serves the admin shell, narrowed to this namespace.
53  needs_dustin: InboxApp;
54}
55
56export interface StatusReport {
57  // The canon documents a driver's write turns into a proposal (src/canon.ts), so a
58  // driver knows before it writes.
59  canon_paths: ReturnType<typeof servedCanonPaths>;
60  // Admin only: the proposals waiting for approval.
61  canon_proposals?: PendingProposal[];
62  // The version a driver passes as approved_by_policy, served here because a
63  // namespace-scoped driver cannot read the capsid namespace. Only the version and
64  // whether it is on, never the body. Reported only when the policy loads (signature
65  // verified, agreeing with the code); otherwise the reason it does not.
66  policies: PolicyVersions;
67  // The overnight run's switch and, when it runs on the subscription, the recorded
68  // decision (src/overnight.ts). The scheduler reads this before it starts a session.
69  overnight: OvernightState;
70  // The auto-merge safety meter and shutoff (src/merge-safety.ts): the last seven days per
71  // namespace and whether auto-merge is paused there, from the report the tick keeps, so
72  // asking costs one KV read. Null before the tick's first pass. A scoped caller sees its
73  // own namespaces' rows only.
74  merge_safety: OpsMergeSafety | null;
75  // The credential inventory. Revoked rows are included and say so, so "revoked" and
76  // "never existed" look different. Never the key or the stored verifier, and only the
77  // flags an agent holds. Absent, not empty, for a scoped caller: an empty list would
78  // read as "no agents exist".
79  agents?: AgentSummary[];
80  namespaces: NamespaceStatus[];
81}
82
83export interface AgentSummary {
84  name: string;
85  kind: string;
86  namespaces: "*" | string[];
87  grants: string[];
88  flags: string[];
89  last_seen: string | null;
90  revoked_at: string | null;
91  // When the watcher pass moved it to agents_archive (src/agents-archive.ts), or null
92  // for a row still in agents. An archived agent is always revoked.
93  archived_at: string | null;
94  // What this credential has done, from job_outcomes. Counts and rates, never a
95  // composite score (src/agent-record.ts says why).
96  record: AgentRecord;
97}
98
99// Exported for the Watch Floor feed (src/ops-feed.ts), which lists the same inventory
100// with the same records rather than a second reading of the agents table.
101// The archive is read newest move first and bounded: the archive grows as revoked agents
102// move out of the live table. The full archive is agents list with
103// archived: true.
104const SUMMARY_ARCHIVE_LIMIT = 50;
105
106export async function agentSummaries(db: D1Database): Promise<AgentSummary[]> {
107  const { results } = await db
108    .prepare(
109      `SELECT name, kind, scopes, last_seen, revoked_at, NULL AS archived_at FROM agents
110       UNION ALL
111       SELECT * FROM (SELECT name, kind, scopes, last_seen, revoked_at, archived_at FROM agents_archive ORDER BY archived_at DESC, name LIMIT ?1)`
112    )
113    .bind(SUMMARY_ARCHIVE_LIMIT)
114    .all<{ name: string; kind: string; scopes: string; last_seen: string | null; revoked_at: string | null; archived_at: string | null }>();
115  // Live first, then revoked, then archived; by name within each.
116  const rank = (r: { revoked_at: string | null; archived_at: string | null }) => (r.archived_at ? 2 : r.revoked_at ? 1 : 0);
117  const rows = [...(results ?? [])].sort((a, b) => rank(a) - rank(b) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
118  const inventory = rows.map((row) => {
119    const scopes = parseScopes(row.scopes);
120    return {
121      name: row.name,
122      kind: row.kind,
123      namespaces: scopes.namespaces,
124      grants: scopes.grants,
125      flags: SCOPE_FLAGS.filter((flag) => scopes.flags[flag]),
126      last_seen: row.last_seen,
127      revoked_at: row.revoked_at,
128      archived_at: row.archived_at,
129    };
130  });
131  // Three grouped reads for the whole inventory, not three per credential.
132  const records = await loadAgentRecords(db, inventory);
133  return inventory.map((agent) => ({ ...agent, record: records[agent.name] }));
134}
135
136/** One signed policy as a driver needs it: which version, and whether it is on. */
137type ServedPolicy = { version: string; enabled: boolean } | { reason: string };
138
139interface PolicyVersions {
140  gates: ServedPolicy;
141  auto_merge: ServedPolicy;
142}
143
144async function servedPolicies(env: Env): Promise<PolicyVersions> {
145  // Each load verifies the stored document's signature and checks it describes no less
146  // than the code enforces. A throw is reported, not raised: a driver asking what
147  // version is current should not have status fail because a policy is being re-signed.
148  const one = async (load: () => Promise<{ policy: { version: string; enabled: boolean } } | { error: string }>): Promise<ServedPolicy> => {
149    try {
150      const loaded = await load();
151      return "error" in loaded ? { reason: loaded.error } : { version: loaded.policy.version, enabled: loaded.policy.enabled };
152    } catch (err) {
153      return { reason: `the policy could not be read: ${err instanceof Error ? err.message : String(err)}` };
154    }
155  };
156  return { gates: await one(() => loadGatePolicy(env)), auto_merge: await one(() => loadMergePolicy(env)) };
157}
158
159// An item an app reported about itself is the app's words, and an agent reads
160// capsid_run_improve action status, so its title is relayed inside an external fence (src/provenance.ts,
161// OWASP item 1; capsid/research/design-inbox-report.md, "Trust").
162function fenceReported(app: InboxApp): InboxApp {
163  return { ...app, items: app.items.map((item) => (item.kind === "report" ? { ...item, title: externalFence("inbox-report", app.namespace, item.title) } : item)) };
164}
165
166export async function capsidStatus(
167  env: Env,
168  only?: string,
169  // The caller's namespaces and whether it is the admin, supplied by the tool from the
170  // resolved agent. Omitted means unrestricted (the cron, the Portal). A scoped caller
171  // sees only its own namespaces and no credential inventory, because both map the
172  // boundary it sits behind.
173  scope?: { namespaces: "*" | string[]; admin: boolean }
174): Promise<StatusReport> {
175  const allowed = scope?.namespaces ?? "*";
176  const requested = only ? [only] : [...APP_ROSTER];
177  const namespaces = allowed === "*" ? requested : requested.filter((n) => allowed.includes(n));
178  const out: NamespaceStatus[] = [];
179
180  // One read for every namespace. An unreadable or malformed key reports an empty set
181  // rather than failing status.
182  let awaitingAll: AwaitingSeat[] = [];
183  try {
184    const raw = await env.APP_KV.get(AWAITING_SEAT_KEY);
185    if (raw) {
186      const parsed: unknown = JSON.parse(raw);
187      if (Array.isArray(parsed)) awaitingAll = parsed as AwaitingSeat[];
188    }
189  } catch {
190    awaitingAll = [];
191  }
192  const mergeSafety = await readSafetyReport(env.APP_KV);
193  const inboxAll = await gatherInbox(env, new Date(), namespaces);
194  const maintenanceList = await readMaintenance(env);
195  const maintenanceAll = maintenanceList?.items ?? [];
196
197  for (const namespace of namespaces) {
198    const report = await env.DB
199      .prepare(
200        `SELECT path, body, updated_at FROM documents
201         WHERE namespace = ?1 AND path LIKE ?2 AND type = 'reference'
202         ORDER BY path DESC LIMIT 1`
203      )
204      .bind(namespace, `${REPORTS_PREFIX}lint-%`)
205      .first<{ path: string; body: string | null; updated_at: string }>();
206
207    out.push({
208      namespace,
209      breaker: await breakerState(env, namespace, new Date()),
210      // The filename is ISO-dated, so ORDER BY path gives the newest date. updated_at
211      // would give the most recently rewritten report instead.
212      latest_report: report
213        ? { path: `${namespace}/${report.path}`, integrity: integrityOf(report.body), generated: report.updated_at }
214        : null,
215      jobs: await jobsSummary(env.DB, namespace, new Date(), env.IMPROVE_SCORE_SECRET),
216      awaiting_seat: awaitingAll.filter((a) => a.namespace === namespace),
217      maintenance: maintenanceAll.filter((m) => m.namespace === namespace),
218      maintenance_prs_read: maintenanceList?.prs_read[namespace] ?? null,
219      maintenance_branches_read: maintenanceList?.branches_read[namespace] ?? null,
220      needs_dustin: fenceReported(inboxAll.apps.find((a) => a.namespace === namespace) ?? { namespace, name: namespace, count: 0, severity: "none", items: [] }),
221    });
222  }
223
224  return {
225    canon_paths: servedCanonPaths(),
226    policies: await servedPolicies(env),
227    overnight: await overnightState(env),
228    merge_safety: mergeSafety && allowed !== "*" ? { ...mergeSafety, namespaces: mergeSafety.namespaces.filter((n) => allowed.includes(n.namespace)) } : mergeSafety,
229    // Admin only: the inventory is the map an agent looking to widen itself would want.
230    ...(scope && !scope.admin ? {} : { agents: await agentSummaries(env.DB), canon_proposals: await pendingProposals(env.DB) }),
231    namespaces: out,
232  };
233}