@cygnuxlabs/tracekit 0.0.0-stage → 1.2.1

package/README.md

@@ -1,3 +1,295 @@
-# Temporary Holding Version
+# @cygnuxlabs/tracekit
 
-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.
+Tracekit for TypeScript and JavaScript agents: every tool call is decided by the Tracekit signer before it runs and
+recorded after, and model responses become signed evidence. The client talks to the signer directly; it needs no Python
+at runtime (the same-user dev signer is started with Python when none is running).
+
+## Install
+
+Node 18 or newer:
+
+```sh
+npm install @cygnuxlabs/tracekit
+```
+
+npm also installs the signer package for your platform (`@cygnuxlabs/tracekit-signer-<platform>`: Apple Silicon
+macOS, Linux x64 and arm64 with glibc, Windows x64), which bundles a Python, so `npx @cygnuxlabs/tracekit up` starts a
+dev signer without one. On an Intel Mac or Alpine there is none: `pip install 'tracekit-ai[signer]'`.
+
+Or build it from a checkout and install the file it makes:
+
+```sh
+cd sdk/typescript && npm ci && npm run build && npm pack    # writes cygnuxlabs-tracekit-<version>.tgz
+cd /path/to/your/app && npm install /path/to/Tracekit/sdk/typescript/cygnuxlabs-tracekit-*.tgz
+```
+
+## Signer client (`@cygnuxlabs/tracekit`)
+
+A native client of the v2 signer RPC with no runtime dependencies (Node ≥ 18 built-ins only, no Python bridge); also
+exported as `@cygnuxlabs/tracekit/v2`.
+
+```ts
+import { Client, withRun, currentRun } from "@cygnuxlabs/tracekit";
+
+const client = new Client();                              // or new Client({ signer: "https://signer:8443" })
+const run = await client.registerRun("research-bot");
+const d = await run.decide(call.id, "Bash", call.function.arguments);   // the raw model string, or a parsed value
+if (d.decision === "allow") {
+  const out = await runShell(call);
+  await run.complete(call.id, "ok", { result: out });      // never throws: a recording failure is a warning
+} else if (d.decision === "ask") {
+  const { approval_id } = await run.approvalRequest(call.id);
+  const { state } = await run.approvalWait(approval_id, 300_000);   // on a connection of its own
+}
+await run.close();
+await client.close();                                     // waits for what is in flight
+```
+
+- **Signer:** `$TRACEKIT_SIGNER` names a Unix socket, `tcp://127.0.0.1:port` (with `$TRACEKIT_SIGNER_TOKEN`; both sides
+  prove they hold it, it never goes on the wire) or `https://host:port` (`$TRACEKIT_SIGNER_TOKEN_FILE`: a bearer token
+  re-read per call; `$TRACEKIT_SIGNER_CERT`/`_KEY`: mTLS; `$TRACEKIT_SIGNER_CA`: the signer's CA). In system mode the
+  signer named by the root-owned `/etc/tracekit/client.json` is used and a different `$TRACEKIT_SIGNER` is refused.
+  Otherwise the same-user dev signer is found, or started with `tracekit up --json`: `$TRACEKIT_PYTHON -m tracekit` if
+  set, else a pip-installed `tracekit` on PATH, else the Python bundled in this platform's
+  `@cygnuxlabs/tracekit-signer-<platform>` package. `npx @cygnuxlabs/tracekit up|down|status|view|verify|signer` runs the
+  same command.
+- **Protocol:** `hello` first; a signer that does not speak this client's RPC version is refused with `Incompatible`.
+  Requests are validated against the RPC schemas before they are sent, pipelined on one connection and answered in
+  order; a call whose connection drops is resent with the same `request_id`. Each handle's events carry the client's
+  `stream` and a `client_seq` per run.
+- **Fail modes:** only when the signer cannot be reached does `decide` return the run's fail mode for the tool class
+  (`fields.tool_class_hint`, from `register_run`'s `fail_modes`, default closed) with `unavailable: true`. A refusal
+  from the signer rejects with `RPCError`, never an allow.
+- **Serverless:** `client.waitUntil(promise)` and `await client.flush()` before the host freezes the process.
+- `withRun(run, fn)` makes `run` the `currentRun()` of everything `fn` awaits (AsyncLocalStorage).
+- `argsDigest(tool, args)`, `canonicalize`, `strictParse`: JCS (RFC 8785) and the strict parser, byte-identical to
+  the Python client on the shared vectors in `tests/vectors/jcs.jsonl`.
+
+## Verify a bundle (`@cygnuxlabs/tracekit/verify`)
+
+An independent verifier of v2 bundles (`.tkb`), written from [docs/format-v2.md](../../docs/format-v2.md) and tested to
+agree with the Python verifier. No dependencies: Web Crypto and `DecompressionStream`, so Node ≥ 20.12 and current
+browsers.
+
+```sh
+npx @cygnuxlabs/tracekit verify run.tkb --trust trust.json [--json] [--strict]
+```
+
+Exit 0 verified, 1 failed, 2 unusable or unverifiable, 3 a warning under `--strict`; the report and `--json` are those
+of `tracekit verify`. In code, Node or a browser:
+
+```ts
+import { verify, formatReport } from "@cygnuxlabs/tracekit/verify";
+
+const bundle = new Uint8Array(await (await fetch("run.tkb")).arrayBuffer());
+const trust = new Uint8Array(await (await fetch("trust.json")).arrayBuffer());   // your own pinned trust config
+const { report, code } = await verify(bundle, trust);
+console.log(report.integrity, report.assurance);   // e.g. "VERIFIED", "witnessed; records ed25519; ..."
+```
+
+It does not check SLH-DSA checkpoint lines, Rekor anchors or certified record keys: a bundle that relies on one is
+`UNVERIFIABLE (not checked by this verifier: ...)`, never `VERIFIED`. Monitor reports, revocations and the v1 format
+bridge need the Python verifier.
+
+## v2 framework adapters
+
+One call registers a run (the dev signer is started if none answers), closes it when the process is about to exit,
+and hands you the adapters bound to it; then `tracekit last` exports, pins and verifies the run:
+
+```ts
+import { instrument } from "@cygnuxlabs/tracekit";
+const tk = await instrument();                    // the same on a second call
+const model = wrapLanguageModel({ model: openai("gpt-5"), middleware: tk.ai.middleware });   // Vercel AI SDK
+const r = await generateText({ model, tools: tk.ai.tools({ pay }), toolApproval: tk.ai.toolApproval, messages });
+const agent = new Agent({ name: "payer", tools: [tk.agents.tool(tool, { name: "pay", description, parameters, execute })] });   // OpenAI Agents JS
+```
+
+ES modules can't be patched from outside, so unlike Python's `tracekit.instrument()` the adapters are passed to the
+framework by you.
+
+Each adapter gates every tool call through the signer: it passes the call id, its attempt and the model's raw
+arguments, the signer decides, an `ask` waits for a person (held in the hook where the framework allows, else paused
+and resumed), and every call, allowed or approved, runs only after the signer's `approval_consume` agrees. A `deny`
+reaches the model as the tool's error result and the run goes on. The run's fail mode (`register_run`'s `fail_modes`)
+applies only when the signer cannot be reached at the decision; a refusal, or a failure while waiting for an approval,
+never lets the call run. Recording a finished call never throws and never changes its result (a failure is a
+`TracekitWarning`). The frameworks are optional peer dependencies: the adapters import none of them, and the client
+keeps no runtime dependencies. No adapter wraps a provider client, so the SDKs' own `APIPromise` (`.withResponse()`)
+and streams (`messages.stream()`, `streamText`) work as without Tracekit. Offline examples: `examples/v2_*.mjs`.
+
+- **A server: a run per conversation.** Register a run per conversation and make it current around each request with
+  `withRun(run, () => runner.run(...))`: every adapter decides the calls made inside it in that run (its complete and
+  approvals follow the call), and uses the run it was built with otherwise. `instrument()`'s own run is replaced by a
+  new one (a warning, linked as `parent_run` while the old one is closing) when the signer closed it after it was idle.
+- **Exit.** `instrument()` closes its run on `beforeExit`, and on SIGINT or SIGTERM when nothing else handles the
+  signal (then the signal's default action runs). A signal your app or a library handles is left to it (`@openai/agents`
+  exits on SIGINT/SIGTERM): close the run in your own handler (`await tk.run.close()`) before you exit. A run stays
+  open while approvals of it wait for a person or, approved, to be resumed. To approve and resume in another process,
+  keep the run's `runId` and `runToken` with the framework's saved state and re-attach:
+  `new RunHandle(new Client(), { run_id, run_token })`; close that client when you are done with it
+  (`run.client.close()`), or re-attach every run through one shared client. `process.exit()` skips all of this: close
+  first.
+- **The LLM gateway.** Point the provider at it with the run in a header, e.g. OpenAI Agents
+  `setDefaultOpenAIClient(new OpenAI({ baseURL, apiKey: <gateway token>, defaultHeaders: { "X-Tracekit-Run":
+  `${run.runId}.${run.runToken}` } }))`, Vercel AI `createOpenAI({ baseURL, apiKey, headers })`. Register the run as
+  the identity the gateway relays (`TRACEKIT_SIGNER=https://…` with the same token), and grant that identity the RPCs
+  the adapters use, `approval_list` included ([limits](../../docs/limits.md#deployment)). The adapters' own model
+  events are then optional: the gateway records each exchange too.
+
+**OpenAI Agents SDK** (`@cygnuxlabs/tracekit/v2/openai-agents`)
+
+```ts
+import { Agent, Runner, tool } from "@openai/agents";
+import { TracekitAgents } from "@cygnuxlabs/tracekit/v2/openai-agents";
+const tk = new TracekitAgents(await new Client().registerRun("payer"));
+const agent = new Agent({ name: "payer", tools: [tk.tool(tool, { name: "pay", description, parameters, execute })] });
+let result = await runner.run(agent, "pay acct-42 $15", { context: {} });   // the context must be an object
+if (result.interruptions.length) {                                         // an `ask`: once decided in the signer
+  await tk.applyDecisions(result.state);
+  result = await runner.run(agent, result.state);
+}
+await tk.recordResponses(result.rawResponses, "gpt-5");
+```
+
+`tk.tool(tool, options)` builds the tool with the SDK's `tool()`: the signer's policy replaces `needsApproval`, and a
+tool input guardrail (after your own) gates the call on its raw arguments. The approval id travels in the RunState only
+as a hint (`context.tracekit.approvals`); the signer checks it. Leave `toolExecution.preApprovalInputGuardrails` off:
+with it on, the guardrail runs before the interruption and every `ask` is refused at once.
+
+A local MCP server (`MCPServerStdio`, SSE, streamable HTTP) is gated through its tool guardrails:
+`new MCPServerStdio({ name: "filesystem", ..., ...tk.mcp("filesystem") })` decides each call as
+`mcp:filesystem/<tool>`, holds an `ask` in the guardrail until a person decides, and completes the call with the
+server's output. Pass the server's own `name`: with `mcpConfig.includeServerInToolNames` the model's
+`mcp_<server>__<tool>` is turned back into `mcp:<server>/<tool>` from it. A call your own input guardrails refuse is
+recorded as refused. Without it, local MCP calls
+are not gated. A sub-agent used as a tool (`agent.asTool()`) is not gated either, and its model responses are not in
+the outer `rawResponses`: gate its own tools with `tk.tool`, and record its responses (`customOutputExtractor` gets
+the nested result) or run the LLM gateway. Also not gated, listed as uncovered: hosted tools (web and file search,
+code interpreter, hosted MCP, hosted shell), shell, apply_patch and computer tools, and handoffs (name them in the
+policy's `handoffs:` so they reconcile). `recordResponses` records them (T3) in a signed model event per response.
+
+**Vercel AI SDK v7** (`@cygnuxlabs/tracekit/v2/vercel-ai`)
+
+```ts
+import { generateText, wrapLanguageModel } from "ai";
+import { tracekitAI } from "@cygnuxlabs/tracekit/v2/vercel-ai";
+const tk = tracekitAI(await new Client().registerRun("assistant"));
+const model = wrapLanguageModel({ model: openai("gpt-5"), middleware: tk.middleware });
+const r = await generateText({ model, tools: tk.tools({ pay }), toolApproval: tk.toolApproval, messages });
+// asks end the step with tool-approval-request parts; once decided in the signer:
+messages.push(...r.response.messages, { role: "tool", content: await tk.approvalResponses(r.content) });
+```
+
+The same options work for `streamText` and `ToolLoopAgent`. `tk.middleware` records each model response (V3 usage,
+the tool calls asked for) and keeps each call's raw arguments by `toolCallId` for the decision. `tk.toolApproval` maps
+`deny` to `denied` and `ask` to `user-approval`; without it an `ask` is refused. `tk.tools()` wraps each `execute`, so a
+forged or replayed `tool-approval-response` runs nothing. `experimental_toolApprovalSecret` (the SDK's HMAC over its own
+approval requests) may be set too; it does not replace the signer's check. Spans from `@ai-sdk/otel` are telemetry, not
+evidence: the signed records are the middleware's and the adapter's. Tools without `execute` and provider-executed tools
+are not gated; they appear in the recorded model responses.
+
+MCP tools (`@ai-sdk/mcp`): `tk.tools(await client.tools(), { mcp: "filesystem" })` decides each as
+`mcp:filesystem/<tool>`. Your own `toolApproval` (a function, or one per tool name) composes with the signer's:
+`toolApproval: tk.toolApprovalWith(mine)` asks the policy first, and your answer applies only to a call the policy
+allows (a call you deny is recorded as refused; one you answer `user-approval` and then deny in your own UI stays
+decided and not completed); `tk.toolApproval` alone replaces yours.
+
+**Claude Agent SDK** (`@cygnuxlabs/tracekit/v2/claude-agent-sdk`)
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { tracekitHooks, tracekitSessionStore } from "@cygnuxlabs/tracekit/v2/claude-agent-sdk";
+const run = await new Client().registerRun("my-agent");
+query({ prompt, options: { hooks: tracekitHooks(run), sessionStore: tracekitSessionStore(myStore, run) } });
+```
+
+The gate is the `PreToolUse` hook (it runs for every call; `canUseTool` is skipped for calls the CLI's permission mode
+allows). An `ask` is held in the hook for up to 540 s, below the hook timeout it sets (600 s); a call not approved by
+then is blocked. `PostToolUse`/`PostToolUseFailure` complete the call, `SessionEnd` closes the run. The session store
+wrapper commits each saved transcript as a `state_write` chained from the last one, so a transcript edited in the store
+between two writes shows up as a signed `state_tamper` gap.
+
+## Migrating from v1
+
+The v1 SDK (`Tracekit`, driving `python -m tracekit.bridge`) is deprecated and removed in 0.5.0. Until then it stays at
+`@cygnuxlabs/tracekit/v1`; `Tracekit.start` warns once per process (`DeprecationWarning`, code `TRACEKIT_V1`) and the bridge
+prints a matching notice on stderr; `TRACEKIT_NO_DEPRECATION=1` silences both. The import becomes
+`import { Tracekit } from "@cygnuxlabs/tracekit/v1"`.
+
+| v1 (`@cygnuxlabs/tracekit/v1`) | v2 (`@cygnuxlabs/tracekit`) |
+|---|---|
+| `await Tracekit.start({ agent })` | `const client = new Client(); const run = await client.registerRun(agent)` |
+| `await tk.tool(name, args, fn, { toolUseId })` | `await run.decide(toolUseId, name, args)`, run `fn` on `allow`, then `await run.complete(toolUseId, "ok", { result })` |
+| `TracekitDenied` | `d.decision === "deny"` (`d.rule_ids`); a refusal by the signer rejects with `RPCError` |
+| held for approval inside `tk.tool` | `d.decision === "ask"`: `run.approvalRequest(id)`, then `run.approvalWait(approval_id)` |
+| `instrumentOpenAI` / `instrumentAnthropic`, `tk.modelBegin` / `tk.modelEnd` | `run.modelEvent(provider, model, "response", { stop_reason, usage, tool_uses })`, or a framework adapter below |
+| `tracekitMiddleware(tk)` | `tracekitAI(run).middleware` from `@cygnuxlabs/tracekit/v2/vercel-ai`, with `tools` and `toolApproval` |
+| `tk.prompt` / `tk.say` / `tk.think` | not recorded by the v2 signer |
+| `tk.end(reason)` | `await run.close(reason); await client.close()` |
+
+```ts
+// v1
+import { Tracekit, TracekitDenied } from "@cygnuxlabs/tracekit/v1";
+const tk = await Tracekit.start({ agent: "research-bot" });
+try {
+  out = await tk.tool("Bash", args, () => runShell(args), { toolUseId: call.id });
+} catch (e) {
+  if (!(e instanceof TracekitDenied)) throw e;
+}
+await tk.end();
+
+// v2
+import { Client } from "@cygnuxlabs/tracekit";
+const client = new Client();
+const run = await client.registerRun("research-bot");
+const d = await run.decide(call.id, "Bash", call.function.arguments);
+if (d.decision === "allow") {
+  out = await runShell(args);
+  await run.complete(call.id, "ok", { result: out });
+}
+await run.close();
+await client.close();
+```
+
+## v1 SDK (deprecated, `@cygnuxlabs/tracekit/v1`)
+
+Removed in 0.5.0; see the migration above. Tool calls pass Tracekit's policy gate before they run, and model calls
+become signed evidence, in the same ledger and format as the Python SDK.
+
+```ts
+import OpenAI from "openai";
+import { Tracekit, TracekitDenied, instrumentOpenAI } from "@cygnuxlabs/tracekit/v1";
+
+const tk = await Tracekit.start({ agent: "research-bot" });
+const openai = instrumentOpenAI(new OpenAI(), tk);        // also: instrumentAnthropic(client, tk), tracekitMiddleware(tk) for the Vercel AI SDK
+
+const r = await openai.chat.completions.create({ model: "gpt-4o", messages, tools });
+for (const call of r.choices[0].message.tool_calls ?? []) {
+  await tk.tool("Bash", JSON.parse(call.function.arguments), () => runShell(call), { toolUseId: call.id });  // TracekitDenied if blocked
+}
+await tk.end();
+```
+
+- `tk.tool(name, args, fn)`: the policy decision is made and signed before `fn` runs; a denied (or held, not approved)
+  call throws `TracekitDenied` and `fn` never runs. Pass the model's call id as `toolUseId` to link request and execution.
+- `instrumentOpenAI` (chat completions, Responses), `instrumentAnthropic` (messages): a signed request event before the
+  call is sent, and a response event with model, finish reason, requested tool calls, token usage, error, status and
+  time to first chunk. Streams are recorded when they end, fail or are abandoned: the SDK replaces the stream's async
+  iterator in place with a recording one; non-streamed responses come back as the provider SDK returned them. The
+  wrapped `create` is an async function, so it returns a plain Promise: helpers on the SDK's own promise object (such
+  as `.withResponse()`) are not available through it. A provider error is recorded and rethrown. The request event is
+  written before the call is sent: if the bridge reports an error or times out, that error is thrown and the call is not sent; if the
+  bridge has exited, `fail_mode: closed` throws `TracekitDenied` and `fail_mode: open` sends the call unrecorded with a
+  warning on stderr. A failure to record a call that already completed is written to stderr and counted in
+  `tk.recordFailures`; it never replaces the call's result.
+- `tracekitMiddleware(tk)`: `wrapLanguageModel({ model, middleware: tracekitMiddleware(tk) })` in the Vercel AI SDK
+  (v4 and v5 result shapes).
+
+**How it works.** The SDK starts `python -m tracekit.bridge` and talks to it over stdio, so policy evaluation, secret
+redaction, the signer client and the event format are Tracekit's own Python code, not a second implementation. It needs
+the `tracekit` Python package and a signer (`tracekit init --dev`); set `TRACEKIT_PYTHON` to pick the interpreter.
+
+Tests (`npm test`): `test/sdk.test.mjs` runs the v1 SDK with the real OpenAI and Anthropic SDKs against a mocked fetch and a real signer, then verify the
+bundle; `test/adapters.test.mjs` runs the adapter contract for each adapter, through small stand-ins for the
+frameworks' hook and middleware interfaces, against an in-test fake signer and (with Python and the signer extra) the
+real one.

package/bin/tracekit.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// `npx @cygnuxlabs/tracekit up|down|status|view|verify|signer ...`: runs the Tracekit CLI that src/v2/launcher.ts finds.
+// `verify BUNDLE --trust trust.json` (a v2 bundle) runs the TypeScript verifier instead, so it needs nothing else,
+// unless an option only the Python verifier has is given.
+import { spawnSync } from "node:child_process";
+import { INSTALL_HINT, signerCommand, signerEnv } from "../dist/v2/launcher.js";
+
+const args = process.argv.slice(2);
+// the options only the Python verifier has (monitor reports, revocations, the v1 bridge) still go to it
+const PYTHON_ONLY = ["--monitor-report", "--revocations", "--v1-ledger", "--v1-key"];
+if (args[0] === "verify" && args.includes("--trust") && !args.some((a) => PYTHON_ONLY.includes(a.split("=")[0]))) {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 20 || major === 20 && minor < 12) {   // the verifier's JSON imports and deflate-raw
+    console.error(`tracekit verify: the TypeScript verifier needs Node >= 20.12 (this is ${process.versions.node})`);
+    process.exit(2);
+  }
+  const { main } = await import("../dist/verify/cli.js");
+  process.exit(await main(args.slice(1)));
+}
+const cmd = signerCommand();
+if (!cmd) {
+  console.error(`tracekit: ${INSTALL_HINT}`);
+  process.exit(1);
+}
+const r = spawnSync(cmd[0], [...cmd.slice(1), ...args], { stdio: "inherit", env: signerEnv(cmd) });
+if (r.error) {
+  console.error(`tracekit: ${cmd[0]}: ${r.error.message}`);
+  process.exit(1);
+}
+process.exit(r.status ?? 1);

package/dist/v1.d.ts

@@ -0,0 +1,97 @@
+export declare class TracekitDenied extends Error {
+    constructor(message: string);
+}
+export interface StartOptions {
+    agent?: string;
+    sessionId?: string;
+    cwd?: string;
+    python?: string;
+    env?: Record<string, string>;
+    /** Per-request timeout for the bridge (default 30 s). */
+    timeoutMs?: number;
+    /** Timeout for a tool call held for approval (default 61 min: the signer caps an approval at one hour). */
+    approvalTimeoutMs?: number;
+}
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens?: number | null;
+    cache_write_tokens?: number | null;
+    reasoning_tokens?: number | null;
+}
+export interface ModelEnd {
+    response?: unknown;
+    error?: string | null;
+    status?: number | null;
+    stop_reason?: string | null;
+    tool_uses?: {
+        id: string;
+        name: string;
+    }[];
+    usage?: Usage | null;
+    model?: string | null;
+    first_byte_ms?: number | null;
+}
+export declare class Tracekit {
+    private bridge;
+    private run;
+    private failMode;
+    private timeoutMs;
+    private approvalTimeoutMs;
+    readonly sessionId: string;
+    /** Recording failures after a wrapped call had already succeeded: reported on stderr, never thrown. */
+    recordFailures: number;
+    private warned;
+    private constructor();
+    /** Start a run. One Tracekit per run; call end() when the agent is done. */
+    static start(opts?: StartOptions): Promise<Tracekit>;
+    /**
+     * One bridge request. If the bridge has exited, the run's fail mode decides: open returns null (the caller proceeds
+     * unrecorded, with a warning), closed refuses with TracekitDenied.
+     */
+    private call;
+    /**
+     * A record that gates nothing (model_begin, prompt, say, think): under fail_mode=open a timeout or bridge error lets
+     * the caller proceed unrecorded, as the Python SDK does. tool_begin never goes through here: a timeout there can be
+     * an unanswered approval hold.
+     */
+    private record;
+    private warnOnce;
+    /** Record after the wrapped call succeeded: a failure here is reported, never thrown over the call's result. */
+    settle(p: Promise<unknown>): Promise<void>;
+    prompt(text: string): Promise<void>;
+    say(text: string): Promise<void>;
+    think(text: string): Promise<void>;
+    /**
+     * Run a tool through the policy gate. The policy decision is made and signed before `fn` runs; a denied (or held and
+     * not approved) call throws TracekitDenied and `fn` never runs. The result or error is recorded afterwards.
+     * Pass the model's tool-call id as toolUseId to link the execution to the model request that asked for it.
+     */
+    tool<T>(name: string, args: Record<string, unknown>, fn: () => T | Promise<T>, opts?: {
+        toolUseId?: string;
+    }): Promise<T>;
+    /** Low level: record a model call yourself. begin() is written before the request is sent. Null: not recorded. */
+    modelBegin(provider: string, operation: string, model: string | null, request: unknown, streamed?: boolean): Promise<string | null>;
+    modelEnd(exchange: string | null, end: ModelEnd): Promise<void>;
+    end(reason?: string): Promise<void>;
+}
+export declare function usageFromOpenAI(u: any): Usage | null;
+export declare function usageFromAnthropic(u: any): Usage | null;
+/** OpenAI SDK: chat.completions.create and responses.create, streaming included. Returns the same client. */
+export declare function instrumentOpenAI<C extends Record<string, any>>(client: C, tk: Tracekit): C;
+/** Anthropic SDK: messages.create, streaming (stream: true) included. Returns the same client. */
+export declare function instrumentAnthropic<C extends Record<string, any>>(client: C, tk: Tracekit): C;
+/**
+ * Vercel AI SDK language-model middleware (use with wrapLanguageModel({ model, middleware: tracekitMiddleware(tk) })).
+ * Works with the v4 (promptTokens/toolCalls) and v5 (inputTokens/content parts) result shapes.
+ */
+export declare function tracekitMiddleware(tk: Tracekit, provider?: string): {
+    wrapGenerate: ({ doGenerate, params, model }: any) => Promise<any>;
+    wrapStream: ({ doStream, params, model }: any) => Promise<any>;
+};
+/**
+ * Stagehand: wrap page/stagehand methods (act, extract, observe, goto by default) so every browser action is a
+ * policy-checked, signed `browser:<method>` step. A denied action throws TracekitDenied and never reaches the browser.
+ * Works on any object with those methods (Stagehand v2 `page`, or the v3 `stagehand` instance). Returns the same object.
+ */
+export declare function instrumentStagehand<P extends Record<string, any>>(page: P, tk: Tracekit, methods?: string[]): P;