Public: anyone can read this; the crew can change it.
Maintenance framework: a maintainer crew role with scheduled duties, budgets and probe-backed findings #8933
mason/forge:mason/7554-maintenance-framework-a-maintainer-crew → main 8 commits fork 3 threads · 3 unresolved
41 files
changed +1592
−4
docs/design/audit.md +1
| @@ -60,6 +60,7 @@ Machine routes are not pages and have no entry: `/audit.csv`, | ||
| 60 | 60 | - `/asked` — `studio/asked_page.ts` · what I answered, as a record · `/asks` · none seen. |
| 61 | 61 | - `/review` — `studio/review_page.ts` · every ask waiting on me, one row each, newest first · `/asks` (same asks, with buttons) · none seen. |
| 62 | 62 | - `/flow` — `pages/flow.ts` · the pipeline from ready issue to live deploy, and the bottleneck · `/system`, `/board`, `/` · none seen. A topbar button points here. |
| 63 | - `/maintain` — `pages/maintain.ts` · the maintainer's duties and latest runs, a forge admin's; Pause and Resume are post forms · `/flow` (a Maintainer button), the terminal's Maintainer entry · none seen. | |
| 63 | 64 | - `/talk` — `pages/talk.ts` · the person's one conversation with the forge: history, composer, Confirm and Cancel; replies stream in over `/talk/stream` · `/settings/confirms` (the same yes, as a list), the home tell box (one line to an app's crew) · none seen; styles in `docs/design/areas/talk.md`. |
| 64 | 65 | - `/notes` — `pages/notes.ts` · what the person wrote, newest first, with the planner's verdict and live state in one line, and one tap to overrule it · the home tell box (Notes button), the user menu, the palette · none seen; styles in `docs/design/areas/notes.md`. |
| 65 | 66 | - `/pipeline` — `pages/pipeline.ts` · the four steps a change follows (check, review, land, live), for a newcomer · a pull page's step line, `/flow` · none seen. |
docs/features/maintainer.md added +32
| @@ -0,0 +1,32 @@ | ||
| 1 | # The maintainer (#7554) | |
| 2 | ||
| 3 | A crew role (`maintainer`) for scheduled duties. A duty is a name, a trigger | |
| 4 | (`{ every: ms }`; an event trigger comes when something emits events), a budget (runs a day, dollars a day, | |
| 5 | milliseconds and network calls a run), a switch and a handler returning | |
| 6 | findings and actions. | |
| 7 | ||
| 8 | - **Add a duty:** one file in `src/maintain/duties/` using `duty({...})`, one | |
| 9 | import and one entry in `duties/index.ts`. `run_log.ts` is the pattern. | |
| 10 | - **Probes:** every finding and action carries `ctx.probe(query, value)`; the | |
| 11 | runner drops one without it and records the run as `refused`. | |
| 12 | - **Findings** go to the open issue for their stable key as a comment, or open | |
| 13 | one (`maintain/file.ts`, table `maintenance_finding`), as the seated | |
| 14 | `maintainer` agent; with none seated nothing is filed. A repeat comments | |
| 15 | only when the evidence changed or a day has passed. A run admits at most 20 | |
| 16 | findings, titles of 200 characters, evidence of 20 lines of 500. | |
| 17 | - **Bulk:** `ctx.bulk(items, { apply, check })` applies one item, checks its | |
| 18 | probe, then continues, capped at 20 a run; a failed check records `canary`. | |
| 19 | - **Budget:** over a day's runs or dollars, or past a run's network ceiling, | |
| 20 | the outcome is `budget`. A handler still going at its time ceiling is | |
| 21 | abandoned (its late calls throw) and the run is `budget`. | |
| 22 | - **Errors:** three in a row pause the duty with the reason. | |
| 23 | - **No landing:** a duty is handed `now`, `probe`, `net`, `spend`, `bulk` and | |
| 24 | `runs` (its own run log), never a database handle, and its files import | |
| 25 | nothing but `../duty.ts`; `src/maintain/` imports nothing that merges, | |
| 26 | pushes or spawns (`test/maintain-no-land.test.ts`). Fixes are pulls. | |
| 27 | - **Doors, all a forge admin's:** `/maintain` (links, post forms to pause or | |
| 28 | resume), the "Maintainer" palette entry in the terminal (`p` toggles), and | |
| 29 | `GET /api/v1/maintain/duties`, `GET …/runs?duty=`, | |
| 30 | `POST …/duties/:name/pause|resume` (forge admin). | |
| 31 | ||
| 32 | Starts on the autonomy clock after the sentinel but detached (`maintainInBackground`), so a slow duty never holds the sentinel, triage or review. |
src/contract/openapi/routes/getApiV1MaintainDuties.ts added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | import type { Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "get", | |
| 5 | path: "/api/v1/maintain/duties", | |
| 6 | summary: | |
| 7 | "The maintainer's duties with trigger, budget, switch, why one is paused and its last run (a person admin's token); answers { duties }", | |
| 8 | auth: true, | |
| 9 | refusals: { forbidden: "the token is not a person who administers the forge" }, | |
| 10 | }; |
src/contract/openapi/routes/getApiV1MaintainRuns.ts added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | import type { Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "get", | |
| 5 | path: "/api/v1/maintain/runs", | |
| 6 | summary: | |
| 7 | "The maintainer's run rows, newest first, each with findings, actions, probes, outcome and cost; ?duty= narrows to one duty (a person admin's token); answers { runs }", | |
| 8 | auth: true, | |
| 9 | refusals: { forbidden: "the token is not a person who administers the forge" }, | |
| 10 | }; |
src/contract/openapi/routes/index.ts +4
| @@ -77,6 +77,8 @@ export { route as getApiV1Front } from "./getApiV1Front.ts"; | ||
| 77 | 77 | export { route as getApiV1Health } from "./getApiV1Health.ts"; |
| 78 | 78 | export { route as getApiV1Here } from "./getApiV1Here.ts"; |
| 79 | 79 | export { route as getApiV1Keeper } from "./getApiV1Keeper.ts"; |
| 80 | export { route as getApiV1MaintainDuties } from "./getApiV1MaintainDuties.ts"; | |
| 81 | export { route as getApiV1MaintainRuns } from "./getApiV1MaintainRuns.ts"; | |
| 80 | 82 | export { route as getApiV1Map } from "./getApiV1Map.ts"; |
| 81 | 83 | export { route as getApiV1MigrateJob } from "./getApiV1MigrateJob.ts"; |
| 82 | 84 | export { route as getApiV1MigrateJobStream } from "./getApiV1MigrateJobStream.ts"; |
| @@ -234,6 +236,8 @@ export { route as postApiV1FleetOpsIdUndo } from "./postApiV1FleetOpsIdUndo.ts"; | ||
| 234 | 236 | export { route as postApiV1Forges } from "./postApiV1Forges.ts"; |
| 235 | 237 | export { route as postApiV1ForgesNameClaimLink } from "./postApiV1ForgesNameClaimLink.ts"; |
| 236 | 238 | export { route as postApiV1Heartbeat } from "./postApiV1Heartbeat.ts"; |
| 239 | export { route as postApiV1MaintainDutiesNamePause } from "./postApiV1MaintainDutiesNamePause.ts"; | |
| 240 | export { route as postApiV1MaintainDutiesNameResume } from "./postApiV1MaintainDutiesNameResume.ts"; | |
| 237 | 241 | export { route as postApiV1Migrate } from "./postApiV1Migrate.ts"; |
| 238 | 242 | export { route as postApiV1Orgs } from "./postApiV1Orgs.ts"; |
| 239 | 243 | export { route as postApiV1OrgsOrgTeams } from "./postApiV1OrgsOrgTeams.ts"; |
src/contract/openapi/routes/postApiV1MaintainDutiesNamePause.ts added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | import type { Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: "/api/v1/maintain/duties/{name}/pause", | |
| 6 | summary: | |
| 7 | "Pause a maintainer duty until it is resumed (admin scope); answers { duties }", | |
| 8 | auth: true, | |
| 9 | refusals: { forbidden: "the token is not a person who administers the forge" }, | |
| 10 | }; |
src/contract/openapi/routes/postApiV1MaintainDutiesNameResume.ts added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | import type { Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "post", | |
| 5 | path: "/api/v1/maintain/duties/{name}/resume", | |
| 6 | summary: | |
| 7 | "Resume a paused maintainer duty and clear its error count (admin scope); answers { duties }", | |
| 8 | auth: true, | |
| 9 | refusals: { forbidden: "the token is not a person who administers the forge" }, | |
| 10 | }; |
src/core/agents.ts +5 −3
| @@ -303,14 +303,16 @@ export function deleteAgent(db: Database, userId: string): boolean { | ||
| 303 | 303 | /** |
| 304 | 304 | * What a crew member is for on one repository: a builder takes what is |
| 305 | 305 | * ready, a planner turns a direction into a map, a reviewer looks at what |
| 306 | * landed. Per repository, because the same agent may plan one and build | |
| 307 | * another. | |
| 306 | * landed, a maintainer runs scheduled duties (`src/maintain/`) and proposes | |
| 307 | * only through pulls. Per repository, because the same agent may plan one | |
| 308 | * and build another. | |
| 308 | 309 | */ |
| 309 | export type CrewRole = "builder" | "planner" | "reviewer"; | |
| 310 | export type CrewRole = "builder" | "planner" | "reviewer" | "maintainer"; | |
| 310 | 311 | export const CREW_ROLES: readonly CrewRole[] = [ |
| 311 | 312 | "planner", |
| 312 | 313 | "builder", |
| 313 | 314 | "reviewer", |
| 315 | "maintainer", | |
| 314 | 316 | ]; |
| 315 | 317 | export const isCrewRole = (value: unknown): value is CrewRole => |
| 316 | 318 | (CREW_ROLES as readonly unknown[]).includes(value); |
src/core/migration-pins/20261103150000-maintenance.pin added +1
| @@ -0,0 +1,1 @@ | ||
| 1 | bcb4fbf97a17f8b60ac4173cf297d0acea8f9e2f0bf1262e4eea092098e8cbaf |
src/core/migrations/20261103150000-maintenance.ts added +32
| @@ -0,0 +1,32 @@ | ||
| 1 | // The maintainer's duties (#7554): which duties are paused and why, one row | |
| 2 | // per run with the findings, actions and probes it left, and the issue a | |
| 3 | // finding's stable key was filed to, when it was last said and with what | |
| 4 | // evidence. Additive. | |
| 5 | export default ` | |
| 6 | CREATE TABLE maintenance_duty ( | |
| 7 | name TEXT PRIMARY KEY, | |
| 8 | enabled INTEGER NOT NULL DEFAULT 1, | |
| 9 | paused_reason TEXT, | |
| 10 | errors INTEGER NOT NULL DEFAULT 0 | |
| 11 | ) WITHOUT ROWID; | |
| 12 | CREATE TABLE maintenance_run ( | |
| 13 | id TEXT PRIMARY KEY, | |
| 14 | duty TEXT NOT NULL, | |
| 15 | started TEXT NOT NULL, | |
| 16 | finished TEXT NOT NULL, | |
| 17 | findings TEXT NOT NULL, | |
| 18 | actions TEXT NOT NULL, | |
| 19 | probes TEXT NOT NULL, | |
| 20 | outcome TEXT NOT NULL, | |
| 21 | cost REAL NOT NULL DEFAULT 0, | |
| 22 | detail TEXT | |
| 23 | ) WITHOUT ROWID; | |
| 24 | CREATE INDEX maintenance_run_duty ON maintenance_run(duty, started); | |
| 25 | CREATE TABLE maintenance_finding ( | |
| 26 | key TEXT PRIMARY KEY, | |
| 27 | issue_id TEXT NOT NULL, | |
| 28 | first_seen TEXT NOT NULL, | |
| 29 | last_seen TEXT NOT NULL, | |
| 30 | evidence TEXT NOT NULL DEFAULT '' | |
| 31 | ) WITHOUT ROWID; | |
| 32 | `; |
src/core/reserved.ts +1
| @@ -57,6 +57,7 @@ export const SYSTEM_NAMES: readonly string[] = [ | ||
| 57 | 57 | // the forge's own pages |
| 58 | 58 | "api", |
| 59 | 59 | "apps", |
| 60 | "maintain", | |
| 60 | 61 | "asks", |
| 61 | 62 | "assets", |
| 62 | 63 | "audit", |
src/crew/autonomy.ts +4
| @@ -64,6 +64,7 @@ import { getHold } from "../core/holds.ts"; | ||
| 64 | 64 | import { certain } from "./decide.ts"; |
| 65 | 65 | import { decideAndRecord } from "./ledger.ts"; |
| 66 | 66 | import { sentinelTick } from "./sentinel.ts"; |
| 67 | import { maintainInBackground } from "../maintain/service.ts"; | |
| 67 | 68 | import { triageTick } from "./triage.ts"; |
| 68 | 69 | import { liveTriage, none as noTriage, tickFields } from "./livetriage.ts"; |
| 69 | 70 | import { wallOf, wallPlain, wallSentence } from "../contract/policy.ts"; |
| @@ -1463,6 +1464,9 @@ export async function autonomyTick( | ||
| 1463 | 1464 | log.error("sentinel failed", { error: String(error) }); |
| 1464 | 1465 | } |
| 1465 | 1466 | await breathe(); |
| 1467 | // The maintainer's duties that are due (`maintain/runner.ts`). | |
| 1468 | maintainInBackground(app, now.getTime(), (error) => log.error("maintainer failed", { error: String(error) })); | |
| 1469 | await breathe(); | |
| 1466 | 1470 | // Review is not autonomy's alone: an agent's green pull is read by the |
| 1467 | 1471 | // crew's reviewer in every repository that has one. |
| 1468 | 1472 | try { |
src/crew/seat_slots.ts +1
| @@ -34,6 +34,7 @@ export const SEAT_UNIT: Record<CrewRole, string> = { | ||
| 34 | 34 | planner: "planning pass at once", |
| 35 | 35 | builder: "build at once", |
| 36 | 36 | reviewer: "review at once", |
| 37 | maintainer: "duty at once", | |
| 37 | 38 | }; |
| 38 | 39 | |
| 39 | 40 | export function slotsOf(repo: Repo, role: CrewRole): number { |
src/http/api.ts +2
| @@ -333,6 +333,7 @@ import { visionRoutes } from "./api/vision.ts"; | ||
| 333 | 333 | import { tokenRoutes } from "./api/tokens.ts"; |
| 334 | 334 | import { accountAdmin, adminRoutes } from "./api/admin.ts"; |
| 335 | 335 | import { flagsRoutes } from "./api/flags.ts"; |
| 336 | import { maintainRoutes } from "./api/maintain.ts"; | |
| 336 | 337 | import { issueRoutes, labelsHandler } from "./api/issues.ts"; |
| 337 | 338 | import { FORGE_NOT_CARRIED } from "../origins/words.ts"; |
| 338 | 339 | import { forgeOriginRoutes } from "./api/forge_origin.ts"; |
| @@ -1166,6 +1167,7 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 1166 | 1167 | forgeOriginRoutes(router); |
| 1167 | 1168 | adminRoutes(router); |
| 1168 | 1169 | flagsRoutes(router); |
| 1170 | maintainRoutes(router); | |
| 1169 | 1171 | |
| 1170 | 1172 | // Open read hooks (#1789): the owner, or an agent holding `telemetry:read`. |
| 1171 | 1173 | // Anyone else is refused; every agent read is logged. |
src/http/api/maintain.ts added +35
| @@ -0,0 +1,35 @@ | ||
| 1 | /** | |
| 2 | * The maintainer's duties over HTTP (#7554): `GET /api/v1/maintain/duties` | |
| 3 | * with each duty's budget, switch and last run; `GET …/runs` for the run | |
| 4 | * rows; `POST …/duties/:name/pause` and `/resume`. A forge admin's door. | |
| 5 | */ | |
| 6 | ||
| 7 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; | |
| 8 | import { dutyBoard, dutyRuns, setDutyPaused } from "../../maintain/service.ts"; | |
| 9 | import type { Ctx, Handler } from "../context.ts"; | |
| 10 | import { json, notFound, requireScope } from "../respond.ts"; | |
| 11 | import type { Router } from "../router.ts"; | |
| 12 | ||
| 13 | const door = (ctx: Ctx, scope: "ro" | "admin"): Response | undefined => { | |
| 14 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); | |
| 15 | return ctx.auth.user?.isAdmin === true ? requireScope(ctx, scope) : notFound(); | |
| 16 | }; | |
| 17 | ||
| 18 | export function maintainRoutes(router: Router<Handler>): void { | |
| 19 | router.add("GET", "/api/v1/maintain/duties", (ctx) => door(ctx, "ro") ?? json({ duties: dutyBoard(ctx.app) })); | |
| 20 | router.add("GET", "/api/v1/maintain/runs", (ctx) => { | |
| 21 | const denied = door(ctx, "ro"); | |
| 22 | if (denied) return denied; | |
| 23 | const duty = ctx.url.searchParams.get("duty") ?? undefined; | |
| 24 | return json({ runs: dutyRuns(ctx.app, duty) }); | |
| 25 | }); | |
| 26 | const switchDuty = (paused: boolean): Handler => (ctx) => { | |
| 27 | const denied = door(ctx, "admin"); | |
| 28 | if (denied) return denied; | |
| 29 | return setDutyPaused(ctx.app, ctx.params.name!, paused, ctx.auth.user!.username) | |
| 30 | ? json({ duties: dutyBoard(ctx.app) }) | |
| 31 | : notFound(); | |
| 32 | }; | |
| 33 | router.add("POST", "/api/v1/maintain/duties/:name/pause", switchDuty(true)); | |
| 34 | router.add("POST", "/api/v1/maintain/duties/:name/resume", switchDuty(false)); | |
| 35 | } |
src/http/server.ts +4
| @@ -275,6 +275,7 @@ import { appStateFragment } from "../web/studio/previews.ts"; | ||
| 275 | 275 | import { changesList, tellsList } from "../web/studio/lists.ts"; |
| 276 | 276 | import { dependencySubmit } from "../web/pages/thread.ts"; |
| 277 | 277 | import { flowPage, suggestionTake, valveSet } from "../web/pages/flow.ts"; |
| 278 | import { maintainPage, switchDuty } from "../web/pages/maintain.ts"; | |
| 278 | 279 | import { heldApply, heldPage, liftHoldSubmit } from "../web/pages/gate.ts"; |
| 279 | 280 | import { |
| 280 | 281 | assigneeSubmit, |
| @@ -801,6 +802,9 @@ export function buildRouter(): Router<Handler> { | ||
| 801 | 802 | router.add("GET", "/flow", flowPage); |
| 802 | 803 | router.add("POST", "/flow/valve", valveSet); |
| 803 | 804 | router.add("POST", "/flow/suggestion", suggestionTake); |
| 805 | router.add("GET", "/maintain", maintainPage); | |
| 806 | router.add("POST", "/maintain/duties/:name/pause", switchDuty(true)); | |
| 807 | router.add("POST", "/maintain/duties/:name/resume", switchDuty(false)); | |
| 804 | 808 | router.add("GET", "/system", systemPage); |
| 805 | 809 | router.add("GET", "/system/stream", systemStream); |
| 806 | 810 | router.add("GET", "/contribute", contributePage); |
src/maintain/duties/index.ts added +6
| @@ -0,0 +1,6 @@ | ||
| 1 | /** Every registered duty: a worker adds its file here and imports it on one line. */ | |
| 2 | ||
| 3 | import type { Duty } from "../duty.ts"; | |
| 4 | import { runLog } from "./run_log.ts"; | |
| 5 | ||
| 6 | export const dutyList: readonly Duty[] = [runLog]; |
src/maintain/duties/run_log.ts added +30
| @@ -0,0 +1,30 @@ | ||
| 1 | /** | |
| 2 | * The maintainer's own housekeeping: `maintenance_run` is read by the board | |
| 3 | * and grows with every run, so rows past 90 days are pruned, the oldest | |
| 4 | * first, one first and its probe checked, then the rest. | |
| 5 | */ | |
| 6 | ||
| 7 | import { DAY_MS, duty } from "../duty.ts"; | |
| 8 | ||
| 9 | const KEEP_DAYS = 90; | |
| 10 | ||
| 11 | export const runLog = duty({ | |
| 12 | name: "run-log", | |
| 13 | trigger: { every: DAY_MS }, | |
| 14 | budget: { runsPerDay: 2, usdPerDay: 0, cpuMsPerRun: 10_000, netCallsPerRun: 0 }, | |
| 15 | async handler(ctx) { | |
| 16 | const before = new Date(ctx.now - KEEP_DAYS * DAY_MS).toISOString(); | |
| 17 | const old = ctx.runs.before(before, 20); | |
| 18 | if (old.length === 0) return {}; | |
| 19 | await ctx.bulk(old, { | |
| 20 | what: "prune run", | |
| 21 | target: (id) => id, | |
| 22 | apply: (id) => ctx.runs.prune(id), | |
| 23 | check: (id) => { | |
| 24 | const left = ctx.runs.has(id) ? 1 : 0; | |
| 25 | return { ...ctx.probe("SELECT COUNT(*) FROM maintenance_run WHERE id = :pruned", left), pass: left === 0 }; | |
| 26 | }, | |
| 27 | }); | |
| 28 | return {}; | |
| 29 | }, | |
| 30 | }); |
src/maintain/duty.ts added +106
| @@ -0,0 +1,106 @@ | ||
| 1 | /** | |
| 2 | * What a duty is (#7554): a name, a trigger, a budget, a switch and a handler | |
| 3 | * that returns findings and actions. Plain data in, plain data out; a duty | |
| 4 | * is given only what `DutyContext` hands it: named accessors, no database | |
| 5 | * handle, and no way to merge or to push a branch. | |
| 6 | */ | |
| 7 | ||
| 8 | /** The measurement behind a finding or an action: the query, what it returned, when. */ | |
| 9 | export interface ProbeRecord { | |
| 10 | readonly query: string; | |
| 11 | readonly value: number | string | boolean; | |
| 12 | readonly at: string; | |
| 13 | } | |
| 14 | ||
| 15 | export interface FindingInput { | |
| 16 | /** Stable across runs: the same fault has the same key. */ | |
| 17 | readonly key: string; | |
| 18 | readonly title: string; | |
| 19 | readonly evidence: readonly string[]; | |
| 20 | readonly probe: ProbeRecord | undefined; | |
| 21 | } | |
| 22 | ||
| 23 | export interface ActionInput { | |
| 24 | readonly what: string; | |
| 25 | readonly target: string; | |
| 26 | readonly probe: ProbeRecord | undefined; | |
| 27 | } | |
| 28 | ||
| 29 | export interface Finding extends FindingInput { | |
| 30 | readonly probe: ProbeRecord; | |
| 31 | } | |
| 32 | export interface Action extends ActionInput { | |
| 33 | readonly probe: ProbeRecord; | |
| 34 | } | |
| 35 | ||
| 36 | /** A duty runs on an interval; an event trigger waits until something emits one. */ | |
| 37 | export interface Trigger { | |
| 38 | readonly every: number; | |
| 39 | } | |
| 40 | ||
| 41 | export interface Budget { | |
| 42 | readonly runsPerDay: number; | |
| 43 | readonly usdPerDay: number; | |
| 44 | /** Wall time one run may take; a handler still going then is abandoned and the run is `budget`. */ | |
| 45 | readonly cpuMsPerRun: number; | |
| 46 | /** Network calls one run may make through `ctx.net()`. */ | |
| 47 | readonly netCallsPerRun: number; | |
| 48 | } | |
| 49 | ||
| 50 | export interface BulkStep<T> { | |
| 51 | readonly what: string; | |
| 52 | readonly target: (item: T) => string; | |
| 53 | readonly apply: (item: T) => void | Promise<void>; | |
| 54 | /** Measured after the first item; the rest run only if `pass`. */ | |
| 55 | readonly check: (item: T) => ProbeRecord & { readonly pass: boolean } | Promise<ProbeRecord & { readonly pass: boolean }>; | |
| 56 | } | |
| 57 | ||
| 58 | /** The maintainer's own run log, the one table a duty may touch. */ | |
| 59 | export interface RunLog { | |
| 60 | /** Ids of runs that started before a moment, oldest first. */ | |
| 61 | before(sinceIso: string, limit: number): string[]; | |
| 62 | prune(id: string): void; | |
| 63 | has(id: string): boolean; | |
| 64 | } | |
| 65 | ||
| 66 | export interface DutyContext { | |
| 67 | readonly now: number; | |
| 68 | readonly runs: RunLog; | |
| 69 | probe(query: string, value: ProbeRecord["value"]): ProbeRecord; | |
| 70 | /** Count a network call; throws once the run's ceiling is passed. */ | |
| 71 | net(): void; | |
| 72 | /** Add to the run's dollar cost. */ | |
| 73 | spend(usd: number): void; | |
| 74 | /** One item first, its probe checked, then the rest, capped. */ | |
| 75 | bulk<T>(items: readonly T[], step: BulkStep<T>): Promise<Action[]>; | |
| 76 | } | |
| 77 | ||
| 78 | export interface DutyResult { | |
| 79 | readonly findings?: readonly FindingInput[]; | |
| 80 | readonly actions?: readonly ActionInput[]; | |
| 81 | } | |
| 82 | ||
| 83 | export interface Duty { | |
| 84 | readonly name: string; | |
| 85 | readonly trigger: Trigger; | |
| 86 | readonly budget: Budget; | |
| 87 | readonly enabled: boolean; | |
| 88 | readonly handler: (ctx: DutyContext) => DutyResult | Promise<DutyResult>; | |
| 89 | } | |
| 90 | ||
| 91 | export const BULK_CAP = 20; | |
| 92 | export const ERRORS_TO_PAUSE = 3; | |
| 93 | export const DAY_MS = 86_400_000; | |
| 94 | ||
| 95 | export type Outcome = "ok" | "error" | "budget" | "canary" | "refused"; | |
| 96 | ||
| 97 | /** A duty with the defaults every duty takes. */ | |
| 98 | export function duty( | |
| 99 | spec: Pick<Duty, "name" | "trigger" | "handler"> & Partial<Pick<Duty, "budget" | "enabled">>, | |
| 100 | ): Duty { | |
| 101 | return { | |
| 102 | enabled: true, | |
| 103 | budget: { runsPerDay: 24, usdPerDay: 0, cpuMsPerRun: 30_000, netCallsPerRun: 0 }, | |
| 104 | ...spec, | |
| 105 | }; | |
| 106 | } |
src/maintain/file.ts added +55
| @@ -0,0 +1,55 @@ | ||
| 1 | /** | |
| 2 | * Where a finding goes (#7554): the open issue for its key gets a comment; | |
| 3 | * a key with none gets an issue. The same de-duplication the sentinel does, | |
| 4 | * by a stable key, kept in `maintenance_finding`. | |
| 5 | */ | |
| 6 | ||
| 7 | import type { App } from "../app.ts"; | |
| 8 | import { addComment, openIssue } from "../actions/issues.ts"; | |
| 9 | import { getAgentByName } from "../core/agents.ts"; | |
| 10 | import { getIssueById } from "../core/issues.ts"; | |
| 11 | import { getRepo } from "../core/repos.ts"; | |
| 12 | import { ownRepoPath } from "../kernel/own_repo.ts"; | |
| 13 | import { DAY_MS, type Finding } from "./duty.ts"; | |
| 14 | import { trackedFinding, trackFinding } from "./store.ts"; | |
| 15 | ||
| 16 | const bodyOf = (f: Finding): string => | |
| 17 | [ | |
| 18 | f.title, | |
| 19 | "", | |
| 20 | "**Evidence**", | |
| 21 | ...f.evidence.map((e) => `- ${e}`), | |
| 22 | "", | |
| 23 | `**Probe:** \`${f.probe.query}\` returned ${String(f.probe.value)} at ${f.probe.at}`, | |
| 24 | ].join("\n"); | |
| 25 | ||
| 26 | /** What a finding says, to tell a changed one from a repeated one. */ | |
| 27 | const digest = (f: Finding): string => JSON.stringify([f.evidence, f.probe.value]); | |
| 28 | ||
| 29 | export function issueFiler(app: App, repoPath = ownRepoPath()): (f: Finding, now: number) => string | undefined { | |
| 30 | return (f, now) => { | |
| 31 | const [owner = "", name = ""] = repoPath.split("/"); | |
outdated
MEDIUM: when no |
||
| 32 | const repo = getRepo(app.db, owner, name); | |
| 33 | // Automated text is the maintainer's, never an admin's: with no maintainer seated, nothing is filed. | |
| 34 | const maintainer = getAgentByName(app.db, "maintainer"); | |
| 35 | if (maintainer === undefined) throw new Error("no maintainer agent is seated; nothing filed"); | |
| 36 | if (repo === undefined) return undefined; | |
| 37 | const actor = maintainer.user; | |
| 38 | const at = new Date(now).toISOString(); | |
| 39 | const evidence = digest(f); | |
| 40 | const known = trackedFinding(app.db, f.key); | |
| 41 | const issue = known === undefined ? undefined : getIssueById(app.db, known.issueId); | |
| 42 | if (known !== undefined && issue !== undefined && issue.state === "open") { | |
| 43 | // Said again only when it changed or a day has passed. | |
outdated
MEDIUM: every run of a still-true finding adds another comment. For a duty that runs hourly this is issue spam and unbounded growth. Track last comment time in |
||
| 44 | if (known.evidence === evidence && now - Date.parse(known.said) < DAY_MS) return `#${issue.number} (unchanged)`; | |
| 45 | const said = addComment(app, actor, repo, issue, `Still there at ${at}:\n${f.evidence.map((e) => `- ${e}`).join("\n")}\n\nProbe \`${f.probe.query}\` returned ${String(f.probe.value)}.`); | |
| 46 | if (!said.ok) throw new Error(`comment: ${String(said.error)}`); | |
| 47 | trackFinding(app.db, f.key, issue.id, at, evidence); | |
| 48 | return `#${issue.number} (commented)`; | |
| 49 | } | |
| 50 | const made = openIssue(app, actor, repo, { title: f.title, body: bodyOf(f) }); | |
| 51 | if (!made.ok) throw new Error(`file: ${String(made.error)}`); | |
| 52 | trackFinding(app.db, f.key, made.value.id, at, evidence); | |
| 53 | return `#${made.value.number}`; | |
| 54 | }; | |
| 55 | } |
src/maintain/probe.ts added +46
| @@ -0,0 +1,46 @@ | ||
| 1 | /** A finding or an action without the measurement behind it is refused (#7554). */ | |
| 2 | ||
| 3 | import type { Action, ActionInput, Finding, FindingInput, ProbeRecord } from "./duty.ts"; | |
| 4 | ||
| 5 | export function validProbe(p: ProbeRecord | undefined): p is ProbeRecord { | |
| 6 | return ( | |
| 7 | p !== undefined && | |
| 8 | typeof p.query === "string" && | |
| 9 | p.query.trim() !== "" && | |
| 10 | (typeof p.value === "number" ? Number.isFinite(p.value) : typeof p.value === "string" || typeof p.value === "boolean") && | |
| 11 | typeof p.at === "string" && | |
| 12 | !Number.isNaN(Date.parse(p.at)) | |
| 13 | ); | |
| 14 | } | |
| 15 | ||
| 16 | export interface Admitted { | |
| 17 | readonly findings: Finding[]; | |
| 18 | readonly actions: Action[]; | |
| 19 | /** One line per item refused, and why. */ | |
| 20 | readonly refused: string[]; | |
| 21 | } | |
| 22 | ||
| 23 | export const MAX_FINDINGS = 20; | |
| 24 | export const MAX_TITLE = 200; | |
| 25 | export const MAX_EVIDENCE = 20; | |
| 26 | export const MAX_EVIDENCE_LINE = 500; | |
| 27 | export const MAX_ACTIONS = 100; | |
| 28 | ||
| 29 | export function admit(findings: readonly FindingInput[], actions: readonly ActionInput[]): Admitted { | |
| 30 | const out: Admitted = { findings: [], actions: [], refused: [] }; | |
| 31 | for (const f of findings) { | |
| 32 | if (out.findings.length >= MAX_FINDINGS) { | |
| 33 | out.refused.push(`finding ${f.key}: more than ${MAX_FINDINGS} findings in a run`); | |
| 34 | } else if (f.title.length > MAX_TITLE || f.evidence.length > MAX_EVIDENCE || f.evidence.some((e) => e.length > MAX_EVIDENCE_LINE)) { | |
| 35 | out.refused.push(`finding ${f.key}: title over ${MAX_TITLE} characters, or evidence over ${MAX_EVIDENCE} lines of ${MAX_EVIDENCE_LINE}`); | |
| 36 | } else if (!validProbe(f.probe)) out.refused.push(`finding ${f.key}: no probe`); | |
| 37 | else if (f.key.trim() === "" || f.title.trim() === "") out.refused.push(`finding ${f.key || "(no key)"}: no key or title`); | |
| 38 | else out.findings.push({ ...f, probe: f.probe }); | |
| 39 | } | |
| 40 | for (const a of actions) { | |
| 41 | if (out.actions.length >= MAX_ACTIONS) out.refused.push(`action ${a.what} ${a.target}: more than ${MAX_ACTIONS} actions in a run`); | |
| 42 | else if (!validProbe(a.probe)) out.refused.push(`action ${a.what} ${a.target}: no probe`); | |
| 43 | else out.actions.push({ ...a, probe: a.probe }); | |
| 44 | } | |
| 45 | return out; | |
| 46 | } |
src/maintain/registry.ts added +21
| @@ -0,0 +1,21 @@ | ||
| 1 | /** The duty registry (#7554): a worker adds one file in `duties/` and one line to `duties/index.ts`. */ | |
| 2 | ||
| 3 | import type { Duty } from "./duty.ts"; | |
| 4 | ||
| 5 | const NAME = /^[a-z][a-z0-9-]{0,63}$/; | |
| 6 | ||
| 7 | export function makeRegistry(initial: readonly Duty[] = []) { | |
| 8 | const byName = new Map<string, Duty>(); | |
| 9 | const add = (d: Duty): void => { | |
| 10 | if (!NAME.test(d.name)) throw new Error(`duty name ${JSON.stringify(d.name)} is not a lowercase word`); | |
| 11 | if (byName.has(d.name)) throw new Error(`duty ${d.name} is registered twice`); | |
| 12 | byName.set(d.name, d); | |
| 13 | }; | |
| 14 | for (const d of initial) add(d); | |
| 15 | return { | |
| 16 | add, | |
| 17 | get: (name: string): Duty | undefined => byName.get(name), | |
| 18 | all: (): Duty[] => [...byName.values()], | |
| 19 | }; | |
| 20 | } | |
| 21 | export type Registry = ReturnType<typeof makeRegistry>; |
src/maintain/runner.ts added +209
| @@ -0,0 +1,209 @@ | ||
| 1 | /** | |
| 2 | * The duty runner (#7554): runs the duties that are due, one at a time per | |
| 3 | * duty, and leaves a `maintenance_run` row for each. A handler that outlives | |
| 4 | * its `cpuMsPerRun` is abandoned and the run recorded as `budget`. It holds | |
| 5 | * no way to merge or push: a duty gets named accessors, not the database, and | |
| 6 | * its fixes are pulls, which the normal gate lands. | |
| 7 | */ | |
| 8 | ||
| 9 | import type { Database } from "bun:sqlite"; | |
| 10 | import { | |
| 11 | BULK_CAP, | |
| 12 | DAY_MS, | |
| 13 | ERRORS_TO_PAUSE, | |
| 14 | type Action, | |
| 15 | type BulkStep, | |
| 16 | type Duty, | |
| 17 | type DutyContext, | |
| 18 | type Finding, | |
| 19 | type Outcome, | |
| 20 | type ProbeRecord, | |
| 21 | } from "./duty.ts"; | |
| 22 | import { admit } from "./probe.ts"; | |
| 23 | import type { Registry } from "./registry.ts"; | |
| 24 | import { | |
| 25 | dutyState, | |
| 26 | lastRun, | |
| 27 | pauseDuty, | |
| 28 | recordRun, | |
| 29 | setErrors, | |
| 30 | usedSince, | |
| 31 | deleteRun, | |
| 32 | runExists, | |
| 33 | runIdsBefore, | |
| 34 | type RunRow, | |
| 35 | } from "./store.ts"; | |
| 36 | ||
| 37 | class OverBudget extends Error {} | |
| 38 | ||
| 39 | /** The handler's answer, or a refusal once its time is up. */ | |
| 40 | function within<T>(ms: number, work: Promise<T>): Promise<T> { | |
| 41 | let timer: ReturnType<typeof setTimeout> | undefined; | |
| 42 | const late = new Promise<never>((_, reject) => { | |
| 43 | timer = setTimeout(() => reject(new OverBudget(`took longer than ${ms} ms`)), ms); | |
| 44 | }); | |
| 45 | return Promise.race([work, late]).finally(() => clearTimeout(timer)); | |
| 46 | } | |
| 47 | ||
| 48 | export interface RunnerDeps { | |
| 49 | readonly db: Database; | |
| 50 | readonly registry: Registry; | |
| 51 | /** Files or comments a finding on the issue for its key; returns the issue it is on. */ | |
| 52 | readonly file?: (finding: Finding, now: number) => string | undefined; | |
| 53 | } | |
| 54 | ||
| 55 | const iso = (ms: number): string => new Date(ms).toISOString(); | |
| 56 | ||
| 57 | export function makeRunner(deps: RunnerDeps) { | |
| 58 | const { db } = deps; | |
| 59 | const running = new Set<string>(); | |
| 60 | ||
| 61 | function due(duty: Duty, now: number): boolean { | |
| 62 | const last = lastRun(db, duty.name); | |
| 63 | return last === undefined || now - Date.parse(last.started) >= duty.trigger.every; | |
| 64 | } | |
| 65 | ||
| 66 | function overBudget(duty: Duty, now: number): string | undefined { | |
| 67 | const used = usedSince(db, duty.name, iso(now - DAY_MS)); | |
| 68 | if (used.runs >= duty.budget.runsPerDay) return `${used.runs} runs in the last day, budget ${duty.budget.runsPerDay}`; | |
| 69 | if (used.usd > duty.budget.usdPerDay) return `$${used.usd.toFixed(2)} in the last day, budget $${duty.budget.usdPerDay}`; | |
| 70 | return undefined; | |
| 71 | } | |
| 72 | ||
| 73 | async function runDuty(duty: Duty, now: number): Promise<RunRow | undefined> { | |
| 74 | const state = dutyState(db, duty.name); | |
| 75 | if (!duty.enabled || !state.enabled) return undefined; | |
| 76 | if (running.has(duty.name)) return undefined; | |
| 77 | running.add(duty.name); | |
| 78 | try { | |
| 79 | return await execute(duty, now); | |
| 80 | } finally { | |
| 81 | running.delete(duty.name); | |
| 82 | } | |
| 83 | } | |
| 84 | ||
| 85 | async function execute(duty: Duty, now: number): Promise<RunRow> { | |
| 86 | const started = iso(now); | |
| 87 | const row = (p: Partial<RunRow>): RunRow => ({ | |
| 88 | id: crypto.randomUUID(), duty: duty.name, started, finished: iso(Date.now()), | |
| 89 | findings: [], actions: [], probes: [], outcome: "ok", cost: 0, detail: null, ...p, | |
| 90 | }); | |
| 91 | const over = overBudget(duty, now); | |
| 92 | if (over !== undefined) { | |
| 93 | // Said once per window, not every tick. | |
| 94 | const last = lastRun(db, duty.name); | |
| 95 | if (last?.outcome === "budget" && now - Date.parse(last.started) < DAY_MS) return last; | |
| 96 | const r = row({ outcome: "budget", detail: over }); | |
| 97 | recordRun(db, r); | |
| 98 | return r; | |
| 99 | } | |
| 100 | ||
| 101 | const used = usedSince(db, duty.name, iso(now - DAY_MS)); | |
| 102 | let cost = 0; | |
| 103 | let calls = 0; | |
| 104 | let halted: string | undefined; | |
| 105 | const done: Action[] = []; | |
| 106 | const probe = (query: string, value: ProbeRecord["value"]): ProbeRecord => ({ query, value, at: iso(Date.now()) }); | |
| 107 | // Once the run has ended, an abandoned handler's late calls do nothing. | |
| 108 | let ended = false; | |
| 109 | const live = (): void => { | |
| 110 | if (ended) throw new OverBudget("the run has ended"); | |
| 111 | }; | |
| 112 | const ctx: DutyContext = { | |
| 113 | now, probe, | |
| 114 | runs: { | |
| 115 | before: (sinceIso, limit) => runIdsBefore(db, sinceIso, limit), | |
| 116 | prune: (id) => (live(), deleteRun(db, id)), | |
| 117 | has: (id) => runExists(db, id), | |
| 118 | }, | |
| 119 | net() { | |
| 120 | live(); | |
| 121 | if (++calls > duty.budget.netCallsPerRun) throw new OverBudget(`more than ${duty.budget.netCallsPerRun} network calls in a run`); | |
| 122 | }, | |
| 123 | spend(usd) { | |
| 124 | live(); | |
| 125 | cost += usd; | |
| 126 | if (used.usd + cost > duty.budget.usdPerDay) throw new OverBudget(`over $${duty.budget.usdPerDay} a day`); | |
| 127 | }, | |
| 128 | async bulk<T>(items: readonly T[], step: BulkStep<T>): Promise<Action[]> { | |
| 129 | const out: Action[] = []; | |
| 130 | for (const item of items) { | |
| 131 | if (halted !== undefined || done.length >= BULK_CAP) break; | |
| 132 | live(); | |
| 133 | await step.apply(item); | |
| 134 | const seen = await step.check(item); | |
| 135 | const action: Action = { what: step.what, target: step.target(item), probe: { query: seen.query, value: seen.value, at: seen.at } }; | |
| 136 | out.push(action); | |
| 137 | done.push(action); | |
| 138 | if (!seen.pass) halted = `${step.what} ${action.target}: probe ${seen.query} returned ${String(seen.value)}; nothing else touched`; | |
| 139 | } | |
| 140 | return out; | |
| 141 | }, | |
| 142 | }; | |
| 143 | ||
| 144 | let outcome: Outcome = "ok"; | |
| 145 | let detail: string | null = null; | |
| 146 | let findings: Finding[] = []; | |
| 147 | let actions: Action[] = []; | |
| 148 | try { | |
| 149 | const result = await within(duty.budget.cpuMsPerRun, Promise.resolve().then(() => duty.handler(ctx))); | |
| 150 | const admitted = admit(result.findings ?? [], result.actions ?? []); | |
| 151 | findings = admitted.findings; | |
| 152 | actions = [...done, ...admitted.actions]; | |
| 153 | if (admitted.refused.length > 0) { | |
| 154 | outcome = "refused"; | |
| 155 | detail = admitted.refused.join("; "); | |
| 156 | } | |
| 157 | if (halted !== undefined) { | |
| 158 | outcome = "canary"; | |
| 159 | detail = halted; | |
| 160 | } | |
| 161 | } catch (error) { | |
| 162 | actions = done; | |
| 163 | outcome = error instanceof OverBudget ? "budget" : "error"; | |
| 164 | detail = error instanceof Error ? error.message : String(error); | |
| 165 | } finally { | |
| 166 | ended = true; | |
| 167 | } | |
| 168 | ||
| 169 | const filed: string[] = []; | |
| 170 | if (outcome !== "error") { | |
| 171 | for (const f of findings) { | |
| 172 | try { | |
| 173 | const ref = deps.file?.(f, now); | |
| 174 | if (ref !== undefined) filed.push(`${f.key} -> ${ref}`); | |
| 175 | } catch (error) { | |
| 176 | detail = `${detail === null ? "" : `${detail}; `}could not file ${f.key}: ${String(error)}`; | |
| 177 | } | |
| 178 | } | |
| 179 | } | |
| 180 | const r = row({ | |
| 181 | findings, actions, outcome, cost, detail, | |
| 182 | probes: [...findings.map((f) => f.probe), ...actions.map((a) => a.probe)], | |
| 183 | }); | |
| 184 | recordRun(db, r); | |
| 185 | ||
| 186 | if (outcome === "error") { | |
| 187 | const errors = dutyState(db, duty.name).errors + 1; | |
| 188 | setErrors(db, duty.name, errors); | |
| 189 | if (errors >= ERRORS_TO_PAUSE) | |
| 190 | pauseDuty(db, duty.name, `errored ${errors} times in a row; last: ${detail ?? "unknown"}`); | |
| 191 | } else if (dutyState(db, duty.name).errors !== 0) setErrors(db, duty.name, 0); | |
| 192 | return r; | |
| 193 | } | |
| 194 | ||
| 195 | return { | |
| 196 | runDuty, | |
| 197 | /** Every duty whose interval has passed, each once. */ | |
| 198 | async runDue(now: number): Promise<RunRow[]> { | |
| 199 | const out: RunRow[] = []; | |
| 200 | for (const d of deps.registry.all()) { | |
| 201 | if (!due(d, now)) continue; | |
| 202 | const r = await runDuty(d, now); | |
| 203 | if (r !== undefined) out.push(r); | |
| 204 | } | |
| 205 | return out; | |
| 206 | }, | |
| 207 | }; | |
| 208 | } | |
| 209 | export type Runner = ReturnType<typeof makeRunner>; |
src/maintain/service.ts added +61
| @@ -0,0 +1,61 @@ | ||
| 1 | /** The maintainer wired to the app (#7554): one runner, the default registry, the sentinel's clock. */ | |
| 2 | ||
| 3 | import type { App } from "../app.ts"; | |
| 4 | import { dutyList } from "./duties/index.ts"; | |
| 5 | import { issueFiler } from "./file.ts"; | |
| 6 | import { makeRegistry } from "./registry.ts"; | |
| 7 | import { makeRunner, type Runner } from "./runner.ts"; | |
| 8 | import { dutyState, listRuns, pauseDuty, resumeDuty, lastRun } from "./store.ts"; | |
| 9 | ||
| 10 | const runners = new WeakMap<App, Runner>(); | |
| 11 | const registry = makeRegistry(dutyList); | |
| 12 | ||
| 13 | export function runnerOf(app: App): Runner { | |
| 14 | let r = runners.get(app); | |
| 15 | if (r === undefined) { | |
| 16 | r = makeRunner({ db: app.db, registry, file: issueFiler(app) }); | |
| 17 | runners.set(app, r); | |
| 18 | } | |
| 19 | return r; | |
| 20 | } | |
| 21 | ||
| 22 | /** Whatever is due runs; each duty is cut off at its own deadline. */ | |
| 23 | export const maintainTick = (app: App, now = Date.now()) => runnerOf(app).runDue(now); | |
| 24 | ||
| 25 | const ticking = new WeakSet<App>(); | |
| 26 | ||
| 27 | /** | |
| 28 | * On the autonomy clock, off its critical path: the tick starts the due duties | |
| 29 | * and returns, so a slow duty never holds the sentinel, triage or review. One | |
| 30 | * pass at a time per app; a tick that finds the last one going does nothing. | |
| 31 | */ | |
| 32 | export function maintainInBackground(app: App, now: number, onError: (error: unknown) => void): void { | |
| 33 | if (ticking.has(app)) return; | |
| 34 | ticking.add(app); | |
| 35 | maintainTick(app, now) | |
| 36 | .catch(onError) | |
| 37 | .finally(() => ticking.delete(app)); | |
| 38 | } | |
| 39 | ||
| 40 | export function dutyBoard(app: App) { | |
| 41 | return registry.all().map((d) => { | |
| 42 | const s = dutyState(app.db, d.name); | |
| 43 | return { | |
| 44 | name: d.name, | |
| 45 | trigger: d.trigger, | |
| 46 | budget: d.budget, | |
| 47 | enabled: d.enabled && s.enabled, | |
| 48 | pausedReason: s.pausedReason, | |
| 49 | lastRun: lastRun(app.db, d.name) ?? null, | |
| 50 | }; | |
| 51 | }); | |
| 52 | } | |
| 53 | ||
| 54 | export function setDutyPaused(app: App, name: string, paused: boolean, by: string): boolean { | |
| 55 | if (registry.get(name) === undefined) return false; | |
| 56 | if (paused) pauseDuty(app.db, name, `paused by ${by}`); | |
| 57 | else resumeDuty(app.db, name); | |
| 58 | return true; | |
| 59 | } | |
| 60 | ||
| 61 | export const dutyRuns = (app: App, name?: string) => listRuns(app.db, name); |
src/maintain/store.ts added +117
| @@ -0,0 +1,117 @@ | ||
| 1 | /** The maintainer's tables (#7554): duty switches, run rows, and the issue each finding key went to. */ | |
| 2 | ||
| 3 | import type { Database } from "bun:sqlite"; | |
| 4 | import type { Action, Finding, Outcome, ProbeRecord } from "./duty.ts"; | |
| 5 | ||
| 6 | export interface DutyState { | |
| 7 | readonly name: string; | |
| 8 | readonly enabled: boolean; | |
| 9 | readonly pausedReason: string | null; | |
| 10 | readonly errors: number; | |
| 11 | } | |
| 12 | ||
| 13 | export interface RunRow { | |
| 14 | readonly id: string; | |
| 15 | readonly duty: string; | |
| 16 | readonly started: string; | |
| 17 | readonly finished: string; | |
| 18 | readonly findings: Finding[]; | |
| 19 | readonly actions: Action[]; | |
| 20 | readonly probes: ProbeRecord[]; | |
| 21 | readonly outcome: Outcome; | |
| 22 | readonly cost: number; | |
| 23 | readonly detail: string | null; | |
| 24 | } | |
| 25 | ||
| 26 | export function dutyState(db: Database, name: string): DutyState { | |
| 27 | const row = db | |
| 28 | .query<{ enabled: number; paused_reason: string | null; errors: number }, [string]>( | |
| 29 | "SELECT enabled, paused_reason, errors FROM maintenance_duty WHERE name = ?1", | |
| 30 | ) | |
| 31 | .get(name); | |
| 32 | return { name, enabled: row === null || row.enabled === 1, pausedReason: row?.paused_reason ?? null, errors: row?.errors ?? 0 }; | |
| 33 | } | |
| 34 | ||
| 35 | function setState(db: Database, name: string, enabled: boolean, reason: string | null, errors: number): void { | |
| 36 | db.query( | |
| 37 | `INSERT INTO maintenance_duty (name, enabled, paused_reason, errors) VALUES (?1, ?2, ?3, ?4) | |
| 38 | ON CONFLICT(name) DO UPDATE SET enabled = ?2, paused_reason = ?3, errors = ?4`, | |
| 39 | ).run(name, enabled ? 1 : 0, reason, errors); | |
| 40 | } | |
| 41 | ||
| 42 | export const pauseDuty = (db: Database, name: string, reason: string): void => | |
| 43 | setState(db, name, false, reason, dutyState(db, name).errors); | |
| 44 | export const resumeDuty = (db: Database, name: string): void => setState(db, name, true, null, 0); | |
| 45 | export const setErrors = (db: Database, name: string, errors: number): void => { | |
| 46 | const s = dutyState(db, name); | |
| 47 | setState(db, name, s.enabled, s.pausedReason, errors); | |
| 48 | }; | |
| 49 | ||
| 50 | export function recordRun(db: Database, row: RunRow): void { | |
| 51 | db.query( | |
| 52 | `INSERT INTO maintenance_run (id, duty, started, finished, findings, actions, probes, outcome, cost, detail) | |
| 53 | VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)`, | |
| 54 | ).run( | |
| 55 | row.id, row.duty, row.started, row.finished, JSON.stringify(row.findings), JSON.stringify(row.actions), | |
| 56 | JSON.stringify(row.probes), row.outcome, row.cost, row.detail, | |
| 57 | ); | |
| 58 | } | |
| 59 | ||
| 60 | export function listRuns(db: Database, duty?: string, limit = 50): RunRow[] { | |
| 61 | const rows = db | |
| 62 | .query<Record<string, string | number | null>, [string | null, number]>( | |
| 63 | `SELECT * FROM maintenance_run WHERE (?1 IS NULL OR duty = ?1) ORDER BY started DESC, id DESC LIMIT ?2`, | |
| 64 | ) | |
| 65 | .all(duty ?? null, limit); | |
| 66 | return rows.map((r) => ({ | |
| 67 | id: String(r.id), duty: String(r.duty), started: String(r.started), finished: String(r.finished), | |
| 68 | findings: JSON.parse(String(r.findings)), actions: JSON.parse(String(r.actions)), | |
| 69 | probes: JSON.parse(String(r.probes)), outcome: String(r.outcome) as Outcome, | |
| 70 | cost: Number(r.cost), detail: r.detail === null ? null : String(r.detail), | |
| 71 | })); | |
| 72 | } | |
| 73 | ||
| 74 | /** Runs started and dollars spent by a duty since a moment (the day's budget). */ | |
| 75 | export function usedSince(db: Database, duty: string, sinceIso: string): { runs: number; usd: number } { | |
| 76 | const row = db | |
| 77 | .query<{ runs: number; usd: number | null }, [string, string]>( | |
| 78 | "SELECT COUNT(*) AS runs, SUM(cost) AS usd FROM maintenance_run WHERE duty = ?1 AND started >= ?2 AND outcome != 'budget'", | |
| 79 | ) | |
| 80 | .get(duty, sinceIso); | |
| 81 | return { runs: row?.runs ?? 0, usd: row?.usd ?? 0 }; | |
| 82 | } | |
| 83 | ||
| 84 | export function lastRun(db: Database, duty: string): RunRow | undefined { | |
| 85 | return listRuns(db, duty, 1)[0]; | |
| 86 | } | |
| 87 | ||
| 88 | export const runIdsBefore = (db: Database, sinceIso: string, limit: number): string[] => | |
| 89 | db.query<{ id: string }, [string, number]>("SELECT id FROM maintenance_run WHERE started < ?1 ORDER BY started LIMIT ?2").all(sinceIso, limit).map((r) => r.id); | |
| 90 | export const deleteRun = (db: Database, id: string): void => void db.query("DELETE FROM maintenance_run WHERE id = ?1").run(id); | |
| 91 | export const runExists = (db: Database, id: string): boolean => | |
| 92 | db.query("SELECT 1 FROM maintenance_run WHERE id = ?1").get(id) !== null; | |
| 93 | ||
| 94 | export interface TrackedFinding { | |
| 95 | readonly issueId: string; | |
| 96 | /** When the issue was last opened or commented on for this key. */ | |
| 97 | readonly said: string; | |
| 98 | /** What that last word carried, to tell a changed finding from a repeated one. */ | |
| 99 | readonly evidence: string; | |
| 100 | } | |
| 101 | ||
| 102 | export function trackedFinding(db: Database, key: string): TrackedFinding | undefined { | |
| 103 | const row = db | |
| 104 | .query<{ issue_id: string; last_seen: string; evidence: string }, [string]>( | |
| 105 | "SELECT issue_id, last_seen, evidence FROM maintenance_finding WHERE key = ?1", | |
| 106 | ) | |
| 107 | .get(key); | |
| 108 | return row === null ? undefined : { issueId: row.issue_id, said: row.last_seen, evidence: row.evidence }; | |
| 109 | } | |
| 110 | ||
| 111 | /** Records that the issue for a key was opened or commented on at `at` with this evidence. */ | |
| 112 | export function trackFinding(db: Database, key: string, issueId: string, at: string, evidence: string): void { | |
| 113 | db.query( | |
| 114 | `INSERT INTO maintenance_finding (key, issue_id, first_seen, last_seen, evidence) VALUES (?1, ?2, ?3, ?3, ?4) | |
| 115 | ON CONFLICT(key) DO UPDATE SET issue_id = ?2, last_seen = ?3, evidence = ?4`, | |
| 116 | ).run(key, issueId, at, evidence); | |
| 117 | } |
src/tui/screens/entries.ts +2
| @@ -27,6 +27,7 @@ import { entry as forges } from "./forges.ts"; | ||
| 27 | 27 | import { entry as homePins } from "./home_pins.ts"; |
| 28 | 28 | import { entry as invites } from "./invites.ts"; |
| 29 | 29 | import { entry as limits } from "./limits.ts"; |
| 30 | import { entry as maintain } from "./maintain.ts"; | |
| 30 | 31 | import { modelCeilingEntry, modelGrantEntry } from "./model.ts"; |
| 31 | 32 | import { entry as orgGrants } from "./orggrants.ts"; |
| 32 | 33 | import { entry as orgTeams } from "./orgteams.ts"; |
| @@ -73,6 +74,7 @@ export const ENTRIES: readonly PaletteEntry[] = [ | ||
| 73 | 74 | telemetry, |
| 74 | 75 | resilience, |
| 75 | 76 | valves, |
| 77 | maintain, | |
| 76 | 78 | access, |
| 77 | 79 | audit, |
| 78 | 80 | secrets, |
src/tui/screens/maintain.ts added +72
| @@ -0,0 +1,72 @@ | ||
| 1 | /** | |
| 2 | * The maintainer's duties in the terminal, a forge admin's who is a person: | |
| 3 | * one row per duty with its trigger, budget, switch and last run, from the | |
| 4 | * same `dutyBoard` as `/maintain` and the API. `p` pauses or resumes the duty | |
| 5 | * under the cursor. | |
| 6 | */ | |
| 7 | ||
| 8 | import { dutyBoard, setDutyPaused } from "../../maintain/service.ts"; | |
| 9 | import type { Ctx, Screen } from "../app/app.ts"; | |
| 10 | import { binding } from "../app/keys.ts"; | |
| 11 | import type { Session } from "../session.ts"; | |
| 12 | import { style } from "../term/style.ts"; | |
| 13 | import { truncate } from "../term/width.ts"; | |
| 14 | import { fill, len, split } from "../ui/layout.ts"; | |
| 15 | import { ListState, drawList, type ListRow } from "./common.ts"; | |
| 16 | import type { PaletteEntry } from "./entries.ts"; | |
| 17 | ||
| 18 | type Duty = ReturnType<typeof dutyBoard>[number]; | |
| 19 | ||
| 20 | const mayMaintain = (f: Session): boolean => f.user?.isAdmin === true && f.user.kind !== "agent"; | |
| 21 | ||
| 22 | function rowOf(d: Duty): ListRow { | |
| 23 | const last = d.lastRun === null ? "has not run" : `last run ${d.lastRun.started.slice(0, 16).replace("T", " ")} ${d.lastRun.outcome}`; | |
| 24 | return { | |
| 25 | title: `${d.name} ${d.enabled ? "on" : "paused"}`, | |
| 26 | meta: `every ${String(Math.round(d.trigger.every / 60_000))} min · ${String(d.budget.runsPerDay)} runs, $${d.budget.usdPerDay.toFixed(2)} a day`, | |
| 27 | note: `${last}${d.pausedReason === null ? "" : ` · ${d.pausedReason}`}`, | |
| 28 | }; | |
| 29 | } | |
| 30 | ||
| 31 | export function maintainScreen(f: Session, ctx: Ctx): Screen { | |
| 32 | const state = new ListState(); | |
| 33 | let duties: readonly Duty[] = []; | |
| 34 | const reload = (): void => { | |
| 35 | duties = mayMaintain(f) ? dutyBoard(f.app) : []; | |
| 36 | ctx.invalidate(); | |
| 37 | }; | |
| 38 | return { | |
| 39 | title: "Maintainer", | |
| 40 | keys: [binding(["j", "k"], "move cursor"), binding(["p"], "pause / resume")], | |
| 41 | load() { | |
| 42 | reload(); | |
| 43 | return Promise.resolve(); | |
| 44 | }, | |
| 45 | render(area, s) { | |
| 46 | const c = ctx.theme.c; | |
| 47 | const [head, list] = split(area, "v", [len(1), fill(1)]); | |
| 48 | s.text(head!.x, head!.y, truncate("scheduled duties: each runs inside its budget and proposes only through issues and pulls", head!.w), style(c.mutedFg, c.bg), head!.x + head!.w); | |
| 49 | drawList(s, list!, c, state, duties.map(rowOf)); | |
| 50 | }, | |
| 51 | key(e) { | |
| 52 | if (e.key !== "p") return state.key(e, duties.length); | |
| 53 | const d = duties[state.index]; | |
| 54 | if (d !== undefined && mayMaintain(f) && f.user !== undefined) { | |
| 55 | setDutyPaused(f.app, d.name, d.enabled, f.user.username); | |
| 56 | ctx.toast(`${d.name} ${d.enabled ? "paused" : "resumed"}`); | |
| 57 | reload(); | |
| 58 | } | |
| 59 | return true; | |
| 60 | }, | |
| 61 | }; | |
| 62 | } | |
| 63 | ||
| 64 | /** The maintainer's duties: a forge admin's who is a person. */ | |
| 65 | export const entry: PaletteEntry = { | |
| 66 | id: "maintain", | |
| 67 | title: "Maintainer", | |
| 68 | hint: "scheduled duties, their budgets and last runs; pause or resume one", | |
| 69 | after: ["valves", "sentinel"], | |
| 70 | offered: mayMaintain, | |
| 71 | run: (session, ctx) => ctx.push(maintainScreen(session, ctx)), | |
| 72 | }; |
src/web/pages/flow.ts +1 −1
| @@ -82,7 +82,7 @@ export function flowPage(ctx: Ctx): Response { | ||
| 82 | 82 | if (user === undefined) return signInFirst(ctx); |
| 83 | 83 | if (!user.isAdmin || user.kind === "agent") return notFoundPage(ctx); |
| 84 | 84 | const p = readPipes(ctx.app.db, user.id); |
| 85 | const body = html`<div class="page-head"><h1>Flow</h1>${btn("Boards", { href: "/boards", variant: "ghost" })}</div> | |
| 85 | const body = html`<div class="page-head"><h1>Flow</h1>${btn("Maintainer", { href: "/maintain", variant: "ghost" })}${btn("Boards", { href: "/boards", variant: "ghost" })}</div> | |
| 86 | 86 | <p class="mb">Money flows from the left to shipped on the right, as wide as this week's real spend. Every repository has a valve: drag it to give the repository a share of the week, all the way down to shut. The crew does exactly what the valves say, from the next tick, and nothing but you turns one.</p> |
| 87 | 87 | ${card(html`<div class="card-body">${pipesSvg(p)} |
| 88 | 88 | <p class="muted small">${money(p.usd)} spent in the last 7 days; ${plural(p.shipped, "pull")} shipped.</p></div>`)} |
src/web/pages/maintain.ts added +70
| @@ -0,0 +1,70 @@ | ||
| 1 | /** | |
| 2 | * /maintain: the maintainer's duties for a forge admin who is a person: each | |
| 3 | * duty's trigger, budget, switch and last run, the latest runs, and a form to | |
| 4 | * pause or resume one. Same board as `GET /api/v1/maintain/duties` and | |
| 5 | * `tui/screens/maintain.ts` (`maintain/service.ts`); anyone else gets a 404. | |
| 6 | */ | |
| 7 | ||
| 8 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; | |
| 9 | import type { Ctx } from "../../http/context.ts"; | |
| 10 | import { dutyBoard, dutyRuns, setDutyPaused } from "../../maintain/service.ts"; | |
| 11 | import { notFoundPage } from "../chrome.ts"; | |
| 12 | import { readForm } from "../form.ts"; | |
| 13 | import { html, when } from "../html.ts"; | |
| 14 | import { flashTo, page } from "../layout.ts"; | |
| 15 | import { badge, btn, card, icon, row, time } from "../ui.ts"; | |
| 16 | ||
| 17 | type Duty = ReturnType<typeof dutyBoard>[number]; | |
| 18 | ||
| 19 | const every = (ms: number): string => (ms % 3_600_000 === 0 ? `every ${String(ms / 3_600_000)} h` : `every ${String(Math.round(ms / 60_000))} min`); | |
| 20 | ||
| 21 | function dutyRow(d: Duty) { | |
| 22 | const verb = d.enabled ? "pause" : "resume"; | |
| 23 | return row({ | |
| 24 | lead: icon("activity"), | |
| 25 | title: html`${d.name} ${d.enabled ? badge("on") : badge("paused", { tone: "attn" })} | |
| 26 | <span class="muted small">${every(d.trigger.every)} · ${String(d.budget.runsPerDay)} runs and $${d.budget.usdPerDay.toFixed(2)} a day</span>`, | |
| 27 | meta: html`${when(d.pausedReason !== null, () => html`<p class="muted small">${d.pausedReason}</p>`)} | |
| 28 | <p class="muted small">${d.lastRun === null ? "Has not run." : html`Last run ${time(d.lastRun.started)}: ${d.lastRun.outcome}${d.lastRun.detail === null ? "" : `, ${d.lastRun.detail}`}.`}</p> | |
| 29 | <form method="post" action="/maintain/duties/${d.name}/${verb}"> | |
| 30 | ${btn(d.enabled ? "Pause" : "Resume", { size: "sm", label: `${d.enabled ? "Pause" : "Resume"} the ${d.name} duty` })} | |
| 31 | </form>`, | |
| 32 | }); | |
| 33 | } | |
| 34 | ||
| 35 | // GET /maintain | |
| 36 | export function maintainPage(ctx: Ctx): Response { | |
| 37 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); | |
| 38 | const user = ctx.auth.user; | |
| 39 | if (user === undefined || !user.isAdmin || user.kind === "agent") return notFoundPage(ctx); | |
| 40 | const duties = dutyBoard(ctx.app); | |
| 41 | const runs = dutyRuns(ctx.app).slice(0, 20); | |
| 42 | const body = html`<div class="page-head"><h1>Maintainer</h1>${btn("Boards", { href: "/boards", variant: "ghost" })}</div> | |
| 43 | <p class="mb">Scheduled duties. Each runs inside its budget, leaves a probe behind every finding and action, and proposes only through issues and pulls; nothing here merges.</p> | |
| 44 | ${card(html`<ul class="list">${duties.map(dutyRow)}</ul>`, { pad: false, head: html`${icon("activity")}<h2>Duties</h2>` })} | |
| 45 | ${card( | |
| 46 | runs.length === 0 | |
| 47 | ? html`<div class="card-body"><p class="muted">No duty has run yet.</p></div>` | |
| 48 | : html`<ul class="list">${runs.map((r) => | |
| 49 | row({ | |
| 50 | title: html`${r.duty} <span class="muted small">${r.outcome} · ${time(r.started)} · ${String(r.findings.length)} findings, ${String(r.actions.length)} actions</span>`, | |
| 51 | ...(r.detail === null ? {} : { meta: html`<p class="muted small">${r.detail}</p>` }), | |
| 52 | }), | |
| 53 | )}</ul>`, | |
| 54 | { pad: false, head: html`${icon("activity")}<h2>Recent runs</h2>` }, | |
| 55 | )}`; | |
| 56 | const rendering = performance.now(); | |
| 57 | const response = page({ ctx, title: "Maintainer", body }); | |
| 58 | notePhase(ctx.request, "render", performance.now() - rendering); | |
| 59 | return response; | |
| 60 | } | |
| 61 | ||
| 62 | // POST /maintain/duties/:name/pause and /resume | |
| 63 | export const switchDuty = (paused: boolean) => async (ctx: Ctx): Promise<Response> => { | |
| 64 | if (ctx.auth.user === undefined || !ctx.auth.user.isAdmin || ctx.auth.user.kind === "agent") return notFoundPage(ctx); | |
| 65 | const form = await readForm(ctx, "admin"); | |
| 66 | if (form instanceof Response) return form; | |
| 67 | const name = ctx.params.name ?? ""; | |
| 68 | if (!setDutyPaused(ctx.app, name, paused, ctx.auth.user.username)) return notFoundPage(ctx); | |
| 69 | return flashTo(ctx, "/maintain", { message: `${name} ${paused ? "paused" : "resumed"}.` }); | |
| 70 | }; |
src/web/studio/crew.ts +2
| @@ -62,6 +62,7 @@ const ROLE_WORD: Record<CrewRole, string> = { | ||
| 62 | 62 | builder: "builds", |
| 63 | 63 | reviewer: "reviews", |
| 64 | 64 | planner: "plans", |
| 65 | maintainer: "keeps up", | |
| 65 | 66 | }; |
| 66 | 67 | |
| 67 | 68 | /** |
| @@ -139,6 +140,7 @@ const SEAT_TITLE: Record<CrewRole, string> = { | ||
| 139 | 140 | planner: "Planners", |
| 140 | 141 | builder: "Builders", |
| 141 | 142 | reviewer: "Reviewers", |
| 143 | maintainer: "Maintainers", | |
| 142 | 144 | }; |
| 143 | 145 | |
| 144 | 146 | /** |
test/forge-looks.test.ts +1
| @@ -56,6 +56,7 @@ const NOT_A_PAGE: Record<string, string> = { | ||
| 56 | 56 | "/events": "a live event stream that never ends", |
| 57 | 57 | "/boards": "the list of boards; /board is pictured, and the slot went to the preview seed's repository as its owner (#8865); covered by test/boards-page.test.ts", |
| 58 | 58 | "/changelog": "the merged changes in words; /releases is pictured, and the slot went to the preview seed's pull as its owner (#8865); covered by test/changelog.test.ts", |
| 59 | "/maintain": "the maintainer's duties for an admin; the cap of 24 looks is full; covered by the maintain tests", | |
| 59 | 60 | "/search": "a search box; its slot went to the preview seed's /next as its owner (#8866)", |
| 60 | 61 | "/contribute": "a static page about how to help; its slot went to the preview seed's /bets as its owner (#8866)", |
| 61 | 62 | "/migrate": "an import form, nothing to picture until a job runs; the look slot went to /repos", |
test/helpers/maintain.ts added +28
| @@ -0,0 +1,28 @@ | ||
| 1 | import { Database } from "bun:sqlite"; | |
| 2 | import maintenance from "../../src/core/migrations/20261103150000-maintenance.ts"; | |
| 3 | import { type Duty, type FindingInput, duty } from "../../src/maintain/duty.ts"; | |
| 4 | import { makeRegistry } from "../../src/maintain/registry.ts"; | |
| 5 | import { makeRunner } from "../../src/maintain/runner.ts"; | |
| 6 | import type { Finding } from "../../src/maintain/duty.ts"; | |
| 7 | ||
| 8 | export const NOW = Date.parse("2026-11-02T12:00:00Z"); | |
| 9 | export const HOUR = 3_600_000; | |
| 10 | ||
| 11 | export function maintainer(duties: Duty[], filed: Finding[] = []) { | |
| 12 | const db = new Database(":memory:"); | |
| 13 | db.exec(maintenance); | |
| 14 | const runner = makeRunner({ | |
| 15 | db, | |
| 16 | registry: makeRegistry(duties), | |
| 17 | file: (f) => { | |
| 18 | filed.push(f); | |
| 19 | return `#${filed.length}`; | |
| 20 | }, | |
| 21 | }); | |
| 22 | return { db, runner }; | |
| 23 | } | |
| 24 | ||
| 25 | export const probed = (ctx: { probe: (q: string, v: number) => unknown }, key = "k"): FindingInput => | |
| 26 | ({ key, title: `finding ${key}`, evidence: ["e"], probe: ctx.probe("SELECT 1", 1) }) as FindingInput; | |
| 27 | ||
| 28 | export { duty }; |
test/maintain-api.test.ts added +70
| @@ -0,0 +1,70 @@ | ||
| 1 | /** The board's switch for a duty, over the API, and the issue a finding is filed to (#7554). */ | |
| 2 | ||
| 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 4 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { createToken } from "../src/core/tokens.ts"; | |
| 9 | import { createUser, getUserByName } from "../src/core/users.ts"; | |
| 10 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 11 | import { runnerOf } from "../src/maintain/service.ts"; | |
| 12 | import { dutyList } from "../src/maintain/duties/index.ts"; | |
| 13 | import { quietLogs } from "./helpers/globals.ts"; | |
| 14 | ||
| 15 | quietLogs(); | |
| 16 | const PASS = "a-long-maintain-passphrase"; | |
| 17 | ||
| 18 | describe("maintainer over HTTP", () => { | |
| 19 | let dataDir = ""; | |
| 20 | let app: App; | |
| 21 | let servers: Servers; | |
| 22 | const tokenOf = (name: string, scope: "ro" | "admin" = "admin") => createToken(app.db, getUserByName(app.db, name)!.id, "t", scope).token; | |
| 23 | const call = (method: string, path: string, token: string | null) => | |
| 24 | fetch(`${servers.url}/api/v1/maintain/${path}`, { method, headers: token ? { authorization: `Bearer ${token}` } : {} }); | |
| 25 | ||
| 26 | beforeAll(async () => { | |
| 27 | dataDir = await mkdtemp(join(tmpdir(), "forge-maintain-")); | |
| 28 | app = createApp({ dataDir, port: 0 }); | |
| 29 | servers = await serve(app); | |
| 30 | for (const [username, isAdmin] of [["alice", true], ["bob", false]] as const) | |
| 31 | await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@x.test`, password: PASS, isAdmin }); | |
| 32 | }, 30_000); | |
| 33 | ||
| 34 | afterAll(async () => { | |
| 35 | servers.stop(); | |
| 36 | app.close(); | |
| 37 | await rm(dataDir, { recursive: true, force: true }); | |
| 38 | }); | |
| 39 | ||
| 40 | test("an admin lists duties, pauses one with a reason, and resumes it", async () => { | |
| 41 | const name = dutyList[0]!.name; | |
| 42 | const listed = (await (await call("GET", "duties", tokenOf("alice", "ro"))).json()) as any; | |
| 43 | expect(listed.duties.map((d: any) => d.name)).toContain(name); | |
| 44 | const paused = (await (await call("POST", `duties/${name}/pause`, tokenOf("alice"))).json()) as any; | |
| 45 | expect(paused.duties.find((d: any) => d.name === name)).toMatchObject({ enabled: false, pausedReason: "paused by alice" }); | |
| 46 | expect(await runnerOf(app).runDue(Date.now() + 10 * 86_400_000)).toEqual([]); | |
| 47 | const resumed = (await (await call("POST", `duties/${name}/resume`, tokenOf("alice"))).json()) as any; | |
| 48 | expect(resumed.duties.find((d: any) => d.name === name).enabled).toBe(true); | |
| 49 | }); | |
| 50 | ||
| 51 | test("a read-only token cannot pause; a plain member and a stranger are told nothing is there", async () => { | |
| 52 | const name = dutyList[0]!.name; | |
| 53 | expect((await call("POST", `duties/${name}/pause`, tokenOf("alice", "ro"))).status).toBe(403); | |
| 54 | expect((await call("GET", "duties", tokenOf("bob"))).status).toBe(404); | |
| 55 | expect((await call("GET", "runs", null)).status).toBe(404); | |
| 56 | expect((await call("POST", "duties/nope/pause", tokenOf("alice"))).status).toBe(404); | |
| 57 | }); | |
| 58 | ||
| 59 | test("the scheduled run leaves a row the API reads", async () => { | |
| 60 | await runnerOf(app).runDue(Date.now() + 100 * 86_400_000); | |
| 61 | const runs = (await (await call("GET", `runs?duty=${dutyList[0]!.name}`, tokenOf("alice", "ro"))).json()) as any; | |
| 62 | expect(runs.runs.length).toBeGreaterThan(0); | |
| 63 | }); | |
| 64 | ||
| 65 | test("the routes are in the OpenAPI document", async () => { | |
| 66 | const doc = (await (await fetch(`${servers.url}/api/v1/openapi.json`)).json()) as any; | |
| 67 | expect(doc.paths["/api/v1/maintain/duties"].get).toBeDefined(); | |
| 68 | expect(doc.paths["/api/v1/maintain/duties/{name}/pause"].post).toBeDefined(); | |
| 69 | }); | |
| 70 | }); |
test/maintain-budget.test.ts added +92
| @@ -0,0 +1,92 @@ | ||
| 1 | /** A duty over budget stops and records "budget" as the outcome (#7554). */ | |
| 2 | ||
| 3 | import { describe, expect, test } from "bun:test"; | |
| 4 | import { HOUR, NOW, duty, maintainer } from "./helpers/maintain.ts"; | |
| 5 | import { listRuns } from "../src/maintain/store.ts"; | |
| 6 | import type { Budget } from "../src/maintain/duty.ts"; | |
| 7 | ||
| 8 | const budget = (b: Partial<Budget>): Budget => ({ runsPerDay: 100, usdPerDay: 1, cpuMsPerRun: 10_000, netCallsPerRun: 2, ...b }); | |
| 9 | ||
| 10 | describe("budget", () => { | |
| 11 | test("runs per day: the run past the budget does not run and says budget", async () => { | |
| 12 | let ran = 0; | |
| 13 | const d = duty({ name: "few", trigger: { every: 1 }, budget: budget({ runsPerDay: 2 }), handler: () => { ran++; return {}; } }); | |
| 14 | const { db, runner } = maintainer([d]); | |
| 15 | for (let i = 0; i < 4; i++) await runner.runDue(NOW + i * 10); | |
| 16 | expect(ran).toBe(2); | |
| 17 | const rows = listRuns(db, "few"); | |
| 18 | expect(rows.filter((r) => r.outcome === "budget")).toHaveLength(1); // said once, not each tick | |
| 19 | expect(rows[0]?.outcome).toBe("budget"); | |
| 20 | }); | |
| 21 | ||
| 22 | test("the day rolls over", async () => { | |
| 23 | const d = duty({ name: "daily", trigger: { every: 1 }, budget: budget({ runsPerDay: 1 }), handler: () => ({}) }); | |
| 24 | const { runner } = maintainer([d]); | |
| 25 | await runner.runDue(NOW); | |
| 26 | expect((await runner.runDue(NOW + HOUR))[0]?.outcome).toBe("budget"); | |
| 27 | expect((await runner.runDue(NOW + 25 * HOUR))[0]?.outcome).toBe("ok"); | |
| 28 | }); | |
| 29 | ||
| 30 | test("dollars: spending past the day's ceiling stops the run", async () => { | |
| 31 | const d = duty({ | |
| 32 | name: "spender", | |
| 33 | trigger: { every: 1 }, | |
| 34 | budget: budget({ usdPerDay: 1 }), | |
| 35 | handler: (ctx) => { | |
| 36 | ctx.spend(0.6); | |
| 37 | ctx.spend(0.6); | |
| 38 | return {}; | |
| 39 | }, | |
| 40 | }); | |
| 41 | const { db, runner } = maintainer([d]); | |
| 42 | await runner.runDue(NOW); | |
| 43 | const [row] = listRuns(db); | |
| 44 | expect(row?.outcome).toBe("budget"); | |
| 45 | expect(row?.detail).toContain("$1"); | |
| 46 | expect(row?.cost).toBeCloseTo(1.2); | |
| 47 | }); | |
| 48 | ||
| 49 | test("network: calls past the ceiling stop the run", async () => { | |
| 50 | const d = duty({ name: "chatty", trigger: { every: 1 }, budget: budget({ netCallsPerRun: 2 }), handler: (ctx) => { ctx.net(); ctx.net(); ctx.net(); return {}; } }); | |
| 51 | const { db, runner } = maintainer([d]); | |
| 52 | await runner.runDue(NOW); | |
| 53 | expect(listRuns(db)[0]?.outcome).toBe("budget"); | |
| 54 | }); | |
| 55 | ||
| 56 | test("time: a run past its ceiling is recorded as budget", async () => { | |
| 57 | const d = duty({ name: "slow", trigger: { every: 1 }, budget: budget({ cpuMsPerRun: 5 }), handler: async () => { await Bun.sleep(30); return {}; } }); | |
| 58 | const { db, runner } = maintainer([d]); | |
| 59 | await runner.runDue(NOW); | |
| 60 | expect(listRuns(db)[0]?.outcome).toBe("budget"); | |
| 61 | }); | |
| 62 | ||
| 63 | test("time: a handler that never settles is cut off at its deadline and frees the duty", async () => { | |
| 64 | const d = duty({ name: "hung", trigger: { every: 1 }, budget: budget({ cpuMsPerRun: 20 }), handler: () => new Promise(() => {}) }); | |
| 65 | const { db, runner } = maintainer([d]); | |
| 66 | const started = performance.now(); | |
| 67 | await runner.runDue(NOW); | |
| 68 | expect(performance.now() - started).toBeLessThan(1000); | |
| 69 | expect(listRuns(db)[0]).toMatchObject({ outcome: "budget", detail: "took longer than 20 ms" }); | |
| 70 | expect(await runner.runDue(NOW + 10)).toHaveLength(1); // not stuck running | |
| 71 | }); | |
| 72 | ||
| 73 | test("an abandoned handler's late calls do nothing", async () => { | |
| 74 | let late: unknown; | |
| 75 | const d = duty({ name: "late", trigger: { every: 1 }, budget: budget({ cpuMsPerRun: 10 }), handler: async (ctx) => { | |
| 76 | await Bun.sleep(40); | |
| 77 | try { ctx.spend(1); late = "spent"; } catch (e) { late = e instanceof Error ? e.message : "?"; } | |
| 78 | return {}; | |
| 79 | } }); | |
| 80 | const { runner } = maintainer([d]); | |
| 81 | await runner.runDue(NOW); | |
| 82 | await Bun.sleep(60); | |
| 83 | expect(late).toBe("the run has ended"); | |
| 84 | }); | |
| 85 | ||
| 86 | test("a budget stop is not an error: it never pauses the duty", async () => { | |
| 87 | const d = duty({ name: "chat", trigger: { every: 1 }, budget: budget({ netCallsPerRun: 0 }), handler: (ctx) => { ctx.net(); return {}; } }); | |
| 88 | const { db, runner } = maintainer([d]); | |
| 89 | for (let i = 0; i < 4; i++) await runner.runDue(NOW + i * 10); | |
| 90 | expect(db.query("SELECT enabled FROM maintenance_duty").all()).toEqual([]); | |
| 91 | }); | |
| 92 | }); |
test/maintain-canary.test.ts added +53
| @@ -0,0 +1,53 @@ | ||
| 1 | /** A bulk action touches one item, waits for its probe, then continues (#7554). */ | |
| 2 | ||
| 3 | import { describe, expect, test } from "bun:test"; | |
| 4 | import { NOW, duty, maintainer } from "./helpers/maintain.ts"; | |
| 5 | import { listRuns } from "../src/maintain/store.ts"; | |
| 6 | import { BULK_CAP, type DutyContext } from "../src/maintain/duty.ts"; | |
| 7 | ||
| 8 | const bulky = (items: number[], touched: number[], passes: (n: number) => boolean) => | |
| 9 | duty({ | |
| 10 | name: "bulk", | |
| 11 | trigger: { every: 1 }, | |
| 12 | handler: async (ctx: DutyContext) => { | |
| 13 | await ctx.bulk(items, { | |
| 14 | what: "touch", | |
| 15 | target: String, | |
| 16 | apply: (n) => void touched.push(n), | |
| 17 | check: (n) => ({ ...ctx.probe(`check ${n}`, passes(n)), pass: passes(n) }), | |
| 18 | }); | |
| 19 | return {}; | |
| 20 | }, | |
| 21 | }); | |
| 22 | ||
| 23 | describe("canary", () => { | |
| 24 | test("a passing canary lets the rest through, each with its probe", async () => { | |
| 25 | const touched: number[] = []; | |
| 26 | const { db, runner } = maintainer([bulky([1, 2, 3], touched, () => true)]); | |
| 27 | await runner.runDue(NOW); | |
| 28 | expect(touched).toEqual([1, 2, 3]); | |
| 29 | const [row] = listRuns(db); | |
| 30 | expect(row?.outcome).toBe("ok"); | |
| 31 | expect(row?.actions.map((a) => a.target)).toEqual(["1", "2", "3"]); | |
| 32 | }); | |
| 33 | ||
| 34 | test("a failing canary touches nothing else", async () => { | |
| 35 | const touched: number[] = []; | |
| 36 | const { db, runner } = maintainer([bulky([1, 2, 3], touched, () => false)]); | |
| 37 | await runner.runDue(NOW); | |
| 38 | expect(touched).toEqual([1]); | |
| 39 | const [row] = listRuns(db); | |
| 40 | expect(row?.outcome).toBe("canary"); | |
| 41 | expect(row?.detail).toContain("nothing else touched"); | |
| 42 | expect(row?.actions).toHaveLength(1); | |
| 43 | expect(row?.actions[0]?.probe.value).toBe(false); | |
| 44 | }); | |
| 45 | ||
| 46 | test("a bulk is capped per run", async () => { | |
| 47 | const touched: number[] = []; | |
| 48 | const many = Array.from({ length: BULK_CAP + 15 }, (_, i) => i); | |
| 49 | const { runner } = maintainer([bulky(many, touched, () => true)]); | |
| 50 | await runner.runDue(NOW); | |
| 51 | expect(touched).toHaveLength(BULK_CAP); | |
| 52 | }); | |
| 53 | }); |
test/maintain-doors.test.ts added +110
| @@ -0,0 +1,110 @@ | ||
| 1 | /** The maintainer's two doors, the page and the terminal screen, both an admin's; (#7554). */ | |
| 2 | ||
| 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 4 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { createUser, type User } from "../src/core/users.ts"; | |
| 9 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 10 | import { dutyList } from "../src/maintain/duties/index.ts"; | |
| 11 | import { dutyBoard } from "../src/maintain/service.ts"; | |
| 12 | import { createForgeApp, forgeCommands } from "../src/tui/forge.ts"; | |
| 13 | import { headlessTerminal } from "../src/tui/term/terminal.ts"; | |
| 14 | import { quietLogs } from "./helpers/globals.ts"; | |
| 15 | import { settleApp, settleUntil } from "./helpers/tui.ts"; | |
| 16 | ||
| 17 | quietLogs(); | |
| 18 | const PASS = "a-good-passphrase"; | |
| 19 | const NAME = dutyList[0]!.name; | |
| 20 | ||
| 21 | describe("the maintainer's doors", () => { | |
| 22 | let dir = ""; | |
| 23 | let app: App; | |
| 24 | let servers: Servers; | |
| 25 | let alice: User; | |
| 26 | let bob: User; | |
| 27 | const login = async (username: string): Promise<string> => { | |
| 28 | const res = await fetch(`${servers.url}/signin`, { | |
| 29 | method: "POST", redirect: "manual", | |
| 30 | headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url }, | |
| 31 | body: new URLSearchParams({ username, password: PASS }), | |
| 32 | }); | |
| 33 | return (res.headers.get("set-cookie") ?? "").split(";")[0] ?? ""; | |
| 34 | }; | |
| 35 | const get = (path: string, cookie: string) => fetch(`${servers.url}${path}`, { headers: { cookie }, redirect: "manual" }); | |
| 36 | const post = (path: string, cookie: string, origin = servers.url) => | |
| 37 | fetch(`${servers.url}${path}`, { method: "POST", redirect: "manual", headers: { cookie, origin, "content-type": "application/x-www-form-urlencoded" }, body: "" }); | |
| 38 | const enabled = () => dutyBoard(app).find((d) => d.name === NAME)!.enabled; | |
| 39 | const identity = (user: User) => ({ sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user }); | |
| 40 | ||
| 41 | beforeAll(async () => { | |
| 42 | dir = await mkdtemp(join(tmpdir(), "forge-maintain-doors-")); | |
| 43 | app = createApp({ dataDir: dir, port: 0 }); | |
| 44 | servers = await serve(app); | |
| 45 | const make = async (username: string, adminIfFirst: boolean) => { | |
| 46 | const u = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: PASS, adminIfFirst }); | |
| 47 | if (!u.ok) throw new Error(u.error); | |
| 48 | return u.value; | |
| 49 | }; | |
| 50 | alice = await make("alice", true); | |
| 51 | bob = await make("bob", false); | |
| 52 | }, 30_000); | |
| 53 | afterAll(async () => { | |
| 54 | servers.stop(); | |
| 55 | app.close(); | |
| 56 | await rm(dir, { recursive: true, force: true }); | |
| 57 | }); | |
| 58 | ||
| 59 | test("the page lists the duties to an admin, and a guest or a member finds nothing", async () => { | |
| 60 | const res = await get("/maintain", await login("alice")); | |
| 61 | expect(res.status).toBe(200); | |
| 62 | const text = await res.text(); | |
| 63 | expect(text).toContain(NAME); | |
| 64 | expect(text).toContain(`action="/maintain/duties/${NAME}/pause"`); | |
| 65 | expect((await get("/maintain", await login("bob"))).status).toBe(404); | |
| 66 | expect((await get("/maintain", "")).status).toBe(404); | |
| 67 | }); | |
| 68 | ||
| 69 | test("pause and resume are post forms: same-origin, admin only, and they change the switch", async () => { | |
| 70 | const cookie = await login("alice"); | |
| 71 | expect((await post(`/maintain/duties/${NAME}/pause`, cookie, "https://evil.example")).status).toBeGreaterThanOrEqual(400); | |
| 72 | expect(enabled()).toBe(true); | |
| 73 | expect((await post(`/maintain/duties/${NAME}/pause`, await login("bob"))).status).toBe(404); | |
| 74 | expect(enabled()).toBe(true); | |
| 75 | expect((await post(`/maintain/duties/${NAME}/pause`, cookie)).status).toBe(303); | |
| 76 | expect(enabled()).toBe(false); | |
| 77 | expect((await get("/maintain", cookie).then((r) => r.text()))).toContain(`/maintain/duties/${NAME}/resume`); | |
| 78 | expect((await post(`/maintain/duties/${NAME}/resume`, cookie)).status).toBe(303); | |
| 79 | expect(enabled()).toBe(true); | |
| 80 | expect((await post("/maintain/duties/nope/pause", cookie)).status).toBe(404); | |
| 81 | }); | |
| 82 | ||
| 83 | const open = (u: User) => { | |
| 84 | const made = createForgeApp(app, identity(u), { terminal: headlessTerminal(140, 24), exitHooks: false }); | |
| 85 | const ids = forgeCommands(made.session)(made.app.ctx).map((c) => c.id); | |
| 86 | return { ...made, ids }; | |
| 87 | }; | |
| 88 | ||
| 89 | test("the terminal offers the screen to an admin only, and p pauses the duty under the cursor", async () => { | |
| 90 | const guest = open(bob); | |
| 91 | expect(guest.ids).not.toContain("maintain"); | |
| 92 | guest.app.stop?.(); | |
| 93 | const { app: tui, ids } = open(alice); | |
| 94 | expect(ids).toContain("maintain"); | |
| 95 | tui.start(); | |
| 96 | const key = (k: string, ctrl = false) => tui.dispatch({ type: "key", key: k, ctrl, alt: false, shift: false }); | |
| 97 | key("k", true); | |
| 98 | for (const ch of "Maintainer") key(ch); | |
| 99 | await settleApp(tui); | |
| 100 | key("enter"); | |
| 101 | await settleUntil(tui, `${NAME} on`, { timeoutMs: 4_000 }); | |
| 102 | key("p"); | |
| 103 | await settleUntil(tui, `${NAME} paused`, { timeoutMs: 4_000 }); | |
| 104 | expect(enabled()).toBe(false); | |
| 105 | key("p"); | |
| 106 | await settleUntil(tui, `${NAME} on`, { timeoutMs: 4_000 }); | |
| 107 | expect(enabled()).toBe(true); | |
| 108 | tui.stop?.(); | |
| 109 | }); | |
| 110 | }); |
test/maintain-file.test.ts added +91
| @@ -0,0 +1,91 @@ | ||
| 1 | /** Where a finding goes: only the maintainer files, and a still-true finding is not said again every run (#7554). */ | |
| 2 | ||
| 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 4 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createRepo } from "../src/actions/repos.ts"; | |
| 8 | import { createApp, type App } from "../src/app.ts"; | |
| 9 | import { createAgentRow } from "../src/core/agents.ts"; | |
| 10 | import { getIssueById, listComments } from "../src/core/issues.ts"; | |
| 11 | import { createUser, type User } from "../src/core/users.ts"; | |
| 12 | import type { Finding } from "../src/maintain/duty.ts"; | |
| 13 | import { issueFiler } from "../src/maintain/file.ts"; | |
| 14 | import { admit } from "../src/maintain/probe.ts"; | |
| 15 | import { trackedFinding } from "../src/maintain/store.ts"; | |
| 16 | import { quietLogs } from "./helpers/globals.ts"; | |
| 17 | ||
| 18 | quietLogs(); | |
| 19 | const DAY = 86_400_000; | |
| 20 | const T0 = Date.parse("2026-11-02T12:00:00Z"); | |
| 21 | const finding = (evidence: string[] = ["3 stale"], value = 3): Finding => ({ | |
| 22 | key: "stale-things", title: "Stale things", evidence, | |
| 23 | probe: { query: "SELECT COUNT(*) FROM stale", value, at: "2026-11-02T12:00:00Z" }, | |
| 24 | }); | |
| 25 | ||
| 26 | describe("the maintainer files", () => { | |
| 27 | let dir = ""; | |
| 28 | let app: App; | |
| 29 | let alice: User; | |
| 30 | const commentsOn = (key: string) => { | |
| 31 | const issue = getIssueById(app.db, trackedFinding(app.db, key)!.issueId)!; | |
| 32 | return listComments(app.db, issue.id).length; | |
| 33 | }; | |
| 34 | ||
| 35 | beforeAll(async () => { | |
| 36 | dir = await mkdtemp(join(tmpdir(), "forge-maintain-file-")); | |
| 37 | app = createApp({ dataDir: dir, port: 0 }); | |
| 38 | const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-long-maintain-passphrase", isAdmin: true }); | |
| 39 | if (!made.ok) throw new Error(made.error); | |
| 40 | alice = made.value; | |
| 41 | const repo = await createRepo(app, alice, { name: "forge", visibility: "public" }); | |
| 42 | if (!repo.ok) throw new Error(String(repo.error)); | |
| 43 | }, 30_000); | |
| 44 | ||
| 45 | afterAll(async () => { | |
| 46 | app.close(); | |
| 47 | await rm(dir, { recursive: true, force: true }); | |
| 48 | }); | |
| 49 | ||
| 50 | test("with no maintainer seated nothing is filed, and no admin speaks for it", () => { | |
| 51 | const file = issueFiler(app, "alice/forge"); | |
| 52 | expect(() => file(finding(), T0)).toThrow("no maintainer agent"); | |
| 53 | expect(trackedFinding(app.db, "stale-things")).toBeUndefined(); | |
| 54 | }); | |
| 55 | ||
| 56 | test("a seated maintainer files as itself; the same finding is not commented again until it changes or a day passes", async () => { | |
| 57 | const made = await createUser(app.db, { origin: "seed", trusted: true, username: "maintainer", email: "[email protected]", password: "a-long-maintain-passphrase" }); | |
| 58 | if (!made.ok) throw new Error(made.error); | |
| 59 | createAgentRow(app.db, { userId: made.value.id, roles: ["maintainer"] }); | |
| 60 | const file = issueFiler(app, "alice/forge"); | |
| 61 | ||
| 62 | expect(file(finding(), T0)).toMatch(/^#\d+$/); | |
| 63 | const issue = getIssueById(app.db, trackedFinding(app.db, "stale-things")!.issueId)!; | |
| 64 | expect(issue.authorId).toBe(made.value.id); | |
| 65 | expect(commentsOn("stale-things")).toBe(0); | |
| 66 | ||
| 67 | expect(file(finding(), T0 + 3_600_000)).toContain("(unchanged)"); | |
| 68 | expect(file(finding(), T0 + 5 * 3_600_000)).toContain("(unchanged)"); | |
| 69 | expect(commentsOn("stale-things")).toBe(0); | |
| 70 | ||
| 71 | expect(file(finding(["4 stale"], 4), T0 + 6 * 3_600_000)).toContain("(commented)"); | |
| 72 | expect(commentsOn("stale-things")).toBe(1); | |
| 73 | ||
| 74 | expect(file(finding(["4 stale"], 4), T0 + 7 * 3_600_000)).toContain("(unchanged)"); | |
| 75 | expect(file(finding(["4 stale"], 4), T0 + 6 * 3_600_000 + DAY)).toContain("(commented)"); | |
| 76 | expect(commentsOn("stale-things")).toBe(2); | |
| 77 | }); | |
| 78 | }); | |
| 79 | ||
| 80 | describe("admit caps what a duty can say", () => { | |
| 81 | const probe = { query: "SELECT 1", value: 1, at: "2026-11-02T12:00:00Z" }; | |
| 82 | test("a long title, long or many evidence lines, and too many findings are refused", () => { | |
| 83 | const mk = (over: Partial<Finding>): Finding => ({ ...finding(), ...over, probe }); | |
| 84 | const r = admit([mk({ key: "t", title: "x".repeat(201) }), mk({ key: "l", evidence: ["y".repeat(501)] }), mk({ key: "n", evidence: Array(21).fill("e") }), mk({ key: "ok" })], []); | |
| 85 | expect(r.findings.map((f) => f.key)).toEqual(["ok"]); | |
| 86 | expect(r.refused).toHaveLength(3); | |
| 87 | const many = admit(Array.from({ length: 25 }, (_, i) => mk({ key: `k${i}` })), []); | |
| 88 | expect(many.findings).toHaveLength(20); | |
| 89 | expect(many.refused).toHaveLength(5); | |
| 90 | }); | |
| 91 | }); |
test/maintain-no-land.test.ts added +53
| @@ -0,0 +1,53 @@ | ||
| 1 | /** The maintainer role has no path to merge or to push main (#7554). */ | |
| 2 | ||
| 3 | import { describe, expect, test } from "bun:test"; | |
| 4 | import { readdirSync, readFileSync } from "node:fs"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { Database } from "bun:sqlite"; | |
| 7 | import { isCrewRole } from "../src/core/agents.ts"; | |
| 8 | ||
| 9 | const root = join(import.meta.dir, "../src/maintain"); | |
| 10 | const sources = (dir: string): string[] => | |
| 11 | readdirSync(dir, { withFileTypes: true }).flatMap((e) => | |
| 12 | e.isDirectory() ? sources(join(dir, e.name)) : e.name.endsWith(".ts") ? [join(dir, e.name)] : [], | |
| 13 | ); | |
| 14 | ||
| 15 | describe("the maintainer proposes, a person lands", () => { | |
| 16 | test("maintainer is a crew role, the same kind of agent as a builder", () => { | |
| 17 | expect(isCrewRole("maintainer")).toBe(true); | |
| 18 | }); | |
| 19 | ||
| 20 | test("nothing under src/maintain imports a way to merge, push or run git", () => { | |
| 21 | const banned = [/mergePull/, /core\/merges/, /git\/(receive|push|hooks)/, /Bun\.spawn/, /node:child_process/, /\bpush\b.*\bmain\b/, /\beval\(/]; | |
| 22 | for (const file of sources(root)) { | |
| 23 | const text = readFileSync(file, "utf8"); | |
| 24 | for (const rule of banned) expect([file, rule.test(text)]).toEqual([file, false]); | |
| 25 | } | |
| 26 | }); | |
| 27 | ||
| 28 | test("a duty's context offers named accessors and no database handle", async () => { | |
| 29 | const { maintainer, NOW, duty } = await import("./helpers/maintain.ts"); | |
| 30 | let ctxSeen: Record<string, unknown> = {}; | |
| 31 | const { runner } = maintainer([duty({ name: "peek", trigger: { every: 1 }, handler: (ctx) => { ctxSeen = ctx as unknown as Record<string, unknown>; return {}; } })]); | |
| 32 | await runner.runDue(NOW); | |
| 33 | expect(Object.keys(ctxSeen).sort()).toEqual(["bulk", "net", "now", "probe", "runs", "spend"]); | |
| 34 | expect(Object.keys(ctxSeen.runs as object).sort()).toEqual(["before", "has", "prune"]); | |
| 35 | const handles = [ctxSeen, ctxSeen.runs].flatMap((o) => Object.values(o as object)).filter((v) => v instanceof Database); | |
| 36 | expect(handles).toEqual([]); | |
| 37 | }); | |
| 38 | ||
| 39 | test("duty files import no database, store or core module: they get what the context hands them", () => { | |
| 40 | for (const file of sources(join(root, "duties")).filter((f) => !f.endsWith("index.ts"))) { | |
| 41 | const imports = [...readFileSync(file, "utf8").matchAll(/from "([^"]+)"/g)].map((m) => m[1]); | |
| 42 | expect([file, imports.filter((i) => i !== "../duty.ts")]).toEqual([file, []]); | |
| 43 | } | |
| 44 | }); | |
| 45 | ||
| 46 | test("a duty cannot write what it was not handed: merge state, tokens and users stay out of reach", async () => { | |
| 47 | const { maintainer, NOW, duty } = await import("./helpers/maintain.ts"); | |
| 48 | let reached: unknown = "untouched"; | |
| 49 | const { runner } = maintainer([duty({ name: "grab", trigger: { every: 1 }, handler: (ctx) => { reached = (ctx as unknown as { db?: unknown }).db; return {}; } })]); | |
| 50 | await runner.runDue(NOW); | |
| 51 | expect(reached).toBeUndefined(); | |
| 52 | }); | |
| 53 | }); |
test/maintain-probe-required.test.ts added +39
| @@ -0,0 +1,39 @@ | ||
| 1 | /** A finding or an action without the probe behind it is refused (#7554). */ | |
| 2 | ||
| 3 | import { describe, expect, test } from "bun:test"; | |
| 4 | import { NOW, duty, maintainer, probed } from "./helpers/maintain.ts"; | |
| 5 | import { listRuns } from "../src/maintain/store.ts"; | |
| 6 | import { validProbe } from "../src/maintain/probe.ts"; | |
| 7 | import type { Finding } from "../src/maintain/duty.ts"; | |
| 8 | ||
| 9 | describe("probe required", () => { | |
| 10 | test("a finding with no probe is refused, one with a probe is kept and filed", async () => { | |
| 11 | const filed: Finding[] = []; | |
| 12 | const d = duty({ | |
| 13 | name: "mixed", | |
| 14 | trigger: { every: 1 }, | |
| 15 | handler: (ctx) => ({ | |
| 16 | findings: [{ key: "bare", title: "no probe", evidence: [], probe: undefined }, probed(ctx, "backed")], | |
| 17 | actions: [{ what: "fix", target: "t", probe: undefined }], | |
| 18 | }), | |
| 19 | }); | |
| 20 | const { db, runner } = maintainer([d], filed); | |
| 21 | await runner.runDue(NOW); | |
| 22 | const [row] = listRuns(db); | |
| 23 | expect(row?.outcome).toBe("refused"); | |
| 24 | expect(row?.findings.map((f) => f.key)).toEqual(["backed"]); | |
| 25 | expect(row?.actions).toEqual([]); | |
| 26 | expect(row?.detail).toContain("finding bare: no probe"); | |
| 27 | expect(row?.detail).toContain("action fix t: no probe"); | |
| 28 | expect(filed.map((f) => f.key)).toEqual(["backed"]); | |
| 29 | }); | |
| 30 | ||
| 31 | test("a probe needs a query, a finite value and a time", () => { | |
| 32 | const ok = { query: "SELECT 1", value: 1, at: "2026-11-02T12:00:00Z" }; | |
| 33 | expect(validProbe(ok)).toBe(true); | |
| 34 | expect(validProbe({ ...ok, query: " " })).toBe(false); | |
| 35 | expect(validProbe({ ...ok, value: Number.NaN })).toBe(false); | |
| 36 | expect(validProbe({ ...ok, at: "yesterday-ish" })).toBe(false); | |
| 37 | expect(validProbe(undefined)).toBe(false); | |
| 38 | }); | |
| 39 | }); |
test/maintain-runner.test.ts added +94
| @@ -0,0 +1,94 @@ | ||
| 1 | /** A duty registered in one place runs on schedule, serialized, and leaves a run row (#7554). */ | |
| 2 | ||
| 3 | import { describe, expect, test } from "bun:test"; | |
| 4 | import { HOUR, NOW, duty, maintainer, probed } from "./helpers/maintain.ts"; | |
| 5 | import { listRuns, dutyState, resumeDuty } from "../src/maintain/store.ts"; | |
| 6 | import { makeRegistry } from "../src/maintain/registry.ts"; | |
| 7 | import { dutyList } from "../src/maintain/duties/index.ts"; | |
| 8 | import type { Finding } from "../src/maintain/duty.ts"; | |
| 9 | ||
| 10 | describe("the duty runner", () => { | |
| 11 | test("runs a due duty and leaves a row with findings, actions and probes", async () => { | |
| 12 | const filed: Finding[] = []; | |
| 13 | const d = duty({ | |
| 14 | name: "look", | |
| 15 | trigger: { every: HOUR }, | |
| 16 | handler: (ctx) => ({ | |
| 17 | findings: [probed(ctx, "a")], | |
| 18 | actions: [{ what: "note", target: "x", probe: ctx.probe("SELECT 2", 2) }], | |
| 19 | }), | |
| 20 | }); | |
| 21 | const { db, runner } = maintainer([d], filed); | |
| 22 | const ran = await runner.runDue(NOW); | |
| 23 | expect(ran).toHaveLength(1); | |
| 24 | const [row] = listRuns(db, "look"); | |
| 25 | expect(row?.outcome).toBe("ok"); | |
| 26 | expect(row?.findings.map((f) => f.key)).toEqual(["a"]); | |
| 27 | expect(row?.actions[0]?.target).toBe("x"); | |
| 28 | expect(row?.probes.map((p) => p.value)).toEqual([1, 2]); | |
| 29 | expect(filed.map((f) => f.key)).toEqual(["a"]); | |
| 30 | }); | |
| 31 | ||
| 32 | test("waits for its interval, then runs again", async () => { | |
| 33 | const { db, runner } = maintainer([duty({ name: "tick", trigger: { every: HOUR }, handler: () => ({}) })]); | |
| 34 | await runner.runDue(NOW); | |
| 35 | expect(await runner.runDue(NOW + HOUR / 2)).toHaveLength(0); | |
| 36 | expect(await runner.runDue(NOW + HOUR)).toHaveLength(1); | |
| 37 | expect(listRuns(db)).toHaveLength(2); | |
| 38 | }); | |
| 39 | ||
| 40 | test("a duty never overlaps itself", async () => { | |
| 41 | let release = () => {}; | |
| 42 | let starts = 0; | |
| 43 | const d = duty({ | |
| 44 | name: "slow", | |
| 45 | trigger: { every: 1 }, | |
| 46 | handler: () => { | |
| 47 | starts++; | |
| 48 | return new Promise((r) => (release = () => r({}))); | |
| 49 | }, | |
| 50 | }); | |
| 51 | const { runner } = maintainer([d]); | |
| 52 | const first = runner.runDuty(d, NOW); | |
| 53 | expect(await runner.runDuty(d, NOW + 5)).toBeUndefined(); | |
| 54 | release(); | |
| 55 | await first; | |
| 56 | expect(starts).toBe(1); | |
| 57 | }); | |
| 58 | ||
| 59 | test("a switched-off duty does not run", async () => { | |
| 60 | const { runner } = maintainer([duty({ name: "off", trigger: { every: 1 }, enabled: false, handler: () => ({}) })]); | |
| 61 | expect(await runner.runDue(NOW)).toHaveLength(0); | |
| 62 | }); | |
| 63 | ||
| 64 | test("three errors in a row pause the duty and say why; resume clears it", async () => { | |
| 65 | const d = duty({ name: "bad", trigger: { every: 1 }, handler: () => { throw new Error("boom"); } }); | |
| 66 | const { db, runner } = maintainer([d]); | |
| 67 | for (let i = 0; i < 3; i++) await runner.runDue(NOW + i * 10); | |
| 68 | const state = dutyState(db, "bad"); | |
| 69 | expect(state.enabled).toBe(false); | |
| 70 | expect(state.pausedReason).toContain("3 times"); | |
| 71 | expect(state.pausedReason).toContain("boom"); | |
| 72 | expect(await runner.runDue(NOW + 100)).toHaveLength(0); | |
| 73 | resumeDuty(db, "bad"); | |
| 74 | expect(await runner.runDue(NOW + 200)).toHaveLength(1); | |
| 75 | }); | |
| 76 | ||
| 77 | test("a success resets the error count", async () => { | |
| 78 | let fail = true; | |
| 79 | const d = duty({ name: "flaky", trigger: { every: 1 }, handler: () => { if (fail) throw new Error("x"); return {}; } }); | |
| 80 | const { db, runner } = maintainer([d]); | |
| 81 | await runner.runDue(NOW); | |
| 82 | await runner.runDue(NOW + 10); | |
| 83 | fail = false; | |
| 84 | await runner.runDue(NOW + 20); | |
| 85 | expect(dutyState(db, "flaky").errors).toBe(0); | |
| 86 | }); | |
| 87 | ||
| 88 | test("the registry refuses a twin and a bad name; the shipped duties register", () => { | |
| 89 | const d = duty({ name: "one", trigger: { every: 1 }, handler: () => ({}) }); | |
| 90 | expect(() => makeRegistry([d, d])).toThrow("twice"); | |
| 91 | expect(() => makeRegistry([duty({ name: "Bad Name", trigger: { every: 1 }, handler: () => ({}) })])).toThrow(); | |
| 92 | expect(makeRegistry(dutyList).all().length).toBeGreaterThan(0); | |
| 93 | }); | |
| 94 | }); |
test/palette-roster.test.ts +1
| @@ -86,6 +86,7 @@ test("a site-admin person is offered the whole roster", () => { | ||
| 86 | 86 | ["flow", "Flow", "the pipeline's bottleneck and throughput"], |
| 87 | 87 | ["system", "System", "the machine now: CPU, memory, disks, processes"], |
| 88 | 88 | ["valves", "Valves", "the week's budget as a valve per repository; turn one and the crew obeys"], |
| 89 | ["maintain", "Maintainer", "scheduled duties, their budgets and last runs; pause or resume one"], | |
| 89 | 90 | ["telemetry", "Telemetry", "which agents may read flow and system; enter flips the grant"], |
| 90 | 91 | ["capacity", "Capacity", "concurrency and guards, live; e changes a settable one"], |
| 91 | 92 | ["resilience", "Resilience", "where snapshots go and the mirror; each protection green, red or untested"], |
new above
offline
HIGH: this await runs duty code inline in the autonomy tick with no hard deadline; a hung duty stops the sentinel, triage and review behind it. Give it a deadline or run it detached with its own guard.