@cohortapp/agent-sdk 2.18.33 → 2.18.35

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 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":
@@ -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 };
@@ -181,16 +181,38 @@ function baseHeaders(token, orgId) {
181
181
  */
182
182
  async function httpRequest(fetchImpl, url, init, timeoutMs = DEFAULT_TIMEOUT_MS) {
183
183
  const f = pickFetch(fetchImpl);
184
- if (!f) return { ok: false, status: 0, body: null };
184
+ if (!f) return { ok: false, status: 0, body: null, failure: "no-fetch" };
185
185
  const ctrl = typeof AbortController === "function" ? new AbortController() : null;
186
- const timer = ctrl ? setTimeout(() => ctrl.abort(), timeoutMs) : null;
186
+ let timedOut = false;
187
+ const timer = ctrl ? setTimeout(() => { timedOut = true; ctrl.abort(); }, timeoutMs) : null;
187
188
  try {
188
189
  const res = await f(url, { ...init, signal: ctrl ? ctrl.signal : undefined });
189
190
  let body = null;
190
191
  try { body = await res.json(); } catch { body = null; }
191
192
  return { ok: !!res.ok, status: typeof res.status === "number" ? res.status : 0, body };
192
- } catch {
193
- return { ok: false, status: 0, body: null };
193
+ } catch (err) {
194
+ // A TIMEOUT AND A BROKEN SOCKET ARE NOT THE SAME FACT, AND THIS DISCARDED BOTH.
195
+ //
196
+ // `catch { }` returned a bare `status: 0`, which `asResFrame` renders as
197
+ // "http 0". A seat then sees "http 0" and cannot tell an abort from a DNS
198
+ // failure, a reset, or a missing origin — so the one piece of information
199
+ // that names the cause was thrown away at the only place that had it.
200
+ //
201
+ // Measured consequence: a seat's `messaging.history` returned at `limit: 3`
202
+ // and failed with "http 0" at normal page sizes, which reads as a transport
203
+ // or payload fault. It is neither — it is this 8s abort firing on a slower
204
+ // query, and the seat missed two hours of inbound while diagnosing the wrong
205
+ // layer. Its sends were landing the whole time, so it looked healthy.
206
+ return {
207
+ ok: false,
208
+ status: 0,
209
+ body: null,
210
+ failure: timedOut ? "timeout" : "transport",
211
+ timeoutMs: timedOut ? timeoutMs : undefined,
212
+ // `code` before `name`: ENOTFOUND/ECONNRESET identify the fault, while
213
+ // `name` is almost always the useless "Error".
214
+ cause: (err && (err.code || err.name)) || "unknown",
215
+ };
194
216
  } finally {
195
217
  if (timer) clearTimeout(timer);
196
218
  }
@@ -220,6 +242,19 @@ function asResFrame(r) {
220
242
  const b = r.body;
221
243
  if (b && typeof b === "object" && typeof b.ok === "boolean") return b; // already a frame
222
244
  if (r.ok) return okFrame(b);
245
+ if (r && r.status === 0 && r.failure === "timeout") {
246
+ // Named, with the budget, so the reader knows what to change.
247
+ // INTERNAL, not a new "TIMEOUT" code, deliberately. ERROR_CODES is the
248
+ // SHARED wire vocabulary (each entry carries an http mapping, so hq reads it
249
+ // too) and errFrame silently degrades an unknown code to INTERNAL — so
250
+ // writing "TIMEOUT" here would have looked like a new code and quietly been
251
+ // INTERNAL anyway, which is the same class of lie this whole change removes.
252
+ // The cause goes in the MESSAGE, which is what a person actually reads.
253
+ return errFrame("INTERNAL", `request timed out after ${r.timeoutMs}ms before any HTTP status — raise timeoutMs for this call, or ask for fewer rows`);
254
+ }
255
+ if (r && r.status === 0 && r.failure) {
256
+ return errFrame("INTERNAL", `transport failed before any HTTP status (${r.cause}) — not an HTTP error`);
257
+ }
223
258
  return errFrame(httpStatusToCode(r.status), `http ${r.status}`);
224
259
  }
225
260
 
@@ -333,11 +368,19 @@ export async function call(method, params, o = {}) {
333
368
  : "");
334
369
  if (key) headers["x-idempotency-key"] = String(key);
335
370
  }
371
+ // THE POST PATH HAD NO TUNABLE TIMEOUT WHILE THE GET PATH DID.
372
+ //
373
+ // This called httpRequest with no fourth argument, so every RPC — including a
374
+ // history read over a busy channel — sat under the same hard 8s ceiling with no
375
+ // way for a caller to ask for more, even though the read helper below already
376
+ // honours `o.timeoutMs`. That asymmetry is the defect; the default is unchanged
377
+ // so nothing moves for callers that do not ask.
378
+ const callTimeoutMs = Number.isFinite(o.timeoutMs) && o.timeoutMs > 0 ? o.timeoutMs : DEFAULT_TIMEOUT_MS;
336
379
  const r = await httpRequest(o.fetchImpl, v1Url(base, method), {
337
380
  method: "POST",
338
381
  headers,
339
382
  body: JSON.stringify(wire),
340
- });
383
+ }, callTimeoutMs);
341
384
  return asResFrame(r);
342
385
  }
343
386
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cohortapp/agent-sdk",
3
- "version": "2.18.33",
3
+ "version": "2.18.35",
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": {