@cygnuxlabs/tracekit 0.0.0-stage → 1.2.2

package/dist/v2/adapters/vercel-ai.js

@@ -0,0 +1,132 @@
+import { digest } from "../jcs.js";
+import { EXECUTOR } from "../executor.js";
+import { BLOCKED, Gate, approvalStates, defined, failure, keep, recordResponse, refusal, take, toolUse } from "./gate.js";
+/** LanguageModelV3/V4 usage as the signer's usage buckets (input_tokens without cache reads). */
+function usage(u) {
+    return u?.inputTokens && defined({ input_tokens: u.inputTokens.noCache ?? u.inputTokens.total, output_tokens: u.outputTokens?.total,
+        cache_read_tokens: u.inputTokens.cacheRead, cache_write_tokens: u.inputTokens.cacheWrite, reasoning_tokens: u.outputTokens?.reasoning });
+}
+const stop = (fr) => (typeof fr === "string" ? fr : fr?.unified);
+export function tracekitAI(run) {
+    const gate = new Gate(run);
+    const executors = new Set(); // the names of tool executor tools tk.tools() was given
+    const raw = new Map(); // toolCallId -> the model's arguments string
+    const decided = new Map(); // toolCallId -> its decision, from toolApproval to execute
+    const named = new Map(); // tool name -> the name it is decided as (mcp:<server>/<tool>)
+    const seen = (p) => {
+        if (p?.type === "tool-call" && !p.providerExecuted && typeof p.input === "string")
+            keep(raw, p.toolCallId, p.input);
+    };
+    const toolUses = (parts) => parts.filter((p) => p?.type === "tool-call")
+        .map((p) => toolUse(p.toolCallId, p.toolName, p.input, !!p.providerExecuted)).slice(0, 128);
+    /** For `toolApproval:` on generateText, streamText and ToolLoopAgent. */
+    const toolApproval = async ({ toolCall, tools }) => {
+        if (tools?.[toolCall.toolName]?.[EXECUTOR] || executors.has(toolCall.toolName))
+            return "not-applicable";
+        const id = toolCall.toolCallId;
+        // the arguments string stays only for a call whose `execute` will take it: not one denied, nor a tool without one
+        const args = tools?.[toolCall.toolName]?.execute ? raw.get(id) : take(raw, id);
+        let d;
+        try {
+            d = await gate.decide(id, named.get(toolCall.toolName) ?? toolCall.toolName, args ?? toolCall.input);
+        }
+        catch (e) {
+            raw.delete(id);
+            return { type: "denied", reason: BLOCKED + `signer refused the call: ${failure(e)}` };
+        }
+        if (d.decision === "deny") {
+            raw.delete(id);
+            return { type: "denied", reason: d.unavailable ? BLOCKED + d.reason : refusal(d.rule_ids) };
+        }
+        keep(decided, id, d);
+        if (d.decision !== "ask")
+            return "not-applicable"; // execute consumes
+        try {
+            await gate.runOf(id).approvalRequest(id, { attempt: gate.attempt(id) });
+        }
+        catch {
+            return "not-applicable"; // no approval to wait for: execute's approval_consume refuses the call
+        }
+        return { type: "user-approval", reason: d.rule_ids.join(", ") };
+    };
+    return {
+        middleware: {
+            specificationVersion: "v4",
+            async wrapGenerate({ doGenerate, model }) {
+                const r = await doGenerate();
+                (r.content ?? []).forEach(seen);
+                await recordResponse(gate.run, model.provider, model.modelId, () => ({ content_digest: digest(r.content ?? []),
+                    stop_reason: stop(r.finishReason), usage: usage(r.usage), tool_uses: toolUses(r.content ?? []) }));
+                return r;
+            },
+            async wrapStream({ doStream, model }) {
+                const r = await doStream(), calls = [], at = gate.run; // the run current when the stream began
+                let finish;
+                return { ...r, stream: r.stream.pipeThrough(new TransformStream({
+                        transform(p, c) {
+                            seen(p);
+                            if (p?.type === "tool-call")
+                                calls.push(p);
+                            if (p?.type === "finish")
+                                finish = p;
+                            c.enqueue(p);
+                        },
+                        // lean: a stream the caller abandons is not recorded; record it on cancel() if abandoned streams matter
+                        flush: () => recordResponse(at, model.provider, model.modelId, () => ({ streamed: true,
+                            stop_reason: stop(finish?.finishReason), usage: usage(finish?.usage), tool_uses: toolUses(calls) })),
+                    })) };
+            },
+        },
+        toolApproval,
+        /** `toolApproval` that also asks the app's own (a function, or one per tool name): the signer's policy first; the
+         * app's answer applies only to a call the policy allows. A call the app denies is completed as refused. */
+        toolApprovalWith(app) {
+            return async (opts) => {
+                const mine = await toolApproval(opts);
+                if (mine !== "not-applicable")
+                    return mine;
+                const { toolCall } = opts, id = toolCall.toolCallId;
+                const own = typeof app === "function" ? app : app?.[toolCall.toolName];
+                const theirs = typeof own === "function"
+                    ? await (typeof app === "function" ? own(opts) : own(toolCall.input, { toolCallId: id, messages: opts.messages }))
+                    : own;
+                if (theirs === "denied" || theirs?.type === "denied") {
+                    take(decided, id);
+                    await gate.runOf(id).complete(id, "error", { attempt: gate.attempt(id), error: "refused by the app's toolApproval" });
+                }
+                return theirs ?? mine;
+            };
+        },
+        /** `tools` with each `execute` gated by the signer. With `mcp` (the server's name: `tools(await mcp.tools(),
+         * { mcp: "filesystem" })`) each is decided as `mcp:<server>/<tool>`. */
+        tools(tools, { mcp } = {}) {
+            const as = (name) => mcp === undefined ? name : `mcp:${mcp.replace(/[^A-Za-z0-9_.-]+/g, "_") || "unknown"}/${name}`;
+            if (mcp !== undefined)
+                for (const name of Object.keys(tools))
+                    named.set(name, as(name));
+            return Object.fromEntries(Object.entries(tools).map(([name, t]) => [name, !t?.execute ? t
+                    : t[EXECUTOR] ? (executors.add(name), t) : {
+                        ...t,
+                        async execute(input, opts) {
+                            const id = opts?.toolCallId;
+                            const why = await gate.admit(id, as(name), take(raw, id) ?? input, { d: take(decided, id) });
+                            if (why !== null)
+                                throw new Error(why);
+                            return gate.execute(id, () => t.execute(gate.input(id, input), opts));
+                        },
+                    }]));
+        },
+        /** `tool-approval-response` parts for the `tool-approval-request` parts the signer's approvers decided. */
+        async approvalResponses(parts) {
+            const states = await approvalStates(gate.run);
+            return parts.filter((p) => p?.type === "tool-approval-request").flatMap((p) => {
+                const s = states.get(p.toolCall?.toolCallId ?? p.toolCallId);
+                if (s === "approved")
+                    return [{ type: "tool-approval-response", approvalId: p.approvalId, approved: true }];
+                if (s === "rejected" || s === "expired")
+                    return [{ type: "tool-approval-response", approvalId: p.approvalId, approved: false, reason: `Tool call ${s} in Tracekit` }];
+                return [];
+            });
+        },
+    };
+}

package/dist/v2/client.d.ts

@@ -0,0 +1,159 @@
+import { type Socket } from "node:net";
+import { TracekitAgents } from "./adapters/openai-agents.js";
+import { tracekitAI } from "./adapters/vercel-ai.js";
+import { RPC_VERSION } from "./rpc_schema.js";
+export { RPC_VERSION };
+export { argsDigest, canonicalize, digest, strictParse, StrictJSONError } from "./jcs.js";
+export declare const SYSTEM_CONFIG = "/etc/tracekit/client.json";
+export type Frame = Record<string, any>;
+export declare class SignerUnavailable extends Error {
+    name: string;
+}
+/** The signer answered but does not speak this client's protocol version. It is left running. */
+export declare class Incompatible extends Error {
+    name: string;
+}
+/** A refusal from the signer (or of a request that fails the contract before it is sent). */
+export declare class RPCError extends Error {
+    readonly code: string;
+    readonly retryAfterMs?: number | undefined;
+    name: string;
+    constructor(code: string, message: string, retryAfterMs?: number | undefined);
+}
+/** Newline-delimited JSON frames on one socket; answers are matched to requests in order. */
+declare class Conn {
+    readonly sock: Socket;
+    private pending;
+    private buf;
+    constructor(sock: Socket);
+    write(frame: Frame): void;
+    send(frame: Frame): Promise<Frame>;
+}
+/** A connection to the signer at `path` (a Unix socket or tcp://host:port) and its hello, after the version check. */
+export declare function connect(path: string, token?: string): Promise<{
+    conn: Conn;
+    hello: Frame;
+}>;
+/** The root-owned system-mode client config, or null when there is none; throws when it exists but can't be trusted. */
+export declare function systemConfig(path?: string): Frame | null;
+/** $TRACEKIT_SIGNER, or in system mode the system signer: there a $TRACEKIT_SIGNER that names another is refused. */
+export declare function defaultSigner(env?: NodeJS.ProcessEnv, system?: Frame | null): string | null;
+/** The dev signer's runtime dir, as tracekit/sdk/autospawn.py `runtime_dir` names it. */
+export declare function runtimeDir(env?: NodeJS.ProcessEnv): string;
+/** The runtime dir of the same-user dev signer; refused in system mode, as tracekit/sdk/autospawn.py `ensure` does. */
+export declare function devRuntimeDir(system?: string): string;
+/** The URL for the run or approval `frame` names, from the signer's `url`. A central signer's replica
+ * (docs/deploy-kubernetes.md) prefixes its ids with its route, `<service>-<n>.`: such an id goes to host `<service>-<n>`
+ * in the signer's domain, as the Python client does. */
+export declare function routeUrl(url: URL, frame: Frame): URL;
+export interface ClientOptions {
+    /** A Unix socket path, tcp://host:port or https://host:port; by default as described above. */
+    signer?: string;
+    /** Per-call timeout (default 30 s), plus a call's own `timeout_ms`. */
+    timeoutMs?: number;
+}
+/** Methods take the request object of an RPC and return its response, or reject with RPCError (a refusal),
+ * SignerUnavailable or Incompatible. */
+export declare class Client {
+    readonly signer: string | null;
+    readonly stream: string;
+    readonly timeoutMs: number;
+    hello: Frame | null;
+    private https;
+    private conn;
+    private seqs;
+    private order;
+    private inflight;
+    constructor(opts?: ClientOptions);
+    /** Register a run (`agent` is a name or {name, version}, `parent` the handle of the run starting it, such as a
+     * sub-agent's parent: the signer records the link); the handle holds its run token. */
+    registerRun(agent: string | {
+        name: string;
+        version?: string;
+    }, fields?: Frame, parent?: RunHandle): Promise<RunHandle>;
+    /** `request_id`, `stream` and `client_seq` are filled in when missing. */
+    call(method: string, req?: Frame): Promise<Frame>;
+    /** Resolves once every call made so far, and every promise given to waitUntil, has settled. */
+    flush(): Promise<void>;
+    /** Have flush() and close() wait for `p` too (for serverless hosts that freeze the process after a response). */
+    waitUntil<T>(p: Promise<T>): Promise<T>;
+    /** Waits for what is in flight, then closes the connection. */
+    close(): Promise<void>;
+    private send;
+    /** Waits up to `ms` for the run's event before this one to be answered, so a run's events reach the signer in
+     * client_seq order on every transport and retry. -> what ends this event's turn; SignerUnavailable after `ms`. */
+    private turn;
+    /** One request on a connection of its own, closed after the answer. */
+    private poll;
+    private connection;
+    private dial;
+}
+/** Whether a call of `toolClass` may run while the signer cannot be reached: its entry in register_run's
+ * `fail_modes`, else their `default`, else closed. A refusal from the signer is never a reason to fail open. */
+export declare function failOpen(failModes: Record<string, string> | undefined, toolClass?: string): boolean;
+export interface Decision extends Frame {
+    decision: "allow" | "deny" | "ask";
+    rule_ids: string[];
+    /** Set when the signer could not be reached: the decision is the run's fail mode, and nothing was recorded. */
+    unavailable?: true;
+    /** Set for a tool the policy lists as untrusted: `complete` should carry the result itself, not its digest, so the
+     * signer can index its values for provenance. */
+    send_result?: true;
+}
+/** A registered run. Its methods fill in run_id and run_token; `fields` adds optional request fields. */
+export declare class RunHandle {
+    readonly client: Client;
+    runId: string;
+    runToken: string;
+    failModes: Record<string, string> | undefined;
+    registered: Frame;
+    closed: boolean;
+    /** The agent name instrument()'s process run renews itself as once the signer closed it after it was idle; null:
+     * never renewed (a run the app registered itself, or one it closed). */
+    renewAs: string | null;
+    private decided;
+    private at;
+    private renewing;
+    constructor(client: Client, registered: Frame);
+    /** With $TRACEKIT_EGRESS_PROXY set (an egress observer, docs/egress.md#attribution): HTTPS_PROXY and HTTP_PROXY,
+     * both cases, naming it with this run's id and token as credentials, for the commands the run starts
+     * (`spawn(cmd, args, { env: { ...process.env, ...run.proxyEnv } })`) or an HTTP client's proxy, so the observer
+     * attributes their connections to this run. {} without it. This process's own environment is left as it is. */
+    get proxyEnv(): Record<string, string>;
+    /** Any per-run RPC with this run's id and token. A call's complete and approvals go to the run it was decided in;
+     * new work refused because the signer closed a renewable run goes to a new run (renewAs). */
+    call(method: string, fields?: Frame): Promise<Frame>;
+    private renew;
+    /** `args` is the model's raw arguments string, or an already parsed value. Only when the signer can't be reached
+     * does the run's fail mode for `fields.tool_class_hint` decide; a refusal rejects. */
+    decide(toolCallId: string, tool: string, args: unknown, fields?: Frame): Promise<Decision>;
+    /** Never rejects: a failure to record a call that already ran is a warning. Defaults decision_id and args_digest to
+     * those of the last `decide` for this tool call. */
+    complete(toolCallId: string, status?: "ok" | "error", fields?: Frame): Promise<Frame | null>;
+    approvalRequest(toolCallId: string, fields?: Frame): Promise<Frame>;
+    /** Waits up to `timeoutMs` (signer cap 300 s) for a decision, on a connection of its own. */
+    approvalWait(approvalId: string, timeoutMs?: number): Promise<Frame>;
+    /** Records content that entered the run other than as a tool result (a mail, a ticket, a page the app fetched) for
+     * the signer's provenance index; the task or user prompt goes in with trust "trusted". Only its commitment is recorded. */
+    observe(value: unknown, source: string, trust?: "trusted" | "untrusted", fields?: Frame): Promise<Frame>;
+    stateWrite(key: string, valueDigest: string, fields?: Frame): Promise<Frame>;
+    modelEvent(provider: string, model: string, phase: "request" | "response", fields?: Frame): Promise<Frame>;
+    close(reason?: string): Promise<void>;
+}
+/** Runs `fn` with `handle` as the current run of everything it awaits. */
+export declare function withRun<T>(handle: RunHandle, fn: () => T): T;
+export declare function currentRun(): RunHandle | undefined;
+export interface Instrumented {
+    run: RunHandle;
+    /** Vercel AI SDK: `wrapLanguageModel({ model, middleware: ai.middleware })`, `tools: ai.tools({...})`,
+     * `toolApproval: ai.toolApproval` (src/v2/adapters/vercel-ai.ts). */
+    ai: ReturnType<typeof tracekitAI>;
+    /** OpenAI Agents SDK: `agents.tool(tool, {...})` for each tool (src/v2/adapters/openai-agents.ts). */
+    agents: TracekitAgents;
+}
+/** One call: registers a run (with the same-user dev signer, started if none answers, unless a signer is configured as
+ * described above), closes it when the process is about to exit, and returns it with the Vercel AI SDK and OpenAI
+ * Agents adapters bound to it. A second call returns the same. ES modules can't be patched from outside, so the
+ * adapters are handed to you to pass to the framework, rather than wired as `tracekit.instrument()` does in Python.
+ * `agent` names the run (default: $TRACEKIT_AGENT, else the script's name). */
+export declare function instrument(agent?: string, opts?: ClientOptions): Promise<Instrumented>;