@cohortapp/agent-sdk 2.18.34 → 2.18.36
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/bin/maestro.mjs +1 -0
- package/lib/assurance/room-budget.mjs +68 -2
- package/lib/cli/skills.mjs +200 -0
- package/package.json +1 -1
package/bin/maestro.mjs
CHANGED
|
@@ -3940,6 +3940,7 @@ switch (command) {
|
|
|
3940
3940
|
case "session": { const r = await (await import("../lib/cli/session.mjs")).run(args); process.exitCode = r.code; break; }
|
|
3941
3941
|
case "board": await (await import("../lib/cli/board.mjs")).boardCmd(args); break;
|
|
3942
3942
|
case "design": await (await import("../lib/cli/design.mjs")).designCmd(args); break;
|
|
3943
|
+
case "skills": process.exitCode = await (await import("../lib/cli/skills.mjs")).skillsCmd(args); break;
|
|
3943
3944
|
case "run": process.exitCode = await (await import("../lib/engine/cli.mjs")).runFromProcess(args); break;
|
|
3944
3945
|
case "init":
|
|
3945
3946
|
case "update-init":
|
|
@@ -127,7 +127,12 @@ export function roomNoticeWindowMs(env = process.env) {
|
|
|
127
127
|
return num(env && env.ASSURANCE_ROOM_NOTICE_WINDOW_MS, DEFAULT_ROOM_NOTICE_WINDOW_MS);
|
|
128
128
|
}
|
|
129
129
|
|
|
130
|
-
/**
|
|
130
|
+
/**
|
|
131
|
+
* How many decision windows an entry is retained for before it is landfill.
|
|
132
|
+
*
|
|
133
|
+
* The retention must be measured against the LONGEST window the entry could be
|
|
134
|
+
* judged by, not the shortest — see the note on `pruneLedger`.
|
|
135
|
+
*/
|
|
131
136
|
const RETAIN_WINDOWS = 2;
|
|
132
137
|
|
|
133
138
|
/** The shape on disk. `v` is there so a future migration is not a guess. */
|
|
@@ -216,6 +221,29 @@ export function noticeKey(o) {
|
|
|
216
221
|
return `${roomKey(a)}|${notice}|${ident}`;
|
|
217
222
|
}
|
|
218
223
|
|
|
224
|
+
/**
|
|
225
|
+
* Was this notice key minted WITH a work id, and therefore judged by the 24-hour
|
|
226
|
+
* window rather than the 15-minute one?
|
|
227
|
+
*
|
|
228
|
+
* Reads the identity segment `noticeKey` writes: `w:<digest>` for a work-keyed
|
|
229
|
+
* notice, a bare digest for a text-keyed one. This is a deliberate coupling to
|
|
230
|
+
* that format and it is why this function lives beside it — the prune cannot
|
|
231
|
+
* retain an entry correctly without knowing which window will judge it, and the
|
|
232
|
+
* key is the only thing the ledger keeps.
|
|
233
|
+
*
|
|
234
|
+
* If `noticeKey`'s format changes, change this with it: the failure mode is
|
|
235
|
+
* silent under-retention, which deletes a stamp that was still refusing and
|
|
236
|
+
* makes the notice look like one never said.
|
|
237
|
+
*
|
|
238
|
+
* @param {string} key
|
|
239
|
+
* @returns {boolean}
|
|
240
|
+
*/
|
|
241
|
+
export function isWorkKeyedNotice(key) {
|
|
242
|
+
const k = String(key == null ? "" : key);
|
|
243
|
+
const i = k.lastIndexOf("|");
|
|
244
|
+
return i >= 0 && k.slice(i + 1).startsWith("w:");
|
|
245
|
+
}
|
|
246
|
+
|
|
219
247
|
/** One of the ledger's maps, or an empty one — never a throw, never a null deref. */
|
|
220
248
|
function mapOf(ledger, field) {
|
|
221
249
|
if (!ledger || typeof ledger !== "object") return {};
|
|
@@ -339,7 +367,45 @@ export function pruneLedger(o = {}) {
|
|
|
339
367
|
}
|
|
340
368
|
return keep;
|
|
341
369
|
};
|
|
342
|
-
|
|
370
|
+
// PRUNE IS A SIZE BOUND, NOT A POLICY — AND IT WAS SILENTLY ACTING AS ONE.
|
|
371
|
+
//
|
|
372
|
+
// The notices map holds entries with TWO intended lifetimes: `noticeAllowed`
|
|
373
|
+
// judges a work-keyed notice against DEFAULT_ROOM_WORK_NOTICE_WINDOW_MS (24h)
|
|
374
|
+
// and every other notice against DEFAULT_ROOM_NOTICE_WINDOW_MS (15m). This
|
|
375
|
+
// sifted ALL of them with the 15-minute figure, so with RETAIN_WINDOWS = 2 a
|
|
376
|
+
// work-keyed entry was deleted after exactly THIRTY MINUTES — and once it is
|
|
377
|
+
// gone `noticeAllowed` finds no stamp, returns "room-notice-new", and allows
|
|
378
|
+
// the notice again. The one-per-day guarantee was really one per half hour.
|
|
379
|
+
//
|
|
380
|
+
// It was observed before it was understood: the document-notice loop measured
|
|
381
|
+
// on 2026-10-01 had a median gap of 11.5 minutes and a MAX of 32.5 — thirty
|
|
382
|
+
// minutes of retention plus a sweep interval. The outer cadence of that loop
|
|
383
|
+
// was partly this line.
|
|
384
|
+
//
|
|
385
|
+
// The fix is to retain against the longest window any entry could be judged
|
|
386
|
+
// by. Over-retaining is free and cannot cause a wrong refusal: `noticeAllowed`
|
|
387
|
+
// applies the correct per-entry window itself, so a surviving stamp outside its
|
|
388
|
+
// own window still returns "room-notice-window-elapsed". UNDER-retaining is the
|
|
389
|
+
// only direction that changes behaviour, because a missing stamp is
|
|
390
|
+
// indistinguishable from a notice never said.
|
|
391
|
+
//
|
|
392
|
+
// GENERAL SHAPE, worth grepping for elsewhere: a ledger whose entries have
|
|
393
|
+
// mixed lifetimes and a single prune. The short lifetime wins and the long
|
|
394
|
+
// guarantee quietly becomes the short one.
|
|
395
|
+
// Each notice is retained against ITS OWN window, read off the key. A blanket
|
|
396
|
+
// max over all entries would also fix the bug, but it would keep 15-minute
|
|
397
|
+
// entries for two days and make the bounded-growth pin meaningless.
|
|
398
|
+
const siftNotices = (map) => {
|
|
399
|
+
const keep = {};
|
|
400
|
+
for (const k of Object.keys(map)) {
|
|
401
|
+
const at = stampAt(map, k);
|
|
402
|
+
if (at == null) continue;
|
|
403
|
+
const win = isWorkKeyedNotice(k) ? DEFAULT_ROOM_WORK_NOTICE_WINDOW_MS : noticeWindowMs;
|
|
404
|
+
if (now - at < win * RETAIN_WINDOWS) keep[k] = at;
|
|
405
|
+
}
|
|
406
|
+
return keep;
|
|
407
|
+
};
|
|
408
|
+
return { v: 1, rooms: sift(rooms, windowMs), notices: siftNotices(notices) };
|
|
343
409
|
}
|
|
344
410
|
|
|
345
411
|
/**
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/cli/skills.mjs — `maestro skills list|approve|show`.
|
|
3
|
+
*
|
|
4
|
+
* THE FUNCTION EXISTED, WAS TESTED, AND WAS UNREACHABLE.
|
|
5
|
+
*
|
|
6
|
+
* `lib/learning/skill-writer.mjs` quarantines every auto-authored skill into
|
|
7
|
+
* `plugins/agent-skills/.pending/` and says, in its own docblock, that nothing
|
|
8
|
+
* loads it "until an operator runs approveSkill()". `approveSkill` is defined at
|
|
9
|
+
* :412, exported at :463, and covered by passing tests — and had NO non-test
|
|
10
|
+
* caller anywhere in the SDK. No CLI command, no MCP tool, no daemon path. The
|
|
11
|
+
* operator gate it describes was not exposed to any operator.
|
|
12
|
+
*
|
|
13
|
+
* Measured on two seats independently. One: 767 skills authored, 0 ever
|
|
14
|
+
* promoted. A second, 37 days old: 149 pending skills (596 KB), 18 live, and an
|
|
15
|
+
* audit log reading create 178, pending_review 178, **approve 0**. And because
|
|
16
|
+
* nothing is ever promoted, the recurring procedures FORK rather than strengthen
|
|
17
|
+
* — `publish-agent-sdk-and-verify-fleet-rollout` authored 25 separate times,
|
|
18
|
+
* `validate-empty-results-with-positive-control` 16, `maestro-morning-brief` 11.
|
|
19
|
+
* Every one of those is a sonnet-class authoring call for a file that is never
|
|
20
|
+
* loaded.
|
|
21
|
+
*
|
|
22
|
+
* This module is the missing surface and nothing more. It does NOT decide when a
|
|
23
|
+
* skill should be promoted: recurrence-gated auto-promotion is a policy question
|
|
24
|
+
* with a threshold someone has to choose, and inventing one here would be
|
|
25
|
+
* answering a product question with a default nobody picked. What it does is make
|
|
26
|
+
* the existing gate openable, and make the duplication visible — `list` reports
|
|
27
|
+
* how many times each pending skill has been authored, because a skill written
|
|
28
|
+
* 25 times is the argument for whatever policy follows.
|
|
29
|
+
*
|
|
30
|
+
* @module lib/cli/skills
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
|
|
34
|
+
import { join } from "node:path";
|
|
35
|
+
|
|
36
|
+
import { approveSkill, pendingDir, skillsDir } from "../learning/skill-writer.mjs";
|
|
37
|
+
|
|
38
|
+
export const USAGE = `Usage:
|
|
39
|
+
maestro skills list [--json] Pending skills, with how often each was re-authored
|
|
40
|
+
maestro skills show <id> Print a pending skill
|
|
41
|
+
maestro skills approve <id> [--by who] Promote it into skills/ so Claude Code loads it
|
|
42
|
+
`;
|
|
43
|
+
|
|
44
|
+
function root(o = {}) {
|
|
45
|
+
return o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** First `description:` line of a skill's frontmatter, or "". */
|
|
49
|
+
function describe(path) {
|
|
50
|
+
try { return (readFileSync(path, "utf8").match(/^description:\s*(.*)$/m) || [, ""])[1].trim(); }
|
|
51
|
+
catch { return ""; }
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* How many times each id has been AUTHORED, from the audit ledger.
|
|
56
|
+
*
|
|
57
|
+
* This is the number that makes the case: an id with a count above one was
|
|
58
|
+
* written again because the first copy was never loaded, so the loop paid for
|
|
59
|
+
* the same procedure repeatedly and kept none of it.
|
|
60
|
+
*
|
|
61
|
+
* @param {string} agentRoot
|
|
62
|
+
* @returns {{creates: Map<string,number>, approves: number}}
|
|
63
|
+
*/
|
|
64
|
+
export function authoringCounts(agentRoot) {
|
|
65
|
+
const creates = new Map();
|
|
66
|
+
let approves = 0;
|
|
67
|
+
const path = join(agentRoot, "logs", "audit", "skills.jsonl");
|
|
68
|
+
if (!existsSync(path)) return { creates, approves };
|
|
69
|
+
let text = "";
|
|
70
|
+
try { text = readFileSync(path, "utf8"); } catch { return { creates, approves }; }
|
|
71
|
+
for (const line of text.split("\n")) {
|
|
72
|
+
if (!line.trim()) continue;
|
|
73
|
+
let row;
|
|
74
|
+
try { row = JSON.parse(line); } catch { continue; }
|
|
75
|
+
const id = String((row && row.id) || "").trim();
|
|
76
|
+
if (row && row.action === "create" && id) creates.set(id, (creates.get(id) || 0) + 1);
|
|
77
|
+
if (row && row.action === "approve") approves += 1;
|
|
78
|
+
}
|
|
79
|
+
return { creates, approves };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The procedure a pending id belongs to, with the fork suffixes stripped.
|
|
84
|
+
*
|
|
85
|
+
* THE AUDIT LEDGER CANNOT SEE THE DUPLICATION, which is a large part of why this
|
|
86
|
+
* went unnoticed for 767 skills. A patch of a pending skill downgrades to a NEW
|
|
87
|
+
* numbered create, so every fork is logged under its own fresh id and the
|
|
88
|
+
* per-id `create` count is 1 for almost all of them. Measured on one seat: the
|
|
89
|
+
* ledger showed a single id authored more than once, while grouping by family
|
|
90
|
+
* showed 150 files across 33 procedures — 117 redundant copies, one procedure
|
|
91
|
+
* forked 31 times. The counter that was supposed to reveal the waste reported
|
|
92
|
+
* almost none of it.
|
|
93
|
+
*
|
|
94
|
+
* So the family is the unit, not the id. Suffixes seen in the wild stack:
|
|
95
|
+
* `-3`, `-3-2`, `-3-2-2` is a patch of a patch of a patch.
|
|
96
|
+
*
|
|
97
|
+
* @param {string} id
|
|
98
|
+
* @returns {string}
|
|
99
|
+
*/
|
|
100
|
+
export function skillFamily(id) {
|
|
101
|
+
return String(id || "").replace(/(-\d+)+$/, "");
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Pending skills, newest first, each with its authoring count.
|
|
106
|
+
* @param {{agentRoot?:string}} [o]
|
|
107
|
+
*/
|
|
108
|
+
export function listPending(o = {}) {
|
|
109
|
+
const agentRoot = root(o);
|
|
110
|
+
const dir = pendingDir(agentRoot);
|
|
111
|
+
const { creates, approves } = authoringCounts(agentRoot);
|
|
112
|
+
if (!existsSync(dir)) return { ok: true, pending: [], live: 0, approves };
|
|
113
|
+
const rows = [];
|
|
114
|
+
for (const name of readdirSync(dir)) {
|
|
115
|
+
if (!name.endsWith(".md")) continue;
|
|
116
|
+
const id = name.slice(0, -3);
|
|
117
|
+
const p = join(dir, name);
|
|
118
|
+
let mtime = 0;
|
|
119
|
+
try { mtime = statSync(p).mtimeMs; } catch { /* ignore */ }
|
|
120
|
+
rows.push({ id, description: describe(p), authored: creates.get(id) || 1, mtimeMs: mtime });
|
|
121
|
+
}
|
|
122
|
+
rows.sort((a, b) => b.mtimeMs - a.mtimeMs);
|
|
123
|
+
// Family counts: the id-keyed ledger misses the forking entirely (see
|
|
124
|
+
// skillFamily), so this is computed from the files on disk.
|
|
125
|
+
const families = new Map();
|
|
126
|
+
for (const r of rows) {
|
|
127
|
+
r.family = skillFamily(r.id);
|
|
128
|
+
families.set(r.family, (families.get(r.family) || 0) + 1);
|
|
129
|
+
}
|
|
130
|
+
for (const r of rows) r.copies = families.get(r.family) || 1;
|
|
131
|
+
let live = 0;
|
|
132
|
+
try { live = readdirSync(skillsDir(agentRoot)).filter((n) => n.endsWith(".md")).length; }
|
|
133
|
+
catch { live = 0; }
|
|
134
|
+
const forked = [...families.entries()].filter(([, n]) => n > 1).sort((a, b) => b[1] - a[1]);
|
|
135
|
+
const wasted = forked.reduce((sum, [, n]) => sum + (n - 1), 0);
|
|
136
|
+
return { ok: true, pending: rows, live, approves, procedures: families.size, forked, wasted };
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Run `maestro skills …`. Prints a human table or JSON; returns the exit code.
|
|
141
|
+
* @param {string[]} argv
|
|
142
|
+
* @param {{agentRoot?:string, stdout?:Function}} [deps]
|
|
143
|
+
* @returns {Promise<number>}
|
|
144
|
+
*/
|
|
145
|
+
export async function skillsCmd(argv = [], deps = {}) {
|
|
146
|
+
const write = deps.stdout || ((s) => process.stdout.write(s));
|
|
147
|
+
const agentRoot = root(deps);
|
|
148
|
+
const [sub, ...rest] = argv;
|
|
149
|
+
const json = rest.includes("--json") || argv.includes("--json");
|
|
150
|
+
|
|
151
|
+
if (!sub || sub === "--help" || sub === "-h") { write(USAGE); return 0; }
|
|
152
|
+
|
|
153
|
+
if (sub === "list") {
|
|
154
|
+
const r = listPending({ agentRoot });
|
|
155
|
+
if (json) { write(`${JSON.stringify(r, null, 2)}\n`); return 0; }
|
|
156
|
+
if (!r.pending.length) { write(`No pending skills. ${r.live} live.\n`); return 0; }
|
|
157
|
+
write(`${r.pending.length} pending files across ${r.procedures} distinct procedures, ${r.live} live, ${r.approves} ever approved.\n`);
|
|
158
|
+
if (r.wasted) write(`${r.wasted} of those files are redundant copies of a procedure already written.\n`);
|
|
159
|
+
write("\n");
|
|
160
|
+
for (const p of r.pending.slice(0, 40)) {
|
|
161
|
+
const n = p.authored > 1 ? ` (authored ${p.authored}x)` : "";
|
|
162
|
+
write(` ${p.id}${n}\n${p.description ? ` ${p.description.slice(0, 96)}\n` : ""}`);
|
|
163
|
+
}
|
|
164
|
+
if (r.pending.length > 40) write(` … and ${r.pending.length - 40} more (--json for all)\n`);
|
|
165
|
+
if (r.forked.length) {
|
|
166
|
+
// The waste, stated plainly: each copy is a separate authoring call for a
|
|
167
|
+
// procedure the seat already had and never loaded.
|
|
168
|
+
write(`\n${r.forked.length} procedures were written more than once — the loop paid for every copy and kept none:\n`);
|
|
169
|
+
for (const [family, n] of r.forked.slice(0, 8)) write(` ${String(n).padStart(3)} copies ${family}\n`);
|
|
170
|
+
}
|
|
171
|
+
if (r.approves === 0 && r.pending.length) {
|
|
172
|
+
write(`\nNothing has ever been approved on this seat. \`maestro skills approve <id>\` is the gate.\n`);
|
|
173
|
+
}
|
|
174
|
+
return 0;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
if (sub === "show") {
|
|
178
|
+
const id = rest.find((a) => !a.startsWith("--"));
|
|
179
|
+
if (!id) { write(USAGE); return 2; }
|
|
180
|
+
const p = join(pendingDir(agentRoot), `${id}.md`);
|
|
181
|
+
if (!existsSync(p)) { write(`not pending: ${id}\n`); return 1; }
|
|
182
|
+
write(readFileSync(p, "utf8"));
|
|
183
|
+
return 0;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
if (sub === "approve") {
|
|
187
|
+
const id = rest.find((a) => !a.startsWith("--"));
|
|
188
|
+
if (!id) { write(USAGE); return 2; }
|
|
189
|
+
const byIdx = rest.indexOf("--by");
|
|
190
|
+
const approvedBy = byIdx >= 0 ? rest[byIdx + 1] : undefined;
|
|
191
|
+
const r = approveSkill({ agentRoot, id, approvedBy });
|
|
192
|
+
write(`${JSON.stringify(r, null, 2)}\n`);
|
|
193
|
+
return r.ok ? 0 : 1;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
write(USAGE);
|
|
197
|
+
return 2;
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
export default { skillsCmd, listPending, authoringCounts, USAGE };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cohortapp/agent-sdk",
|
|
3
|
-
"version": "2.18.
|
|
3
|
+
"version": "2.18.36",
|
|
4
4
|
"description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|