@cohortapp/agent-sdk 2.3.2 → 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
@@ -268,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 = {}) {
@@ -279,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);
 }
@@ -571,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? }
  */
@@ -1577,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

@@ -875,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"]);
 });