src/controls-perform.ts

Functions

Imports

It imports src/agents-admin.ts, src/agents.ts, src/canon.ts, src/controls-base.ts, src/env.ts, src/github.ts, src/job-breaker.ts, src/jobs-park.ts, src/jobs-seat.ts, src/jobs-transition.ts, src/log.ts, src/merge-safety.ts, src/merge-units.ts, src/ops-packages.ts, src/ops-sites.ts, src/ops-types/portal.ts, src/overnight.ts, src/policy-sign.ts, src/pr-approvals.ts, src/site-repair.ts, src/store-guards.ts. Imported by src/controls.ts.

Source

1import { adminAgentForEmail } from "./agents";
2import { revokeAgent } from "./agents-admin";
3import { approveProposal, rejectProposal, readSweep } from "./canon";
4import {
5  type ActionParams,
6  type Surface,
7  AUTOMERGE_RESUME_REASON,
8  CANON_REJECT_REASON,
9  UNIT_RESUME_REASON,
10  SWITCHES,
11  auditPrefix,
12  clickAuditAction,
13  revisionOf,
14  shippedEvidence,
15  sweepOrder,
16  switchReasonRefusal,
17} from "./controls-base";
18import type { Env } from "./env";
19import { managePr } from "./github";
20import { resetBreaker } from "./job-breaker";
21import { parkJob, unparkJob } from "./jobs-park";
22import { resumeJob, releaseJob, adminFailJob, completeAsCaller, supersedeJob } from "./jobs-seat";
23import { readJob } from "./jobs-transition";
24import { logEvent } from "./log";
25import { resumeNamespace } from "./merge-safety";
26import { liftSuspension } from "./merge-units";
27import { removePackage, validatePackage, addPackage, editPackage, describePackage } from "./ops-packages";
28import { removeSite, validateSite, addSite, editSite, describeSite } from "./ops-sites";
29import type { PortalAction } from "./ops-types/portal";
30import { overnightValueRefusal, setOvernight } from "./overnight";
31import { performPolicyChange, performPolicyFromRepo } from "./policy-sign";
32import { planApproval, performApproval } from "./pr-approvals";
33import { runSiteRepair } from "./site-repair";
34import { auditStatement } from "./store-guards";
35
36// A control's perform (src/controls.ts is the core): the one dispatch to the shared
37// mutators, run once a signed preview token is verified.
38
39function required(params: ActionParams, field: string): string | null {
40  const value = params[field];
41  return typeof value === "string" && value.trim() ? value.trim() : null;
42}
43
44// The click's own audit row, naming the admin and the address the click came from
45// (sourceAddress). The shared mutators' rows do not always say who asked.
46async function auditClick(
47  env: Env,
48  actor: string,
49  source: string | null,
50  surface: Surface,
51  action: PortalAction,
52  namespace: string | null,
53  params: object,
54  name = `${auditPrefix(surface)}${action}`
55) {
56  await env.DB.batch([auditStatement(env.DB, actor, name, namespace, null, { ...params, surface, source_address: source })]);
57}
58
59export type ActionResult =
60  // It happened. warning is set when the click's own audit row was not written.
61  | { ok: true; summary: string; warning: string | null }
62  // It did not happen, and why.
63  | { ok: false; refusal: string };
64
65/** One action, performed by the administrator `email`: the shared mutator the MCP tool
66 *  calls, then the click's audit row. Nothing here reimplements a transition. */
67export async function performAction(
68  env: Env,
69  email: string,
70  source: string | null,
71  now: Date,
72  action: PortalAction,
73  params: ActionParams,
74  surface: Surface = "portal"
75): Promise<ActionResult> {
76  const agent = adminAgentForEmail(email);
77  const actor = agent.actor;
78  // Set once the mutator succeeds, so the catch knows whether the action happened.
79  let committed = false;
80  let summary = "";
81  // The switches: a reason in both directions, checked again here because the token
82  // binds the params and a token signed before this rule could lack one. The reason and
83  // whether this is an Undo go in the click row.
84  const switchReason = SWITCHES.has(action) ? required(params, "reason") : null;
85  if (SWITCHES.has(action) && !switchReason) return { ok: false, refusal: switchReasonRefusal(action) };
86  const undo = params.undo === "true";
87  const click = clickAuditAction(action, params, surface);
88  const switchDetail = (result: object) => ({ ...result, reason: switchReason, ...(undo ? { undo: true } : {}) });
89  try {
90    switch (action) {
91      case "reset_breaker": {
92        const namespace = required(params, "namespace");
93        if (!namespace) return { ok: false, refusal: "reset_breaker needs a namespace." };
94        const result = await resetBreaker(env, actor, now, { namespace });
95        if (!result.ok) return { ok: false, refusal: result.error };
96        committed = true;
97        summary = `Reset the circuit breaker for ${namespace}.`;
98        await auditClick(env, actor, source, surface, action, namespace, result.state);
99        break;
100      }
101      case "overnight": {
102        const value = required(params, "value");
103        const bad = overnightValueRefusal(value ?? undefined);
104        if (bad) return { ok: false, refusal: bad };
105        const result = await setOvernight(env, actor, now, { value: value ?? undefined, reason: switchReason ?? undefined });
106        committed = true;
107        summary = result.mode === "off" ? "Turned the overnight run off." : `Set the overnight run to run on ${result.mode === "api" ? "the API key" : "the subscription"}.`;
108        await auditClick(env, actor, source, surface, action, null, switchDetail({ mode: result.mode, ...(result.decision ? { decision: result.decision } : {}) }), click);
109        break;
110      }
111      case "resume_job":
112      case "release_job":
113      case "fail_job": {
114        const id = required(params, "id");
115        const reason = required(params, "reason");
116        if (!id) return { ok: false, refusal: `${action} needs a job id.` };
117        if (!reason) {
118          return {
119            ok: false,
120            refusal:
121              action === "resume_job"
122                ? "resume needs a reason: what you approved. A job that came back off a gate with no record of who cleared it is a gate that did not happen."
123                : action === "release_job"
124                  ? "release needs a reason: why the holder is not coming back."
125                  : "fail needs a reason. A failed job with no reason is one nobody can retry or rule on.",
126          };
127        }
128        // resume_job's note is the full approval when it is longer than a line (stale jobs
129        // D6): the driver reads it as resume_note.note on its next claim or list.
130        const note = action === "resume_job" ? (required(params, "note") ?? undefined) : undefined;
131        const result =
132          action === "resume_job"
133            ? await resumeJob(env, agent, now, id, reason, { note })
134            : action === "release_job"
135              ? await releaseJob(env, agent, now, id, reason)
136              : await adminFailJob(env, agent, now, id, reason);
137        if (!result.ok) return { ok: false, refusal: result.refusal ?? `${action} was refused.` };
138        committed = true;
139        summary =
140          action === "resume_job"
141            ? result.job?.status === "queued"
142              ? `Resumed ${id}; it went back to the queue. ${result.note ?? ""}`.trim()
143              : `Resumed ${id}; it is claimed again by ${result.job?.claimed_by ?? "its claimant"}.`
144            : action === "release_job"
145              ? `Released ${id} back to the queue.`
146              : `Marked ${id} failed.`;
147        await auditClick(env, actor, source, surface, action, result.job?.namespace ?? null, { id, reason, ...(note ? { note } : {}) });
148        break;
149      }
150      case "close_shipped": {
151        const id = required(params, "id");
152        const reason = required(params, "reason");
153        if (!id) return { ok: false, refusal: "close_shipped needs a job id." };
154        if (!reason) return { ok: false, refusal: "close_shipped needs a reason: what shipped, and how you know. It is the job's result summary." };
155        const job = await readJob(env.DB, id);
156        if (!job) return { ok: false, refusal: `no job ${id}.` };
157        const shipped = shippedEvidence(job);
158        const result = await completeAsCaller(env, agent, now, id, {
159          result_summary: `Closed as shipped by ${actor}: ${reason}`,
160          ...(shipped.result_ref ? { result_ref: shipped.result_ref } : {}),
161          ...(shipped.prs.length ? { evidence: { prs: shipped.prs } } : {}),
162        });
163        if (!result.ok) return { ok: false, refusal: result.refusal ?? "close_shipped was refused." };
164        committed = true;
165        summary = `Closed ${id} as shipped; the outcome is credited to ${job.claimed_by ?? "its holder"}.`;
166        await auditClick(env, actor, source, surface, action, job.namespace, { id, reason, held_by: job.claimed_by, prs: shipped.prs.length });
167        break;
168      }
169      case "supersede_job": {
170        const id = required(params, "id");
171        const reason = required(params, "reason");
172        if (!id) return { ok: false, refusal: "supersede_job needs a job id." };
173        if (!reason) return { ok: false, refusal: "supersede_job needs a reason: what replaced this job, or why it was withdrawn." };
174        const replaced_by = required(params, "replaced_by") ?? undefined;
175        const result = await supersedeJob(env, agent, now, id, { reason, replaced_by });
176        if (!result.ok) return { ok: false, refusal: result.refusal ?? "supersede_job was refused." };
177        committed = true;
178        summary = `Superseded ${id}${replaced_by ? ` with ${replaced_by}` : ""}.`;
179        await auditClick(env, actor, source, surface, action, result.job?.namespace ?? null, { id, reason, ...(replaced_by ? { replaced_by } : {}) });
180        break;
181      }
182      case "park_job":
183      case "unpark_job": {
184        const id = required(params, "id");
185        if (!id) return { ok: false, refusal: `${action} needs a job id.` };
186        const reason = required(params, "reason");
187        if (action === "park_job" && !reason) return { ok: false, refusal: "park_job needs a reason in one line saying when the job comes back." };
188        const result = action === "park_job" ? await parkJob(env, agent, now, id, reason ?? undefined) : await unparkJob(env, agent, now, id);
189        if (!result.ok) return { ok: false, refusal: result.refusal ?? `${action} was refused.` };
190        committed = true;
191        summary = action === "park_job" ? `Parked ${id}.` : `Unparked ${id}; it is queued again.`;
192        await auditClick(env, actor, source, surface, action, result.job?.namespace ?? null, { id, reason, ...(undo ? { undo: true } : {}) }, click);
193        break;
194      }
195      case "approve_pr": {
196        // Planned again from the state now: the heads, the classes and the open approvals
197        // may have moved since the preview, and the approval is of what is true now.
198        const clean = Object.fromEntries(Object.entries(params).filter((e): e is [string, string] => typeof e[1] === "string"));
199        const plan = await planApproval(env, actor, clean, surface, click);
200        if (!plan.ok) return { ok: false, refusal: plan.refusal };
201        summary = await performApproval(env, actor, plan, required(params, "reason"), now);
202        committed = true;
203        await auditClick(env, actor, source, surface, action, plan.namespace, { repo: plan.repo, prs: plan.targets.map((t) => ({ pr: t.number, head_sha: t.head_sha, class: t.class })), approval_surface: plan.surface, ...(undo ? { undo: true } : {}) }, click);
204        break;
205      }
206      case "sign_policy_change": {
207        // Planned again from the policy now, and refused unless the new version is typed.
208        const done = await performPolicyChange(env, actor, required(params, "change") ?? undefined, required(params, "unit") ?? undefined, required(params, "confirm") ?? undefined);
209        if (!done.ok) return { ok: false, refusal: done.error };
210        summary = done.summary;
211        committed = true;
212        await auditClick(env, actor, source, surface, action, "capsid", { change: params.change, unit: params.unit, confirm: params.confirm, reason: required(params, "reason") }, click);
213        break;
214      }
215      case "sign_policy_from_repo": {
216        // The file is read again and must read as the preview's did (the hash the token
217        // binds), and the typed version must be the file's.
218        const done = await performPolicyFromRepo(env, actor, required(params, "confirm") ?? undefined, required(params, "source_sha") ?? undefined);
219        if (!done.ok) return { ok: false, refusal: done.error };
220        summary = done.summary;
221        committed = true;
222        await auditClick(env, actor, source, surface, action, "capsid", { confirm: params.confirm, source_sha: params.source_sha, reason: required(params, "reason") }, click);
223        break;
224      }
225      case "unit_resume": {
226        const reason = required(params, "reason");
227        if (!reason) return { ok: false, refusal: UNIT_RESUME_REASON };
228        const done = await liftSuspension(env, actor, required(params, "unit") ?? undefined, reason, now);
229        if (!done.ok) return { ok: false, refusal: done.refusal };
230        summary = done.summary;
231        committed = true;
232        await auditClick(env, actor, source, surface, action, (params.unit ?? "").split("/")[0]!.trim() || null, { unit: params.unit, reason }, click);
233        break;
234      }
235      case "automerge_resume": {
236        const reason = required(params, "reason");
237        if (!reason) return { ok: false, refusal: AUTOMERGE_RESUME_REASON };
238        const done = await resumeNamespace(env, actor, required(params, "namespace") ?? undefined, reason, now);
239        if (!done.ok) return { ok: false, refusal: done.refusal };
240        summary = done.summary;
241        committed = true;
242        await auditClick(env, actor, source, surface, action, (params.namespace ?? "").trim() || null, { namespace: params.namespace, reason }, click);
243        break;
244      }
245      case "pr_close": {
246        const namespace = required(params, "namespace");
247        const number = Number(required(params, "number"));
248        const reason = required(params, "reason");
249        if (!namespace || !Number.isInteger(number) || number < 1) return { ok: false, refusal: "pr_close needs a namespace and the pull request's number." };
250        if (!reason) return { ok: false, refusal: "pr_close needs a reason: why the pull request is closed without merging." };
251        const repo = required(params, "repo") ?? undefined;
252        // Only the close shape comes back from action "close".
253        const result = (await managePr(env, namespace, number, "close", "squash", repo)) as { repo: string; head_branch: string | null; head_branch_deleted: boolean };
254        committed = true;
255        summary = `Closed ${result.repo}#${number}${result.head_branch_deleted ? `; its branch ${result.head_branch} was deleted` : ""}.`;
256        // managePr writes no audit row of its own (the guardedWrite behind capsid_close_pr action close does),
257        // so the control writes the change's row beside the click row.
258        await env.DB.batch([auditStatement(env.DB, actor, "pr-closed", namespace, null, { repo: result.repo, number, reason, head_branch: result.head_branch, head_branch_deleted: result.head_branch_deleted })]);
259        await auditClick(env, actor, source, surface, action, namespace, { repo: result.repo, number, reason });
260        break;
261      }
262      case "revoke_agent": {
263        const name = required(params, "name");
264        if (!name) return { ok: false, refusal: "revoke_agent needs an agent name." };
265        const result = await revokeAgent(env.DB, actor, name);
266        if (!result.ok) return { ok: false, refusal: result.refusal ?? `revoking ${name} was refused.` };
267        committed = true;
268        summary = `Revoked the agent ${name}.`;
269        await auditClick(env, actor, source, surface, action, null, { name });
270        break;
271      }
272      case "site_add":
273      case "site_edit":
274      case "site_remove": {
275        // Checked again here, not only at preview: the token binds the params, and the
276        // rules could have changed under a token signed before a deploy.
277        let result;
278        if (action === "site_remove") {
279          const revision = revisionOf(params.revision);
280          if (!params.namespace || revision === null) return { ok: false, refusal: "site_remove needs a namespace and the revision it previewed." };
281          result = await removeSite(env.DB, actor, params.namespace, revision);
282        } else {
283          const checked = validateSite(params);
284          if (!checked.ok) return { ok: false, refusal: checked.refusal };
285          if (action === "site_add") {
286            result = await addSite(env.DB, actor, checked.site);
287          } else {
288            const revision = revisionOf(params.revision);
289            if (revision === null) return { ok: false, refusal: "site_edit needs the revision it previewed." };
290            result = await editSite(env.DB, actor, checked.site, revision);
291          }
292        }
293        if (!result.ok) return { ok: false, refusal: result.refusal };
294        committed = true;
295        summary =
296          action === "site_add"
297            ? `Added ${result.site.namespace}: ${describeSite(result.site)}.`
298            : action === "site_edit"
299              ? `Changed ${result.site.namespace}: ${describeSite(result.site)}.`
300              : `Removed ${result.site.namespace} from the site configuration.`;
301        await auditClick(env, actor, source, surface, action, result.site.namespace, params);
302        break;
303      }
304      case "package_add":
305      case "package_edit":
306      case "package_remove": {
307        // Checked again here, as the site controls are: the token binds the params, not
308        // the rules they were checked against.
309        let result;
310        if (action === "package_remove") {
311          const revision = revisionOf(params.revision);
312          if (!params.name || revision === null) return { ok: false, refusal: "package_remove needs a name and the revision it previewed." };
313          result = await removePackage(env.DB, actor, params.name, revision);
314        } else {
315          const checked = validatePackage(params);
316          if (!checked.ok) return { ok: false, refusal: checked.refusal };
317          if (action === "package_add") {
318            result = await addPackage(env.DB, actor, checked.pkg);
319          } else {
320            const revision = revisionOf(params.revision);
321            if (revision === null) return { ok: false, refusal: "package_edit needs the revision it previewed." };
322            result = await editPackage(env.DB, actor, checked.pkg, revision);
323          }
324        }
325        if (!result.ok) return { ok: false, refusal: result.refusal };
326        committed = true;
327        summary =
328          action === "package_add"
329            ? `Added ${describePackage(result.pkg)}.`
330            : action === "package_edit"
331              ? `Changed ${result.pkg.name}: ${describePackage(result.pkg)}.`
332              : `Removed ${result.pkg.name} from the packages.`;
333        await auditClick(env, actor, source, surface, action, null, params);
334        break;
335      }
336      case "canon_approve":
337      case "canon_reject": {
338        // Checked again here, as the site controls are: the token binds the params, and
339        // the proposal or its document can move between the preview and this click.
340        const id = revisionOf(params.id);
341        if (id === null) return { ok: false, refusal: `${action} needs the proposal id, a positive integer.` };
342        const reason = required(params, "reason");
343        if (action === "canon_reject" && !reason) return { ok: false, refusal: CANON_REJECT_REASON };
344        const result = action === "canon_approve" ? await approveProposal(env.DB, actor, now, id) : await rejectProposal(env.DB, actor, now, id, reason as string);
345        if (!result.ok) return { ok: false, refusal: result.refusal };
346        committed = true;
347        summary =
348          action === "canon_approve"
349            ? `Approved proposal ${id}: ${result.row.namespace}/${result.row.path} is written as ${result.row.proposer} proposed.`
350            : `Rejected proposal ${id} for ${result.row.namespace}/${result.row.path}.`;
351        await auditClick(env, actor, source, surface, action, result.row.namespace, { id, ...(reason ? { reason } : {}), path: result.row.path });
352        break;
353      }
354      case "canon_approve_all": {
355        // The token binds the plan its preview read. The queue is read again and the plan
356        // must read the same, so a proposal that arrived, was decided or went stale since
357        // is never swept in: the perform is refused and the preview shows the queue as it is.
358        const bound = params.plan;
359        if (!bound) return { ok: false, refusal: "canon_approve_all carries the plan its preview read, and this confirmation has none. Nothing changed. Preview again." };
360        const sweep = await readSweep(env.DB);
361        if (!sweep.ok) return { ok: false, refusal: `${sweep.refusal} The pending canon proposals changed since the preview. Nothing changed.` };
362        if (sweep.key !== bound) {
363          return { ok: false, refusal: `the pending canon proposals changed since the preview (it planned ${bound}; they now plan ${sweep.key}). Nothing changed. Preview again.` };
364        }
365        const reason = required(params, "reason");
366        const done: Array<{ id: number; outcome: string; target: string }> = [];
367        const failed: Array<{ id: number; outcome: string; target: string; refusal: string }> = [];
368        for (const item of sweepOrder(sweep.items)) {
369          const { id } = item.proposal;
370          const target = `${item.proposal.namespace}/${item.proposal.path}`;
371          // One failure does not stop the rest: each is its own decision, guarded on its
372          // own state, and a failure is reported with its refusal.
373          try {
374            const result = item.reason === null ? await approveProposal(env.DB, actor, now, id) : await rejectProposal(env.DB, actor, now, id, item.reason);
375            if (result.ok) done.push({ id, outcome: item.outcome, target });
376            else failed.push({ id, outcome: item.outcome, target, refusal: result.refusal });
377          } catch (err) {
378            const message = err instanceof Error ? err.message : String(err);
379            logEvent("error", "CANON_APPROVE_ALL_ITEM_FAILED", { id, outcome: item.outcome, message });
380            failed.push({ id, outcome: item.outcome, target, refusal: message });
381          }
382        }
383        const failures = failed.map((f) => `${f.id} (${f.target}, to ${f.outcome === "approve" ? "approve" : "reject"}): ${f.refusal}`);
384        if (!done.length) return { ok: false, refusal: `canon_approve_all decided nothing. ${failures.join(" ")}` };
385        committed = true;
386        const approved = done.filter((d) => d.outcome === "approve");
387        const rejected = done.filter((d) => d.outcome !== "approve");
388        summary = [
389          `Decided ${done.length} of ${sweep.items.length} canon proposal(s).`,
390          approved.length ? `Approved ${approved.map((d) => `${d.id} (${d.target})`).join(", ")}.` : "",
391          rejected.length ? `Rejected ${rejected.map((d) => `${d.id} (${d.target}, ${d.outcome})`).join(", ")}.` : "",
392          failed.length ? `Failed ${failed.length}: ${failures.join(" ")}` : "",
393        ]
394          .filter(Boolean)
395          .join(" ");
396        await auditClick(env, actor, source, surface, action, null, {
397          plan: bound,
398          ...(reason ? { reason } : {}),
399          approved: approved.map((d) => d.id),
400          rejected: rejected.map((d) => d.id),
401          failed: failed.map((f) => ({ id: f.id, refusal: f.refusal })),
402        });
403        break;
404      }
405      case "site_repair": {
406        // Every check runs again inside runSiteRepair: the allowlist, the token and the
407        // rate limit can all change between the preview and this click.
408        const namespace = required(params, "namespace");
409        const tool = required(params, "tool");
410        if (!namespace || !tool) return { ok: false, refusal: "site_repair needs a namespace and a tool." };
411        const outcome = await runSiteRepair(env, { namespace, tool, actor, auto: false, via: surface }, now);
412        if (!outcome.ran) return { ok: false, refusal: outcome.refusal };
413        committed = true;
414        summary = `${namespace}: ${outcome.line}.${outcome.recorded ? "" : " The call's audit row was not written (SITE_REPAIR_NOT_RECORDED in the log)."}`;
415        await auditClick(env, actor, source, surface, action, namespace, { tool, ok: outcome.call.ok, converged: outcome.call.converged });
416        break;
417      }
418    }
419  } catch (err) {
420    const message = err instanceof Error ? err.message : String(err);
421    if (committed) {
422      // The action happened; only the Portal's own audit row failed, so no refusal.
423      const warning = `${action} completed, but the Portal audit row naming ${actor} was not written: ${message}`;
424      logEvent("error", "PORTAL_ACTION_AUDIT_FAILED", { message: warning });
425      return { ok: true, summary, warning };
426    }
427    return { ok: false, refusal: message };
428  }
429  return { ok: true, summary, warning: null };
430}