@cohortapp/agent-sdk 2.3.1 → 2.4.0

package/lib/subagents/client.mjs

@@ -0,0 +1,373 @@
+/**
+ * lib/subagents/client.mjs — the hq half of the registry (§2.1, §4).
+ *
+ * Nine verbs (`subagent.list|get|resolve|create|publishVersion|fork|pin|unpin|
+ * yank`) plus one cheap GET read (`subagent.roster`). The split matters and is
+ * the whole reason there are two read paths: `roster` returns
+ * `{rosterVersion, entries:[{slug, definitionId, version, contentHash}]}` with NO
+ * bodies and is what `doctor` polls; `resolve` returns bodies and is the
+ * expensive one `apply`/`pull` call.
+ *
+ * WHY THIS MODULE HAS ITS OWN TRANSPORT RATHER THAN lib/org/client.mjs `call()`.
+ * `call()` looks the method up in the frozen `METHODS` table and returns
+ * `NOT_FOUND` for anything it does not know. The `subagent` family is a protocol
+ * change (canonical source `lib/org/protocol.mjs`, then `sync-protocol.mjs` into
+ * hq, then a checksum bump in BOTH repos) and that dual-repo ritual is landed
+ * separately, once, complete — see §6's protocol-drift risk. Wiring this module
+ * to `call()` before the family exists would make every verb fail-open into
+ * silence. The transport below is a deliberate 60-line mirror of `httpRequest` +
+ * `v1Url` + `baseHeaders`; once the family lands, `postRpc`/`getRead` are the
+ * only two functions that need to be swapped for `call`/`read`, and every verb
+ * above them is unchanged.
+ *
+ * FAIL-OPEN IS NOT OPTIONAL HERE. `apply` throws are FATAL to the whole wizard
+ * (lib/setup/runner.mjs:220-227), so every function in this file returns a
+ * result object and never throws — a timeout, a 500, a missing key and an
+ * unparseable body all come back as `{ok:false, ...}` with `degraded:true`. The
+ * caller degrades to cache-or-local and records `degraded:["workspace"]`.
+ *
+ * Writes made with no reachable server QUEUE to `state/subagents/outbox/` and
+ * replay on `maestro sync`. They are idempotent server-side by `contentHash` +
+ * `(orgId, slug)`, so a replay of a write that actually landed is a no-op.
+ *
+ * Timeout is 5 s (not the org client's 8 s): this runs inside an interactive
+ * wizard step, and a human waiting on a dead server is a worse outcome than a
+ * degraded roster.
+ *
+ * Node builtins only (global fetch on Node 20). ESM.
+ *
+ * @module lib/subagents/client
+ */
+
+"use strict";
+
+import { loadOrgConfig, configFromAgent } from "../org/client.mjs";
+import { queueOutbox, writeCache } from "./lock.mjs";
+import { hashBody, stringifyAgentMd, stripProvenance } from "./schema.mjs";
+
+/** 5 s — an interactive wizard must not hang on a dead server. */
+export const TIMEOUT_MS = 5000;
+
+/** The protocol version header every /v1 request carries. */
+const PROTOCOL_VERSION = 1;
+
+/**
+ * Resolve `{base, token, orgId, memberId, enabled}` for the registry.
+ *
+ * Precedence mirrors `cohortPullEnv` + `configFromAgent` exactly, because an
+ * operator who set `COHORT_API_KEY` for enrolment must not have to set a second
+ * variable for sub-agents. `enabled` false is a legitimate steady state, not an
+ * error: an un-enrolled agent simply has no layer 1 (§4 — the section reports
+ * `status:"skipped"`).
+ *
+ * @param {{agentRoot?:string, env?:NodeJS.ProcessEnv, cfg?:object}} o
+ * @returns {{enabled:boolean, base:string, token:string, orgId:string, memberId:string}}
+ */
+export function resolveConfig(o = {}) {
+  const env = o.env || process.env;
+  const cfg = o.cfg || (o.agentRoot ? loadOrgConfig(o.agentRoot) : {});
+  const c = configFromAgent(cfg);
+  const base = String(env.COHORT_BASE || env.COHORT_API_URL || c.base || "").replace(/\/+$/, "");
+  const token = String(c.token || env.COHORT_API_KEY || env.COHORT_API_TOKEN || env.COHORT_TOKEN || "");
+  const orgId = String(c.orgId || env.COHORT_ORG_ID || "");
+  const memberId = String(env.COHORT_MEMBER_ID || env.COHORT_AGENT_ID || "");
+  return { enabled: !!(base && token), base, token, orgId, memberId };
+}
+
+/** Bearer + protocol + tenant-pin headers. Mirrors lib/org/client baseHeaders. */
+function headers(cfg, withBody) {
+  const h = {
+    authorization: `Bearer ${cfg.token}`,
+    "x-org-protocol": String(PROTOCOL_VERSION),
+  };
+  if (cfg.orgId) h["x-org-id"] = cfg.orgId;
+  if (withBody) h["content-type"] = "application/json";
+  return h;
+}
+
+function v1Url(base, path) {
+  return `${String(base).replace(/\/+$/, "")}/v1/${String(path).replace(/^\/+/, "")}`;
+}
+
+function pickFetch(fetchImpl) {
+  if (typeof fetchImpl === "function") return fetchImpl;
+  return typeof fetch === "function" ? fetch : null;
+}
+
+/**
+ * One HTTP round-trip with a hard timeout. Returns a normalised
+ * `{ok, status, body}` — never throws, never rejects.
+ * @returns {Promise<{ok:boolean, status:number, body:any, error?:string}>}
+ */
+async function http(url, init, fetchImpl, timeoutMs) {
+  const f = pickFetch(fetchImpl);
+  if (!f) return { ok: false, status: 0, body: null, error: "no fetch available" };
+  const ctrl = typeof AbortController === "function" ? new AbortController() : null;
+  const ms = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : TIMEOUT_MS;
+  const timer = ctrl ? setTimeout(() => ctrl.abort(), ms) : null;
+  try {
+    const res = await f(url, { ...init, signal: ctrl ? ctrl.signal : undefined });
+    const status = typeof res.status === "number" ? res.status : 0;
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    const ok = typeof res.ok === "boolean" ? res.ok : status >= 200 && status < 300;
+    return { ok, status, body };
+  } catch (e) {
+    return { ok: false, status: 0, body: null, error: e && e.name === "AbortError" ? `timeout after ${ms}ms` : String((e && e.message) || e) };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * POST an RPC method. Returns `{ok, result, error, degraded}`.
+ * `degraded:true` means "the server did not answer" (as opposed to "the server
+ * said no") — the caller uses that to decide between outbox-queueing and
+ * surfacing a real error to the operator.
+ * @param {string} method @param {object} params
+ * @param {{cfg:object, fetchImpl?:Function, timeoutMs?:number, idempotencyKey?:string}} o
+ */
+export async function postRpc(method, params, o = {}) {
+  const cfg = o.cfg || {};
+  if (!cfg.base || !cfg.token) return { ok: false, degraded: true, error: { code: "UNAUTHORIZED", message: "no base/token — agent is not enrolled" } };
+  const h = headers(cfg, true);
+  if (o.idempotencyKey) h["x-idempotency-key"] = String(o.idempotencyKey);
+  const r = await http(v1Url(cfg.base, method), { method: "POST", headers: h, body: JSON.stringify(params || {}) }, o.fetchImpl, o.timeoutMs);
+  if (!r.ok && r.status === 0) return { ok: false, degraded: true, error: { code: "INTERNAL", message: r.error || "transport error" } };
+  const frame = r.body && typeof r.body === "object" ? r.body : null;
+  if (frame && frame.ok === true) return { ok: true, result: frame.result === undefined ? null : frame.result };
+  const error = (frame && frame.error) || { code: `HTTP_${r.status}`, message: `http ${r.status}` };
+  return { ok: false, degraded: false, status: r.status, error };
+}
+
+/**
+ * GET a read endpoint. Reads return the BARE payload on 200 (not a frame) —
+ * same convention as lib/org/client.read.
+ */
+export async function getRead(path, o = {}) {
+  const cfg = o.cfg || {};
+  if (!cfg.base || !cfg.token) return { ok: false, degraded: true, error: { code: "UNAUTHORIZED", message: "no base/token — agent is not enrolled" } };
+  const r = await http(v1Url(cfg.base, path), { method: "GET", headers: headers(cfg, false) }, o.fetchImpl, o.timeoutMs);
+  if (!r.ok && r.status === 0) return { ok: false, degraded: true, error: { code: "INTERNAL", message: r.error || "transport error" } };
+  if (r.ok) return { ok: true, payload: r.body };
+  const error = (r.body && r.body.error) || { code: `HTTP_${r.status}`, message: `http ${r.status}` };
+  return { ok: false, degraded: false, status: r.status, error };
+}
+
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+
+/**
+ * The cheap poll: `GET /v1/subagent.roster`. No bodies. This is what `doctor`
+ * compares against the lock's `rosterVersion` to say "N sub-agents behind
+ * workspace" — the ONLY tell that the offline cache has gone stale (§6).
+ * @param {{cfg:object, fetchImpl?:Function, timeoutMs?:number}} o
+ * @returns {Promise<{ok:boolean, rosterVersion:number, entries:Array, degraded:boolean, error?:object}>}
+ */
+export async function fetchRoster(o = {}) {
+  const r = await getRead("subagent.roster", o);
+  if (!r.ok) return { ok: false, rosterVersion: 0, entries: [], degraded: !!r.degraded, error: r.error };
+  const p = r.payload && typeof r.payload === "object" ? r.payload : {};
+  return {
+    ok: true,
+    degraded: false,
+    rosterVersion: Number.isFinite(p.rosterVersion) ? p.rosterVersion : 0,
+    entries: Array.isArray(p.entries) ? p.entries : [],
+  };
+}
+
+/**
+ * The expensive read: `subagent.resolve` → bodies + rewire advice.
+ *
+ * Every returned body is written to `state/subagents/cache/<slug>@<v>.md` when an
+ * `agentRoot` is supplied, so the NEXT run resolves layer 1 with no network.
+ * A `memberId` other than the actor's own is FORBIDDEN server-side unless the
+ * actor holds `admin` — we send it verbatim and let hq decide (the dispatcher
+ * holds the coarse scope; the real gate is in-domain).
+ *
+ * @param {{cfg:object, agentRoot?:string, memberId?:string, function?:string, altitude?:string, refs?:string[], fetchImpl?:Function, timeoutMs?:number}} o
+ */
+export async function fetchResolve(o = {}) {
+  const params = {};
+  if (o.memberId) params.memberId = o.memberId;
+  if (o.function) params.function = o.function;
+  if (o.altitude) params.altitude = o.altitude;
+  if (Array.isArray(o.refs) && o.refs.length) params.refs = o.refs.map(String);
+
+  const r = await postRpc("subagent.resolve", params, o);
+  if (!r.ok) return { ok: false, degraded: !!r.degraded, rosterVersion: 0, entries: [], rewire: [], unmatched: [], error: r.error };
+
+  const res = r.result && typeof r.result === "object" ? r.result : {};
+  const entries = Array.isArray(res.entries) ? res.entries : [];
+  if (o.agentRoot) {
+    for (const e of entries) {
+      if (!e || !e.slug || typeof e.body !== "string") continue;
+      // Cache the raw body with the frontmatter the server sent, so an offline
+      // resolve reconstructs the identical entry (not a re-derived one). Emitted
+      // through the SAME serializer the resolver parses with, so a cache round
+      // trip is lossless.
+      const fm = e.frontmatter && typeof e.frontmatter === "object" ? e.frontmatter : {};
+      writeCache(o.agentRoot, e.slug, e.version, stringifyAgentMd(fm, e.body));
+    }
+  }
+  return {
+    ok: true,
+    degraded: false,
+    rosterVersion: Number.isFinite(res.rosterVersion) ? res.rosterVersion : 0,
+    entries,
+    rewire: Array.isArray(res.rewire) ? res.rewire : [],
+    unmatched: Array.isArray(res.unmatched) ? res.unmatched : [],
+  };
+}
+
+/** `subagent.list` — the catalogue, no bodies. */
+export async function listDefinitions(o = {}) {
+  const r = await postRpc("subagent.list", { ...(o.params || {}) }, o);
+  return r.ok ? { ok: true, items: Array.isArray(r.result && r.result.items) ? r.result.items : [] } : { ok: false, items: [], degraded: !!r.degraded, error: r.error };
+}
+
+/** `subagent.get` — one definition with its head version body. */
+export async function getDefinition(slug, o = {}) {
+  const r = await postRpc("subagent.get", { slug: String(slug) }, o);
+  return r.ok ? { ok: true, definition: r.result } : { ok: false, definition: null, degraded: !!r.degraded, error: r.error };
+}
+
+// ---------------------------------------------------------------------------
+// Writes — each queues to the outbox when the server is unreachable
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a write, and on a DEGRADED failure (server unreachable, not a rejection)
+ * queue it for `maestro sync` to replay.
+ *
+ * The distinction is load-bearing: a 403 must NOT be queued (it will be rejected
+ * forever and the operator would never see why), while a timeout must be, or an
+ * offline `maestro subagents publish` silently loses the operator's work.
+ *
+ * @param {string} method @param {object} params
+ * @param {{cfg:object, agentRoot?:string, idempotencyKey?:string, fetchImpl?:Function, timeoutMs?:number, queue?:boolean}} o
+ * @returns {Promise<{ok:boolean, result?:object, queued?:string|null, degraded?:boolean, error?:object}>}
+ */
+export async function writeVerb(method, params, o = {}) {
+  const r = await postRpc(method, params, { ...o, idempotencyKey: o.idempotencyKey });
+  if (r.ok) return { ok: true, result: r.result };
+  if (r.degraded && o.queue !== false && o.agentRoot) {
+    const queued = queueOutbox(o.agentRoot, method, params);
+    return { ok: false, degraded: true, queued, error: r.error };
+  }
+  return { ok: false, degraded: !!r.degraded, error: r.error };
+}
+
+/**
+ * `subagent.create` — a NEW org-scoped definition + its version 1.
+ * `body` is stored with tokens UNRENDERED and with provenance stripped: a
+ * definition describes prose, not where a copy of it happened to live.
+ */
+export function createDefinition(params, o = {}) {
+  const body = String(params.body || "");
+  const frontmatter = stripProvenance(params.frontmatter || {});
+  return writeVerb("subagent.create", {
+    slug: String(params.slug),
+    title: String(params.title || params.slug),
+    summary: String(params.summary || ""),
+    tags: Array.isArray(params.tags) ? params.tags.map(String) : [],
+    functions: Array.isArray(params.functions) ? params.functions.map(String) : [],
+    altitudes: Array.isArray(params.altitudes) ? params.altitudes.map(String) : [],
+    baseLayer: String(params.baseLayer || "none"),
+    baseSlug: params.baseSlug ? String(params.baseSlug) : null,
+    frontmatter,
+    body,
+    contentHash: hashBody(body),
+    generator: params.generator || { source: "human" },
+  }, { ...o, idempotencyKey: `subagent.create:${o.cfg && o.cfg.orgId}:${params.slug}` });
+}
+
+/** `subagent.publishVersion` — the "I edited it locally, promote it" path. */
+export function publishVersion(params, o = {}) {
+  const body = String(params.body || "");
+  return writeVerb("subagent.publishVersion", {
+    slug: String(params.slug),
+    definitionId: params.definitionId ? String(params.definitionId) : undefined,
+    frontmatter: stripProvenance(params.frontmatter || {}),
+    body,
+    contentHash: hashBody(body),
+    generator: params.generator || { source: "human" },
+  }, { ...o, idempotencyKey: `subagent.publishVersion:${params.slug}:${hashBody(body)}` });
+}
+
+/** `subagent.fork` — copy a resolved body into a NEW org definition (§5.2). */
+export function forkDefinition(params, o = {}) {
+  const body = String(params.body || "");
+  return writeVerb("subagent.fork", {
+    slug: String(params.slug),
+    baseLayer: String(params.baseLayer || "sdk"),
+    baseSlug: String(params.baseSlug || params.slug),
+    title: String(params.title || params.slug),
+    summary: String(params.summary || ""),
+    frontmatter: stripProvenance(params.frontmatter || {}),
+    body,
+    contentHash: hashBody(body),
+    generator: params.generator || { source: "fork", forkedFrom: params.baseSlug || params.slug },
+  }, { ...o, idempotencyKey: `subagent.fork:${o.cfg && o.cfg.orgId}:${params.slug}` });
+}
+
+/** `subagent.pin` — give THIS member this definition at this version. */
+export function pinDefinition(params, o = {}) {
+  return writeVerb("subagent.pin", {
+    memberId: params.memberId ? String(params.memberId) : undefined,
+    definitionId: params.definitionId ? String(params.definitionId) : undefined,
+    slug: params.slug ? String(params.slug) : undefined,
+    versionId: params.versionId ? String(params.versionId) : undefined,
+    version: Number.isFinite(params.version) ? params.version : undefined,
+  }, { ...o, idempotencyKey: `subagent.pin:${params.memberId || "self"}:${params.definitionId || params.slug}` });
+}
+
+/** `subagent.unpin` — remove the seat's pin. NEVER a row delete (§2.4). */
+export function unpinDefinition(params, o = {}) {
+  return writeVerb("subagent.unpin", {
+    memberId: params.memberId ? String(params.memberId) : undefined,
+    definitionId: params.definitionId ? String(params.definitionId) : undefined,
+    slug: params.slug ? String(params.slug) : undefined,
+  }, o);
+}
+
+/** `subagent.yank` — admin-scoped curation. Status flip, never a delete. */
+export function yankDefinition(params, o = {}) {
+  return writeVerb("subagent.yank", {
+    definitionId: params.definitionId ? String(params.definitionId) : undefined,
+    slug: params.slug ? String(params.slug) : undefined,
+    versionId: params.versionId ? String(params.versionId) : undefined,
+    reason: params.reason ? String(params.reason) : "",
+  }, o);
+}
+
+/**
+ * Replay queued offline writes, oldest first. Stops at the FIRST degraded
+ * failure (the server is down again — draining the rest would just re-queue
+ * them) but continues past a rejection (that entry is dead; dropping it is the
+ * only way the outbox ever empties, and the error is returned to the caller).
+ *
+ * @param {{agentRoot:string, cfg:object, fetchImpl?:Function, timeoutMs?:number, entries?:Array}} o
+ * @returns {Promise<{replayed:number, dropped:Array<object>, remaining:number, stopped:boolean}>}
+ */
+export async function flushOutbox(o = {}) {
+  const { listOutbox, removeOutbox } = await import("./lock.mjs");
+  const entries = Array.isArray(o.entries) ? o.entries : listOutbox(o.agentRoot);
+  let replayed = 0;
+  const dropped = [];
+  let stopped = false;
+  let i = 0;
+  for (; i < entries.length; i++) {
+    const e = entries[i];
+    const r = await postRpc(e.op, e.payload, o);
+    if (r.ok) { removeOutbox(e.path); replayed++; continue; }
+    if (r.degraded) { stopped = true; break; }
+    // A REJECTION (403/409/…) is dead on arrival: retrying forever would make the
+    // outbox unemptiable and hide the real error. Drop it and report it.
+    removeOutbox(e.path);
+    dropped.push({ op: e.op, error: r.error });
+  }
+  // Everything from the stop point onward is still queued.
+  return { replayed, dropped, remaining: entries.length - i, stopped };
+}