@threadpoolai/sdk

Dependency-free TypeScript client for the ThreadPool governance gateway. It asks ThreadPool to authorize each agent step, reports the result, and triggers independent verification. Your agent and its provider credentials stay in your infrastructure.

Install

npm install @threadpoolai/sdk

Requires Node.js 18 or later.

Use

import { ThreadPoolGateway } from "@threadpoolai/sdk";

const threadpool = new ThreadPoolGateway({
  baseUrl: process.env.THREADPOOL_URL!,
  apiKey: process.env.THREADPOOL_API_KEY!, // API key with gateway:run
});

const { run } = await threadpool.openRun({ title: "Weekly market report" });
const { step } = await threadpool.declareStep(run.id, {
  capability: "summarization",
  agent: { id: "reporter-v1", name: "Reporter" },
});

const result = await threadpool.governed(
  { runId: run.id, stepId: step.id },
  async () => ({ output: await myAgent.run() }),
);

if (!result.ran) console.log(`Not run: ${result.decision.reason.code}`);
else console.log(result.verdict.outcome);

await threadpool.closeRun(run.id);

governed() only calls your function after ThreadPool returns allow. A denial or pending approval returns without invoking it. API errors throw ThreadPoolGatewayError with HTTP status, API error code, details, and request ID.

Capabilities, step kinds and enforcement

• capability is a catalog value, not a tool name. declareStep takes the GatewayCapability union (the GATEWAY_CAPABILITIES constant), so a typo or a tool name fails to compile instead of returning a 400. await threadpool.listCapabilities() returns the live list with what each is for. Pick the capability that describes the kind of work and put the tool's name in description.
• kind: "data_retrieval" marks a step that only reports what a tool or provider returned (a quote, a price series, a computed statistic). QA then checks fidelity to the call and provenance (source, time) instead of asking for analytical hedging. The default is "analysis".
• enforcement: "record" on openRun keeps a QA rejection on the record but off the agent's failure streak, so a strict review can't take the agent offline. The default is "block".
• onRejected on governed() runs when ThreadPool rejects the output. Throw from it to make a rejection block your caller; otherwise governed() returns the verdict as before.

const { run } = await threadpool.openRun({ title: "Market snapshot", enforcement: "record" });
const { step } = await threadpool.declareStep(run.id, {
  capability: "data_extraction",
  kind: "data_retrieval",
  description: "Latest quote for RELIANCE.NS from the get_stock_quote tool.",
  agent: { id: "quote-agent", name: "Quote agent" },
});

const result = await threadpool.governed({ runId: run.id, stepId: step.id }, () => fetchQuote("RELIANCE.NS"), {
  onRejected: (v) => console.warn(`QA rejected: ${v.verdict.reason}`),
});

An agent that fails QA several times in a row is taken offline by the Circuit Breaker. A denial then carries decision.reason.retryAfter, the time the agent is reinstated automatically.

For endpoint behavior, policies, approval handling, and limits, see the gateway documentation.