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)
| Option | Default | Description |
|---|---|---|
apiKey | COCO_API_KEY | The project key. |
url | COCO_GATE_URL | The gate. |
mode | enforce | What the client assumes before the gate has answered. After that, the gate's own mode. |
timeoutMs | 5000 | The timeout per request. |
failOpen | false | Lets a call run when the gate is unreachable. |
fetch | Global fetch | A 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 field | Sent as | Description |
|---|---|---|
action | action | The contract action. |
args | args | The arguments the model proposed. |
state | state | Facts from your systems of record, which rules read as state.*. |
sessionId | session_id | The conversation. Defaults to default. |
agent | agent | The agent's identity. |
callId | call_id | Ties a retry to its escalation. |
conversation | conversation | { role, content } messages. The last 12 are sent, for judge checks. |
tool | tool | name, 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 field | Description |
|---|---|
verdict | AUTO_EXECUTE, OBSERVE, ESCALATE, or DENY. |
effect | run, escalate, or deny, after the mode. |
mode | monitor or enforce. |
reason, rule, deciding_check | Why, and which contract and check decided. |
audit_id, receipt_hash | The receipt in the gate's ledger. |
escalation, obligations | The open escalation, and what the contract asks of the approver. |
runs, denied, waiting | The effect as booleans. |
unreached | true 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 returnsnullwhen 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);