@cohortapp/agent-sdk 2.18.37 → 2.19.1

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.
Files changed (39) hide show
  1. package/bin/maestro.mjs +10 -1
  2. package/docs/guides/billing-console-keys.md +16 -3
  3. package/lib/assurance/first-reply.mjs +31 -2
  4. package/lib/assurance/operator-plane-store.mjs +164 -0
  5. package/lib/assurance/operator-plane.mjs +689 -0
  6. package/lib/budget-guard.mjs +93 -3
  7. package/lib/cli/attention.mjs +300 -0
  8. package/lib/cli/seat-auth.mjs +86 -6
  9. package/lib/comms/receipts.mjs +15 -3
  10. package/lib/comms/send-gate.mjs +329 -2
  11. package/lib/org/awareness.mjs +15 -2
  12. package/lib/org/clause-match.mjs +470 -0
  13. package/lib/org/client.mjs +27 -1
  14. package/lib/org/escalation-chain.mjs +134 -0
  15. package/lib/org/first-run.mjs +263 -0
  16. package/lib/org/genesis-contract.mjs +271 -0
  17. package/lib/org/governance-runtime.mjs +409 -0
  18. package/lib/org/governance-store.mjs +238 -0
  19. package/lib/org/governance.mjs +326 -0
  20. package/lib/org/mesh.mjs +135 -0
  21. package/lib/org/protocol.checksum +1 -1
  22. package/lib/org/protocol.mjs +6 -0
  23. package/lib/org/registry.mjs +7 -1
  24. package/lib/org/tool-surface.mjs +28 -0
  25. package/lib/setup/enroll-from-cohort.mjs +11 -0
  26. package/lib/telemetry/alerts.mjs +86 -1
  27. package/lib/telemetry/collect.mjs +237 -1
  28. package/package.json +1 -1
  29. package/scripts/daemon/agent-daemon.mjs +41 -2
  30. package/scripts/daemon/assurance.mjs +482 -55
  31. package/scripts/daemon/cadence-consumer.mjs +17 -0
  32. package/scripts/daemon/context-compiler.mjs +25 -0
  33. package/scripts/daemon/deliver.mjs +71 -5
  34. package/scripts/fleet/closing-sweep.mjs +266 -0
  35. package/scripts/healthcheck.sh +35 -0
  36. package/scripts/local-triggers/autoupdate.sh +61 -5
  37. package/scripts/maintenance/check-stamp-freshness.mjs +314 -0
  38. package/scripts/org/send-orgmail.mjs +112 -25
  39. package/scripts/session/supervisor.mjs +14 -0
package/bin/maestro.mjs CHANGED
@@ -266,7 +266,13 @@ function create(targetName) {
266
266
 
267
267
  log("Generating operational templates...");
268
268
 
269
- // Queue templates — 16 operational queues
269
+ // Queue templates — 16 operational queues.
270
+ //
271
+ // A queue added here is a new machine-internal name, so it must also be named
272
+ // by the `queue-file` rule in lib/comms/send-gate.mjs (MACHINE_LEAK_RULES) —
273
+ // lib/comms/fallback-leak-corpus.test.mjs fails if it is not. A new queue-ID
274
+ // prefix for it goes into `queue-item-id` and that corpus's DEDICATED cases in
275
+ // the same change (docs/engineering/functional-architecture.md §9).
270
276
  const queueTemplates = {
271
277
  "action-stack": "Active action items requiring attention or follow-through",
272
278
  "decision-queue": "Key decisions awaiting principal input or closure",
@@ -3941,6 +3947,7 @@ switch (command) {
3941
3947
  case "board": await (await import("../lib/cli/board.mjs")).boardCmd(args); break;
3942
3948
  case "design": await (await import("../lib/cli/design.mjs")).designCmd(args); break;
3943
3949
  case "skills": process.exitCode = await (await import("../lib/cli/skills.mjs")).skillsCmd(args); break;
3950
+ case "attention": process.exitCode = await (await import("../lib/cli/attention.mjs")).attentionCmd(args); break;
3944
3951
  case "run": process.exitCode = await (await import("../lib/engine/cli.mjs")).runFromProcess(args); break;
3945
3952
  case "init":
3946
3953
  case "update-init":
@@ -3972,6 +3979,8 @@ Usage:
3972
3979
  npx @cohortapp/agent-sdk seat-auth [--row|--fleet] Which Claude billing rail this seat is on (G4) — variable NAMES only, never a value
3973
3980
  npx @cohortapp/agent-sdk session <cmd> Front-door session: status|attach|start|stop|restart|spawn|peers|handoffs|ack
3974
3981
  npx @cohortapp/agent-sdk board mine|track|claim|complete Your work across every board (maestro board --help)
3982
+ npx @cohortapp/agent-sdk attention list|clusters|show Dead asks in the operator plane, grouped (maestro attention --help)
3983
+ npx @cohortapp/agent-sdk skills list|show|approve Pending auto-authored skills, and the approval gate
3975
3984
  npx @cohortapp/agent-sdk design sync [--out <dir>] Pull the brand foundation → DESIGN.md + PRODUCT.md
3976
3985
  npx @cohortapp/agent-sdk run -p "<prompt>" [flags] Cohort Engine, headless (cohort run --help)
3977
3986
 
@@ -105,9 +105,22 @@ only doctor still sees it.
105
105
 
106
106
  ### The fleet inventory
107
107
 
108
- A seat's environment lives on the seat's own machine. There is no remote
109
- inventory mechanism and this tooling does not invent one. So the fleet report is
110
- a **template plus paste-able rows**: run `maestro seat-auth --fleet` once (it
108
+ **Start from the beat, not from a tour.** Every seat's presence beat now carries
109
+ its verdict as `machine.seatAuth = { rail, compliant }`, from the first SDK
110
+ release that carries this change onward (it landed after 2.18.37; the release
111
+ line is the SDK owner's, so read `machine.sdkVersion` rather than trusting a
112
+ number written here). "Which seats are still on subscription OAuth" is therefore
113
+ a query against the fleet view, not sixteen SSH sessions — use it to pick the
114
+ seats worth visiting. Two limits to know. The beat carries the rail and a
115
+ boolean and **nothing** that could identify a credential: not the values, not a
116
+ mask, not a key id or its last four, not even the variable names. And a seat on
117
+ an older SDK sends no `seatAuth` field at all, which is "unknown", not "clean".
118
+ The same beat carries `machine.engine`, so an `engine: cohort` seat reading
119
+ `neither` is correct, not broken.
120
+
121
+ The rest of a seat's environment lives on the seat's own machine, and the
122
+ Console-side facts live in the Console. So the fleet report is still a
123
+ **template plus paste-able rows**: run `maestro seat-auth --fleet` once (it
111
124
  pre-fills one row per member from the org directory), then on each machine run
112
125
  `maestro seat-auth --row` and paste the line over that seat's row. The measured
113
126
  columns — seat, agent id, machine, verdict, which variable names are present,
@@ -467,10 +467,15 @@ export default {
467
467
  * arriving from a seat that has not upgraded yet must still be recognised long
468
468
  * after the local composer that produced it has changed.
469
469
  */
470
+ /** `assurance.composeSilentSuccess`'s head. FROZEN LITERAL, see above. */
471
+ const SILENT_SUCCESS_HEAD = /^finished this but didn'?t get a reply out to you\s*[—–-]\s*my fault\b/i;
472
+ /** `assurance.composeRefusedSend`'s head. FROZEN LITERAL, see above. */
473
+ const REFUSED_SEND_HEAD = /^couldn'?t get this out to you\s*[—–-]\s*the send was blocked\b/i;
474
+
470
475
  const STATUS_NOTICE_PATTERNS = Object.freeze([
471
476
  // composeSilentSuccess — the recovery notice, with or without an excerpt.
472
477
  // The excerpt is unbounded prose, so this anchors on the head alone.
473
- /^finished this but didn'?t get a reply out to you\s*[—–-]\s*my fault\b/i,
478
+ SILENT_SUCCESS_HEAD,
474
479
  // composeInterrupted.
475
480
  /^heads up\s*[—–-]\s*my session on this was interrupted\b/i,
476
481
  // notice-voice's generated failure/progress lines, which name the topic:
@@ -485,9 +490,33 @@ const STATUS_NOTICE_PATTERNS = Object.freeze([
485
490
  // precisely when an emitted notice was not recognisable to the seat receiving
486
491
  // it: the gate missed, the notice was dispatched as an ask, and the answering
487
492
  // seat's own rescue fired back.
488
- /^couldn'?t get this out to you\s*[\u2014\u2013-]\s*the send was blocked\b/i,
493
+ REFUSED_SEND_HEAD,
489
494
  ]);
490
495
 
496
+ /**
497
+ * Does this body OPEN as one of the two assurance rescue notices \u2014 the
498
+ * silent-success or the send-refused wrapper \u2014 whatever follows the head?
499
+ *
500
+ * THE OUTBOUND BACKSTOP for the late-reply fallback. Those two composers wrap a
501
+ * session's own end-of-turn text in a sentence that apologises for it, and the
502
+ * end-of-turn text is the session's report to the process that spawned it: its
503
+ * file paths, its queue ids, its "a concurrent session". `settleSession` no
504
+ * longer sends either wrapper to anyone (the text is held in the operator
505
+ * plane); `deliver()` refuses any body this returns true for, so a stale caller
506
+ * or a branch added later cannot put the wrapper back in a conversation.
507
+ *
508
+ * The OPENING paragraph only, on purpose: a real reply that quotes the phrase
509
+ * further down is not the wrapper.
510
+ *
511
+ * @param {unknown} body
512
+ * @returns {boolean}
513
+ */
514
+ export function opensAsRescueNotice(body) {
515
+ const head = normaliseLine(String(body == null ? "" : body).trim().split(/\n\s*\n/, 1)[0]);
516
+ if (!head) return false;
517
+ return SILENT_SUCCESS_HEAD.test(head) || REFUSED_SEND_HEAD.test(head);
518
+ }
519
+
491
520
  /**
492
521
  * Is this body a seat narrating its own work, rather than asking for any?
493
522
  *
@@ -0,0 +1,164 @@
1
+ /**
2
+ * lib/assurance/operator-plane-store.mjs — the operator plane's disk, read-only.
3
+ *
4
+ * The edge half of the reader. `operator-plane.mjs` is pure and decides what the
5
+ * rows MEAN; this file knows only where they are and how to not throw.
6
+ *
7
+ * WHY IT IS A MODULE OF ITS OWN AND NOT PART OF THE CLI. Two callers need the
8
+ * same join: `maestro attention` (a person asking) and `lib/telemetry/collect.mjs`
9
+ * (the presence beat, every 30 s, pushing a summary off the box). If the CLI
10
+ * owned the reading, the beat would grow a second copy of the paths and the two
11
+ * would drift — and a drifted path here does not fail, it reports an empty plane,
12
+ * which is indistinguishable from a healthy one. That is exactly the failure mode
13
+ * this subsystem keeps producing.
14
+ *
15
+ * NEVER THROWS, AND NEVER WRITES. A reader that can crash the presence beat is
16
+ * worse than a reader that reports less, and nothing in the operator plane is
17
+ * this module's to change: `mkdirSync` is deliberately absent, so reading a seat
18
+ * that has never failed does not create the directory it is looking for.
19
+ *
20
+ * @module lib/assurance/operator-plane-store
21
+ */
22
+
23
+ "use strict";
24
+
25
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
26
+ import { join } from "node:path";
27
+
28
+ import {
29
+ OPERATOR_PLANE_RETENTION_MS,
30
+ groupIncidents,
31
+ clusterIncidents,
32
+ summarisePlane,
33
+ } from "./operator-plane.mjs";
34
+
35
+ /** The agent root, by the same precedence `lib/cli/skills.mjs` uses. */
36
+ export function planeRoot(o = {}) {
37
+ return o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
38
+ }
39
+
40
+ /** The retention window this seat is actually running, env override included. */
41
+ export function planeWindowMs(env = process.env) {
42
+ const n = Number(env && env.ASSURANCE_RETENTION_MS);
43
+ return Number.isFinite(n) && n > 0 ? n : OPERATOR_PLANE_RETENTION_MS;
44
+ }
45
+
46
+ function obligationsDir(agentRoot) {
47
+ return join(agentRoot, "state", "obligations");
48
+ }
49
+
50
+ function readJson(path) {
51
+ try { return JSON.parse(readFileSync(path, "utf8")); }
52
+ catch { return null; }
53
+ }
54
+
55
+ /**
56
+ * `state/obligations/needs-attention/*.json` — one row per key, overwritten in
57
+ * place, never pruned in production before this change.
58
+ * @param {string} agentRoot
59
+ * @returns {object[]}
60
+ */
61
+ export function readNeedsAttention(agentRoot) {
62
+ const dir = join(obligationsDir(agentRoot), "needs-attention");
63
+ let names = [];
64
+ try { names = readdirSync(dir); } catch { return []; }
65
+ const out = [];
66
+ for (const name of names) {
67
+ if (!name.endsWith(".json")) continue;
68
+ const row = readJson(join(dir, name));
69
+ // A row whose `key` was lost is still evidence that something failed, so it
70
+ // is kept and named by its FILE — which is the sanitised key, and the only
71
+ // handle an operator has for it anyway.
72
+ if (row && typeof row === "object") out.push({ ...row, key: row.key || name.slice(0, -5), _file: name });
73
+ }
74
+ return out;
75
+ }
76
+
77
+ /**
78
+ * `state/obligations/notice-journal.jsonl` — append-only, the only ordered record.
79
+ *
80
+ * A corrupt line is SKIPPED rather than failing the read: this file is appended
81
+ * to by a daemon that may be killed mid-write, and losing one line is not a
82
+ * reason to report an empty plane.
83
+ *
84
+ * @param {string} agentRoot
85
+ * @returns {object[]}
86
+ */
87
+ export function readNoticeJournal(agentRoot) {
88
+ const path = join(obligationsDir(agentRoot), "notice-journal.jsonl");
89
+ let raw = "";
90
+ try { raw = readFileSync(path, "utf8"); } catch { return []; }
91
+ const out = [];
92
+ for (const line of raw.split("\n")) {
93
+ if (!line.trim()) continue;
94
+ try { const row = JSON.parse(line); if (row && typeof row === "object") out.push(row); }
95
+ catch { /* a torn append is one lost line, not an empty plane */ }
96
+ }
97
+ return out;
98
+ }
99
+
100
+ /**
101
+ * `state/obligations/*.json` — the join target, pruned at the retention window.
102
+ * The `needs-attention/` subdirectory and the journal are skipped by extension.
103
+ * @param {string} agentRoot
104
+ * @returns {object[]}
105
+ */
106
+ export function readObligationRecords(agentRoot) {
107
+ const dir = obligationsDir(agentRoot);
108
+ let names = [];
109
+ try { names = readdirSync(dir); } catch { return []; }
110
+ const out = [];
111
+ for (const name of names) {
112
+ if (!name.endsWith(".json")) continue;
113
+ const rec = readJson(join(dir, name));
114
+ if (rec && typeof rec === "object" && rec.key) out.push(rec);
115
+ }
116
+ return out;
117
+ }
118
+
119
+ /**
120
+ * Read all three sinks and hand them to the pure join.
121
+ *
122
+ * `now` is a parameter, not a read: the digest the beat publishes and the screen
123
+ * an operator sees must be able to describe the same instant, and a test must be
124
+ * able to describe any instant at all.
125
+ *
126
+ * @param {object} [o] {agentRoot, now, windowMs, env}
127
+ * @returns {{incidents:object[], clusters:object[], summary:object|null,
128
+ * counts:{rows:number, journal:number, records:number},
129
+ * windowMs:number, now:number, agentRoot:string}}
130
+ */
131
+ export function readOperatorPlane(o = {}) {
132
+ const agentRoot = planeRoot(o);
133
+ const now = Number.isFinite(o.now) ? Number(o.now) : Date.now();
134
+ const windowMs = Number.isFinite(o.windowMs) && o.windowMs > 0 ? Number(o.windowMs) : planeWindowMs(o.env);
135
+ const rows = readNeedsAttention(agentRoot);
136
+ const journal = readNoticeJournal(agentRoot);
137
+ const records = readObligationRecords(agentRoot);
138
+ const grouped = groupIncidents({ rows, journal, records, now, windowMs });
139
+ const clusters = clusterIncidents(grouped.incidents);
140
+ const summary = summarisePlane({
141
+ incidents: grouped.incidents,
142
+ date: new Date(now).toISOString().slice(0, 10),
143
+ });
144
+ return {
145
+ agentRoot,
146
+ now,
147
+ windowMs,
148
+ incidents: grouped.incidents,
149
+ causes: grouped.causes,
150
+ clusters,
151
+ summary,
152
+ counts: { rows: rows.length, journal: journal.length, records: records.length },
153
+ journalPresent: existsSync(join(obligationsDir(agentRoot), "notice-journal.jsonl")),
154
+ };
155
+ }
156
+
157
+ export default {
158
+ planeRoot,
159
+ planeWindowMs,
160
+ readNeedsAttention,
161
+ readNoticeJournal,
162
+ readObligationRecords,
163
+ readOperatorPlane,
164
+ };