@feigi/fleet-ctl 3.49.4 → 3.50.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.49.4",
3
+ "version": "3.50.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,240 @@
1
+ #!/usr/bin/env node
2
+ // The shape of a member's report: one JSON Schema per member family, and the
3
+ // check that a report file has that shape.
4
+ //
5
+ // report-schema.mjs print <family>
6
+ // report-schema.mjs validate <family> <file>
7
+ //
8
+ // Reached through the Resolver: `~/.fleet/bin/fleet-run report-schema.mjs ...`.
9
+ // <family> is one of `impl`, `fix-pr`, `finisher`, `merge-bot`. The review
10
+ // runner is not a family here: its report already has a shape of its own.
11
+ //
12
+ // `print` writes the family's schema to stdout as JSON, the text a brief
13
+ // quotes or a `task` call carries as its `outputSchema`. `validate` reads
14
+ // <file> as JSON and checks it against the family's schema.
15
+ //
16
+ // Exit vocabulary:
17
+ //
18
+ // 0 print: the schema is on stdout. validate: `valid` on stdout
19
+ // 1 validate: `invalid: <violation>` on stdout, naming the FIRST violation;
20
+ // a file that is not JSON is invalid too, as `$: not JSON (...)`
21
+ // 2 usage: no or unknown subcommand, a wrong argument count, an unknown
22
+ // family, any flag; or <file> could not be read; or print could not
23
+ // write the schema to stdout. Refused on stderr, nothing on stdout
24
+ //
25
+ // A validate verdict line that stdout would not take changes nothing: the
26
+ // exit code, 0 or 1, is the verdict.
27
+ //
28
+ // Every field a family lists is required, a nullable one included: a report
29
+ // says `null`, it never leaves the field out. Only the top level is closed
30
+ // (`additionalProperties: false`); objects inside it may carry more than
31
+ // their schema names.
32
+ //
33
+ // The validator below is hand-written and covers exactly the keywords these
34
+ // schemas use: `type` (one or a list; `integer` is a whole number), `enum`,
35
+ // `required`, `properties`, `additionalProperties: false`, `items` and
36
+ // `pattern`. A keyword it does not know is not checked, so a schema here
37
+ // that starts using one needs the validator to learn it first. It walks in a
38
+ // fixed order, which is what makes "the first violation" one answer: at
39
+ // each value `type`, then `enum`, then `pattern`; in an object every
40
+ // `required` field in the schema's order, then any unexpected field in the
41
+ // report's order, then each property in the schema's order; in an array each
42
+ // item in turn. A violation is named by its path from the report's root, `$`,
43
+ // as `$.merged[1].sha`.
44
+ //
45
+ // Strict mode. A `task` call can carry this schema as `outputSchema` with
46
+ // `schemaMode: "strict"`. Measured 2026-10-14 under omp/18.10.3, and only on
47
+ // the path a member session can reach: the session's `task` tool takes items
48
+ // of { agent, name, solutionSpace, task, tools } and no `outputSchema` or
49
+ // `schemaMode`, so the same schema was handed to `eval`'s `agent(prompt,
50
+ // { schema, schemaMode })`, with a child told to submit `{}` and never
51
+ // anything else, against a schema requiring a field `x`. Each of its first
52
+ // three submissions got a notice from the child's `yield` tool:
53
+ //
54
+ // Output does not match schema: x: is required. Call yield again with the
55
+ // corrected shape — 2 retry attempt(s) remain before the schema constraint
56
+ // is dropped.
57
+ //
58
+ // then `1 retry attempt(s) remain`, then `this is the final retry`, and the
59
+ // fourth submission was taken: `Result submitted (schema validation
60
+ // overridden after 4 failed attempt(s)).` What the caller then saw depended
61
+ // on the mode:
62
+ //
63
+ // strict job status `failed`; the handle's wait() rejected with
64
+ // `schema_violation: missing required fields: x`; its output
65
+ // text was {"error":"schema_violation","message":"x: is
66
+ // required","missingRequired":["x"],"data":"{}"}
67
+ // permissive job status `completed`; the invalid `{}` came back as the
68
+ // result
69
+ //
70
+ // A child that corrected itself after the first notice, in strict mode,
71
+ // resolved with its corrected data. Not measured: a `task` dispatch that
72
+ // carries both fields, which this session's tool cannot express. So a caller
73
+ // reading a report validates the file itself, whatever the dispatch's
74
+ // schema mode.
75
+
76
+ import { readFileSync } from "node:fs";
77
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
78
+ import { isCLI } from "./is-cli.mjs";
79
+ import { HALT_CAUSES } from "./ledger-grammar.mjs";
80
+
81
+ const NAME = "report-schema";
82
+ const die = makeDie(NAME);
83
+
84
+ const USAGE = "usage: report-schema.mjs print <family> | validate <family> <file>";
85
+
86
+ const HEX = "^[0-9a-f]{40}$";
87
+ const str = { type: "string" };
88
+ const int = { type: "integer" };
89
+ const sha = { type: "string", pattern: HEX };
90
+ const strings = { type: "array", items: str };
91
+
92
+ // An object node whose every named property is required.
93
+ const obj = (properties, type = "object") => ({ type, required: Object.keys(properties), properties });
94
+ const listOf = (properties) => ({ type: "array", items: obj(properties) });
95
+
96
+ // A family's top level: every field required, nothing else allowed.
97
+ const report = (properties) => ({ ...obj(properties), additionalProperties: false });
98
+
99
+ const issues = listOf({ issue: int, subject: str });
100
+
101
+ export const SCHEMAS = {
102
+ impl: report({
103
+ member: str,
104
+ outcome: { type: "string", enum: ["pr", "bailed"] },
105
+ pr: { type: ["integer", "null"] },
106
+ head: { type: ["string", "null"], pattern: HEX },
107
+ branch: str,
108
+ sizing: obj(
109
+ { verdict: { type: "string", enum: ["light", "heavy"] }, signal: str, ranBeforePr: { type: "boolean" } },
110
+ ["object", "null"],
111
+ ),
112
+ bailCause: { type: ["string", "null"], enum: ["undecided", "fork", "hands", null] },
113
+ bailDetail: { type: ["string", "null"] },
114
+ confirmation: strings,
115
+ }),
116
+ "fix-pr": report({
117
+ member: str,
118
+ outcome: { type: "string", enum: ["applied", "no-op", "failed"] },
119
+ head: sha,
120
+ branch: str,
121
+ applied: listOf({ bucket: str, index: int }),
122
+ deferred: listOf({ bucket: str, index: int, issue: int }),
123
+ filed: issues,
124
+ unrecorded: issues,
125
+ dispositionsRecord: { type: "string", pattern: "^/" },
126
+ testRun: obj({ cmd: str, exit: int, tests: int, cancelled: int }),
127
+ confirmation: strings,
128
+ }),
129
+ finisher: report({
130
+ member: str,
131
+ outcome: { type: "string", enum: ["labelled", "halted", "failed"] },
132
+ // The ledger's own `halted:<cause>` vocabulary, so a cause added there is accepted here.
133
+ cause: { type: ["string", "null"], enum: [...HALT_CAUSES, null] },
134
+ evidence: { type: ["string", "null"] },
135
+ pin: sha,
136
+ labelsReadBack: strings,
137
+ kill: obj({ red: str, baseline: str }, ["object", "null"]),
138
+ filed: issues,
139
+ unrecorded: issues,
140
+ confirmation: strings,
141
+ }),
142
+ "merge-bot": report({
143
+ member: str,
144
+ merged: listOf({ pr: int, sha }),
145
+ held: listOf({ pr: int, behind: int }),
146
+ conflictHold: { type: "array", items: int },
147
+ refused: listOf({ pr: int, reason: str }),
148
+ branchKept: listOf({ pr: int, by: int }),
149
+ }),
150
+ };
151
+
152
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
153
+
154
+ function typeOf(v) {
155
+ if (v === null) return "null";
156
+ if (Array.isArray(v)) return "array";
157
+ if (typeof v === "number") return Number.isInteger(v) ? "integer" : "number";
158
+ return typeof v;
159
+ }
160
+
161
+ const show = (v) => JSON.stringify(v);
162
+
163
+ // The first violation of `schema` by `value`, as `<path>: <what>`, or null.
164
+ export function validate(schema, value, path = "$") {
165
+ if (schema.type !== undefined) {
166
+ const types = [].concat(schema.type);
167
+ if (!types.includes(typeOf(value))) return `${path}: expected ${types.join(" or ")}, got ${typeOf(value)}`;
168
+ }
169
+ if (schema.enum !== undefined && !schema.enum.includes(value)) {
170
+ return `${path}: ${show(value)} is not one of ${schema.enum.map(show).join(", ")}`;
171
+ }
172
+ if (typeof value === "string" && schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {
173
+ return `${path}: ${show(value)} does not match ${schema.pattern}`;
174
+ }
175
+ if (isObject(value)) {
176
+ for (const key of schema.required ?? []) {
177
+ if (!Object.hasOwn(value, key)) return `${path}: missing required field ${show(key)}`;
178
+ }
179
+ const props = schema.properties ?? {};
180
+ if (schema.additionalProperties === false) {
181
+ const extra = Object.keys(value).find((key) => !Object.hasOwn(props, key));
182
+ if (extra !== undefined) return `${path}: unexpected field ${show(extra)}`;
183
+ }
184
+ for (const [key, sub] of Object.entries(props)) {
185
+ if (!Object.hasOwn(value, key)) continue;
186
+ const found = validate(sub, value[key], `${path}.${key}`);
187
+ if (found !== null) return found;
188
+ }
189
+ }
190
+ if (Array.isArray(value) && schema.items !== undefined) {
191
+ for (let i = 0; i < value.length; i++) {
192
+ const found = validate(schema.items, value[i], `${path}[${i}]`);
193
+ if (found !== null) return found;
194
+ }
195
+ }
196
+ return null;
197
+ }
198
+
199
+ function familyOf(name) {
200
+ if (!Object.hasOwn(SCHEMAS, name)) die(`unknown family '${name}' — known: ${Object.keys(SCHEMAS).join(", ")}`);
201
+ return SCHEMAS[name];
202
+ }
203
+
204
+ function main() {
205
+ // No flags at all: the sweep refuses every `--` token by name. The
206
+ // positionals are read by count below, not by stray(), whose grammar holds
207
+ // one positional slot and this command line has up to three.
208
+ defineFlags(die, { flags: {} }).sweep();
209
+ const [cmd, family, path, ...rest] = process.argv.slice(2);
210
+ if (rest.length > 0 || family === undefined) die(USAGE);
211
+
212
+ if (cmd === "print" && path === undefined) {
213
+ if (!writeAll(1, `${JSON.stringify(familyOf(family), null, 2)}\n`)) die("the schema could not be written to stdout");
214
+ return;
215
+ }
216
+ if (cmd !== "validate" || path === undefined) die(USAGE);
217
+
218
+ const schema = familyOf(family);
219
+ let text;
220
+ try {
221
+ text = readFileSync(path, "utf8");
222
+ } catch (e) {
223
+ die(`cannot read ${path}: ${e.code ?? e.message}`);
224
+ }
225
+ let value;
226
+ try {
227
+ value = JSON.parse(text);
228
+ } catch (e) {
229
+ writeAll(1, `invalid: $: not JSON (${e.message})\n`);
230
+ process.exit(1);
231
+ }
232
+ const violation = validate(schema, value);
233
+ if (violation !== null) {
234
+ writeAll(1, `invalid: ${violation}\n`);
235
+ process.exit(1);
236
+ }
237
+ writeAll(1, "valid\n");
238
+ }
239
+
240
+ if (isCLI(import.meta.url)) main();