@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/org/client.mjs

@@ -38,6 +38,7 @@ import {
   okFrame,
   errFrame,
 } from "./protocol.mjs";
+import { normalizeParams, logReportOnce, toRegisterParams } from "./param-contract.mjs";
 import { applyBrandEnvCompat } from "../env-compat.mjs";
 
 // SDK self-bridge: agent instances import this module directly from their own
@@ -63,13 +64,31 @@ const DEFAULT_TIMEOUT_MS = 8000;
  * @returns {object}
  */
 export function loadOrgConfig(agentRoot) {
+  const p = join(agentRoot, "config", "org.yaml");
+  // Genuinely absent is not a fault: an un-enrolled agent has no org.yaml.
+  if (!existsSync(p)) return {};
   try {
-    const p = join(agentRoot, "config", "org.yaml");
-    if (!existsSync(p)) return {};
     const require = createRequire(import.meta.url);
     const yaml = require("js-yaml");
     return yaml.load(readFileSync(p, "utf8")) || {};
-  } catch {
+  } catch (err) {
+    // The file EXISTS but could not be read/parsed. Returning {} silently here
+    // is how an enrolled agent ends up quietly un-enrolled: `isEnabled({})` is
+    // false, so the org mesh no-ops, the daemon logs nothing, and the agent
+    // never beats or receives the kill switch. Observed in the wild — the
+    // scaffold's package.json omitted `js-yaml`, so this require() threw on
+    // every freshly-created agent and the org integration was simply off.
+    //
+    // Still fail-open (callers depend on never throwing), but never silent.
+    const why = /Cannot find module 'js-yaml'/.test(String(err && err.message))
+      ? "js-yaml is not installed — run `npm install` (it is a required runtime dep)"
+      : String(err && err.message);
+    try {
+      console.warn(
+        `[org] config/org.yaml exists but could not be loaded (${why}). ` +
+        `Treating this agent as NOT enrolled — it will not join the org mesh.`,
+      );
+    } catch { /* never throw from logging */ }
     return {};
   }
 }
@@ -250,9 +269,18 @@ export async function pairRequest(o = {}) {
  * posts the params object, and returns the parsed res frame. Fail-open: a
  * transport error yields an INTERNAL error frame rather than throwing.
  *
+ * THE WIRE-CONTRACT CHOKEPOINT. Every plane reaches hq through this one function
+ * — the 2 090 `ui-parity.mjs` wrappers, the curated `tool-surface.mjs` table, the
+ * `org_rpc` escape hatch, and every hand-written helper in `lib/org/*.mjs` — so
+ * `normalizeParams` (lib/org/param-contract.mjs) runs HERE. That is what makes
+ * param-name drift a class of bug this SDK cannot ship again: a call site cannot
+ * opt out, and a newly added wrapper inherits the contract for free. The rewrite
+ * is reported once per distinct (method, rewrite) per process — fail-open, but
+ * NEVER silent (silent fail-open is what hid all 18 drift rows).
+ *
  * @param {string} method full dotted method name (e.g. "board.claim")
  * @param {object} params the params object (request body)
- * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl? }
+ * @param {object} o - { base, token, orgId?, idempotencyKey?, fetchImpl?, logImpl? }
  * @returns {Promise<object>} res frame
  */
 export async function call(method, params, o = {}) {
@@ -261,15 +289,45 @@ export async function call(method, params, o = {}) {
   const def = methodDef(method);
   if (!def) return errFrame("NOT_FOUND", `unknown method ${method}`);
 
+  // Project the caller's params onto the names hq's zod schemas actually read.
+  // Pure + total; a method with no contract entry passes through unchanged.
+  let wire = params || {};
+  try {
+    const report = normalizeParams(method, wire);
+    wire = report.params;
+    logReportOnce(method, report, o.logImpl);
+  } catch (err) {
+    // Fail-open, but NEVER SILENT. Every production bug in this system has been
+    // a quiet catch: the org mesh 401'd for hours without a line, the daemon
+    // read the wrong config file and logged "not configured", the inbound filter
+    // dropped six DMs saying nothing. If the param contract throws, the call
+    // still goes out with the RAW params — which is very likely the drift this
+    // module exists to correct — so the operator has to be told, or they debug a
+    // BAD_REQUEST with no idea the normaliser bailed.
+    try {
+      const log = typeof o.logImpl === "function" ? o.logImpl : console.warn;
+      log(
+        `[org] param contract failed for ${method} (${err && err.message}) — ` +
+          `sending RAW params; wire-name drift will NOT be corrected for this call`,
+      );
+    } catch { /* never throw from logging */ }
+  }
+
   const headers = baseHeaders(def.auth === false ? "" : token, def.auth === false ? "" : orgId);
   if (def.sideEffecting) {
-    const key = o.idempotencyKey || (def.idempotent ? defaultIdempotencyKey(method, params) : "");
+    // Key off the ORIGINAL params too: the contract may have renamed the id the
+    // legacy key derivation reads.
+    const key =
+      o.idempotencyKey ||
+      (def.idempotent
+        ? defaultIdempotencyKey(method, wire) || defaultIdempotencyKey(method, params)
+        : "");
     if (key) headers["x-idempotency-key"] = String(key);
   }
   const r = await httpRequest(o.fetchImpl, v1Url(base, method), {
     method: "POST",
     headers,
-    body: JSON.stringify(params || {}),
+    body: JSON.stringify(wire),
   });
   return asResFrame(r);
 }
@@ -553,6 +611,13 @@ export async function fetchHierarchy(o = {}) {
 
 /**
  * register self with the org (registry.register). Idempotent.
+ *
+ * Accepts EITHER a rich maestro self-entry (assembleSelfEntry shape) or an
+ * already-projected registerSchema params object: `call()` runs the wire contract
+ * (`toRegisterParams`) and hq's `.strict()` schema sees only
+ * {displayName, archetype, humanSponsor, card}. Passing the raw entry used to
+ * 400 on every boot while the caller logged success.
+ *
  * @param {object} entry directory entry (id, displayName, role, focus, pubkey…)
  * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
  */
@@ -1559,28 +1624,17 @@ export function brandingRestoreFoundation(params, o = {}) {
  * models { displayName, archetype:string, humanSponsor, card } — so we MUST trim
  * here or a rich entry 400s (BAD_REQUEST). Everything the server doesn't model is
  * preserved REDACTION-SAFE under `card` (the handler records only a `hasCard`
- * boolean on the chain, never the blob). Pure; never throws.
+ * boolean on the chain, never the blob).
+ *
+ * THE projection now lives in lib/org/param-contract (`toRegisterParams`) — the
+ * same table `call()` applies — so `client.register(rawEntry)` and
+ * `publishEntry({entry})` can no longer disagree about the shape. Re-exported
+ * under the historical name for the callers that already import it.
  * @param {object} entry
  * @returns {object} registerSchema-shaped params
  */
-function entryToRegisterParams(entry) {
-  const e = entry || {};
-  const displayName = e.fullName || e.name || e.displayName || String(e.id || "");
-  // archetype is an object in the maestro entry ({function,altitude,label}); the
-  // server wants a single string. Prefer the human label, then the function.
-  const arch = e.archetype;
-  const archetype =
-    typeof arch === "string"
-      ? arch
-      : (arch && (arch.label || arch.function || arch.altitude)) || "";
-  const humanSponsor =
-    (e.principal && (e.principal.fullName || e.principal.title)) || e.humanSponsor || "";
-  const params = { card: e };
-  if (displayName) params.displayName = String(displayName).slice(0, 200);
-  if (archetype) params.archetype = String(archetype).slice(0, 120);
-  if (humanSponsor) params.humanSponsor = String(humanSponsor).slice(0, 200);
-  return params;
-}
+const entryToRegisterParams = toRegisterParams;
+export { entryToRegisterParams };
 
 /**
  * Publish (upsert) this agent's directory entry — now via the /v1 binding

package/lib/org/client.test.mjs

@@ -8,9 +8,22 @@
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Run `fn` with console.warn captured; returns the captured lines. */
+function captureWarn(fn) {
+  const lines = [];
+  const real = console.warn;
+  console.warn = (...a) => { lines.push(a.join(" ")); };
+  try { fn(); } finally { console.warn = real; }
+  return lines;
+}
 
 import {
   isEnabled,
+  loadOrgConfig,
   configFromAgent,
   pairRequest,
   call,
@@ -862,7 +875,9 @@ test("knowledgeSearch: side-effecting (POST), Bearer set, posts the query body",
   assert.equal(f.calls[0].init.method, "POST");
   assert.equal(f.calls[0].url, `${BASE}/api/v1/knowledge.search`);
   assert.equal(f.calls[0].headers.authorization, `Bearer ${TOKEN}`);
-  assert.deepEqual(JSON.parse(f.calls[0].init.body), { query: "q", group: "org", limit: 5 });
+  // The wire contract canonicalises `query`→`q` (hq reads `p.q ?? p.query`) and
+  // keeps the legacy name alongside for an older server.
+  assert.deepEqual(JSON.parse(f.calls[0].init.body), { query: "q", q: "q", group: "org", limit: 5 });
   assert.deepEqual(frame.result.returned_ids, ["k-1"]);
 });
 
@@ -1105,3 +1120,41 @@ test("fetchHierarchy: GET /v1/hierarchy bare payload → {members,reporting}; nu
   const fail = fakeFetch(() => ({ ok: false, status: 503, body: { error: { code: "INTERNAL", message: "down" } } }));
   assert.equal(await fetchHierarchy({ base: BASE, token: TOKEN, orgId: "acme", fetchImpl: fail }), null);
 });
+
+// ---------------------------------------------------------------------------
+// loadOrgConfig — an enrolled agent must never go quietly un-enrolled
+// ---------------------------------------------------------------------------
+
+test("loadOrgConfig: absent org.yaml is silent (an un-enrolled agent is not a fault)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "orgcfg-"));
+  const warnings = captureWarn(() => {
+    assert.deepEqual(loadOrgConfig(dir), {});
+  });
+  assert.deepEqual(warnings, [], "no file, no noise");
+});
+
+test("loadOrgConfig: parses config/org.yaml", () => {
+  const dir = mkdtempSync(join(tmpdir(), "orgcfg-"));
+  mkdirSync(join(dir, "config"), { recursive: true });
+  writeFileSync(
+    join(dir, "config", "org.yaml"),
+    "org:\n  cohort:\n    enabled: true\n    base: https://os.example.com\n",
+  );
+  const cfg = loadOrgConfig(dir);
+  assert.equal(cfg.org.cohort.enabled, true);
+  assert.equal(isEnabled(cfg), true);
+});
+
+test("loadOrgConfig: a PRESENT but unparseable org.yaml WARNS (never silently un-enrols)", () => {
+  // Returning {} quietly is how an enrolled agent ends up out of the mesh:
+  // isEnabled({}) is false, so the daemon no-ops, never beats, and cannot
+  // receive `halt`. Fail-open is right; silence is not.
+  const dir = mkdtempSync(join(tmpdir(), "orgcfg-"));
+  mkdirSync(join(dir, "config"), { recursive: true });
+  writeFileSync(join(dir, "config", "org.yaml"), "org:\n  cohort:\n   - [unbalanced\n");
+  let cfg;
+  const warnings = captureWarn(() => { cfg = loadOrgConfig(dir); });
+  assert.deepEqual(cfg, {}, "still fail-open");
+  assert.match(warnings.join("\n"), /could not be loaded/, "the operator must be told");
+  assert.match(warnings.join("\n"), /NOT enrolled/, "and told what it means");
+});

package/lib/org/doctor.mjs

@@ -190,6 +190,70 @@ export async function checkOrgConnectivity(o = {}) {
     results.push({ level: "warn", msg: `pairing probe inconclusive (${chan.error?.code || "?"}: ${chan.error?.message || "no detail"})` });
   }
 
+  // ── 3b. INBOUND PATH probe — can this agent actually RECEIVE a message? ───
+  //
+  // Pairing proves the key is bound to a member. It does NOT prove the agent
+  // can hear anything, and those are different failures with the same healthy
+  // appearance. In production an enrolled, beating, correctly-paired agent was
+  // deaf for hours: the inbound cadence read org config from the wrong file, and
+  // the history call sent `channel` where hq validates `channelId`. Doctor was
+  // green throughout, because nothing exercised the receive path.
+  //
+  // So exercise it: read history from a real channel the agent belongs to. That
+  // single call covers the param contract, the read scope, and the ACL. A
+  // BAD_REQUEST here means protocol drift between this SDK and the server —
+  // the class of bug that leaves a fresh machine silently mute.
+  if (chan.ok) {
+    const rooms = chan.result && (Array.isArray(chan.result.channels) ? chan.result.channels : Array.isArray(chan.result) ? chan.result : []);
+    const probeRoom = (rooms || []).map((c) => c && (c.id || c.channelId)).find(Boolean);
+    if (!probeRoom) {
+      results.push({ level: "warn", msg: "inbound probe skipped — this member is in no channels yet" });
+    } else {
+      const hist = await call("messaging.history", { channelId: probeRoom, limit: 1 }, callOpts);
+      if (hist.ok) {
+        results.push({ level: "ok", msg: "inbound path works (messaging.history readable)" });
+      } else if (hist.error && hist.error.code === "BAD_REQUEST") {
+        results.push({
+          level: "fail",
+          msg:
+            `inbound path BROKEN — messaging.history rejected this SDK's params ` +
+            `(${hist.error.message || "BAD_REQUEST"}). The agent cannot read messages ` +
+            `sent to it. This is SDK/server protocol drift: upgrade with ` +
+            `\`npm update @cohortapp/agent-sdk && npx @cohortapp/agent-sdk upgrade\``,
+        });
+      } else {
+        results.push({
+          level: "warn",
+          msg: `inbound probe inconclusive (${hist.error?.code || "?"}: ${hist.error?.message || "no detail"})`,
+        });
+      }
+    }
+  }
+
+  // ── 3c. Is org enrolment visible to the DAEMON's config loader? ───────────
+  //
+  // The org client reads config/org.yaml; the cadence guards read the agent cfg.
+  // When those disagree the agent enrols successfully and still ignores every
+  // inbound event, because each org-facing guard bails out with "org messaging
+  // not configured". Assert the daemon's own view here rather than the client's.
+  try {
+    const { loadOrgConfig: loadOrg } = await import("./client.mjs");
+    const daemonView = loadOrg(agentRoot);
+    if (!daemonView || !daemonView.org || !daemonView.org.cohort) {
+      results.push({
+        level: "fail",
+        msg:
+          "org enrolment is NOT visible to the daemon's config loader — every " +
+          "org-facing cadence (messaging-inbound, brand-steward, …) will silently " +
+          "do nothing. Check config/org.yaml exists and js-yaml is installed.",
+      });
+    } else {
+      results.push({ level: "ok", msg: "org enrolment visible to the daemon cadences" });
+    }
+  } catch (err) {
+    results.push({ level: "warn", msg: `daemon org-config check failed (${err && err.message})` });
+  }
+
   // ── 4/5. workspace mailbox ───────────────────────────────────────────────
   const orgmailGate = existsSync(join(agentRoot, "config", "orgmail.yaml"));
   if (orgmailGate) {

package/lib/org/doctor.test.mjs

@@ -62,6 +62,8 @@ function stubFetch(routes) {
 }
 
 const DIR_OK = { status: 200, body: { members: [] }, headers: { "x-org-protocol": String(PROTOCOL_VERSION) } };
+const HISTORY_OK = { status: 200, body: { ok: true, result: { messages: [] } } };
+const HISTORY_BAD_PARAMS = { status: 400, body: { ok: false, error: { code: "BAD_REQUEST", message: "channelId: Required" } } };
 const CHANNELS_OK = { status: 200, body: { ok: true, result: { channels: [{ id: "c1" }, { id: "c2" }] } } };
 
 const levelsOf = (rs) => rs.map((r) => r.level);
@@ -80,10 +82,17 @@ test("probe 1: not enrolled → single ok line, no network", async () => {
 
 test("probe 2: happy path — reachable + latency + aligned protocol header + paired", async () => {
   const r = root();
-  const f = stubFetch({ "/api/v1/directory": DIR_OK, "/api/v1/messaging.channels": CHANNELS_OK });
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/messaging.history": HISTORY_OK,
+  });
   let t = 1000;
   const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {}, now: () => (t += 40) });
-  assert.deepEqual(levelsOf(rs), ["ok", "ok", "ok", "ok"]);
+  // …reachable, protocol, paired, INBOUND PATH, daemon-visible org config.
+  assert.deepEqual(levelsOf(rs), ["ok", "ok", "ok", "ok", "ok", "ok"]);
+  assert.match(msgs(rs), /inbound path works/);
+  assert.match(msgs(rs), /visible to the daemon cadences/);
   assert.match(msgs(rs), /directory \d+ms/);
   assert.match(msgs(rs), /protocol version aligned/);
   assert.match(msgs(rs), /paired to a workforce member \(2 channel\(s\)\)/);
@@ -210,3 +219,23 @@ test("no orgmail gate file → no mailbox probe at all", async () => {
   assert.ok(!f.calls.some((c) => c.url.includes("email.inbox")));
   rmSync(r, { recursive: true, force: true });
 });
+
+test("inbound probe FAILS loudly when the server rejects this SDK's params", () => {
+  // The real incident: fetchHistory sent `channel`, hq validates `channelId`,
+  // so the agent could not read a single message sent to it — while every other
+  // doctor line stayed green. Protocol drift must be a FAIL, not a shrug.
+  const r = root();
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/messaging.history": HISTORY_BAD_PARAMS,
+  });
+  return checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} }).then((rs) => {
+    const bad = rs.find((x) => /inbound path BROKEN/.test(x.msg));
+    assert.ok(bad, "a rejected inbound probe must surface");
+    assert.equal(bad.level, "fail");
+    assert.match(bad.msg, /protocol drift/);
+    assert.match(bad.msg, /upgrade/);
+    rmSync(r, { recursive: true, force: true });
+  });
+});