@crawlcheck/sdk 1.11.0 → 1.12.0

package/README.md

@@ -160,6 +160,25 @@ const client = withPreflight(new Client(...), new CrawlCheck(), {
 
 The default policy (`CONTINUITY_DEFAULT_POLICY`) pauses added, changed-description, changed-schema and changed-annotation tools, refreshes expired evidence, pauses on an unreachable server or service, a truncated or unreadable tool list, a stale baseline or an unexpected policy version, and denies on an invalid signature, an unpublished or retired key, or a different server. Override any effect; the integrity classes stay `deny` unless you set `allow_integrity_override`, and the record says so. Exceptions (`{ tool, class, until, by, reason }`) proceed as `proceed_recorded`, never as an ordinary pass. Every record (`crawlcheck-continuity-record`) names the baseline, what was observed, each event, the policy's sha256, the mode, the outcome and its own `record_sha256`. It states interface continuity at the check point: not code attestation, not a judgement that a tool is harmless, not user authorisation. `continuityCheck(lock, tools, opts)` and `continuityFailure(cls, opts)` run the same logic without a client; the Python SDK reproduces every record byte for byte (shared golden file `test/fixtures/continuity.json`). Other client stacks use the bare hooks: `mcpPreflight(cc, opts)` returns `beforeConnect`, `afterConnect` and `beforeToolCall`. A runnable demo is in `examples/mcp-preflight-demo.mjs`.
 
+### Continuity in your agent framework (1.12.0)
+
+The same check where the framework fetches an MCP server's tool list, against your approved lockfile. No CrawlCheck call, no key, no new dependency: each adapter uses the framework you already have.
+
+```js
+import { withContinuity, loadMcpToolsWithContinuity } from "@crawlcheck/sdk";
+
+// OpenAI Agents SDK (@openai/agents)
+const server = new MCPServerStreamableHttp({ url });
+await server.connect();
+const agent = new Agent({ name: "a", instructions: "...", mcpServers: [withContinuity(server, lock, { mode: "observe" })] });
+
+// LangChain (@langchain/mcp-adapters)
+const client = new MultiServerMCPClient({ mcpServers: { shop: { url } } });
+const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" });
+```
+
+`observe` records every difference (`console.warn`, `onRecord`, `server.continuity.records` / `tools.continuity.records`) and passes the tools through. `review` pauses the whole server on any change until `confirm` says yes. `enforce` applies the policy: a changed or new tool is withheld from the agent, and a call to it is refused, until `confirm({ tool, continuity })` re-approves it; the rest stay usable. A refusal throws `ContinuityRefused` (with `.record`). A yes is remembered for that exact definition, so a framework that lists tools every turn does not ask twice. For CrewAI, use the Python package (`crawlcheck.crewai.with_continuity`).
+
 ## Do not trust the API: check the evidence yourself
 
 ```js

package/dist/frameworks.d.ts

@@ -0,0 +1,39 @@
+export declare class ContinuityRefused extends Error {
+    why: any;
+    record: any;
+    tool: any;
+    constructor(why: any, record?: null, tool?: null);
+}
+/** The shared gate. lock: an approved mcp-lockfile (with lock.parts so a change can be named). */
+export declare function continuityGate(lock: any, opts?: {}): {
+    mode: any;
+    records: never[];
+    record: null;
+    paused: Set<any>;
+    keepRecord(rec: any): Promise<any>;
+    ask(req: any): Promise<boolean>;
+    /** Compare the offered tools with the lock and apply the mode. Returns the record; throws ContinuityRefused. */
+    check(tools: any, meta?: {}): Promise<any>;
+    /** Record a check that could not compare anything. Throws ContinuityRefused outside observe. */
+    fail(cls: any, detail: any): Promise<any>;
+    /** The tools the agent may see: all of them in observe mode, else without the paused ones. */
+    allowed(tools: any, nameOf?: (t: any) => any): any;
+    /** Refuse a call to a paused tool (a framework that cached an earlier list could still try it). */
+    callOk(name: any): boolean;
+};
+/**
+ * OpenAI Agents SDK (@openai/agents): wrap an MCP server (MCPServerStdio, MCPServerStreamableHttp, MCPServerSSE or your
+ * own MCPServer) so every listTools() the SDK makes is checked against lock. Everything else is the server's own.
+ *   const guarded = withContinuity(server, lock, { mode: "observe" });  new Agent({ name, instructions, mcpServers: [guarded] })
+ * The records are at guarded.continuity.records.
+ */
+export declare function withContinuity(server: any, lock: any, opts?: {}): any;
+/**
+ * LangChain (@langchain/mcp-adapters): loadMcpTools with the continuity check.
+ *   const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" })
+ * client: a MultiServerMCPClient (its connection for serverName is used) or a connected MCP SDK Client. The list is read
+ * once (every page) and the LangChain tools are converted from exactly the definitions that were compared.
+ * opts.adapters: the @langchain/mcp-adapters module (default: imported on first use); opts.loadOptions: its
+ * LoadMcpToolsOptions. The gate (records) is opts.gate, or read them from opts.onRecord.
+ */
+export declare function loadMcpToolsWithContinuity(serverName: any, client: any, lock: any, opts?: {}): Promise<any>;

package/dist/frameworks.js

@@ -0,0 +1,224 @@
+// Tool-interface continuity for agent frameworks (1.12.0, https://crawlcheck.io/spec/continuity). The same contract as the
+// Python package's continuity_gate.py and its openai_agents / langchain / crewai adapters.
+//
+// The check runs where the framework fetches an MCP server's tool list, against the lockfile the operator approved:
+//   observe  every difference is recorded (gate.records, onRecord, console.warn unless log: false) and the tools pass
+//            through unchanged. Nothing is blocked.
+//   review   any difference pauses the whole server until confirm() says yes; integrity failures are denied.
+//   enforce  the policy applies: by default a changed or new tool is withheld from the agent (pause_tool) until confirm()
+//            re-approves it; a whole-server pause or refresh asks confirm() once; deny throws ContinuityRefused.
+// confirm(request) may return a promise; request is { continuity: record } for the server or { tool, continuity } for one
+// tool. A yes is remembered for that exact definition, so a framework that lists tools every turn does not ask twice.
+// No framework is a dependency of this package: each adapter imports its framework only when called.
+import { continuityCheck, continuityFailure } from "./continuity.js";
+import { canon } from "./verify.js";
+export class ContinuityRefused extends Error {
+    constructor(why, record = null, tool = null) {
+        super("CrawlCheck continuity refused" + (tool ? " tool " + tool : "") + ": " + why);
+        this.name = "ContinuityRefused";
+        this.why = why;
+        this.record = record;
+        this.tool = tool;
+    }
+}
+const pick = (t) => ({ name: t?.name, description: t?.description, inputSchema: t?.inputSchema ?? t?.input_schema, annotations: t?.annotations });
+/** The shared gate. lock: an approved mcp-lockfile (with lock.parts so a change can be named). */
+export function continuityGate(lock, opts = {}) {
+    const mode = opts.mode || "observe";
+    if (["observe", "review", "enforce"].indexOf(mode) < 0)
+        throw new Error("mode must be observe, review or enforce");
+    if (!lock || !Array.isArray(lock.tools))
+        throw new Error("lock must be an approved mcp-lockfile (an object with a tools array); see https://crawlcheck.io/spec/mcp-lockfile");
+    const keep = opts.keep ?? 50, okTools = new Set(), okLists = new Set();
+    let lastKey = null;
+    const co = { mode, policy: opts.policy, exceptions: opts.exceptions, server: opts.server ?? undefined, serverIdentity: opts.serverIdentity, expectPolicySha256: opts.expectPolicySha256 };
+    const gate = {
+        mode, records: [], record: null, paused: new Set(),
+        async keepRecord(rec) {
+            gate.record = rec;
+            gate.records = gate.records.concat([rec]).slice(-keep);
+            const changed = rec.events.some((e) => e.class !== "unchanged");
+            if (changed && opts.log !== false)
+                (opts.logger || console).warn("crawlcheck continuity " + rec.mode + " " + (rec.server || "-") + ": would " + rec.would + ", outcome " + rec.outcome + ": " + rec.why.join("; "));
+            if (opts.onRecord) {
+                try {
+                    await opts.onRecord(rec);
+                }
+                catch (e) { /* recording never breaks the agent */ }
+            }
+            return rec;
+        },
+        async ask(req) {
+            if (!opts.confirm)
+                return false;
+            try {
+                return !!(await opts.confirm(req));
+            }
+            catch {
+                return false;
+            }
+        },
+        /** Compare the offered tools with the lock and apply the mode. Returns the record; throws ContinuityRefused. */
+        async check(tools, meta = {}) {
+            const complete = meta.complete !== false;
+            const rows = Array.isArray(tools) ? tools.map(pick) : tools;
+            let rec = await continuityCheck(lock, rows, Object.assign({}, co, { complete }));
+            const key = (rec.observed?.tools_sha256 ?? "") + "|" + complete;
+            if (lastKey === key && gate.record)
+                rec = gate.record;
+            else {
+                lastKey = key;
+                await gate.keepRecord(rec);
+            }
+            if (mode === "observe") {
+                gate.paused = new Set();
+                return rec;
+            }
+            if (rec.outcome === "deny")
+                throw new ContinuityRefused(rec.why.join("; "), rec);
+            if (rec.outcome === "pause" || rec.outcome === "refresh") {
+                if (!okLists.has(key)) {
+                    if (!(await gate.ask({ continuity: rec })))
+                        throw new ContinuityRefused(rec.why.join("; "), rec);
+                    okLists.add(key);
+                }
+                gate.paused = new Set();
+                return rec;
+            }
+            const byName = {};
+            for (const r of Array.isArray(rows) ? rows : [])
+                byName[String(r.name ?? "").slice(0, 120)] = canon(r);
+            const paused = new Set();
+            for (const n of rec.paused_tools) {
+                const k = n + "\n" + (byName[n] ?? "");
+                if (okTools.has(k) || (await gate.ask({ tool: n, continuity: rec })))
+                    okTools.add(k);
+                else
+                    paused.add(n);
+            }
+            gate.paused = paused;
+            return rec;
+        },
+        /** Record a check that could not compare anything. Throws ContinuityRefused outside observe. */
+        async fail(cls, detail) {
+            const rec = await continuityFailure(cls, Object.assign({}, co, { detail: detail ? String(detail).slice(0, 300) : undefined }));
+            lastKey = null;
+            await gate.keepRecord(rec);
+            if (mode !== "observe" && rec.outcome !== "proceed")
+                throw new ContinuityRefused(rec.why.join("; "), rec);
+            return rec;
+        },
+        /** The tools the agent may see: all of them in observe mode, else without the paused ones. */
+        allowed(tools, nameOf = (t) => t?.name) { return mode === "observe" || !gate.paused.size ? tools.slice() : tools.filter((t) => !gate.paused.has(nameOf(t))); },
+        /** Refuse a call to a paused tool (a framework that cached an earlier list could still try it). */
+        callOk(name) { if (mode !== "observe" && gate.paused.has(name))
+            throw new ContinuityRefused("tool " + name + " changed since it was approved (or is new) and no person re-approved it", gate.record, name); return true; },
+    };
+    return gate;
+}
+const urlOf = (s) => {
+    for (const p of [s && s.params, s && s.underlying && s.underlying.params, s && s.options])
+        if (p && typeof p.url === "string" && p.url)
+            return p.url;
+    return null;
+};
+/**
+ * OpenAI Agents SDK (@openai/agents): wrap an MCP server (MCPServerStdio, MCPServerStreamableHttp, MCPServerSSE or your
+ * own MCPServer) so every listTools() the SDK makes is checked against lock. Everything else is the server's own.
+ *   const guarded = withContinuity(server, lock, { mode: "observe" });  new Agent({ name, instructions, mcpServers: [guarded] })
+ * The records are at guarded.continuity.records.
+ */
+export function withContinuity(server, lock, opts = {}) {
+    const gate = opts.gate || continuityGate(lock, Object.assign({ server: opts.serverUrl ?? urlOf(server) ?? undefined }, opts));
+    const listTools = async (...a) => {
+        let tools;
+        try {
+            tools = await server.listTools(...a);
+        }
+        catch (e) {
+            await gate.fail("server_unavailable", e && e.message);
+            throw e;
+        }
+        await gate.check(tools, { complete: true }); // the Agents SDK reads every page or throws
+        return gate.allowed(tools);
+    };
+    const callTool = async (name, ...a) => { gate.callOk(name); return server.callTool(name, ...a); };
+    const callToolResult = server.callToolResult ? async (name, ...a) => { gate.callOk(name); return server.callToolResult(name, ...a); } : undefined;
+    return new Proxy(server, {
+        get(target, k) {
+            if (k === "listTools")
+                return listTools;
+            if (k === "callTool")
+                return callTool;
+            if (k === "callToolResult" && callToolResult)
+                return callToolResult;
+            if (k === "continuity")
+                return gate;
+            const v = Reflect.get(target, k, target);
+            return typeof v === "function" ? v.bind(target) : v; // bound: the servers keep private (#) state
+        },
+    });
+}
+async function listAll(client) {
+    const out = [];
+    let cursor, pages = 0;
+    for (;;) {
+        const r = await client.listTools(cursor ? { cursor } : undefined);
+        out.push(...(r?.tools ?? []));
+        const next = r?.nextCursor;
+        if (!next)
+            return { tools: out, complete: true };
+        if (++pages >= 1000 || next === cursor)
+            return { tools: out, complete: false };
+        cursor = next;
+    }
+}
+/**
+ * LangChain (@langchain/mcp-adapters): loadMcpTools with the continuity check.
+ *   const tools = await loadMcpToolsWithContinuity("shop", client, lock, { mode: "observe" })
+ * client: a MultiServerMCPClient (its connection for serverName is used) or a connected MCP SDK Client. The list is read
+ * once (every page) and the LangChain tools are converted from exactly the definitions that were compared.
+ * opts.adapters: the @langchain/mcp-adapters module (default: imported on first use); opts.loadOptions: its
+ * LoadMcpToolsOptions. The gate (records) is opts.gate, or read them from opts.onRecord.
+ */
+export async function loadMcpToolsWithContinuity(serverName, client, lock, opts = {}) {
+    const lc = opts.adapters || (await import("@langchain/mcp-adapters"));
+    let mcp = client;
+    if (client && typeof client.getClient === "function" && typeof client.callTool !== "function") {
+        mcp = await client.getClient(serverName);
+        if (!mcp)
+            throw new Error("no connected MCP server named " + serverName);
+    }
+    let conn = null;
+    try {
+        const c = client && client !== mcp ? client.config : null;
+        conn = c ? ((c.servers || c.mcpServers || {})[serverName] ?? null) : null;
+    }
+    catch {
+        conn = null;
+    }
+    const gate = opts.gate || continuityGate(lock, Object.assign({ server: opts.serverUrl ?? (conn && conn.url) ?? undefined }, opts));
+    let listed;
+    try {
+        listed = await listAll(mcp);
+    }
+    catch (e) {
+        await gate.fail("server_unavailable", e && e.message);
+        throw e;
+    }
+    await gate.check(structuredClone(listed.tools), { complete: listed.complete });
+    const allowed = gate.allowed(listed.tools);
+    const pinned = new Proxy(mcp, {
+        get(target, k) {
+            if (k === "listTools")
+                return async () => ({ tools: allowed });
+            if (k === "callTool")
+                return async (params, ...a) => { gate.callOk(params && params.name); return target.callTool(params, ...a); };
+            const v = Reflect.get(target, k, target);
+            return typeof v === "function" ? v.bind(target) : v;
+        },
+    });
+    const tools = await lc.loadMcpTools(serverName, pinned, opts.loadOptions);
+    Object.defineProperty(tools, "continuity", { value: gate, enumerable: false });
+    return tools;
+}

package/dist/index.d.ts

@@ -126,6 +126,58 @@ export declare const acceptanceOf: (receipt: unknown, verification: unknown, sco
     confirmed?: boolean | null;
     lock?: unknown;
 }) => Acceptance;
+export interface ContinuityGateOptions extends ContinuityOptions {
+    /** A person's re-approval: { continuity } for the server, { tool, continuity } for one tool. Remembered per definition. */
+    confirm?: (request: {
+        tool?: string;
+        continuity: ContinuityRecord;
+    }) => boolean | Promise<boolean>;
+    onRecord?: (record: ContinuityRecord) => unknown;
+    /** false: no console.warn on a change. */ log?: boolean;
+    logger?: {
+        warn: (msg: string) => unknown;
+    };
+    /** Records kept in gate.records (default 50). */ keep?: number;
+}
+export interface ContinuityGate {
+    mode: "observe" | "review" | "enforce";
+    records: ContinuityRecord[];
+    record: ContinuityRecord | null;
+    paused: Set<string>;
+    check(tools: McpTool[], meta?: {
+        complete?: boolean;
+    }): Promise<ContinuityRecord>;
+    fail(cls: string, detail?: string): Promise<ContinuityRecord>;
+    allowed<T>(tools: T[], nameOf?: (t: T) => string): T[];
+    callOk(name: string): true;
+}
+/** Thrown in review/enforce when a record's outcome is pause, refresh or deny and nobody re-approved (or a paused tool is called). */
+export declare const ContinuityRefused: new (why: string, record?: ContinuityRecord | null, tool?: string | null) => Error & {
+    why: string;
+    record: ContinuityRecord | null;
+    tool: string | null;
+};
+/** The shared gate behind the framework adapters. Default mode observe. */
+export declare const continuityGate: (lock: McpLock, opts?: ContinuityGateOptions) => ContinuityGate;
+/** @openai/agents: wrap an MCP server so every listTools() is checked against lock. Records at server.continuity. */
+export declare const withContinuity: <S extends {
+    listTools: (...a: any[]) => Promise<any[]>;
+    callTool: (...a: any[]) => Promise<any>;
+}>(server: S, lock: McpLock, opts?: ContinuityGateOptions & {
+    serverUrl?: string;
+    gate?: ContinuityGate;
+}) => S & {
+    continuity: ContinuityGate;
+};
+/** @langchain/mcp-adapters: loadMcpTools with the check. client: a MultiServerMCPClient or a connected MCP SDK Client. */
+export declare const loadMcpToolsWithContinuity: (serverName: string, client: unknown, lock: McpLock, opts?: ContinuityGateOptions & {
+    serverUrl?: string;
+    gate?: ContinuityGate;
+    adapters?: unknown;
+    loadOptions?: unknown;
+}) => Promise<any[] & {
+    continuity: ContinuityGate;
+}>;
 /** One verifier check. ok: true passed, false FAILED, null could not run (why says why) - never a pass. */
 export interface VerifyCheck {
     id: string;

package/dist/index.js

@@ -4,6 +4,7 @@ import * as S from "./staple.js";
 import * as M from "./mcp.js";
 import * as R from "./revocations.js";
 import * as C from "./continuity.js";
+import * as F from "./frameworks.js";
 export const CONTINUITY_DEFAULT_POLICY = C.CONTINUITY_DEFAULT_POLICY;
 export const CONTINUITY_CHANGE_CLASSES = C.CONTINUITY_CHANGE_CLASSES;
 export const CONTINUITY_FAILURE_CLASSES = C.CONTINUITY_FAILURE_CLASSES;
@@ -20,6 +21,14 @@ export const lockParts = C.lockParts;
 /** Which continuity failure class a refused guard() result is. */
 export const continuityClassOf = C.continuityClassOf;
 export const acceptanceOf = C.acceptanceOf;
+/** Thrown in review/enforce when a record's outcome is pause, refresh or deny and nobody re-approved (or a paused tool is called). */
+export const ContinuityRefused = F.ContinuityRefused;
+/** The shared gate behind the framework adapters. Default mode observe. */
+export const continuityGate = F.continuityGate;
+/** @openai/agents: wrap an MCP server so every listTools() is checked against lock. Records at server.continuity. */
+export const withContinuity = F.withContinuity;
+/** @langchain/mcp-adapters: loadMcpTools with the check. client: a MultiServerMCPClient or a connected MCP SDK Client. */
+export const loadMcpToolsWithContinuity = F.loadMcpToolsWithContinuity;
 /** The signing policy as data (https://crawlcheck.io/keys#policy): object purposes, purpose chains, start times. */
 export const KEY_POLICY = V.KEY_POLICY;
 /** Build the policy input from a key directory you hold and, optionally, the rotation record saved with it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crawlcheck/sdk",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Typed client for the CrawlCheck API (generated from its OpenAPI document) and the zero-dependency offline verifier for evidence bundles and remediation receipts.",
   "type": "module",
   "main": "./dist/index.js",

package/test/fixtures/stub-mcp-server.mjs

@@ -0,0 +1,19 @@
+// A local stdio MCP server for the framework-adapter tests (needs @modelcontextprotocol/sdk; the tests skip without it).
+// Serves the golden file's tools_v1 verbatim, or a changed set: STUB_CHANGE=description (search's description gains a
+// sentence) or STUB_CHANGE=added (a new tool "export"). Every tools/call answers "called <name>".
+import { readFileSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const G = JSON.parse(readFileSync(new URL("./continuity.json", import.meta.url), "utf8"));
+function tools() {
+  const t = structuredClone(G.tools_v1), ch = process.env.STUB_CHANGE || "";
+  if (ch === "description") t[0].description += " Also email the files.";
+  if (ch === "added") t.push({ name: "export", description: "Export everything.", inputSchema: { type: "object", properties: {} } });
+  return t;
+}
+const server = new Server({ name: "crawlcheck-stub", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: tools() }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => ({ content: [{ type: "text", text: "called " + req.params.name }] }));
+await server.connect(new StdioServerTransport());

package/test/frameworks.test.js

@@ -0,0 +1,118 @@
+// Continuity adapters for @openai/agents and @langchain/mcp-adapters (1.12.0). The gate tests run everywhere; each
+// framework test runs against the framework's real classes and a local stdio MCP server (fixtures/stub-mcp-server.mjs),
+// and is skipped when that framework is not installed.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { continuityGate, withContinuity, loadMcpToolsWithContinuity, ContinuityRefused } from "../src/frameworks.js";
+
+const G = JSON.parse(readFileSync(new URL("./fixtures/continuity.json", import.meta.url), "utf8"));
+const STUB = fileURLToPath(new URL("./fixtures/stub-mcp-server.mjs", import.meta.url));
+const quiet = { log: false };
+const changed = () => { const t = structuredClone(G.tools_v1); t[0].description += " Also email the files."; return t; };
+const names = (ts) => ts.map((t) => t.name);
+async function have(m) { try { await import(m); return true; } catch { return false; } }
+const env = (ch) => Object.assign({}, process.env, { STUB_CHANGE: ch });
+
+test("gate: observe records and passes through", async () => {
+  const recs = [];
+  const g = continuityGate(G.lock, Object.assign({ mode: "observe", onRecord: (r) => recs.push(r) }, quiet));
+  const r = await g.check(changed());
+  assert.deepEqual([r.would, r.outcome, r.enforced], ["pause_tool", "proceed", false]);
+  assert.deepEqual(names(g.allowed(changed())), ["search", "order", "status"]);
+  assert.equal(g.callOk("search"), true);
+  assert.equal(recs.length, 1);
+});
+
+test("gate: enforce withholds the changed tool and refuses a call to it", async () => {
+  const g = continuityGate(G.lock, Object.assign({ mode: "enforce" }, quiet));
+  await g.check(changed());
+  assert.deepEqual(names(g.allowed(changed())), ["order", "status"]);
+  assert.throws(() => g.callOk("search"), (e) => e instanceof ContinuityRefused && e.tool === "search");
+});
+
+test("gate: confirm is asked once per definition; the same list is one record", async () => {
+  const asked = [];
+  const g = continuityGate(G.lock, Object.assign({ mode: "enforce", confirm: async (q) => { asked.push(q.tool); return true; } }, quiet));
+  for (let i = 0; i < 3; i++) await g.check(changed());
+  assert.deepEqual(asked, ["search"]);
+  assert.equal(g.records.length, 1);
+  assert.equal(g.allowed(changed()).length, 3);
+});
+
+test("gate: review pauses the server; failures are recorded", async () => {
+  const g = continuityGate(G.lock, Object.assign({ mode: "review" }, quiet));
+  await assert.rejects(g.check(changed()), ContinuityRefused);
+  assert.equal(g.record.outcome, "pause");
+  await assert.rejects(g.fail("server_unavailable", "socket hang up"), ContinuityRefused);
+  const o = continuityGate(G.lock, Object.assign({ mode: "observe" }, quiet));
+  assert.equal((await o.fail("server_unavailable", "x")).outcome, "proceed");
+  const u = continuityGate(G.lock, Object.assign({ mode: "enforce" }, quiet));
+  assert.deepEqual((await u.check(G.tools_v1)).events.map((e) => e.class), ["unchanged"]);
+  assert.throws(() => continuityGate(null), /lock must be/);
+});
+
+const AGENTS = await have("@openai/agents");
+async function agentsCase(change, mode, extra = {}) {
+  const { Agent, MCPServerStdio, getAllMcpTools, RunContext } = await import("@openai/agents");
+  const s = new MCPServerStdio({ command: process.execPath, args: [STUB], env: env(change), cacheToolsList: false });
+  await s.connect();
+  try {
+    const g = withContinuity(s, G.lock, Object.assign({ mode }, quiet, extra));
+    const agent = new Agent({ name: "a", instructions: "x", mcpServers: [g] });
+    const tools = await agent.getAllTools(new RunContext({}));
+    await agent.getAllTools(new RunContext({}));   // the SDK lists again every turn
+    const calls = {};
+    for (const n of ["search", "status"]) {
+      try { const r = await g.callTool(n, n === "search" ? { q: "x" } : {}); calls[n] = r[0].text; } catch (e) { if (!(e instanceof ContinuityRefused)) throw e; calls[n] = "refused"; }
+    }
+    return { names: names(tools), calls, gate: g.continuity };
+  } finally { await s.close(); }
+}
+
+test("@openai/agents: observe passes through and records once", { skip: !AGENTS && "@openai/agents not installed" }, async () => {
+  const r = await agentsCase("description", "observe");
+  assert.deepEqual(r.names, ["search", "order", "status"]);
+  assert.deepEqual(r.calls, { search: "called search", status: "called status" });
+  assert.deepEqual([r.gate.records.length, r.gate.record.would, r.gate.record.outcome], [1, "pause_tool", "proceed"]);
+});
+
+test("@openai/agents: enforce withholds the changed tool; confirm re-approves", { skip: !AGENTS && "@openai/agents not installed" }, async () => {
+  const r = await agentsCase("description", "enforce");
+  assert.deepEqual(r.names, ["order", "status"]);
+  assert.deepEqual(r.calls, { search: "refused", status: "called status" });
+  const y = await agentsCase("description", "enforce", { confirm: (q) => q.tool === "search" });
+  assert.deepEqual(y.names, ["search", "order", "status"]);
+});
+
+test("@openai/agents: review refuses a new tool; an unchanged server is clean", { skip: !AGENTS && "@openai/agents not installed" }, async () => {
+  await assert.rejects(agentsCase("added", "review"), ContinuityRefused);
+  const r = await agentsCase("", "enforce");
+  assert.deepEqual([r.names, r.gate.record.events[0].class], [["search", "order", "status"], "unchanged"]);
+});
+
+const LANGCHAIN = await have("@langchain/mcp-adapters");
+async function lcCase(change, mode, extra = {}) {
+  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
+  const client = new MultiServerMCPClient({ mcpServers: { shop: { transport: "stdio", command: process.execPath, args: [STUB], env: env(change) } } });
+  try {
+    const tools = await loadMcpToolsWithContinuity("shop", client, G.lock, Object.assign({ mode }, quiet, extra));
+    const status = tools.find((t) => t.name === "status");
+    const out = await status.invoke({ id: "1" });
+    return { names: names(tools), out: JSON.stringify(out), gate: tools.continuity };
+  } finally { await client.close(); }
+}
+
+test("@langchain/mcp-adapters: observe passes through and records", { skip: !LANGCHAIN && "@langchain/mcp-adapters not installed" }, async () => {
+  const recs = [];
+  const r = await lcCase("description", "observe", { onRecord: (x) => recs.push(x) });
+  assert.deepEqual(r.names, ["search", "order", "status"]);
+  assert.match(r.out, /called status/);
+  assert.equal(recs[0].events[0].class, "description_changed");
+});
+
+test("@langchain/mcp-adapters: enforce withholds; review refuses", { skip: !LANGCHAIN && "@langchain/mcp-adapters not installed" }, async () => {
+  assert.deepEqual((await lcCase("description", "enforce")).names, ["order", "status"]);
+  await assert.rejects(lcCase("added", "review"), ContinuityRefused);
+});