@cohortapp/agent-sdk 2.4.1 → 2.5.1

package/lib/org/protocol.mjs

@@ -55,6 +55,27 @@ export const FAMILIES = Object.freeze([
   // the Directory (2026-07): the canonical registry of external people and
   // organisations every other desk resolves its counterparties through.
   "directory",
+  // the sub-agent registry (2026-08): layer 1 of the SDK / workspace /
+  // agent-local resolution model — org-scoped, versioned sub-agent definitions
+  // pinned per seat. Governs the DISTRIBUTION and provenance of agent prose;
+  // resolution itself runs locally on the agent, never here.
+  "subagent",
+  // the agent's own control lane (2026-08): agent.wait, the bounded long-poll a
+  // daemon parks on instead of polling every 45s. Read-only — nothing in this
+  // family appends to the chain; it only READS the chain by seq.
+  "agent",
+  // the MANDATE spine (2026-08, SPEC "Three-Dimensional Agent Autonomy"): the
+  // objective tree, its KPI samples, the published per-seat mandate snapshot,
+  // and the agent's own capability/plan/drift reports. hq owns the MANDATE
+  // (outcomes, owners, targets, budgets, kill-switch); the agent owns the PLAN
+  // (obligations, schedule, rung) and compiles it locally. This family is the
+  // wire between the two halves.
+  "mandate",
+  // member-scoped PREFERENCES (2026-08, SPEC §9 reverse parity). hq has always
+  // injected these into responder context automatically; the family exists so a
+  // seat can PERSIST one it learned rather than re-deriving it every session.
+  // The chain rows carry subject + domain + key only — never the value.
+  "preference",
 ]);
 
 /**
@@ -131,6 +152,17 @@ export const SCOPES = Object.freeze([
   "directory.write", // Directory writes: create/update parties, channels, captures, links, lists. Structural verbs (merge execution, awareness change, archive) refuse an agent actor in-domain and create a review item instead
   "design.read",     // Design reads: the SAVED brand foundation snapshot (never a draft), voice, visible templates. Renders and voice rewrites are AUDITED side-effecting reads under this scope (files.exportRequest precedent)
   "design.write",    // Design writes: generate imagery, propose a foundation change. Foundation mutation itself is admin-only and human-gated -- a proposal creates a reviewable diff, it does not write
+  // mandate spine (2026-08). The read/propose/write split is the anti-Goodhart
+  // law expressed as scopes, and it deliberately mirrors approval.request vs
+  // approval.decide: an agent may READ its mandate and PROPOSE against it, but
+  // ADOPTING an objective (making it live, work-creating and graded) is a
+  // human/manager act the seat's own credential cannot perform.
+  "mandate.read",    // read own mandate snapshot + version + KPI series
+  "mandate.propose", // propose/update objectives — `state:'proposed'` ONLY, never an adopted row
+  "mandate.write",   // adopt / retire an objective. NOT in DEFAULT_AGENT_SCOPES — human/manager only
+  "kpi.write",       // report a KPI sample against an objective. Honesty is enforced by the
+                     //   server-set `source` field, never by scope: a seat may always report,
+                     //   but an `llm`-sourced number is advisory and cannot create work.
   "admin",           // pairing approval, deactivate (kill switch), governance, policy, credential put/revoke
 ]);
 
@@ -148,6 +180,11 @@ export const DEFAULT_AGENT_SCOPES = Object.freeze([
   "files.read", "files.write", "calendar.read", "calendar.write",
   "crm.read", "crm.write", "books.read", "books.write",
   "directory.read", "directory.write", "design.read", "design.write",
+  // mandate spine (2026-08): a seat reads its own mandate, proposes against it,
+  // and reports its own samples. `mandate.write` (adopt/retire) is POINTEDLY
+  // ABSENT — that is the whole anti-Goodhart law. A seat cannot define, measure
+  // AND be graded on the same number.
+  "mandate.read", "mandate.propose", "kpi.write",
 ]);
 
 /** Knowledge group scopes: org-wide, per-unit, or an information-barrier cell (deny-override). */
@@ -240,6 +277,13 @@ export const METHODS = Object.freeze({
   "messaging.react": { family: "messaging", scope: "messaging.write", sideEffecting: true },
   "messaging.edit": { family: "messaging", scope: "messaging.write", sideEffecting: true },
   "messaging.history": { family: "messaging", scope: "messaging.read", sideEffecting: false },
+  // --- messaging.search (2026-08 REVERSE PARITY, SPEC §9): the family carried
+  //     thirteen methods and no search, so an SDK-driven seat could not answer
+  //     "what did we decide about X anywhere?" while the hq responder in the
+  //     same workspace could (its `search_messages` tool). Postgres FTS across
+  //     every channel the paired member can read; the ACL floor is computed
+  //     server-side, so `channelId`/`channelSlug` narrow and can never widen. ---
+  "messaging.search": { family: "messaging", scope: "messaging.read", sideEffecting: false },
   // --- messaging.typing (2026-08): the "is composing…" indicator an agent raises
   //     while it works. The ONE write-less method in the family — it appends NO
   //     chain event and writes NO row, it publishes an EPHEMERAL frame that
@@ -357,6 +401,14 @@ export const METHODS = Object.freeze({
   "escalation.create": { family: "escalation", scope: "org.write", sideEffecting: true, idempotent: true },
   "escalation.resolve": { family: "escalation", scope: "org.write", sideEffecting: true },
   "escalation.list": { family: "escalation", scope: "org.read", sideEffecting: false },
+  // `OpenQuestion`'s FIRST WRITERS. The model has had readers and a UI for
+  // months with no producer, so a charter `escalationTrigger` firing could only
+  // ever emit prose. `ask` requires >= 2 concrete options (a one-option question
+  // is a notification, not a decision); `answer` is deliberately NOT idempotent
+  // — a second answer is a CONFLICT so the first decision stands — and refuses
+  // the asker, the same law as `Approval.requester ≠ approver`.
+  "escalation.ask": { family: "escalation", scope: "org.write", sideEffecting: true },
+  "escalation.answer": { family: "escalation", scope: "org.write", sideEffecting: true },
   // --- annotation ---
   "annotation.create": { family: "annotation", scope: "org.write", sideEffecting: true, idempotent: true },
   "annotation.comment": { family: "annotation", scope: "org.write", sideEffecting: true },
@@ -380,6 +432,26 @@ export const METHODS = Object.freeze({
   "memory.proposeAmendment": { family: "memory", scope: "knowledge.write", sideEffecting: true },
   "memory.mergeAmendment": { family: "memory", scope: "knowledge.write", sideEffecting: true },
   "memory.list": { family: "memory", scope: "knowledge.read", sideEffecting: false },
+  // --- memory.recall (2026-08 REVERSE PARITY, SPEC §9): layered semantic recall
+  //     over the unified agent memory, with the FULL contract the hq responder's
+  //     `recall_memory` tool has had since the agent-memory program shipped —
+  //     scope (org|self|channel) / refType+refId / time range / depth /
+  //     drill-down pointers. `knowledge.search` is a narrowed projection of this
+  //     (shared facts only, no controls), so until now an SDK seat reasoned off
+  //     a strictly smaller memory than the chat lane in the same workspace.
+  //     ACL is server-side off the paired member — fail-closed, never a param. ---
+  "memory.recall": { family: "memory", scope: "knowledge.read", sideEffecting: false },
+  // --- preference (2026-08 REVERSE PARITY, SPEC §9): there was NO preference.*
+  //     family at all. An SDK agent could LEARN a durable member-scoped fact and
+  //     had nowhere to put it, while the hq responder's `remember_preference`
+  //     wrote straight into PreferenceMemory — which hq then injects into every
+  //     future conversation. Same workspace, two memories. `upsert` converges on
+  //     one row per (subject, domain, key) and REQUIRES evidence; the chain
+  //     append carries whose/which-key and never the value (a preference value
+  //     is content). `list` ships with it because a write-only family is not
+  //     parity: hq SEES injected preferences for free, a seat has to ask. ---
+  "preference.upsert": { family: "preference", scope: "org.write", sideEffecting: true, idempotent: true },
+  "preference.list": { family: "preference", scope: "org.read", sideEffecting: false },
   // --- compact ---
   "compact.upsert": { family: "compact", scope: "org.write", sideEffecting: true, idempotent: true },
   // --- notification ---
@@ -775,8 +847,124 @@ export const METHODS = Object.freeze({
   "files.comments": { family: "files", scope: "files.read", sideEffecting: false },
   "files.sheetFedRange": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
   "files.ask": { family: "files", scope: "files.read", sideEffecting: false },
+  // --- subagent (2026-08): the org-scoped sub-agent registry. NO NEW SCOPES —
+  //     a sub-agent definition is org-structural authored content exactly like
+  //     a persona, an SOP or an annotation, which is what `org.write` covers,
+  //     and both org.read/org.write are already in DEFAULT_AGENT_SCOPES.
+  //     Curation (`yank`) is admin, like every other destructive verb.
+  //
+  //     `resolve` is the EXPENSIVE read (bodies + provenance + rewire hints);
+  //     the cheap poll is the `subagent.roster` GET in READS, which returns
+  //     {slug, definitionId, version, contentHash} and no bodies. Naming a
+  //     memberId other than the caller's own seat requires `admin` — enforced
+  //     in-domain (methods/subagent/_shared.ts), the invokeTool doctrine. ---
+  "subagent.list": { family: "subagent", scope: "org.read", sideEffecting: false },
+  "subagent.get": { family: "subagent", scope: "org.read", sideEffecting: false },
+  "subagent.resolve": { family: "subagent", scope: "org.read", sideEffecting: false },
+  "subagent.create": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.publishVersion": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.fork": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.pin": { family: "subagent", scope: "org.write", sideEffecting: true, idempotent: true },
+  "subagent.unpin": { family: "subagent", scope: "org.write", sideEffecting: true },
+  "subagent.yank": { family: "subagent", scope: "admin", sideEffecting: true },
+  // --- agent control lane (2026-08): the bounded long-poll a daemon parks on so
+  //     it learns about its own work in ~0s instead of on a 45s poll cadence.
+  //     Modelled on the `approval.wait` precedent (READS, a held request), but
+  //     registered here as a POST method because it takes a CURSOR + a page of
+  //     structured results, which is the METHODS shape — and because a held GET
+  //     is far more likely to be cached/coalesced by an intermediary.
+  //
+  //     NO NEW SCOPE. `org.read` is the floor to call it at all (it is in
+  //     DEFAULT_AGENT_SCOPES, so every paired agent can park), and each LANE it
+  //     reports on is gated separately in-domain against the key's own scopes
+  //     (messaging.read / board.read / email.read) — a key minted without
+  //     email.read is never told that mail arrived. sideEffecting:false: it
+  //     appends NOTHING to the chain, it only reads the chain by seq. ---
+  "agent.wait": { family: "agent", scope: "org.read", sideEffecting: false },
+  // --- mandate (2026-08): the MANDATE half of the mandate/plan split. hq is
+  //     authoritative for WHAT the outcomes are; the agent compiles the plan.
+  //
+  //     The scope split is the design: `mandate.read`/`mandate.propose`/
+  //     `kpi.write` are in DEFAULT_AGENT_SCOPES, `mandate.write` is not.
+  //     `adopt`/`retire` are ALSO governanceGated — the decision-rights matrix
+  //     must exist before a seat can be handed a live, graded objective, the
+  //     same ordering rule that gates board.assign and handoff.*.
+  //
+  //     `declareCapability`/`publishPlan`/`reportDrift` reuse `registry.write`:
+  //     they are a seat reporting facts about ITSELF, exactly like
+  //     registry.register, and every paired agent already holds it. ---
+  "mandate.get": { family: "mandate", scope: "mandate.read", sideEffecting: false },
+  "mandate.version": { family: "mandate", scope: "mandate.read", sideEffecting: false },
+  "mandate.tree": { family: "mandate", scope: "org.read", sideEffecting: false },
+  "mandate.series": { family: "mandate", scope: "mandate.read", sideEffecting: false },
+  "mandate.propose": { family: "mandate", scope: "mandate.propose", sideEffecting: true, idempotent: true },
+  "mandate.adopt": { family: "mandate", scope: "mandate.write", sideEffecting: true, governanceGated: true },
+  "mandate.retire": { family: "mandate", scope: "mandate.write", sideEffecting: true, governanceGated: true },
+  "mandate.sample": { family: "mandate", scope: "kpi.write", sideEffecting: true, idempotent: true },
+  "mandate.declareCapability": { family: "mandate", scope: "registry.write", sideEffecting: true, idempotent: true },
+  "mandate.publishPlan": { family: "mandate", scope: "registry.write", sideEffecting: true, idempotent: true },
+  "mandate.reportDrift": { family: "mandate", scope: "registry.write", sideEffecting: true },
+  // --- board review lane (2026-08 consensus fix): `Task.reviewerId` has existed
+  //     since T19 and had NO writer on the agent plane, so "send it for review"
+  //     was unreachable from a daemon and every review round-trip degraded to a
+  //     comment. These two methods are the writer. ---
+  "board.requestReview": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.resolveReview": { family: "board", scope: "board.write", sideEffecting: true },
+  // --- escalation as a QUESTION (2026-08): `OpenQuestion` shipped with readers
+  //     and no writer at all. `escalation.ask` is its first one. The difference
+  //     from `escalation.create` matters: an Escalation is "a human is needed
+  //     here"; an OpenQuestion is "here are 2-3 concrete options, pick one",
+  //     which is what a Charter.escalationTriggers hit should actually produce. ---
+  // NOTE: `escalation.ask` / `escalation.answer` (raise an OpenQuestion with
+  // concrete options, and the human picking one) are deliberately NOT registered
+  // yet — `ask` needs a `_question` projector that is not written. A METHODS
+  // entry with no working handler is not a placeholder, it is a live promise the
+  // dispatcher cannot keep: the protocol advertises the method, the caller gets
+  // through scope resolution, and the call 500s. Register each in the same
+  // change that lands its handler.
+  // NOTE: `escalation.answer` (the human picking one of the offered options) is
+  // deliberately NOT registered yet — its handler is not written. A METHODS
+  // entry with no handler file is not a placeholder, it is a live promise the
+  // dispatcher cannot keep: the protocol advertises the method, callers get
+  // through scope resolution, and the call 500s. Register it in the same change
+  // that adds src/server/methods/escalation/answer.ts.
 });
 
+/**
+ * The ONE action-class table (SPEC §8 "Approvals"). Replaces maestro's local
+ * `GATED_CLASSES` and hq's free-form `Approval.actionClass` strings with a
+ * shared vocabulary both sides validate against.
+ *
+ * `GATED_ACTION_CLASSES` is the blast-radius gate: an action in one of these
+ * classes forces an approval BEFORE any execution rung runs, at every rung.
+ * @type {readonly string[]}
+ */
+export const ACTION_CLASSES = Object.freeze([
+  "internal",     // stays inside the workspace; reversible; no spend
+  "external",     // leaves the org (email to a third party, a public post)
+  "irreversible", // cannot be undone by a subsequent method call
+  "financial",    // moves money or commits spend
+]);
+
+/** Action classes that force a human approval before execution. */
+export const GATED_ACTION_CLASSES = Object.freeze(["external", "irreversible", "financial"]);
+
+/**
+ * PlanDrift kinds — the reconciler's vocabulary for "the plan and the world
+ * disagree". Shared so hq can index/report on them without string drift.
+ * @type {readonly string[]}
+ */
+export const DRIFT_KINDS = Object.freeze([
+  "uncovered_event",        // a directed event matched no REACT obligation
+  "unreachable_capability", // an obligation cites a capability that failed its probe
+  "stale_sensor",           // no sample within 2x the objective's cadence
+  "schedule_missing",       // a SCHEDULE obligation has no launchd trigger on disk
+  "kpi_gap",                // measured value is outside tolerance of target
+  "budget_breach",          // an obligation exhausted its envelope
+  "orphan_work",            // open work with no objective behind it
+  "mandate_stale",          // the cached mandate aged past the staleness ladder
+]);
+
 /**
  * Is a method refused until the org server is `governance_ready` (decision_rights
  * populated AND signing live)? A partially deployed control plane is worse than
@@ -806,6 +994,12 @@ export const READS = Object.freeze({
   // phase 4 reads
   "contacts.list": "knowledge.read",   // org contacts registry (ACL-filtered)
   "meetings.list": "knowledge.read",   // org meetings registry (ACL-filtered)
+  // sub-agent registry (2026-08): the CHEAP roster poll. Returns the bare
+  // {rosterVersion, entries:[{slug, definitionId, version, contentHash}]} — no
+  // bodies — so a seat can diff its `.maestro/subagents.lock.json` on every
+  // beat without paying for prose. `subagent.resolve` (METHODS) is the
+  // expensive twin that carries bodies.
+  "subagent.roster": "org.read",
 });
 
 /** Error codes (the error contract; HTTP status hints are advisory). */
@@ -822,8 +1016,26 @@ export const ERROR_CODES = Object.freeze({
   INTERNAL: { http: 500 },
 });
 
-/** Directive kinds the presence.beat response may carry (kill-switch + nudges). */
-export const DIRECTIVES = Object.freeze(["halt", "rotate_token", "policy_stale", "resync"]);
+/**
+ * Directive kinds the presence.beat response may carry (kill-switch + nudges).
+ *
+ * Levels 1-3 of the four-level kill-switch (SPEC §8) live here and are
+ * COOPERATIVE: they only work while the daemon is healthy enough to beat and
+ * honest enough to obey. Level 4 — `credential.revoke` + API-key disable — is
+ * the only control that works against a wedged or compromised laptop. Say that
+ * out loud rather than implying the beat is a hard stop.
+ */
+export const DIRECTIVES = Object.freeze([
+  "halt",            // stop entirely. hq ALSO closes the SSE lane (`event: bye`) so a
+                     //   daemon that stopped beating stops receiving work to do.
+  "rotate_token",
+  "policy_stale",
+  "resync",
+  // --- mandate spine (2026-08) ---
+  "pause_schedules", // stop INITIATING (Loop B + Loop C); keep answering when addressed
+  "plan_stale",      // the seat's mandate moved — refetch `mandate.get` and recompile
+  "revoke_scope",    // a scope was withdrawn; drop it locally and re-probe capabilities
+]);
 
 // ---------------------------------------------------------------------------
 // Helpers (shared, pure)

package/lib/org/protocol.test.mjs

@@ -131,7 +131,10 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // from the UI-parity "file" pins/comments family), and directory (external
   // people + organisations; the Design half of that program rides the existing
   // `branding` family — the section is renamed, the wire name is not).
-  assert.equal(FAMILIES.length, 47, "family count");
+  // The 2026-08 protocol-convergence pass adds 4: subagent (the org-scoped
+  // sub-agent registry), agent (the agent.wait control lane), mandate (the
+  // MANDATE spine) and preference (member-scoped preferences) → 51.
+  assert.equal(FAMILIES.length, 51, "family count");
   // 357 = the mesh-protocol + agent UI-parity + calling + branding + email
   // methods, plus the Live Integrations surface: integration.toolsetVersion +
   // integration.listAgentTools (SP1) and integration.invokeTool (SP5, execute a
@@ -160,8 +163,14 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // "is composing…" indicator an SDK-driven agent raises while it works —
   // sideEffecting:false, no chain event, expires client-side) → 431.
   // Bumped deliberately alongside
+  // The 2026-08 protocol-convergence pass closes the 29-method gap against hq's
+  // vendored table (the client rejected every one of them BEFORE the network,
+  // so mandate.* et al were unreachable from a daemon): messaging.search,
+  // escalation.ask/answer, memory.recall, preference.upsert/list (6 reverse-
+  // parity methods), the 9 subagent.* registry methods, agent.wait, the 11
+  // mandate.* spine methods, and board.requestReview/resolveReview → 460.
   // the descriptors; the checksum (read at runtime) is the primary drift guard.
-  assert.equal(Object.keys(METHODS).length, 431, "method count");
+  assert.equal(Object.keys(METHODS).length, 460, "method count");
 });
 
 test("protocol SP3: messaging + calling families/methods/scopes", async () => {