brydge-core

The verification client at the centre of BRYDGE: ask before an agent acts, then check against the destination system's own records whether the work actually happened.

This is the shared core every BRYDGE framework adapter is built on — brydge-langchain, brydge-mcp, the CrewAI tool and the n8n node all turn their own tool shape into these calls and the answers back into their own. It imports nothing from any framework, so a new integration is a thin wrapper, not another copy of the engine.

Most people use a framework package instead of this one directly. Reach for brydge-core when you are wiring BRYDGE into a framework it does not yet have an adapter for.

Install

npm install brydge-core

Requires Node.js 20 or later.

Use

import { BrydgeClient } from "brydge-core";

const brydge = new BrydgeClient(); // reads BRYDGE_API_KEY, and BRYDGE_URL if set

// 1. Ask before acting.
const decision = await brydge.supervise({
  actor: "agent:refund-ops",
  action: "refund",
  target: "ch_3QxF8c…",
  facts: { amount: 4200 },
  idempotencyKey: "refund:ch_3QxF8c…",
});

if (decision.decision === "ALLOWED") {
  // 2. Carry the action out, writing decision.id into the record it creates,
  //    then tell BRYDGE what you believe happened.
  await brydge.report(decision.id, "SUCCEEDED");
}

// 3. Check it against the destination's own records.
const finding = await brydge.verify(decision.id);
finding.state; // "VERIFIED" | "FAILED" | "MISMATCH" | "UNKNOWN" | "PENDING"

ESCALATED means a person decides and the work must not be done yet. Asking again with the same idempotencyKey returns their answer once they have given it: ALLOWED, or settled: "REFUSED".

The client

const brydge = new BrydgeClient({
  apiKey: "brydge_sk_…",          // default: BRYDGE_API_KEY
  baseUrl: "https://…",           // default: BRYDGE_URL, then BRYDGE's hosted service
  timeoutMs: 30_000,              // default
  integration: "brydge-acme/1.0", // how this integration names itself to BRYDGE's logs
});

await brydge.supervise({ actor, action, target, facts, idempotencyKey }); // ask before acting
await brydge.report(authorization, "SUCCEEDED");                          // what the agent says happened
await brydge.verify(authorization);                                       // read the records now
await brydge.finding(authorization);                                      // what BRYDGE has found so far, free
await brydge.headroom(actor, action);                                     // how much the agent may do without a person today

The client sends your key only over https, except to localhost. BRYDGE's decisions come back as values; anything that stopped BRYDGE from answering — a missing key, an unreachable server, a refusal — is a BrydgeError, never a decision about the action itself. BrydgeError.find(error) recovers it from a framework's wrapping error.

Development

npm install
npm test
npm run build

License

MIT