@cohortapp/agent-sdk 2.3.0

package/lib/org/integration-tools.mjs

@@ -0,0 +1,182 @@
+/**
+ * lib/org/integration-tools.mjs — the daemon's versioned cache of the workspace's
+ * GRANTED integration (plugin) tools, and its persistence to disk (SP5).
+ *
+ * THE GAP this closes: SP1 gave hq the `integration.toolsetVersion` (cheap ETag
+ * poll) + `integration.listAgentTools` (the authoritative granted-tool manifest,
+ * SCHEMAS ONLY — never plugin code or secrets) reads. This module is the agent
+ * half: it polls the version, refetches the manifest only when it changed, maps
+ * each granted tool into the canonical tool-surface descriptor, and — so per
+ * session `cohort-mcp` subprocesses and the native tool snapshot pick up the
+ * current set WITHOUT a daemon restart — persists the versioned set to
+ * `state/org/toolset.json`.
+ *
+ * Both SP1 endpoints are protocol METHODS (POST) not GET reads, so BOTH ride the
+ * client's `call(method, params, o)` — which returns a res frame `{ok, result}`.
+ * `call` is injected (deps) so tests never touch the network.
+ *
+ * Tool name uses the SP3/SP4 convention (`plugin__<slug>__<tool>`) so a tool is
+ * named IDENTICALLY across the in-app responder, the hq MCP server, and here.
+ * Execution proxies back to hq through `integration.invokeTool` (SP5) — the
+ * descriptor carries `{integration:{slug,tool}}` so `executeOrgTool` can send the
+ * right params.
+ *
+ * FAIL-OPEN like the rest of the org client: any transport/parse hiccup returns
+ * the last-good cache; a refresh never throws past the boundary.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/org/integration-tools
+ */
+
+"use strict";
+
+import { existsSync, mkdirSync, writeFileSync, renameSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/** In-memory cache: the current version + mapped tools + when we last fetched. */
+let cache = { version: 0, tools: [], fetchedAt: 0 };
+
+/**
+ * Resolve the agent root the same env-first way `resolveOrgToolConfig` /
+ * lib/agent-root do, so the long-lived daemon and a per-session subprocess agree
+ * on the `state/org/toolset.json` location. Fail-open: worst case is cwd.
+ * @param {string} [agentRoot]
+ * @returns {string}
+ */
+function resolveAgentRoot(agentRoot) {
+  return resolve(
+    agentRoot ||
+      process.env.COHORT_AGENT_ROOT ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd(),
+  );
+}
+
+/**
+ * The canonical cross-process cache path: `<agentRoot>/state/org/toolset.json`.
+ * The daemon WRITES it on refresh (Task 4); `getOrgTools()` + the native plane
+ * READ it (tool-surface.loadIntegrationToolsFromDisk). Shape:
+ * `{ version:number, tools:SurfaceTool[], fetchedAt:number }`.
+ * @param {string} [agentRoot]
+ * @returns {string}
+ */
+export function integrationToolsetPath(agentRoot) {
+  return join(resolveAgentRoot(agentRoot), "state", "org", "toolset.json");
+}
+
+/** Build the SP3/SP4 tool name; sanitized + capped at 64 chars. */
+function mcpName(slug, tool) {
+  return `plugin__${String(slug).replace(/[^a-z0-9]/gi, "_")}__${tool}`.slice(
+    0,
+    64,
+  );
+}
+
+/**
+ * Map a `listAgentTools` manifest entry → the canonical tool-surface descriptor
+ * (the SAME shape ORG_TOOLS uses), carrying an `integration:{slug,tool}` hint so
+ * `executeOrgTool` can proxy to `integration.invokeTool`.
+ * @param {object} t
+ * @returns {object}
+ */
+export function toSurfaceTool(t) {
+  return {
+    name: mcpName(t.slug, t.name),
+    title: t.name,
+    description: `${t.slug}: ${t.description ?? ""}`.trim(),
+    input_schema:
+      t.inputSchema && typeof t.inputSchema === "object"
+        ? t.inputSchema
+        : { type: "object" },
+    access: "write",
+    binding: { kind: "rpc", method: "integration.invokeTool" },
+    // Carried so executeOrgTool passes {slug, tool} to invokeTool (Task 3).
+    integration: { slug: t.slug, tool: t.name },
+  };
+}
+
+/**
+ * Cheap version poll + conditional refetch. `deps` inject `call` (+ optional
+ * `agentMemberId`, `now`) for tests. Both SP1 endpoints are protocol METHODS, so
+ * both go through `call` (res frame `{ok, result}`); a transport failure or a
+ * bad shape returns the last-good cache. Returns the (possibly unchanged) cache.
+ *
+ * @param {object} deps - { call, agentMemberId?, now? }
+ * @returns {Promise<{version:number, tools:object[], fetchedAt:number}>}
+ */
+export async function maybeRefresh({ call, agentMemberId, now } = {}) {
+  if (typeof call !== "function") return cache;
+  const vres = await call("integration.toolsetVersion", {}).catch(() => null);
+  const version = vres && vres.result ? vres.result.version : undefined;
+  if (typeof version !== "number") return cache;
+  // A matching version with a populated set is a no-op (the cheap poll's payoff).
+  if (version === cache.version && cache.tools.length) return cache;
+
+  const tres = await call(
+    "integration.listAgentTools",
+    agentMemberId ? { agentMemberId } : {},
+  ).catch(() => null);
+  const tools = tres && tres.result ? tres.result.tools : undefined;
+  if (!Array.isArray(tools)) return cache;
+
+  cache = {
+    version,
+    tools: tools.map(toSurfaceTool),
+    fetchedAt: typeof now === "function" ? now() : Date.now(),
+  };
+  return cache;
+}
+
+/** The current mapped integration tools (surface-shaped). */
+export function getIntegrationTools() {
+  return cache.tools;
+}
+
+/** The current cached toolset version (0 before the first successful refresh). */
+export function currentToolsetVersion() {
+  return cache.version;
+}
+
+/**
+ * Persist the versioned tool set to `state/org/toolset.json` (atomic write via a
+ * temp file + rename) so per-session subprocesses + the native snapshot read the
+ * current set. Fail-open: never throws (a persistence hiccup must not break the
+ * beat that calls it).
+ * @param {string} agentRoot
+ * @param {{version:number, tools:object[]}} snapshot
+ * @returns {boolean} true when written
+ */
+export function writeIntegrationToolsToDisk(agentRoot, snapshot) {
+  try {
+    const path = integrationToolsetPath(agentRoot);
+    const dir = join(resolveAgentRoot(agentRoot), "state", "org");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const doc = {
+      version: Number(snapshot && snapshot.version) || 0,
+      tools: Array.isArray(snapshot && snapshot.tools) ? snapshot.tools : [],
+      fetchedAt: Date.now(),
+    };
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(doc, null, 2));
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Reset the in-memory cache — test-only. */
+export function _resetForTest() {
+  cache = { version: 0, tools: [], fetchedAt: 0 };
+}
+
+export default {
+  maybeRefresh,
+  getIntegrationTools,
+  currentToolsetVersion,
+  writeIntegrationToolsToDisk,
+  integrationToolsetPath,
+  toSurfaceTool,
+};

package/lib/org/integration-tools.test.mjs

@@ -0,0 +1,160 @@
+/**
+ * integration-tools.test.mjs — the versioned integration-tools cache (SP5).
+ *
+ * Hermetic: the hq fetch rides an injected `call` (no network). Disk tests write
+ * into a fresh mkdtemp root. Run: node --test lib/org/integration-tools.test.mjs
+ */
+
+"use strict";
+
+import { test, beforeEach, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  maybeRefresh,
+  getIntegrationTools,
+  currentToolsetVersion,
+  writeIntegrationToolsToDisk,
+  integrationToolsetPath,
+  _resetForTest,
+} from "./integration-tools.mjs";
+
+/** A fake `call` that answers the two SP1 read-methods from a canned set. */
+function makeCall({ version, tools }) {
+  const calls = [];
+  const call = async (method, params) => {
+    calls.push({ method, params });
+    if (method === "integration.toolsetVersion") {
+      return { ok: true, result: { version, updatedAt: null } };
+    }
+    if (method === "integration.listAgentTools") {
+      return { ok: true, result: { version, tools } };
+    }
+    return { ok: false, error: { code: "NOT_FOUND", message: "?" } };
+  };
+  return { call, calls };
+}
+
+const TOOLS_V5 = [
+  {
+    slug: "open-meteo",
+    name: "forecast",
+    description: "Get the forecast",
+    inputSchema: { type: "object", properties: { city: { type: "string" } } },
+    outputSchema: { type: "object" },
+  },
+];
+
+const roots = [];
+function freshRoot() {
+  const r = mkdtempSync(join(tmpdir(), "int-tools-"));
+  roots.push(r);
+  return r;
+}
+
+beforeEach(() => _resetForTest());
+after(() => {
+  for (const r of roots) {
+    try {
+      rmSync(r, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+});
+
+test("first refresh populates the cache from version + tools", async () => {
+  const { call, calls } = makeCall({ version: 5, tools: TOOLS_V5 });
+  const cache = await maybeRefresh({ call });
+  assert.equal(cache.version, 5);
+  assert.equal(currentToolsetVersion(), 5);
+  const got = getIntegrationTools();
+  assert.equal(got.length, 1);
+  const t = got[0];
+  assert.equal(t.name, "plugin__open_meteo__forecast");
+  assert.equal(t.access, "write");
+  assert.equal(t.binding.kind, "rpc");
+  assert.equal(t.binding.method, "integration.invokeTool");
+  assert.deepEqual(t.integration, { slug: "open-meteo", tool: "forecast" });
+  assert.deepEqual(t.input_schema, TOOLS_V5[0].inputSchema);
+  // Both reads happened on the first refresh.
+  assert.deepEqual(
+    calls.map((c) => c.method),
+    ["integration.toolsetVersion", "integration.listAgentTools"],
+  );
+});
+
+test("same version → no refetch of listAgentTools", async () => {
+  const first = makeCall({ version: 5, tools: TOOLS_V5 });
+  await maybeRefresh({ call: first.call });
+  const second = makeCall({ version: 5, tools: TOOLS_V5 });
+  await maybeRefresh({ call: second.call });
+  assert.deepEqual(
+    second.calls.map((c) => c.method),
+    ["integration.toolsetVersion"],
+    "a matching version polls the cheap version read only",
+  );
+});
+
+test("a bumped version refetches + swaps in the new tools", async () => {
+  await maybeRefresh(makeCall({ version: 5, tools: TOOLS_V5 }));
+  const v6Tools = [
+    { slug: "stripe", name: "list_charges", description: "List charges", inputSchema: {} },
+  ];
+  await maybeRefresh(makeCall({ version: 6, tools: v6Tools }));
+  assert.equal(currentToolsetVersion(), 6);
+  const names = getIntegrationTools().map((t) => t.name);
+  assert.deepEqual(names, ["plugin__stripe__list_charges"]);
+});
+
+test("passes agentMemberId through to listAgentTools when given", async () => {
+  const { call, calls } = makeCall({ version: 1, tools: TOOLS_V5 });
+  await maybeRefresh({ call, agentMemberId: "wm_agent" });
+  const list = calls.find((c) => c.method === "integration.listAgentTools");
+  assert.deepEqual(list.params, { agentMemberId: "wm_agent" });
+});
+
+test("a non-numeric version leaves the cache untouched (fail-open)", async () => {
+  const call = async () => ({ ok: true, result: {} }); // no version
+  const cache = await maybeRefresh({ call });
+  assert.equal(cache.version, 0);
+  assert.equal(getIntegrationTools().length, 0);
+});
+
+test("a throwing call fails open to the existing cache", async () => {
+  await maybeRefresh(makeCall({ version: 2, tools: TOOLS_V5 }));
+  const boom = async () => {
+    throw new Error("network down");
+  };
+  const cache = await maybeRefresh({ call: boom });
+  assert.equal(cache.version, 2, "kept the last-good cache");
+  assert.equal(getIntegrationTools().length, 1);
+});
+
+test("the mcp name sanitizes non-alnum slug chars and caps at 64", async () => {
+  const tools = [
+    { slug: "My.Weird-Slug", name: "do_thing", description: "d", inputSchema: {} },
+  ];
+  await maybeRefresh(makeCall({ version: 1, tools }));
+  const [t] = getIntegrationTools();
+  assert.equal(t.name, "plugin__My_Weird_Slug__do_thing");
+  assert.ok(t.name.length <= 64);
+});
+
+test("writeIntegrationToolsToDisk persists {version,tools} atomically", async () => {
+  const root = freshRoot();
+  await maybeRefresh(makeCall({ version: 9, tools: TOOLS_V5 }));
+  writeIntegrationToolsToDisk(root, {
+    version: currentToolsetVersion(),
+    tools: getIntegrationTools(),
+  });
+  const p = integrationToolsetPath(root);
+  assert.ok(existsSync(p), "toolset.json exists");
+  const doc = JSON.parse(readFileSync(p, "utf8"));
+  assert.equal(doc.version, 9);
+  assert.equal(doc.tools.length, 1);
+  assert.equal(doc.tools[0].name, "plugin__open_meteo__forecast");
+});

package/lib/org/keys.mjs

@@ -0,0 +1,131 @@
+/**
+ * lib/org/keys.mjs — device keypair for the Cohort org binding.
+ *
+ * Every paired agent owns one long-lived Ed25519 device key. The PUBLIC key is
+ * presented in the pairing handshake (`pairing.request { pubkey }`) and pinned
+ * by peers / the verify layer; the PRIVATE key never leaves the machine and is
+ * used to sign outbound material (and, symmetrically, to let the detective layer
+ * verify signatures the server makes over snapshots — see lib/org/verify.mjs).
+ *
+ * The private key is stored 0600 under `state/org/` and loaded-or-created on
+ * first use, so a freshly-provisioned agent self-bootstraps a stable identity
+ * that survives restarts. Keys are SubjectPublicKeyInfo / PKCS#8 PEM so they are
+ * portable across `node:crypto`, OpenSSL, and any Ed25519 verifier.
+ *
+ * Pure node:crypto + node:fs (atomic write via lib/fs-atomic). Fully testable:
+ * `ensureDeviceKey` is the only fs-touching entry point; `verifySignature` and
+ * the returned `sign` are pure over their inputs.
+ *
+ * @module lib/org/keys
+ */
+
+"use strict";
+
+import {
+  generateKeyPairSync,
+  createPrivateKey,
+  createPublicKey,
+  sign as edSign,
+  verify as edVerify,
+} from "node:crypto";
+import { readFileSync, existsSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+
+import { writeFileAtomic } from "../fs-atomic.mjs";
+
+/** Relative location of the device private key under the agent root. */
+const KEY_DIR = join("state", "org");
+const PRIV_FILE = "device-key.pem";
+
+/** Resolve the on-disk path of the private key PEM for an agent root. */
+function privKeyPath(agentRoot) {
+  return join(String(agentRoot || "."), KEY_DIR, PRIV_FILE);
+}
+
+/**
+ * Derive the public-key PEM (SPKI) from a private-key PEM (PKCS#8). Pure.
+ * @param {string} privateKeyPem
+ * @returns {string}
+ */
+function publicPemFromPrivate(privateKeyPem) {
+  const pub = createPublicKey(createPrivateKey(privateKeyPem));
+  return pub.export({ type: "spki", format: "pem" }).toString();
+}
+
+/**
+ * Generate a fresh Ed25519 keypair as PEM strings. Pure.
+ * @returns {{publicKeyPem:string, privateKeyPem:string}}
+ */
+export function generateDeviceKey() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  return {
+    publicKeyPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  };
+}
+
+/**
+ * Sign a buffer with an Ed25519 private-key PEM. Ed25519 takes no digest
+ * algorithm (the second arg to `crypto.sign` is null). Returns base64. Pure.
+ * @param {string} privateKeyPem PKCS#8 PEM
+ * @param {Buffer|Uint8Array|string} data
+ * @returns {string} base64 signature
+ */
+export function signWith(privateKeyPem, data) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+  const key = createPrivateKey(privateKeyPem);
+  return edSign(null, buf, key).toString("base64");
+}
+
+/**
+ * Verify an Ed25519 signature over `data` against a public-key PEM. Never
+ * throws — a malformed key/signature returns false (the detective layer treats
+ * "can't verify" as "don't trust"). Pure.
+ * @param {string} publicKeyPem SPKI PEM
+ * @param {Buffer|Uint8Array|string} data
+ * @param {string} sigB64 base64 signature
+ * @returns {boolean}
+ */
+export function verifySignature(publicKeyPem, data, sigB64) {
+  try {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    const sig = Buffer.from(String(sigB64 || ""), "base64");
+    if (sig.length === 0) return false;
+    const key = createPublicKey(publicKeyPem);
+    return edVerify(null, buf, key, sig);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load the agent's device key, creating it on first use. The private key is
+ * stored 0600 under `state/org/device-key.pem`; only the public key and a bound
+ * `sign(buf)->base64` closure are returned (the private PEM never escapes).
+ *
+ * Idempotent and crash-safe: the create path writes atomically (temp→fsync→
+ * rename) with mode 0600, then re-chmods defensively in case a pre-existing key
+ * had looser perms.
+ *
+ * @param {string} agentRoot absolute path to the agent instance root
+ * @returns {{publicKeyPem:string, sign:(data:(Buffer|Uint8Array|string))=>string}}
+ */
+export function ensureDeviceKey(agentRoot) {
+  const path = privKeyPath(agentRoot);
+  let privateKeyPem;
+  if (existsSync(path)) {
+    privateKeyPem = readFileSync(path, "utf8");
+    // Defensive: tighten perms if a previous writer left them loose.
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  } else {
+    const kp = generateDeviceKey();
+    privateKeyPem = kp.privateKeyPem;
+    writeFileAtomic(path, privateKeyPem, { mode: 0o600 });
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  }
+  const publicKeyPem = publicPemFromPrivate(privateKeyPem);
+  return {
+    publicKeyPem,
+    sign: (data) => signWith(privateKeyPem, data),
+  };
+}

package/lib/org/keys.test.mjs

@@ -0,0 +1,92 @@
+/**
+ * keys.test.mjs — device keypair crypto round-trips + tamper rejection.
+ * Run: node --test lib/org/keys.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, statSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  generateDeviceKey,
+  signWith,
+  verifySignature,
+  ensureDeviceKey,
+} from "./keys.mjs";
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), "cohort-keys-"));
+}
+
+test("generateDeviceKey: emits SPKI public + PKCS#8 private PEM", () => {
+  const { publicKeyPem, privateKeyPem } = generateDeviceKey();
+  assert.match(publicKeyPem, /-----BEGIN PUBLIC KEY-----/);
+  assert.match(privateKeyPem, /-----BEGIN PRIVATE KEY-----/);
+});
+
+test("sign/verify: round-trip succeeds", () => {
+  const { publicKeyPem, privateKeyPem } = generateDeviceKey();
+  const msg = Buffer.from("the org snapshot bytes");
+  const sig = signWith(privateKeyPem, msg);
+  assert.equal(typeof sig, "string");
+  assert.equal(verifySignature(publicKeyPem, msg, sig), true);
+  // string payload accepted too
+  assert.equal(verifySignature(publicKeyPem, "the org snapshot bytes", sig), true);
+});
+
+test("verify: rejects tampered message", () => {
+  const { publicKeyPem, privateKeyPem } = generateDeviceKey();
+  const sig = signWith(privateKeyPem, Buffer.from("original"));
+  assert.equal(verifySignature(publicKeyPem, Buffer.from("tampered"), sig), false);
+});
+
+test("verify: rejects signature from a different key", () => {
+  const a = generateDeviceKey();
+  const b = generateDeviceKey();
+  const msg = Buffer.from("payload");
+  const sig = signWith(a.privateKeyPem, msg);
+  assert.equal(verifySignature(b.publicKeyPem, msg, sig), false);
+});
+
+test("verify: never throws on garbage inputs", () => {
+  assert.equal(verifySignature("not a pem", Buffer.from("x"), "AAAA"), false);
+  assert.equal(verifySignature(generateDeviceKey().publicKeyPem, Buffer.from("x"), ""), false);
+  assert.equal(verifySignature(generateDeviceKey().publicKeyPem, Buffer.from("x"), "!!!notb64"), false);
+});
+
+test("ensureDeviceKey: creates 0600 key under state/org and returns signer", () => {
+  const root = tmpRoot();
+  try {
+    const { publicKeyPem, sign } = ensureDeviceKey(root);
+    assert.match(publicKeyPem, /BEGIN PUBLIC KEY/);
+    const path = join(root, "state", "org", "device-key.pem");
+    assert.equal(existsSync(path), true);
+    // perms must be owner-only (0600)
+    const mode = statSync(path).mode & 0o777;
+    assert.equal(mode, 0o600);
+    // the returned signer signs verifiably against the returned public key
+    const sig = sign(Buffer.from("hello"));
+    assert.equal(verifySignature(publicKeyPem, Buffer.from("hello"), sig), true);
+    // private PEM is on disk but never returned
+    assert.match(readFileSync(path, "utf8"), /BEGIN PRIVATE KEY/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("ensureDeviceKey: idempotent — reload returns the SAME identity", () => {
+  const root = tmpRoot();
+  try {
+    const first = ensureDeviceKey(root);
+    const second = ensureDeviceKey(root);
+    assert.equal(first.publicKeyPem, second.publicKeyPem);
+    // a signature from the first loader verifies under the second's public key
+    const sig = first.sign(Buffer.from("cross"));
+    assert.equal(verifySignature(second.publicKeyPem, Buffer.from("cross"), sig), true);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});