Coco
Integrate and operate

TypeScript

Check tool calls from Node with CocoEnforcer, the TypeScript client for the hosted gate.

Check tool calls from Node with CocoEnforcer, the TypeScript client for the hosted gate.

@trustcoco/sdk asks the gate about each tool call before your code runs it. The gate decides and keeps the receipt. The client decides only one thing itself: it denies when the gate doesn't answer.

Prerequisites: Node 20 or later, or any runtime with global fetch and AbortController. The package has no runtime dependencies.

Keep in mind: The package isn't published to npm yet. For access, contact us at trustcoco.ai.


Check a call

Ask the gate before you run the tool:

import { CocoEnforcer } from "@trustcoco/sdk";

const coco = new CocoEnforcer({ apiKey: process.env.COCO_API_KEY, url: process.env.COCO_GATE_URL });
const result = await coco.enforce({ action: "payments.send", args: { amount: 900, payee: "Sunrise" } });
if (result.runs) await sendPayment();
else if (result.waiting) await coco.waitForDecision(result.escalation!.id);

COCO_GATE_URL is the gate's address, which coco connect prints. The client sends no X-Coco-Project header, so use a key bound to one project.

new CocoEnforcer(options)

OptionDefaultDescription
apiKeyCOCO_API_KEYThe project key.
urlCOCO_GATE_URLThe gate.
modeenforceWhat the client assumes before the gate has answered. After that, the gate's own mode.
timeoutMs5000The timeout per request.
failOpenfalseLets a call run when the gate is unreachable.
fetchGlobal fetchA replacement, for tests or another runtime.

The constructor throws when it has no key or no URL.

enforce(request)

enforce(request: ActionRequest | string, args?: Record<string, unknown>): Promise<Decision>

Asks the gate about one proposed call. It never throws.

Request fieldSent asDescription
actionactionThe contract action.
argsargsThe arguments the model proposed.
statestateFacts from your systems of record, which rules read as state.*.
sessionIdsession_idThe conversation. Defaults to default.
agentagentThe agent's identity.
callIdcall_idTies a retry to its escalation.
conversationconversation{ role, content } messages. The last 12 are sent, for judge checks.
tooltoolname, description, schema, and impact, for a tool no contract governs.

Keep in mind: Give each conversation its own sessionId. Calls sharing default share one set of session counts and totals.

Decision fieldDescription
verdictAUTO_EXECUTE, OBSERVE, ESCALATE, or DENY.
effectrun, escalate, or deny, after the mode.
modemonitor or enforce.
reason, rule, deciding_checkWhy, and which contract and check decided.
audit_id, receipt_hashThe receipt in the gate's ledger.
escalation, obligationsThe open escalation, and what the contract asks of the approver.
runs, denied, waitingThe effect as booleans.
unreachedtrue when the gate wasn't reached and the client decided, closed.

When the gate doesn't answer

A gate the client can't reach, a timeout, or an answer without a verdict gives a decision with verdict: "DENY", unreached: true, no audit_id, and a reason starting The call was not authorised:.

In Enforce, its effect is deny. In Monitor, or with failOpen: true, its effect is run. The gate never saw the call, so no receipt exists for it. If you need a record of unreached decisions, log them yourself.

waitForDecision(id, options)

waitForDecision(id: string, options?: { pollMs?: number; timeoutMs?: number; signal?: AbortSignal }): Promise<Escalation>

Polls the escalation every pollMs (default 2000) until a person decides, then resolves with it. status is approved or rejected, with decided_by and decision_reason. It rejects when timeoutMs (default 10 minutes) passes or signal aborts, so your code never runs a tool nobody approved.

  • escalation(id): Reads one escalation once, or returns null when the gate doesn't say.
  • withdraw(id, reason): Closes an escalation this agent opened, as rejected.

An agent never approves. A person does.

guard(request, execute, wait)

guard<T>(request: ActionRequest, execute: () => Promise<T> | T, wait?: WaitOptions)
  : Promise<{ ran: true; value: T; decision: Decision } | { ran: false; decision: Decision }>

Runs execute only when Coco allows it. With wait, an escalation waits for a person. Once approved, guard asks the gate again and runs execute if the answer is run. Without wait, an escalation counts as not allowed. A wait that times out or aborts rejects the promise, and execute never runs.

Keep in mind: Set sessionId and callId on a request you pass with wait. The gate finds the approved escalation by session and call id. Without them, the second question is a new call and escalates again.

const out = await coco.guard(
  { action: "payments.send", args: { amount: 25000, payee: "Sunrise" }, sessionId: "run-42", callId: "call-7" },
  () => sendPayment(25000, "Sunrise"),
  { timeoutMs: 15 * 60 * 1000 },
);
if (!out.ran) console.log(out.decision.reason);

On this page