Skip to main content

TypeScript SDK (@supertruth/vigil)

Zero runtime dependencies, Node 18+ fetch, ESM and CJS, typed errors, three attempts with jittered backoff on 429 and 5xx, and a gate you have to opt out of honoring. Works in Node, Next.js and edge runtimes with fetch.

Install​

Published to GitHub Packages on tags ts-v*. Add to .npmrc:

@supertruth:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

then:

npm install @supertruth/vigil

Emit and honor​

import { Vigil, HeldOutput } from "@supertruth/vigil";

const vg = new Vigil({ apiKey: process.env.VIGIL_API_KEY! });
const gate = await vg.emit("support-agent", "output_generated", { content_length: 812 }, { dti: 0.9 });
await gate.honor();   // throws HeldOutput on hold, alert, collapse

Held output:

try {
  await gate.honor();
} catch (e) {
  if (e instanceof HeldOutput) {
    const action = await vg.waitForRelease(e.actionId, { timeoutMs: 600_000 });   // polls GET /enforcement/{id} every 5s
    if (action.review_outcome !== "released") throw e;
  }
}

gate.honor({ allowPropagation: true }) lets the output through but first emits an output_generated event with source: "vigil" and payload { gate_ignored: true, action_id, gate_status }, so overriding the gate is itself on the ledger.

Surface​

MethodRoute
registerAgent(agentId, name, { description?, existOk? })POST /agents/
getAgent, listAgents, setMonitoring(agentId, monitored)GET /agents/{id}, GET /agents/, PATCH /agents/{id}/monitoring
emit(agentId, eventType, payload, { dti?, source?, actor? })POST /events/
getTrust(agentId, dti?), scoreHistory(agentId, limit?)GET /scores/{id}/latest, /history
audit(agentId, limit?), verify(agentId), exportLedger(sinceSeq?, limit?)GET /audit/...
pending(limit?), getAction(id), latestAction(agentId), waitForRelease(id, { timeoutMs?, intervalMs? })GET /enforcement/...
me(), usage(days?)GET /orgs/me, GET /usage
createKey, listKeys, revokeKey/keys/ (admin)
listScenarios, runScenario/test/... (review)

Errors and options​

VigilAuthError (401, 403), VigilNotFound (404), VigilRateLimited (429 after retries), VigilUnavailable (5xx after retries or no answer), VigilTimeout (waitForRelease), HeldOutput (honor()). All extend VigilError with .status and .detail.

Options: baseUrl (default https://vigil.supertruth.ai), timeoutMs (10000), maxAttempts (3), backoffMs (250), and fetch / sleep for tests.

Run it against your org​

The same calls the SDK makes, with Node's built-in fetch and nothing installed:

node --input-type=module - <<'EOF'
const url = process.env.VIGIL_URL, key = process.env.VIGIL_KEY;
const call = async (method, path, body) => {
  const r = await fetch(url + path, { method, headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
                                      body: body ? JSON.stringify(body) : undefined });
  return [r.status, await r.json()];
};
let [s] = await call("POST", "/agents/", { agent_id: "docs-typescript", name: "Docs TypeScript" });
if (![200, 201, 409].includes(s)) throw new Error(`register ${s}`);
let [status, gate] = await call("POST", "/events/", { agent_id: "docs-typescript", event_type: "output_generated", payload: { content_length: 640 }, dti: 0.9 });
if (status !== 200) throw new Error(`emit ${status} ${JSON.stringify(gate)}`);
console.log("gate", gate.gate_status, "bii", gate.bii, "action", gate.action_id);
EOF