@threadpoolai/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ThreadPool contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @threadpoolai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+```bash
+npm install @threadpoolai/sdk
+```
+
+Requires Node.js 18 or later.
+
+## Use
+
+```ts
+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.
+
+For endpoint behavior, policies, approval handling, and limits, see the [gateway documentation](https://github.com/ayantik2006/project-innofusion3.0/blob/main/docs/api/gateway.md).

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+export type DataSensitivity = "PUBLIC" | "INTERNAL" | "SENSITIVE";
+export interface ApiErrorBody {
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    requestId: string;
+}
+export interface GatewayStep {
+    id: string;
+    sequence: number;
+    capability: string;
+    skill: string | null;
+    description: string | null;
+    status: string;
+    agent: {
+        id: string;
+        reference: string | null;
+        name: string;
+        status: string;
+    } | null;
+    attempts: number;
+    maxAttempts: number;
+    qaScore: number | null;
+    outcome: string | null;
+    report: {
+        outputHash: string;
+        outputChars: number;
+        reportedAt: string;
+        reportedLatencyMs: number | null;
+        measuredLatencyMs: number;
+        artifactsBytes: number;
+    } | null;
+    verdict: {
+        outputHash: string;
+        passed: boolean;
+        accepted: boolean;
+        score: number;
+        threshold: number;
+        reason: string;
+        issues: string[];
+        verifiedBy: "qa_model" | "deterministic_checks" | "deterministic_fallback";
+        verifiedByLabel: string;
+        verifiedAt: string;
+    } | null;
+    notDelivered: string | null;
+}
+export interface GatewayRun {
+    id: string;
+    origin: "gateway";
+    originNote: string;
+    title: string;
+    status: string;
+    qualityThreshold: number;
+    dataSensitivity: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    steps: GatewayStep[];
+    approvals: Array<{
+        id: string;
+        kind: string;
+        status: string;
+        subtaskId: string | null;
+        agentId: string | null;
+        reasons: unknown[];
+        expiresAt: string | null;
+        decidedAt: string | null;
+        decisionReason: string | null;
+        createdAt: string | null;
+    }>;
+}
+export interface CredentialScope {
+    id: string;
+    operations: string[];
+    expiresAt: string;
+    maxUses: number;
+    usesRemaining: number;
+    scope: {
+        runId: string;
+        stepId: string;
+        agentId: string;
+    };
+}
+export type AuthorizeResponse = {
+    decision: "allow";
+    reason: {
+        code: "authorized";
+        message: string;
+    };
+    credential: CredentialScope;
+    assignmentId: string;
+    step: GatewayStep;
+} | {
+    decision: "deny";
+    reason: {
+        code: string;
+        message: string;
+        ruleIds?: string[];
+    };
+    agentRevoked: boolean;
+    step: GatewayStep;
+} | {
+    decision: "pending_approval";
+    reason: {
+        code: "awaiting_human_approval";
+        message: string;
+    };
+    approval: {
+        id: string;
+        expiresAt: string;
+        reasons: string[];
+    };
+    step: GatewayStep;
+};
+export interface ReportResponse {
+    step: GatewayStep;
+    report: {
+        outputHash: string;
+        outputChars: number;
+        measuredLatencyMs: number;
+        reportedLatencyMs: number | null;
+    };
+}
+export interface VerifyResponse {
+    verdict: {
+        passed: boolean;
+        accepted: boolean;
+        score: number;
+        threshold: number;
+        reason: string;
+        issues: string[];
+        verifiedBy: "qa_model" | "deterministic_checks" | "deterministic_fallback";
+        verifiedByLabel: string;
+        outputHash: string;
+        note: string;
+    };
+    outcome: "accepted" | "rejected";
+    outcomeReason: string;
+    attemptsUsed: number;
+    attemptsRemaining: number;
+    step: GatewayStep;
+}
+export interface CloseResponse {
+    run: GatewayRun;
+    summary: {
+        steps: number;
+        accepted: number;
+        rejected: number;
+        unknown: number;
+        notAuthorized: number;
+    };
+    accountability: unknown;
+    receipt: {
+        hash: string;
+        body: unknown;
+    };
+}
+export interface OpenRunInput {
+    title: string;
+    qualityThreshold?: number;
+    dataSensitivity?: DataSensitivity;
+}
+export interface DeclareStepInput {
+    capability: string;
+    skill?: string;
+    description?: string;
+    /** Your own identifier for the agent (stable across runs) and a display name. */
+    agent: {
+        id: string;
+        name: string;
+    };
+}
+export interface ReportInput {
+    credentialId: string;
+    output: string;
+    artifacts?: Record<string, unknown>;
+    /** Your own measurement. ThreadPool records it as reported; it measures latency itself. */
+    latencyMs?: number;
+}
+/** The raw API answer, exactly as ThreadPool sent it. */
+export interface RawResponse {
+    ok: boolean;
+    status: number;
+    body: unknown;
+}
+export declare class ThreadPoolGatewayError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    readonly requestId?: string | undefined;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined, requestId?: string | undefined);
+}
+export interface ThreadPoolGatewayOptions {
+    /** Your ThreadPool deployment, e.g. https://threadpool.example.com */
+    baseUrl: string;
+    /** An organization API key with the gateway:run scope. */
+    apiKey: string;
+    fetch?: typeof fetch;
+    /** Generates the Idempotency-Key for each write. Defaults to a random UUID. */
+    idempotencyKey?: () => string;
+    /** Retries of a write after a network error, a 5xx or "still processing", with the SAME key. Default 2. */
+    retries?: number;
+    /** Delay between retries in ms (doubles each time). Default 500. */
+    retryDelayMs?: number;
+}
+export type GatewayOperation = "open_run" | "get_run" | "declare_step" | "authorize_step" | "report_step" | "verify_step" | "close_run";
+export interface GovernedStep {
+    runId: string;
+    stepId: string;
+}
+/** What your function returns: the output text, optionally with artifacts. */
+export type GovernedOutput = string | {
+    output: string;
+    artifacts?: Record<string, unknown>;
+};
+export type GovernedResult = {
+    ran: false;
+    decision: Extract<AuthorizeResponse, {
+        decision: "deny" | "pending_approval";
+    }>;
+} | {
+    ran: true;
+    decision: Extract<AuthorizeResponse, {
+        decision: "allow";
+    }>;
+    report: ReportResponse;
+    verdict: VerifyResponse;
+};
+export declare class ThreadPoolGateway {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly newKey;
+    private readonly retries;
+    private readonly retryDelayMs;
+    constructor(options: ThreadPoolGatewayOptions);
+    call(operation: GatewayOperation, args?: Record<string, unknown>): Promise<RawResponse>;
+    private send;
+    private unwrap;
+    openRun(input: OpenRunInput): Promise<{
+        run: GatewayRun;
+    }>;
+    getRun(runId: string): Promise<{
+        run: GatewayRun;
+    }>;
+    declareStep(runId: string, input: DeclareStepInput): Promise<{
+        step: GatewayStep;
+    }>;
+    /** Ask before acting. allow | deny | pending_approval - all answers, not errors. */
+    authorizeStep(runId: string, stepId: string): Promise<AuthorizeResponse>;
+    reportStep(runId: string, stepId: string, input: ReportInput): Promise<ReportResponse>;
+    verifyStep(runId: string, stepId: string): Promise<VerifyResponse>;
+    closeRun(runId: string): Promise<CloseResponse>;
+    /**
+     * Authorize, run `fn`, report and verify. `fn` runs ONLY on "allow"; on
+     * "deny" or "pending_approval" it is never called and the decision is
+     * returned (ask again later for a pending approval). If `fn` throws, nothing
+     * is reported: the authorization lapses at its expiry and the step's record
+     * shows "unknown", never a guess.
+     */
+    governed(step: GovernedStep, fn: (credential: CredentialScope) => Promise<GovernedOutput>): Promise<GovernedResult>;
+}

package/dist/index.js

@@ -0,0 +1,150 @@
+// @threadpoolai/sdk - a small, dependency-free client for ThreadPool's governance
+// gateway (/api/v1/gateway). Your agents keep running where they run today;
+// ThreadPool authorizes each step, verifies what your agent produced, and
+// records who did what under which authority.
+//
+// The client holds no governance logic: every decision (allow, deny,
+// pending_approval, the QA verdict) is made by ThreadPool and returned as-is.
+// It never sends your model traffic or provider keys anywhere: it sends only
+// what you pass it.
+//
+//   const tp = new ThreadPoolGateway({ baseUrl, apiKey });          // key scope: gateway:run
+//   const { run } = await tp.openRun({ title: "Weekly market report" });
+//   const { step } = await tp.declareStep(run.id, { capability: "web_research", agent: { id: "researcher-v2", name: "Researcher" } });
+//   const result = await tp.governed({ runId: run.id, stepId: step.id }, async () => myAgent.research("..."));
+//   if (!result.ran) console.log("refused:", result.decision.reason);
+//   await tp.closeRun(run.id);
+export class ThreadPoolGatewayError extends Error {
+    status;
+    code;
+    details;
+    requestId;
+    constructor(status, code, message, details, requestId) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.requestId = requestId;
+        this.name = "ThreadPoolGatewayError";
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class ThreadPoolGateway {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    newKey;
+    retries;
+    retryDelayMs;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("ThreadPoolGateway: apiKey is required (a key with the gateway:run scope).");
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.newKey = options.idempotencyKey ?? (() => `tpsdk_${globalThis.crypto.randomUUID()}`);
+        this.retries = options.retries ?? 2;
+        this.retryDelayMs = options.retryDelayMs ?? 500;
+    }
+    // ── Raw calls: the API's answer verbatim (used by the MCP server) ──────
+    async call(operation, args = {}) {
+        const runId = typeof args.runId === "string" ? encodeURIComponent(args.runId) : "";
+        const stepId = typeof args.stepId === "string" ? encodeURIComponent(args.stepId) : "";
+        const { runId: _r, stepId: _s, ...body } = args;
+        void _r;
+        void _s;
+        switch (operation) {
+            case "open_run":
+                return this.send("POST", "/api/v1/gateway/runs", body);
+            case "get_run":
+                return this.send("GET", `/api/v1/gateway/runs/${runId}`);
+            case "declare_step":
+                return this.send("POST", `/api/v1/gateway/runs/${runId}/steps`, body);
+            case "authorize_step":
+                return this.send("POST", `/api/v1/gateway/runs/${runId}/steps/${stepId}/authorize`, {});
+            case "report_step":
+                return this.send("POST", `/api/v1/gateway/runs/${runId}/steps/${stepId}/report`, body);
+            case "verify_step":
+                return this.send("POST", `/api/v1/gateway/runs/${runId}/steps/${stepId}/verify`, {});
+            case "close_run":
+                return this.send("POST", `/api/v1/gateway/runs/${runId}/close`, {});
+        }
+    }
+    async send(method, path, body) {
+        const headers = { authorization: `Bearer ${this.apiKey}`, accept: "application/json" };
+        if (method === "POST") {
+            headers["content-type"] = "application/json";
+            // One key per logical write, reused on every retry of it.
+            headers["idempotency-key"] = this.newKey();
+        }
+        let attempt = 0;
+        for (;;) {
+            try {
+                const res = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers, body: method === "POST" ? JSON.stringify(body ?? {}) : undefined });
+                const parsed = await res.json().catch(() => null);
+                const stillProcessing = res.status === 409 && parsed?.error?.code === "CONFLICT" && /still being processed/i.test(parsed.error.message);
+                if ((res.status >= 500 || stillProcessing) && attempt < this.retries) {
+                    attempt += 1;
+                    await sleep(this.retryDelayMs * 2 ** (attempt - 1));
+                    continue;
+                }
+                return { ok: res.ok, status: res.status, body: parsed };
+            }
+            catch (err) {
+                if (attempt >= this.retries)
+                    throw err;
+                attempt += 1;
+                await sleep(this.retryDelayMs * 2 ** (attempt - 1));
+            }
+        }
+    }
+    async unwrap(response) {
+        const r = await response;
+        if (r.ok)
+            return r.body;
+        const e = r.body?.error;
+        throw new ThreadPoolGatewayError(r.status, e?.code ?? "UNKNOWN", e?.message ?? `HTTP ${r.status}`, e?.details, r.body?.requestId);
+    }
+    // ── The calls ──────────────────────────────────────────────────────────
+    openRun(input) {
+        return this.unwrap(this.call("open_run", { ...input }));
+    }
+    getRun(runId) {
+        return this.unwrap(this.call("get_run", { runId }));
+    }
+    declareStep(runId, input) {
+        return this.unwrap(this.call("declare_step", { runId, ...input }));
+    }
+    /** Ask before acting. allow | deny | pending_approval - all answers, not errors. */
+    authorizeStep(runId, stepId) {
+        return this.unwrap(this.call("authorize_step", { runId, stepId }));
+    }
+    reportStep(runId, stepId, input) {
+        return this.unwrap(this.call("report_step", { runId, stepId, ...input }));
+    }
+    verifyStep(runId, stepId) {
+        return this.unwrap(this.call("verify_step", { runId, stepId }));
+    }
+    closeRun(runId) {
+        return this.unwrap(this.call("close_run", { runId }));
+    }
+    /**
+     * Authorize, run `fn`, report and verify. `fn` runs ONLY on "allow"; on
+     * "deny" or "pending_approval" it is never called and the decision is
+     * returned (ask again later for a pending approval). If `fn` throws, nothing
+     * is reported: the authorization lapses at its expiry and the step's record
+     * shows "unknown", never a guess.
+     */
+    async governed(step, fn) {
+        const decision = await this.authorizeStep(step.runId, step.stepId);
+        if (decision.decision !== "allow")
+            return { ran: false, decision };
+        const started = Date.now();
+        const produced = await fn(decision.credential);
+        const latencyMs = Date.now() - started;
+        const { output, artifacts } = typeof produced === "string" ? { output: produced, artifacts: undefined } : produced;
+        const report = await this.reportStep(step.runId, step.stepId, { credentialId: decision.credential.id, output, ...(artifacts ? { artifacts } : {}), latencyMs });
+        const verdict = await this.verifyStep(step.runId, step.stepId);
+        return { ran: true, decision, report, verdict };
+    }
+}

package/package.json

@@ -1,6 +1,49 @@
-{
-  "name": "@threadpoolai/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@threadpoolai/sdk",
+  "version": "0.1.0",
+  "description": "Client for ThreadPool's governance gateway: scoped authority, independent QA and an accountability record for agents you run yourself.",
+  "type": "module",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "keywords": [
+    "threadpool",
+    "ai-agents",
+    "agent-governance",
+    "governance",
+    "mcp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ayantik2006/project-innofusion3.0.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/ayantik2006/project-innofusion3.0/issues"
+  },
+  "homepage": "https://github.com/ayantik2006/project-innofusion3.0#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}