@cohortapp/agent-sdk 2.3.0

package/lib/org/doctor.mjs

@@ -0,0 +1,212 @@
+/**
+ * lib/org/doctor.mjs — Cohort connectivity probes for `cohort doctor`.
+ *
+ * Replaces the presence-only org block in bin/maestro.mjs doctor() with REAL
+ * connectivity checks (spec 2026-07-21 §5). Pure + injectable (fetchImpl,
+ * clock, env) so every outcome is unit-testable without a network.
+ *
+ * Probes (8s budget each, sequential; fail-open to `warn` unless noted):
+ *   1. Config resolution (env + config/org.yaml via configFromAgent).
+ *      Absent/disabled → a single `ok` "not enrolled" line and STOP — doctor
+ *      stays useful offline/pre-enrollment.
+ *   2. GET {base}/api/v1/directory — issued through fetchImpl DIRECTLY (the
+ *      client's read() does not surface response headers): reachability +
+ *      latency. 401/403 → FAIL "token rejected". Unreachable → FAIL (an
+ *      enrolled agent that cannot reach its org is broken). Drift signal: the
+ *      `x-org-protocol` RESPONSE header hq's phase 1 adds — present and ≠
+ *      local PROTOCOL_VERSION → warn "protocol drift"; absent → warn "server
+ *      does not report protocol version (hq predates 2.0 phase 1)".
+ *   3. RPC `messaging.channels {}` — THE pairing probe: hq's actingMemberId()
+ *      throws FORBIDDEN_SCOPE for an unpaired key, the zod schema accepts {},
+ *      and messaging.read is in DEFAULT_AGENT_SCOPES. ok → paired (channel
+ *      count; best-effort member-slug garnish via fetchSelfProfile when an
+ *      identity hint resolves — a missing hint never degrades the probe).
+ *      FORBIDDEN_SCOPE → FAIL "key not paired to a member".
+ *      (`profile.get {}` cannot serve here: hq's handler requires memberId
+ *      and BAD_REQUESTs every empty-params caller, paired or not.)
+ *   4. config/orgmail.yaml present + email family vendored → one
+ *      `email.inbox {limit:1}` probe → mailbox reachable (surface the address).
+ *   5. config/orgmail.yaml present but the vendored protocol LACKS the email
+ *      family → warn "SDK predates workspace email".
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/org/doctor
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PROTOCOL_VERSION, methodDef } from "./protocol.mjs";
+import { loadOrgConfig, configFromAgent, call, fetchSelfProfile } from "./client.mjs";
+
+const PROBE_TIMEOUT_MS = 8000;
+
+/** Join an org origin + a /v1 path the same way the client transport does. */
+function v1Url(base, path) {
+  const b = String(base).replace(/\/+$/, "");
+  if (/\/(?:api\/)?v1$/.test(b)) return `${b}/${path}`;
+  return `${b}/api/v1/${path}`;
+}
+
+/** Read one response header across real fetch Responses and plain fakes. */
+function readHeader(res, name) {
+  try {
+    if (res && res.headers && typeof res.headers.get === "function") return res.headers.get(name) || undefined;
+    if (res && res.headers && typeof res.headers === "object") return res.headers[name] || res.headers[name.toLowerCase()];
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+/** Identity hint for the probe-3 garnish: env → config/agent.json email. */
+function identityHints(agentRoot, env) {
+  const hints = { agentId: env.COHORT_AGENT_ID ? String(env.COHORT_AGENT_ID) : "", emailHint: "" };
+  if (env.COHORT_AGENT_EMAIL) {
+    hints.emailHint = String(env.COHORT_AGENT_EMAIL);
+    return hints;
+  }
+  try {
+    const p = join(agentRoot, "config", "agent.json");
+    if (existsSync(p)) {
+      const doc = JSON.parse(readFileSync(p, "utf8"));
+      if (doc && (doc.agentEmail || doc.email)) hints.emailHint = String(doc.agentEmail || doc.email);
+    }
+  } catch {
+    /* hints are best-effort */
+  }
+  return hints;
+}
+
+/**
+ * Run the Cohort connectivity probes.
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {Function} [o.fetchImpl]  injectable fetch (tests)
+ * @param {object} [o.env]          injectable env (tests; default process.env)
+ * @param {() => number} [o.now]    injectable clock for latency (tests)
+ * @returns {Promise<Array<{level:"ok"|"warn"|"fail", msg:string}>>}
+ */
+export async function checkOrgConnectivity(o = {}) {
+  const agentRoot = o.agentRoot || process.cwd();
+  const env = o.env || process.env;
+  const now = typeof o.now === "function" ? o.now : Date.now;
+  const results = [];
+
+  // ── 1. config resolution ─────────────────────────────────────────────────
+  const cfg = configFromAgent(loadOrgConfig(agentRoot));
+  const base = cfg.base || (env.COHORT_BASE ? String(env.COHORT_BASE).replace(/\/+$/, "") : "");
+  if (!cfg.enabled && !base) {
+    results.push({ level: "ok", msg: "Org plane: not enrolled (config/org.yaml absent/disabled) — `cohort setup --only org` to enroll" });
+    return results;
+  }
+  if (!cfg.token) {
+    results.push({ level: "fail", msg: "Org plane enrolled but NO token resolved — set COHORT_API_TOKEN or re-run `cohort setup --only org`" });
+    return results;
+  }
+  results.push({ level: "ok", msg: `Org enrollment resolved (base ${base}${cfg.orgId ? `, org ${cfg.orgId}` : ""})` });
+
+  const f = typeof o.fetchImpl === "function" ? o.fetchImpl : (typeof fetch === "function" ? fetch : null);
+  if (!f) {
+    results.push({ level: "warn", msg: "no fetch available in this runtime — skipping live probes" });
+    return results;
+  }
+
+  // ── 2. reachability + latency + protocol-drift header ────────────────────
+  let dirRes = null;
+  const t0 = now();
+  try {
+    const ctrl = typeof AbortController === "function" ? new AbortController() : null;
+    const timer = ctrl ? setTimeout(() => ctrl.abort(), PROBE_TIMEOUT_MS) : null;
+    try {
+      dirRes = await f(v1Url(base, "directory"), {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${cfg.token}`,
+          "x-org-protocol": String(PROTOCOL_VERSION),
+          ...(cfg.orgId ? { "x-org-id": String(cfg.orgId) } : {}),
+        },
+        signal: ctrl ? ctrl.signal : undefined,
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  } catch {
+    dirRes = null;
+  }
+  const latencyMs = now() - t0;
+
+  if (!dirRes) {
+    results.push({ level: "fail", msg: `Cohort unreachable at ${base} (directory probe timed out/failed) — an enrolled agent that cannot reach its org is broken` });
+    return results;
+  }
+  if (dirRes.status === 401 || dirRes.status === 403) {
+    results.push({ level: "fail", msg: "Org token rejected (401/403) — re-mint the key in Cohort → Settings → API keys" });
+    return results;
+  }
+  if (!dirRes.ok) {
+    results.push({ level: "warn", msg: `directory read returned HTTP ${dirRes.status} — server reachable but unhealthy` });
+  } else {
+    results.push({ level: "ok", msg: `Cohort reachable (directory ${latencyMs}ms)` });
+  }
+
+  const serverProto = readHeader(dirRes, "x-org-protocol");
+  if (serverProto === undefined || serverProto === null || serverProto === "") {
+    results.push({ level: "warn", msg: "server does not report protocol version (hq predates 2.0 phase 1)" });
+  } else if (String(serverProto) !== String(PROTOCOL_VERSION)) {
+    results.push({ level: "warn", msg: `protocol drift — server x-org-protocol ${serverProto} ≠ local ${PROTOCOL_VERSION}; run \`cohort upgrade\`` });
+  } else {
+    results.push({ level: "ok", msg: `protocol version aligned (v${PROTOCOL_VERSION})` });
+  }
+
+  // ── 3. pairing probe: messaging.channels {} ──────────────────────────────
+  const callOpts = { base, token: cfg.token, orgId: cfg.orgId, fetchImpl: o.fetchImpl };
+  const chan = await call("messaging.channels", {}, callOpts);
+  if (chan.ok) {
+    const list = chan.result && (Array.isArray(chan.result.channels) ? chan.result.channels : Array.isArray(chan.result) ? chan.result : null);
+    let garnish = "";
+    const hints = identityHints(agentRoot, env);
+    if (hints.agentId || hints.emailHint) {
+      try {
+        const who = await fetchSelfProfile({
+          base,
+          apiKey: cfg.token,
+          orgId: cfg.orgId,
+          agentId: hints.agentId || undefined,
+          emailHint: hints.emailHint || undefined,
+          fetchImpl: o.fetchImpl,
+        });
+        if (who && who.ok && who.result && who.result.slug) garnish = ` — member ${who.result.slug}`;
+      } catch {
+        /* garnish is best-effort; never degrade the probe */
+      }
+    }
+    results.push({ level: "ok", msg: `key paired to a workforce member (${list ? `${list.length} channel(s)` : "channels listed"})${garnish}` });
+  } else if (chan.error && chan.error.code === "FORBIDDEN_SCOPE") {
+    results.push({ level: "fail", msg: "key not paired to a member — pair it in Cohort → Settings → API keys, or `cohort pair`" });
+  } else {
+    results.push({ level: "warn", msg: `pairing probe inconclusive (${chan.error?.code || "?"}: ${chan.error?.message || "no detail"})` });
+  }
+
+  // ── 4/5. workspace mailbox ───────────────────────────────────────────────
+  const orgmailGate = existsSync(join(agentRoot, "config", "orgmail.yaml"));
+  if (orgmailGate) {
+    if (!methodDef("email.inbox")) {
+      results.push({ level: "warn", msg: "config/orgmail.yaml present but this SDK predates workspace email — `npm i -g @cohortapp/agent-sdk@latest`" });
+    } else {
+      const inbox = await call("email.inbox", { limit: 1 }, callOpts);
+      if (inbox.ok) {
+        const addr = inbox.result?.mailbox?.address || "";
+        results.push({ level: "ok", msg: `workspace mailbox reachable${addr ? ` (${addr})` : ""}` });
+      } else {
+        results.push({ level: "warn", msg: `workspace mailbox probe: ${inbox.error?.code || "?"} — ${inbox.error?.message || "no detail"} (admin: Cohort → Settings → Email)` });
+      }
+    }
+  }
+
+  return results;
+}
+
+export default { checkOrgConnectivity };

package/lib/org/doctor.test.mjs

@@ -0,0 +1,212 @@
+/**
+ * doctor.test.mjs — Cohort connectivity probes (lib/org/doctor.mjs).
+ * All five probe outcomes with a stubbed fetch: not-enrolled short-circuit,
+ * token-rejected fail, unreachable fail, drift-header warn/absent/aligned,
+ * paired-ok vs unpaired-FORBIDDEN_SCOPE, and the orgmail mailbox probes.
+ * Run: node --test lib/org/doctor.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { checkOrgConnectivity } from "./doctor.mjs";
+import { PROTOCOL_VERSION } from "./protocol.mjs";
+
+// Ambient COHORT_* vars must not leak in.
+for (const k of ["COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_ORG_ID", "COHORT_BASE", "COHORT_API_URL", "COHORT_AGENT_ID", "COHORT_AGENT_EMAIL"]) delete process.env[k];
+
+function root({ enrolled = true, orgmail = false } = {}) {
+  const r = mkdtempSync(join(tmpdir(), "org-doctor-"));
+  mkdirSync(join(r, "config"), { recursive: true });
+  if (enrolled) {
+    writeFileSync(
+      join(r, "config", "org.yaml"),
+      ["org:", "  cohort:", "    enabled: true", "    base: https://org.example", "    orgId: acme", "    token: tok-doc"].join("\n"),
+    );
+  }
+  if (orgmail) writeFileSync(join(r, "config", "orgmail.yaml"), "orgmail:\n  enabled: true\n");
+  return r;
+}
+
+/**
+ * A routed fetch stub. `routes` maps a URL suffix to a responder
+ * ({status, body, headers}) or a function of (url, init).
+ */
+function stubFetch(routes) {
+  const calls = [];
+  const fn = async (url, init) => {
+    const u = String(url);
+    calls.push({ url: u, init: init || {} });
+    for (const [suffix, r] of Object.entries(routes)) {
+      if (u.endsWith(suffix)) {
+        const spec = typeof r === "function" ? r(u, init) : r;
+        if (spec === "throw") throw new Error("network down");
+        const status = spec.status ?? 200;
+        return {
+          ok: status >= 200 && status < 300,
+          status,
+          headers: { get: (k) => (spec.headers ? spec.headers[k.toLowerCase()] : undefined) },
+          json: async () => spec.body ?? {},
+        };
+      }
+    }
+    throw new Error(`unrouted ${u}`);
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+const DIR_OK = { status: 200, body: { members: [] }, headers: { "x-org-protocol": String(PROTOCOL_VERSION) } };
+const CHANNELS_OK = { status: 200, body: { ok: true, result: { channels: [{ id: "c1" }, { id: "c2" }] } } };
+
+const levelsOf = (rs) => rs.map((r) => r.level);
+const msgs = (rs) => rs.map((r) => r.msg).join("\n");
+
+test("probe 1: not enrolled → single ok line, no network", async () => {
+  const r = root({ enrolled: false });
+  const f = stubFetch({});
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  assert.equal(rs.length, 1);
+  assert.equal(rs[0].level, "ok");
+  assert.match(rs[0].msg, /not enrolled/);
+  assert.equal(f.calls.length, 0);
+  rmSync(r, { recursive: true, force: true });
+});
+
+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 });
+  let t = 1000;
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {}, now: () => (t += 40) });
+  assert.deepEqual(levelsOf(rs), ["ok", "ok", "ok", "ok"]);
+  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\)\)/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 2: 401 → FAIL token rejected, remaining probes skipped", async () => {
+  const r = root();
+  const f = stubFetch({ "/api/v1/directory": { status: 401, body: {} } });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  assert.equal(rs.at(-1).level, "fail");
+  assert.match(rs.at(-1).msg, /token rejected .*Settings → API keys/i);
+  assert.equal(f.calls.length, 1, "no further probes after a rejected token");
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 2: unreachable → FAIL (enrolled agent that cannot reach its org is broken)", async () => {
+  const r = root();
+  const f = stubFetch({ "/api/v1/directory": "throw" });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  assert.equal(rs.at(-1).level, "fail");
+  assert.match(rs.at(-1).msg, /unreachable/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 2 drift: header present ≠ local → warn `cohort upgrade`", async () => {
+  const r = root();
+  const f = stubFetch({
+    "/api/v1/directory": { status: 200, body: {}, headers: { "x-org-protocol": "99" } },
+    "/api/v1/messaging.channels": CHANNELS_OK,
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const drift = rs.find((x) => /protocol drift/.test(x.msg));
+  assert.ok(drift, "drift line present");
+  assert.equal(drift.level, "warn");
+  assert.match(drift.msg, /99 ≠ local 1/);
+  assert.match(drift.msg, /cohort upgrade/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 2 drift: header ABSENT → warn hq-predates-phase-1", async () => {
+  const r = root();
+  const f = stubFetch({
+    "/api/v1/directory": { status: 200, body: {} }, // no headers at all
+    "/api/v1/messaging.channels": CHANNELS_OK,
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const absent = rs.find((x) => /does not report protocol version/.test(x.msg));
+  assert.ok(absent);
+  assert.equal(absent.level, "warn");
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 3: FORBIDDEN_SCOPE from messaging.channels → FAIL not-paired", async () => {
+  const r = root();
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": { status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "not paired to a workforce member" } } },
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const pair = rs.find((x) => /not paired/.test(x.msg));
+  assert.ok(pair);
+  assert.equal(pair.level, "fail");
+  assert.match(pair.msg, /cohort pair/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 3 garnish: identity hint appends the member slug; hint failure never degrades", async () => {
+  const r = root();
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/org/members/astra?orgId=acme": { status: 200, body: { slug: "astra", displayName: "Astra" } },
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: { COHORT_AGENT_ID: "astra" } });
+  const paired = rs.find((x) => /paired to a workforce member/.test(x.msg));
+  assert.match(paired.msg, /member astra/);
+  // hint present but whoami fails → still ok, no garnish
+  const f2 = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/org/members/astra?orgId=acme": { status: 404, body: {} },
+  });
+  const rs2 = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f2, env: { COHORT_AGENT_ID: "astra" } });
+  const paired2 = rs2.find((x) => /paired to a workforce member/.test(x.msg));
+  assert.equal(paired2.level, "ok");
+  assert.ok(!/member astra/.test(paired2.msg));
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 4: orgmail gate + family vendored → mailbox probe surfaces the address", async () => {
+  const r = root({ orgmail: true });
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/email.inbox": { status: 200, body: { ok: true, result: { mailbox: { address: "astra@agents.example" }, messages: [] } } },
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const mail = rs.find((x) => /workspace mailbox/.test(x.msg));
+  assert.equal(mail.level, "ok");
+  assert.match(mail.msg, /astra@agents\.example/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("probe 4: mailbox probe failure warns with the admin remedy (never a fail)", async () => {
+  const r = root({ orgmail: true });
+  const f = stubFetch({
+    "/api/v1/directory": DIR_OK,
+    "/api/v1/messaging.channels": CHANNELS_OK,
+    "/api/v1/email.inbox": { status: 404, body: { ok: false, error: { code: "NOT_FOUND", message: "no mailbox for member" } } },
+  });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  const mail = rs.find((x) => /workspace mailbox probe/.test(x.msg));
+  assert.equal(mail.level, "warn");
+  assert.match(mail.msg, /Settings → Email/);
+  rmSync(r, { recursive: true, force: true });
+});
+
+test("no orgmail gate file → no mailbox probe at all", async () => {
+  const r = root();
+  const f = stubFetch({ "/api/v1/directory": DIR_OK, "/api/v1/messaging.channels": CHANNELS_OK });
+  const rs = await checkOrgConnectivity({ agentRoot: r, fetchImpl: f, env: {} });
+  assert.ok(!rs.some((x) => /mailbox/.test(x.msg)));
+  assert.ok(!f.calls.some((c) => c.url.includes("email.inbox")));
+  rmSync(r, { recursive: true, force: true });
+});