@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.
- package/bin/maestro.mjs +10 -1
- package/docs/guides/billing-console-keys.md +16 -3
- package/lib/assurance/first-reply.mjs +31 -2
- package/lib/assurance/operator-plane-store.mjs +164 -0
- package/lib/assurance/operator-plane.mjs +689 -0
- package/lib/budget-guard.mjs +93 -3
- package/lib/cli/attention.mjs +300 -0
- package/lib/cli/seat-auth.mjs +86 -6
- package/lib/comms/receipts.mjs +15 -3
- package/lib/comms/send-gate.mjs +329 -2
- package/lib/org/awareness.mjs +15 -2
- package/lib/org/clause-match.mjs +470 -0
- package/lib/org/client.mjs +27 -1
- package/lib/org/escalation-chain.mjs +134 -0
- package/lib/org/first-run.mjs +263 -0
- package/lib/org/genesis-contract.mjs +271 -0
- package/lib/org/governance-runtime.mjs +409 -0
- package/lib/org/governance-store.mjs +238 -0
- package/lib/org/governance.mjs +326 -0
- package/lib/org/mesh.mjs +135 -0
- package/lib/org/protocol.checksum +1 -1
- package/lib/org/protocol.mjs +6 -0
- package/lib/org/registry.mjs +7 -1
- package/lib/org/tool-surface.mjs +28 -0
- package/lib/setup/enroll-from-cohort.mjs +11 -0
- package/lib/telemetry/alerts.mjs +86 -1
- package/lib/telemetry/collect.mjs +237 -1
- package/package.json +1 -1
- package/scripts/daemon/agent-daemon.mjs +41 -2
- package/scripts/daemon/assurance.mjs +482 -55
- package/scripts/daemon/cadence-consumer.mjs +17 -0
- package/scripts/daemon/context-compiler.mjs +25 -0
- package/scripts/daemon/deliver.mjs +71 -5
- package/scripts/fleet/closing-sweep.mjs +266 -0
- package/scripts/healthcheck.sh +35 -0
- package/scripts/local-triggers/autoupdate.sh +61 -5
- package/scripts/maintenance/check-stamp-freshness.mjs +314 -0
- package/scripts/org/send-orgmail.mjs +112 -25
- 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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
};
|