@cohortapp/agent-sdk 2.3.0

package/lib/org/knowledge.mjs

@@ -0,0 +1,463 @@
+/**
+ * lib/org/knowledge.mjs — agent-facing shared-memory API over the Cohort
+ * knowledge plane (SPEC-org-server §4.7).
+ *
+ * THE compounding-collaboration lever. Where lib/learning/ and lib/collective/
+ * give one agent a memory of its OWN sessions, this module gives every agent a
+ * window into the ORG's shared, ACL'd knowledge: a fact promoted by agent A is
+ * retrievable by agent B inside the ACL, invisible outside it. It is the org-wide
+ * RAG source an agent's context-assembly can consult — `recall(query)` pulls the
+ * shared facts the server's RLS floor permits, and `remember(fact)` lands new
+ * shared knowledge for everyone else.
+ *
+ * The verb surface is deliberately small and human:
+ *   - remember(fact, {group})    → knowledge.append (episodes; commutes) or
+ *                                   knowledge.replace (CAS) when {id, expectedVersion}
+ *   - recall(query, {group?})    → knowledge.search → the ACL-visible facts
+ *   - forget(id, {reason?})      → knowledge.invalidate (tombstone, NEVER delete)
+ *   - rewrite(id, text, …)       → knowledge.rewrite (designated-owner-only)
+ *   - upsertContact / contacts   → contacts.upsert / contacts.list
+ *   - recordMeeting / meetings   → meetings.record / meetings.list
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * THE SERVER IS AUTHORITATIVE FOR ACL. This is load-bearing and non-negotiable.
+ *
+ * This module NEVER decides what an agent may read or write. It does not inspect
+ * a fact's `group`, does not know which barrier:<cell> the agent holds, and does
+ * NOT filter `recall()` results. The non-bypassable RLS floor — org/unit group
+ * membership, `barrier:<cell>` DENY-OVERRIDE (never returned unless explicitly
+ * granted, even to an org/unit member), and participant-derived ACLs — lives in
+ * the server's query layer (the SQLite/Postgres-RLS floor every read passes
+ * through). The agent's groups derive from its VERIFIED identity, not from
+ * anything this client sends. `recall()` renders exactly what the server chose to
+ * return; the `{group}` argument is a SCOPING HINT to the server, never a filter
+ * the client enforces. If you want to narrow a search, the server still applies
+ * the floor on top of your hint — a hint can only ever shrink, never widen, what
+ * comes back.
+ *
+ * Every `recall()` is a SIDE-EFFECTING, AUDITED retrieval: the server appends a
+ * 'knowledge' org_events row {agent, query, returned_ids, groups_considered} —
+ * the regulator-facing read-audit trail. There is no "silent" read of the plane.
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ * G16 (zero-LLM-in-the-coordination-loop): NOTHING here makes an LLM call. These
+ * are pure parameter shaping + a fail-open HTTP round-trip. Episode CONSOLIDATION
+ * (the optional ingest worker that distils episodes into facts) is the only LLM
+ * consumer in the plane and lives server-side, OUT of this synchronous path.
+ *
+ * Fail-open by design: a disabled/unreachable server makes `remember/forget`
+ * a no-op `{ok:false, skipped}` and `recall/contacts/meetings` return `[]` —
+ * never a throw — so the org knowledge binding can never take down the agent's
+ * main path. `fetchImpl` is injectable everywhere for deterministic tests.
+ *
+ * Node builtins only (global fetch on Node 20). ESM.
+ *
+ * @module lib/org/knowledge
+ */
+
+"use strict";
+
+import {
+  isEnabled,
+  configFromAgent,
+  knowledgeAppend,
+  knowledgeReplace,
+  knowledgeRewrite,
+  knowledgeInvalidate,
+  knowledgeSearch,
+  contactsUpsert,
+  contactsList,
+  meetingsRecord,
+  meetingsList,
+} from "./client.mjs";
+import { KNOWLEDGE_GROUP_KINDS } from "./protocol.mjs";
+
+/** Default cap on facts returned by a single recall (the server may cap lower). */
+const DEFAULT_RECALL_LIMIT = 20;
+
+// ---------------------------------------------------------------------------
+// Group hints (the server is still authoritative — these are advisory shapes)
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise a group hint to a `group_id` string of the form the plane uses:
+ * `org` | `unit:<id>` | `barrier:<cell>` (KNOWLEDGE_GROUP_KINDS). Accepts either
+ * a ready string or a `{kind, id}` object. Returns undefined when nothing usable
+ * is given (the server then picks the group from the caller's verified identity).
+ *
+ * This is a SHAPE helper only — emitting `barrier:<cell>` here does NOT grant the
+ * agent that cell. The server still deny-overrides any barrier group the agent's
+ * verified identity was not explicitly granted.
+ *
+ * @param {string|{kind?:string,id?:string,cell?:string}|undefined} group
+ * @returns {string|undefined}
+ */
+export function normalizeGroup(group) {
+  if (group == null) return undefined;
+  if (typeof group === "string") {
+    const s = group.trim();
+    if (!s) return undefined;
+    if (s === "org") return "org";
+    // Already in `kind:rest` form, or a bare unit/barrier id we leave to the server.
+    if (s.includes(":")) {
+      const kind = s.split(":", 1)[0];
+      return KNOWLEDGE_GROUP_KINDS.includes(kind) ? s : undefined;
+    }
+    return undefined;
+  }
+  if (typeof group === "object") {
+    const kind = group.kind ? String(group.kind) : "";
+    if (kind === "org") return "org";
+    const id = group.id != null ? String(group.id) : (group.cell != null ? String(group.cell) : "");
+    if ((kind === "unit" || kind === "barrier") && id) return `${kind}:${id}`;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// remember — land shared knowledge (append episode, or CAS-replace a fact)
+// ---------------------------------------------------------------------------
+
+/**
+ * Remember a fact into the org's shared knowledge plane.
+ *
+ * Default path is `knowledge.append` — an episode, the SOLE shared-write
+ * primitive; it COMMUTES, so concurrent appends from different agents both land
+ * with no coordination. When the caller supplies `{id, expectedVersion}` it's an
+ * update to an existing fact and routes to `knowledge.replace` (compare-and-swap
+ * on the version; a stale CAS comes back as a CONFLICT frame). Use `rewrite()`
+ * (not this) for an owner-only in-place rewrite.
+ *
+ * The `group` is a HINT only; the server assigns/validates the fact's group from
+ * the caller's verified identity subject to the RLS floor. Never throws; returns
+ * a benign skipped result when the integration is disabled.
+ *
+ * @param {string|{text:string,...}} fact the episode text, or a fact object
+ * @param {object} opts - {
+ *   cfg, group?, id?, expectedVersion?, kind?, participants?, provenance?,
+ *   links?, refs?, idempotencyKey?, fetchImpl?
+ * }
+ * @returns {Promise<{ok:boolean, skipped?:boolean, mode?:'append'|'replace', id?:string, result?:any, error?:object}>}
+ */
+export async function remember(fact, opts = {}) {
+  if (!isEnabled(opts.cfg)) return { ok: false, skipped: true };
+  const params = factToParams(fact, opts);
+  if (!params.text && !params.id) return { ok: false, skipped: false, error: { code: "BAD_REQUEST", message: "empty fact" } };
+
+  const c = configFromAgent(opts.cfg);
+  const tx = { base: c.base, token: c.token, fetchImpl: opts.fetchImpl };
+
+  // {id, expectedVersion} ⇒ CAS replace of an existing fact; otherwise append.
+  const isReplace = !!(params.id && (opts.expectedVersion != null || params.expectedVersion != null));
+  if (isReplace) {
+    const replaceParams = { ...params, expectedVersion: opts.expectedVersion ?? params.expectedVersion };
+    const frame = await knowledgeReplace(replaceParams, { ...tx, idempotencyKey: opts.idempotencyKey });
+    return shapeWrite(frame, "replace", params.id);
+  }
+
+  const frame = await knowledgeAppend(params, {
+    ...tx,
+    idempotencyKey: opts.idempotencyKey || (params.id ? `knowledge.append:${params.id}` : undefined),
+  });
+  return shapeWrite(frame, "append", params.id);
+}
+
+/**
+ * Rewrite a fact in place (knowledge.rewrite) — DESIGNATED-OWNER-ONLY. Distinct
+ * from remember()'s CAS path: rewrite is the owner asserting authorship, not a
+ * versioned update; the server enforces ownership and rejects a non-owner. Use
+ * sparingly — most updates should append (provenance-preserving) or CAS-replace.
+ *
+ * @param {string} id
+ * @param {string|{text:string,...}} fact
+ * @param {object} opts - { cfg, group?, provenance?, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<{ok:boolean, skipped?:boolean, mode?:'rewrite', id?:string, result?:any, error?:object}>}
+ */
+export async function rewrite(id, fact, opts = {}) {
+  if (!isEnabled(opts.cfg)) return { ok: false, skipped: true };
+  if (!id) return { ok: false, skipped: false, error: { code: "BAD_REQUEST", message: "missing id" } };
+  const params = { ...factToParams(fact, opts), id: String(id) };
+  const c = configFromAgent(opts.cfg);
+  const frame = await knowledgeRewrite(params, {
+    base: c.base, token: c.token, idempotencyKey: opts.idempotencyKey, fetchImpl: opts.fetchImpl,
+  });
+  return shapeWrite(frame, "rewrite", params.id);
+}
+
+// ---------------------------------------------------------------------------
+// recall — the org-RAG read (ACL-floored by the server; the client never filters)
+// ---------------------------------------------------------------------------
+
+/**
+ * Recall shared knowledge for a query — the org-wide RAG source. Calls
+ * `knowledge.search` and returns the facts the SERVER chose to return after
+ * applying the non-bypassable RLS floor. The client performs NO ACL filtering:
+ * whatever facts come back are, by construction, the ones this agent's verified
+ * groups may see (barrier:<cell> deny-override already applied server-side).
+ *
+ * This is the call an agent's context-assembly makes to pull org knowledge into a
+ * prompt — drop it alongside the local lib/collective recall. Because every
+ * retrieval is audited server-side (org_events family 'knowledge'), do not loop
+ * it gratuitously; one query per context build is the intended cadence.
+ *
+ * The `{group}` option is a scoping HINT to the server (it can only shrink the
+ * result, never widen it past the floor). `lexical` flags that a keyword/lexical
+ * match was requested — an acceptable phase-4 stand-in for vector search, which
+ * the server notes; ranking/embedding is the server's job either way.
+ *
+ * Fail-open: a disabled/unreachable server yields []. Never throws.
+ *
+ * @param {string} query natural-language or keyword query
+ * @param {object} opts - {
+ *   cfg, group?, limit?, kind?, includeInvalid?, lexical?, idempotencyKey?, fetchImpl?
+ * }
+ * @returns {Promise<object[]>} the ACL-visible facts (server-filtered), or []
+ */
+export async function recall(query, opts = {}) {
+  const r = await recallDetailed(query, opts);
+  return r.facts;
+}
+
+/**
+ * Like recall(), but returns the full retrieval envelope the server reported:
+ * `{ ok, facts, returnedIds, groupsConsidered }`. `returnedIds`/`groupsConsidered`
+ * mirror the read-audit row the server wrote — useful for surfacing provenance
+ * (e.g. "answered from facts X,Y across groups org,unit:eng") without a second
+ * call, and for the cascade/blast-radius drill. Still does no client-side ACL
+ * filtering. Fail-open: yields `{ok:false, facts:[]}`.
+ *
+ * @param {string} query
+ * @param {object} opts - see recall()
+ * @returns {Promise<{ok:boolean, facts:object[], returnedIds:string[], groupsConsidered:string[], error?:object}>}
+ */
+export async function recallDetailed(query, opts = {}) {
+  const empty = { ok: false, facts: [], returnedIds: [], groupsConsidered: [] };
+  if (!isEnabled(opts.cfg)) return empty;
+  const q = query == null ? "" : String(query);
+  if (!q.trim()) return empty;
+
+  const params = { query: q };
+  const group = normalizeGroup(opts.group);
+  if (group) params.group = group;
+  params.limit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : DEFAULT_RECALL_LIMIT;
+  if (opts.kind) params.kind = String(opts.kind);
+  if (opts.includeInvalid) params.includeInvalid = true;
+  if (opts.lexical) params.lexical = true;
+
+  const c = configFromAgent(opts.cfg);
+  const frame = await knowledgeSearch(params, {
+    base: c.base, token: c.token, idempotencyKey: opts.idempotencyKey, fetchImpl: opts.fetchImpl,
+  });
+  if (!frame || !frame.ok) {
+    return { ok: false, facts: [], returnedIds: [], groupsConsidered: [], error: frame && frame.error };
+  }
+  const result = frame.result || {};
+  // Render WHATEVER the server returned. We do NOT re-derive, re-sort, or filter
+  // by group — the server already applied the RLS floor. We only coerce shapes.
+  const facts = pickArray(result, ["facts", "results", "items"]);
+  const returnedIds = Array.isArray(result.returned_ids)
+    ? result.returned_ids.map(String)
+    : facts.map((f) => (f && (f.id != null ? String(f.id) : null))).filter(Boolean);
+  const groupsConsidered = Array.isArray(result.groups_considered) ? result.groups_considered.map(String) : [];
+  return { ok: true, facts, returnedIds, groupsConsidered };
+}
+
+// ---------------------------------------------------------------------------
+// forget — invalidate (tombstone), never hard-delete
+// ---------------------------------------------------------------------------
+
+/**
+ * Forget a fact — INVALIDATE, DON'T DELETE. Routes to `knowledge.invalidate`:
+ * the server marks the fact invalid (provenance + tombstone) and excludes it from
+ * future recall, but the ROW PERSISTS for audit and the cascade/blast-radius
+ * drill (provenance can still enumerate everyone who read the bad fact). There is
+ * no client-side delete and no server hard-delete in this plane.
+ *
+ * Fail-open: disabled ⇒ `{ok:false, skipped:true}`. Never throws.
+ *
+ * @param {string} id the fact id to invalidate
+ * @param {object} opts - { cfg, reason?, supersededBy?, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<{ok:boolean, skipped?:boolean, id?:string, result?:any, error?:object}>}
+ */
+export async function forget(id, opts = {}) {
+  if (!isEnabled(opts.cfg)) return { ok: false, skipped: true };
+  if (!id) return { ok: false, skipped: false, error: { code: "BAD_REQUEST", message: "missing id" } };
+  const c = configFromAgent(opts.cfg);
+  const params = { id: String(id) };
+  if (opts.reason) params.reason = String(opts.reason);
+  if (opts.supersededBy) params.supersededBy = String(opts.supersededBy);
+  const frame = await knowledgeInvalidate(params, {
+    base: c.base,
+    token: c.token,
+    idempotencyKey: opts.idempotencyKey || `knowledge.invalidate:${params.id}`,
+    fetchImpl: opts.fetchImpl,
+  });
+  return shapeWrite(frame, "invalidate", params.id);
+}
+
+// ---------------------------------------------------------------------------
+// contacts + meetings (ACL-filtered registries on the same plane)
+// ---------------------------------------------------------------------------
+
+/**
+ * Upsert an org contact into the shared registry (contacts.upsert). Idempotent.
+ * ACL-filtered on read by the server like every other knowledge surface. Fail-open.
+ * @param {object} contact - { id?, name?, emails?, phones?, handles?, org?, group?, fields? }
+ * @param {object} opts - { cfg, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<{ok:boolean, skipped?:boolean, id?:string, result?:any, error?:object}>}
+ */
+export async function upsertContact(contact, opts = {}) {
+  if (!isEnabled(opts.cfg)) return { ok: false, skipped: true };
+  const c = configFromAgent(opts.cfg);
+  const params = contact && typeof contact === "object" ? { ...contact } : {};
+  const group = normalizeGroup(params.group);
+  if (group) params.group = group; else delete params.group;
+  const frame = await contactsUpsert(params, {
+    base: c.base,
+    token: c.token,
+    idempotencyKey: opts.idempotencyKey || (params.id ? `contacts.upsert:${params.id}` : undefined),
+    fetchImpl: opts.fetchImpl,
+  });
+  return shapeWrite(frame, "contact", params.id, "contacts.upsert");
+}
+
+/**
+ * List org contacts the agent may see (contacts.list). The SERVER ACL-filters;
+ * the client renders the list as-is. Returns [] when disabled or on failure.
+ * @param {object} opts - { cfg, q?, group?, limit?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function listContacts(opts = {}) {
+  if (!isEnabled(opts.cfg)) return [];
+  const c = configFromAgent(opts.cfg);
+  return contactsList({
+    base: c.base, token: c.token, fetchImpl: opts.fetchImpl,
+    q: opts.q, group: normalizeGroup(opts.group), limit: opts.limit,
+  });
+}
+
+/**
+ * Record a meeting into the shared registry (meetings.record). Idempotent. The
+ * server derives a participant ACL for the meeting fact. Fail-open.
+ * @param {object} meeting - { id?, title?, at?, participants?, notes?, group?, refs?, fields? }
+ * @param {object} opts - { cfg, idempotencyKey?, fetchImpl? }
+ * @returns {Promise<{ok:boolean, skipped?:boolean, id?:string, result?:any, error?:object}>}
+ */
+export async function recordMeeting(meeting, opts = {}) {
+  if (!isEnabled(opts.cfg)) return { ok: false, skipped: true };
+  const c = configFromAgent(opts.cfg);
+  const params = meeting && typeof meeting === "object" ? { ...meeting } : {};
+  const group = normalizeGroup(params.group);
+  if (group) params.group = group; else delete params.group;
+  const frame = await meetingsRecord(params, {
+    base: c.base,
+    token: c.token,
+    idempotencyKey: opts.idempotencyKey || (params.id ? `meetings.record:${params.id}` : undefined),
+    fetchImpl: opts.fetchImpl,
+  });
+  return shapeWrite(frame, "meeting", params.id, "meetings.record");
+}
+
+/**
+ * List org meetings the agent may see (meetings.list). The SERVER ACL-filters
+ * (participant-derived). Returns [] when disabled or on failure.
+ * @param {object} opts - { cfg, q?, group?, since?, limit?, fetchImpl? }
+ * @returns {Promise<object[]>}
+ */
+export async function listMeetings(opts = {}) {
+  if (!isEnabled(opts.cfg)) return [];
+  const c = configFromAgent(opts.cfg);
+  return meetingsList({
+    base: c.base, token: c.token, fetchImpl: opts.fetchImpl,
+    q: opts.q, group: normalizeGroup(opts.group), since: opts.since, limit: opts.limit,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// internals (pure shaping)
+// ---------------------------------------------------------------------------
+
+/** Coerce a fact arg (string text or fact object) + opts into the wire params. */
+function factToParams(fact, opts = {}) {
+  const base = typeof fact === "string" ? { text: fact } : (fact && typeof fact === "object" ? { ...fact } : {});
+  // Pull through the structured options without letting opts plumbing leak.
+  if (opts.id != null && base.id == null) base.id = opts.id;
+  if (opts.kind != null && base.kind == null) base.kind = opts.kind;
+  if (opts.participants != null && base.participants == null) base.participants = opts.participants;
+  if (opts.provenance != null && base.provenance == null) base.provenance = opts.provenance;
+  if (opts.links != null && base.links == null) base.links = opts.links;
+  if (opts.refs != null && base.refs == null) base.refs = opts.refs;
+  if (opts.expectedVersion != null && base.expectedVersion == null) base.expectedVersion = opts.expectedVersion;
+  const group = normalizeGroup(opts.group != null ? opts.group : base.group);
+  if (group) base.group = group; else delete base.group;
+  if (base.id != null) base.id = String(base.id);
+  return base;
+}
+
+/** Methods that have already emitted their one-shot "server does not implement" warning. */
+const _unimplementedWarned = new Set();
+
+/**
+ * Loudly, ONCE per method, surface that the org server has no handler for a
+ * write the agent attempted (dispatch returns NOT_FOUND). Silently swallowing
+ * this (as the old wrappers did) hides a real capability gap — the doctor and
+ * the operator need to see it. Fail-open: writing the warning never throws.
+ * @param {string} method the wire method (e.g. "contacts.upsert")
+ */
+function warnUnimplemented(method) {
+  if (_unimplementedWarned.has(method)) return;
+  _unimplementedWarned.add(method);
+  try {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[maestro/org] the org server does not implement ${method} (NOT_FOUND) — ` +
+      `this write was dropped. Upgrade Cohort or run \`maestro doctor\` for detail.`
+    );
+  } catch { /* fail-open */ }
+}
+
+/**
+ * Normalise a write res frame into the module's `{ok, mode, id, result|error}`
+ * shape. When the server returns NOT_FOUND (the method's handler lane is not
+ * built), the result is flagged `unimplemented:true` AND a one-shot warning is
+ * emitted, so a genuine capability gap is never swallowed silently.
+ * @param {object} frame the res frame
+ * @param {string} mode  the surface label (e.g. "contact", "meeting")
+ * @param {string} [id]
+ * @param {string} [method] the wire method, for the unimplemented warning
+ */
+function shapeWrite(frame, mode, id, method) {
+  const ok = !!(frame && frame.ok);
+  const result = ok ? (frame.result ?? null) : undefined;
+  const resolvedId = (result && result.id) || id || undefined;
+  if (ok) return { ok: true, mode, id: resolvedId, result };
+  const error = (frame && frame.error) || { code: "INTERNAL", message: "no frame" };
+  if (error.code === "NOT_FOUND") {
+    if (method) warnUnimplemented(method);
+    return { ok: false, mode, id: resolvedId, unimplemented: true, error };
+  }
+  return { ok: false, mode, id: resolvedId, error };
+}
+
+/** Return the first array found under the given keys, else []. */
+function pickArray(obj, keys) {
+  if (Array.isArray(obj)) return obj;
+  if (!obj || typeof obj !== "object") return [];
+  for (const k of keys) if (Array.isArray(obj[k])) return obj[k];
+  return [];
+}
+
+export const _internals = { factToParams, shapeWrite, pickArray, DEFAULT_RECALL_LIMIT };
+
+export default {
+  remember,
+  rewrite,
+  recall,
+  recallDetailed,
+  forget,
+  upsertContact,
+  listContacts,
+  recordMeeting,
+  listMeetings,
+  normalizeGroup,
+};