src/jobs-schema.ts

Functions

Imports

It imports src/agents-schema.ts, src/agents.ts, src/encoding.ts, src/scope.ts. Imported by src/controls-base.ts, src/fail-exemption.ts, src/job-outcomes.ts, src/jobs-begin.ts, src/jobs-claim.ts, src/jobs-edit.ts, src/jobs-holder.ts, src/jobs-mirror.ts, src/jobs-park.ts, src/jobs-seat.ts, src/jobs-transition.ts, src/namespace-delete.ts, src/ops-feed.ts, src/push.ts, src/routine-fire.ts, src/rule-docs.ts, src/shadow.ts, src/tools/docs-write.ts, src/tools/jobs.ts, src/watcher.ts.

Source

1import { bytesToHex } from "./encoding";
2import { SCOPE_FLAGS, type ScopeFlag } from "./agents-schema";
3import type { Agent } from "./agents";
4import { checkScope, JOBS_TOOL } from "./scope";
5
6// The work queue's vocabulary, in one place so the table, the tool and the driver
7// cannot disagree about it.
8
9// parked: wanted but not now (src/jobs-park.ts). Not open, not terminal: it holds no title slot
10// and its mirror stays active.
11export const JOB_STATUSES = ["queued", "claimed", "done", "failed", "blocked", "superseded", "parked"] as const;
12export type JobStatus = (typeof JOB_STATUSES)[number];
13
14// The states a job still holds a title slot in. The partial unique index names the
15// same values, and test/jobs.test.ts asserts they agree with the last migration that
16// defines it: a status added here and not there would let two open jobs share a title.
17//
18// Blocked is open (migrations/0019). It is a pause with somebody waiting on it, and
19// resume takes the same row back to claimed; leaving it out would let a watcher post
20// the same finding again while the first copy waits for the seat.
21export const OPEN_JOB_STATUSES: readonly JobStatus[] = ["queued", "claimed", "blocked"];
22
23// The finished states. A job's mirror document closes on these. Superseded is finished
24// but not a failure (migrations/0020): the job was replaced before any work was done,
25// so it writes no outcome row.
26const TERMINAL_JOB_STATUSES: readonly JobStatus[] = ["done", "failed", "superseded"];
27
28export function isTerminalJobStatus(status: JobStatus): boolean {
29  return TERMINAL_JOB_STATUSES.includes(status);
30}
31
32export const JOB_ACTIONS = ["post", "list", "claim", "complete", "record", "fail", "block", "resume", "supersede", "release", "begin", "fire", "routine", "edit", "park", "unpark"] as const;
33
34export const JOBS_ROWS_MAX = 100;
35
36// Every job is also a document, so brief and search see the queue. The table is the
37// source of truth for status.
38// Nothing else writes under it: the docs write tools refuse it (src/tools/docs-write.ts).
39export const JOB_DOC_PREFIX = "jobs/";
40export const jobDocPath = (id: string) => `${JOB_DOC_PREFIX}${id}.md`;
41
42export interface JobRow {
43  id: string;
44  namespace: string;
45  title: string;
46  body: string;
47  priority: number;
48  status: JobStatus;
49  posted_by: string;
50  claimed_by: string | null;
51  claimed_at: string | null;
52  result_ref: string | null;
53  result_summary: string | null;
54  // The holder's signature over result_summary (migrations/0027, src/job-signing.ts),
55  // or null: written before signing, or by a writer that does not sign.
56  summary_sig?: string | null;
57  gate_required: number;
58  // The scopes this job's work needs of the driver that claims it, as JSON, or null
59  // for the jobs that need nothing unusual (migrations/0009).
60  required_scopes: string | null;
61  // The track record this job needs of that driver, as JSON, or null (migrations/0011).
62  min_record: string | null;
63  // Gates hit and human resumes, counted where they happen (migrations/0007).
64  blocked_count: number;
65  resumed_count: number;
66  // The retry cap's budget (migrations/0016): only the times the work was sent back to
67  // be corrected. See atCorrectionCap.
68  corrections_count: number;
69  // 1 when a reviewer must speak before the work reaches the seat (migrations/0017).
70  // On the row, so the party being reviewed does not decide whether it is reviewed.
71  review_required: number;
72  // The kind Capsid read or was given, and the model and effort it recommends, with the
73  // one-line reason (migrations/0032, src/model-routing.ts). NULL: not routed yet, which
74  // the next claim fixes.
75  kind?: string | null;
76  model_recommended?: string | null;
77  effort_recommended?: string | null;
78  routing_reason?: string | null;
79  // The started label (migrations/0042, src/jobs-begin.ts): who marked a queued job
80  // started, and when. It never expires and refuses nothing. NULL until
81  // somebody begins the job.
82  started_at?: string | null;
83  started_by?: string | null;
84  created_at: string;
85  updated_at: string;
86}
87
88// The started label as a reader is told it (src/jobs-begin.ts): who began the job, when,
89// and what that means. Null for a job nobody began.
90export interface StartedNotice {
91  by: string;
92  at: string;
93  note: string;
94}
95
96export function startedNotice(job: Pick<JobRow, "started_at" | "started_by">): StartedNotice | null {
97  if (!job.started_by || !job.started_at) return null;
98  return {
99    by: job.started_by,
100    at: job.started_at,
101    note: `${job.started_by} started this job at ${job.started_at}. A label: nothing is refused, but that session may already have a branch or a pull request for it.`,
102  };
103}
104
105// The retry cap: two corrections, then a human. Each round is defensible on its own,
106// which is why the ceiling is counted rather than judged.
107
108export const CORRECTION_CAP = 2;
109
110export const RETRY_CAP_REASON = "retry cap; human decision required";
111
112/** Whether a job has spent its correction budget. Fails closed: a count that is not a
113 *  finite number at or above zero is treated as at the cap. */
114export function atCorrectionCap(corrections: number): boolean {
115  if (!Number.isFinite(corrections) || corrections < 0) return true;
116  return corrections >= CORRECTION_CAP;
117}
118
119/** A capped job's summary: the cap, then the driver's own summary, which the human
120 *  deciding needs to read. */
121export function cappedSummary(summary: string | null): string {
122  const said = summary?.trim();
123  return said ? `${RETRY_CAP_REASON}\n\n${said}` : RETRY_CAP_REASON;
124}
125
126export function isJobStatus(value: unknown): value is JobStatus {
127  return typeof value === "string" && (JOB_STATUSES as readonly string[]).includes(value);
128}
129
130// The scopes a job's work requires (migrations/0009), checked by the same function as
131// an agent's scopes. Flags only: the write grant and the namespace are required of
132// every claim already, so a job has only blast radius left to declare.
133export interface RequiredScopes {
134  flags: ScopeFlag[];
135}
136
137// A requirement that cannot be read is corrupt, not absent. Failing open would hand out a
138// job whose requirement had been damaged to any driver at all, and a garbled "needs
139// can_merge" is not the same statement as "needs nothing". post validates both fields
140// before it writes them, so an unreadable value only comes from a write that bypassed
141// post, which is the row that should not be handed out.
142//
143// So the job cannot strand behind a refusal nothing can satisfy, the claim marks it
144// failed with the field named, as it does a bad signature; resume refuses and leaves
145// it blocked. null, undefined, "" and an object without the field are no requirement.
146export type ParsedRequirement<T> = { ok: true; value: T } | { ok: false; problem: string };
147
148function parseObject(field: string, json: string): ParsedRequirement<Record<string, unknown>> {
149  let raw: unknown;
150  try {
151    raw = JSON.parse(json);
152  } catch {
153    return { ok: false, problem: `${field} is not JSON` };
154  }
155  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
156    return { ok: false, problem: `${field} is not a JSON object` };
157  }
158  return { ok: true, value: raw as Record<string, unknown> };
159}
160
161export function parseRequiredScopes(json: string | null | undefined): ParsedRequirement<RequiredScopes> {
162  if (!json) return { ok: true, value: { flags: [] } };
163  const parsed = parseObject("required_scopes", json);
164  if (!parsed.ok) return parsed;
165  const flags = parsed.value.flags;
166  if (flags === undefined) return { ok: true, value: { flags: [] } };
167  if (!Array.isArray(flags)) return { ok: false, problem: "required_scopes.flags is not an array" };
168  const unknown = flags.filter((f) => !(SCOPE_FLAGS as readonly unknown[]).includes(f));
169  if (unknown.length) {
170    const names = unknown.map((f) => JSON.stringify(f)).join(", ");
171    return { ok: false, problem: `required_scopes.flags names ${names}, which ${unknown.length === 1 ? "is not a flag" : "are not flags"}` };
172  }
173  return { ok: true, value: { flags: flags as ScopeFlag[] } };
174}
175
176/** The problem with a job's stored requirements, or null when both read cleanly. */
177export function corruptRequirement(job: { required_scopes: string | null; min_record: string | null }): string | null {
178  const scopes = parseRequiredScopes(job.required_scopes);
179  if (!scopes.ok) return scopes.problem;
180  const min = parseMinRecord(job.min_record);
181  return min.ok ? null : min.problem;
182}
183
184export function serializeRequiredScopes(required: Partial<RequiredScopes>): string {
185  return JSON.stringify({ flags: required.flags ?? [] });
186}
187
188// The claim's authorization, through the one enforcement point: the write grant and
189// the namespace for every job, plus the job's own flags. Returns a refusal or null.
190export function missingForJob(agent: Agent, namespace: string, requiredScopes: string | null | undefined): string | null {
191  const required = parseRequiredScopes(requiredScopes);
192  // Fails closed for a caller that skipped the claim's corrupt check.
193  if (!required.ok) return `this job's ${required.problem}, so nothing can be checked against it.`;
194  return checkScope(agent, { tool: JOBS_TOOL, namespace, grant: "write", flags: required.value.flags });
195}
196
197/** The namespace half of missingForJob, for a resume that returns a job to its own
198 *  claimant: the caller acquires nothing but still moves the job. */
199export function outsideJobNamespace(agent: Agent, namespace: string): string | null {
200  return checkScope(agent, { tool: JOBS_TOOL, namespace, grant: "write" });
201}
202
203// job_<12 hex>, random rather than sequential so an id quoted in chat cannot be used
204// to address a job by arithmetic. The PRIMARY KEY refuses a collision.
205// Hex through bytesToHex (src/encoding.ts).
206export function mintJobId(): string {
207  return `job_${bytesToHex(crypto.getRandomValues(new Uint8Array(6)))}`;
208}
209
210// What a job needs of the driver's history (migrations/0011): a scope says what a
211// credential may do, this says what it has done. Each bar must be a number the agent
212// record computes and the Portal shows. No rate bar: a rate over a small
213// denominator is noise.
214export interface MinRecord {
215  prs_merged?: number;
216}
217
218// Fails closed, as parseRequiredScopes does.
219export function parseMinRecord(json: string | null | undefined): ParsedRequirement<MinRecord> {
220  if (!json) return { ok: true, value: {} };
221  const parsed = parseObject("min_record", json);
222  if (!parsed.ok) return parsed;
223  const value = parsed.value.prs_merged;
224  if (value === undefined) return { ok: true, value: {} };
225  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
226    return { ok: false, problem: `min_record.prs_merged is ${JSON.stringify(value)}, not a whole number of zero or more` };
227  }
228  return { ok: true, value: { prs_merged: value } };
229}
230
231export function serializeMinRecord(min: MinRecord): string {
232  return JSON.stringify({ prs_merged: min.prs_merged ?? 0 });
233}
234
235// The bar against the record's numbers, a pure comparison; src/agent-record.ts
236// computes them. Returns a refusal naming the shortfall, or null.
237export function missingForRecord(record: { prs_merged: number }, minRecord: string | null | undefined): string | null {
238  const parsed = parseMinRecord(minRecord);
239  if (!parsed.ok) return `this job's ${parsed.problem}, so no record can be compared against it.`;
240  const { prs_merged } = parsed.value;
241  if (prs_merged === undefined || record.prs_merged >= prs_merged) return null;
242  return `this job asks for a driver with at least ${prs_merged} merged pull request${prs_merged === 1 ? "" : "s"} on its record, and this one has ${record.prs_merged}.`;
243}
244
245// A swallowed parameter tag: a caller that closes a parameter tag inside a value sends
246// the later arguments as literal text in that value. Refused rather than cleaned up,
247// because the lost arguments cannot be recovered from the text, and the outcome row
248// cannot be corrected after the write. test/jobs.test.ts derives these names from
249// the tool's schema.
250export const JOB_PARAM_NAMES = [
251  "action",
252  "namespace",
253  "title",
254  "body",
255  "id",
256  "result_summary",
257  "result_ref",
258  "reason",
259  "replaced_by",
260  "command",
261  "evidence",
262  "claim",
263  "kind",
264  "stale",
265] as const;
266
267// Only the full `</name>` spelling, so a body that discusses this rule is not refused.
268const SWALLOWED_TAG = new RegExp(`</(${JOB_PARAM_NAMES.join("|")})>`);
269
270// The first parameter name found, which is where the value was cut off, or null.
271export function swallowedParamTag(value: string): string | null {
272  const match = SWALLOWED_TAG.exec(value ?? "");
273  return match ? match[1] : null;
274}
275
276// One message for every call site. It names both the field and the tag, because a
277// value cut off by its own closing tag reads confusingly unless both are stated.
278export function swallowedTagRefusal(field: string, tag: string): string {
279  const own = field === tag ? " (its own closing tag)" : "";
280  return (
281    `${field} contains the literal text '</${tag}>'${own}. That means a parameter tag was closed inside a value, ` +
282    `so '${tag}' and everything after it were swallowed into ${field} rather than arriving as their own arguments. ` +
283    `Nothing was written. Re-send the call with each parameter as a separate argument.`
284  );
285}