@cygnuxlabs/tracekit 0.0.0-stage → 1.2.2

package/dist/v2/client.js

@@ -0,0 +1,749 @@
+/**
+ * Native client for the v2 signer RPC (tracekit/sdk/client.py in TypeScript), Node built-ins only.
+ *
+ *   import { Client, withRun } from "@cygnuxlabs/tracekit/v2";
+ *   const run = await new Client().registerRun("my-agent");
+ *   const d = await run.decide("call-1", "Bash", '{"command": "ls"}');
+ *   if (d.decision === "allow") await run.complete("call-1", "ok");
+ *   await run.close();
+ *
+ * The signer is the Unix socket in $TRACEKIT_SIGNER, `tcp://host:port` with $TRACEKIT_SIGNER_TOKEN (the loopback dev
+ * transport, mutual HMAC proof of the token), or an `https://host:port` URL (each call is one POST /v2/rpc;
+ * $TRACEKIT_SIGNER_TOKEN_FILE names a bearer token file re-read per call, $TRACEKIT_SIGNER_CERT/_KEY a client
+ * certificate for mTLS, $TRACEKIT_SIGNER_CA the signer's CA). In system mode the signer is the one the root-owned
+ * /etc/tracekit/client.json names, and a $TRACEKIT_SIGNER naming another is refused. Without either, the same-user dev
+ * signer of the runtime dir is used, started with `tracekit up --json` (found as src/v2/launcher.ts says) when none answers.
+ * Requests go out in order on one connection and are answered in order; `approval_wait` gets a connection of its own.
+ * Every request is validated against the RPC contract before it is sent. Calls that change state carry a `request_id`
+ * and are resent with it when the connection drops. Event calls carry this client's `stream` and a `client_seq` per run;
+ * a run's events go out one at a time, each once the one before it is answered, so they reach the signer in order.
+ * The client writes nothing to disk.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { execFile } from "node:child_process";
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
+import { Agent, request } from "node:https";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { basename, extname, join } from "node:path";
+import { TracekitAgents } from "./adapters/openai-agents.js";
+import { tracekitAI } from "./adapters/vercel-ai.js";
+import { argsDigest } from "./jcs.js";
+import { INSTALL_HINT, signerCommand, signerEnv } from "./launcher.js";
+import { REQUESTS, RPC_VERSION } from "./rpc_schema.js";
+import { validate } from "./validate.js";
+export { RPC_VERSION };
+export { argsDigest, canonicalize, digest, strictParse, StrictJSONError } from "./jcs.js";
+export const SYSTEM_CONFIG = "/etc/tracekit/client.json";
+const CONNECT_TIMEOUT_MS = 2000;
+const RETRIES = 3;
+export class SignerUnavailable extends Error {
+    name = "SignerUnavailable";
+}
+/** The signer answered but does not speak this client's protocol version. It is left running. */
+export class Incompatible extends Error {
+    name = "Incompatible";
+}
+/** A refusal from the signer (or of a request that fails the contract before it is sent). */
+export class RPCError extends Error {
+    code;
+    retryAfterMs;
+    name = "RPCError";
+    constructor(code, message, retryAfterMs) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+class ConnectionLost extends Error {
+}
+const newId = () => randomUUID().replaceAll("-", "");
+const hmac = (token, label, nonce) => createHmac("sha256", token).update(`${label}\n${nonce}`).digest("hex");
+function warn(message) {
+    process.emitWarning(message, "TracekitWarning");
+}
+function withTimeout(p, ms, onTimeout) {
+    let timer;
+    const t = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            onTimeout();
+            reject(new SignerUnavailable(`no answer from the signer within ${ms / 1000}s`));
+        }, ms);
+    });
+    return Promise.race([p, t]).finally(() => clearTimeout(timer));
+}
+/** Newline-delimited JSON frames on one socket; answers are matched to requests in order. */
+class Conn {
+    sock;
+    pending = [];
+    buf = "";
+    constructor(sock) {
+        this.sock = sock;
+        sock.setEncoding("utf8");
+        sock.unref(); // an idle connection does not keep the process alive
+        sock.on("data", (d) => {
+            this.buf += d;
+            for (let n; (n = this.buf.indexOf("\n")) >= 0;) {
+                const line = this.buf.slice(0, n), p = this.pending.shift();
+                this.buf = this.buf.slice(n + 1);
+                let frame;
+                try {
+                    frame = JSON.parse(line);
+                }
+                catch {
+                    frame = null;
+                }
+                if (!p || typeof frame !== "object" || frame === null) { // an answer nobody asked for, or not a frame
+                    if (p)
+                        this.pending.unshift(p);
+                    return void sock.destroy();
+                }
+                if (!this.pending.length)
+                    sock.unref();
+                p.resolve(frame);
+            }
+        });
+        sock.on("error", () => { }); // "close" follows
+        sock.on("close", () => {
+            for (const p of this.pending.splice(0))
+                p.reject(new ConnectionLost());
+        });
+    }
+    write(frame) {
+        this.sock.write(JSON.stringify(frame) + "\n");
+    }
+    send(frame) {
+        return new Promise((resolve, reject) => {
+            if (this.sock.destroyed)
+                return reject(new ConnectionLost());
+            const line = JSON.stringify(frame) + "\n"; // may throw: before anything waits for an answer
+            this.pending.push({ resolve, reject });
+            this.sock.ref();
+            this.sock.write(line);
+        });
+    }
+}
+function open(sock) {
+    return new Promise((resolve, reject) => {
+        sock.setTimeout(CONNECT_TIMEOUT_MS, () => sock.destroy(new Error("connect timed out")));
+        sock.once("connect", () => {
+            sock.setTimeout(0);
+            resolve(sock);
+        });
+        sock.once("error", reject);
+    });
+}
+function check(hello, where) {
+    const proto = hello?.proto;
+    if (!(Array.isArray(proto) && proto.length === 2 && proto[0] <= RPC_VERSION && RPC_VERSION <= proto[1]))
+        throw new Incompatible(`the Tracekit signer ${hello?.version ?? "?"} (pid ${hello?.pid ?? "?"}, protocol ` +
+            `${JSON.stringify(proto)}) at ${where} cannot serve this client (protocol ${RPC_VERSION}). It was left running. ` +
+            "Stop it with `tracekit down`, or replace it with `tracekit up --replace`");
+}
+/** A connection to the signer at `path` (a Unix socket or tcp://host:port) and its hello, after the version check. */
+export async function connect(path, token) {
+    let conn, hello;
+    try {
+        if (path.startsWith("tcp://")) {
+            const hostPort = path.slice(6), k = hostPort.lastIndexOf(":"), host = hostPort.slice(0, k);
+            if (!["127.0.0.1", "::1", "localhost"].includes(host)) // frames after the handshake are plaintext
+                throw new SignerUnavailable(`${path}: tcp:// signers must be on loopback (127.0.0.1, ::1 or localhost)`);
+            token ||= process.env.TRACEKIT_SIGNER_TOKEN;
+            if (!token)
+                throw new SignerUnavailable(`${path}: tcp:// signers need TRACEKIT_SIGNER_TOKEN`);
+            conn = new Conn(await open(createConnection({ host, port: Number(hostPort.slice(k + 1)) })));
+            // the signer proves it holds the token over our nonce before we prove it over its own (transport/tcp_dev.py)
+            const nonce = randomBytes(16).toString("hex");
+            const reply = await withTimeout(conn.send({ method: "hello", nonce }), CONNECT_TIMEOUT_MS, () => conn.sock.destroy());
+            const proof = Buffer.from(String(reply.proof)), want = Buffer.from(hmac(token, "signer", nonce));
+            if (proof.length !== want.length || !timingSafeEqual(proof, want))
+                throw new Error("dev token proof mismatch");
+            if (typeof reply.nonce !== "string" || reply.nonce.length < 16 || reply.nonce.length > 128)
+                throw new Error("handshake needs a nonce of 16-128 characters");
+            conn.write({ proof: hmac(token, "client", reply.nonce) });
+        }
+        else if (process.platform !== "win32") {
+            conn = new Conn(await open(createConnection(path)));
+        }
+        else {
+            throw new SignerUnavailable(`this platform has no Unix sockets: name the signer tcp://host:port, not ${path}`);
+        }
+        const c = conn;
+        hello = await withTimeout(c.send({ method: "hello" }), CONNECT_TIMEOUT_MS, () => c.sock.destroy());
+    }
+    catch (e) {
+        conn?.sock.destroy();
+        if (e instanceof SignerUnavailable && !conn)
+            throw e;
+        throw new SignerUnavailable(`no signer answering at ${path}: ${e.message}`);
+    }
+    try {
+        check(hello, path);
+    }
+    catch (e) {
+        conn.sock.destroy();
+        throw e;
+    }
+    return { conn, hello };
+}
+/** The root-owned system-mode client config, or null when there is none; throws when it exists but can't be trusted. */
+export function systemConfig(path = SYSTEM_CONFIG) {
+    if (process.platform === "win32")
+        return null; // no root-owned config there, as in the Python client
+    let st;
+    try {
+        st = statSync(path);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw new Error(`${path} cannot be read: ${e.message}`);
+    }
+    if (st.uid !== 0 || st.mode & 0o022)
+        throw new Error(`${path} must be owned by root and not group- or world-writable`);
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${path} cannot be parsed: ${e.message}`);
+    }
+    if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg))
+        throw new Error(`${path} must hold a JSON object`);
+    return cfg;
+}
+/** $TRACEKIT_SIGNER, or in system mode the system signer: there a $TRACEKIT_SIGNER that names another is refused. */
+export function defaultSigner(env = process.env, system = systemConfig()) {
+    const mine = env.TRACEKIT_SIGNER || null, theirs = system?.signer || null;
+    if (theirs && mine && mine !== theirs)
+        throw new SignerUnavailable(`TRACEKIT_SIGNER=${mine.slice(0, 256)} is not the system signer ${theirs}; refused`);
+    return theirs || mine;
+}
+/** The dev signer's runtime dir, as tracekit/sdk/autospawn.py `runtime_dir` names it. */
+export function runtimeDir(env = process.env) {
+    if (env.TRACEKIT_RUNTIME_DIR)
+        return env.TRACEKIT_RUNTIME_DIR;
+    if (process.platform === "win32")
+        return join(env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "tracekit", "run");
+    if (process.platform === "darwin") {
+        const d = join(homedir(), "Library/Application Support/tracekit/run");
+        return Buffer.byteLength(join(d, "signer.sock")) > 103 ? `/tmp/tk-${process.getuid()}` : d; // macOS: 104-byte socket paths
+    }
+    return env.XDG_RUNTIME_DIR ? join(env.XDG_RUNTIME_DIR, "tracekit") : `/tmp/tracekit-${process.getuid()}`;
+}
+/** The runtime dir of the same-user dev signer; refused in system mode, as tracekit/sdk/autospawn.py `ensure` does. */
+export function devRuntimeDir(system = SYSTEM_CONFIG) {
+    if (existsSync(system))
+        throw new SignerUnavailable("dev auto-spawn is off when TRACEKIT_SIGNER is set or in system mode");
+    return runtimeDir();
+}
+/** [path, token] of the dev signer in runtime dir `d`; SignerUnavailable while there is none or the dir isn't private. */
+function devAddress(d) {
+    try {
+        if (process.platform !== "win32") {
+            const st = lstatSync(d);
+            if (!st.isDirectory() || st.uid !== process.getuid() || st.mode & 0o077)
+                throw new SignerUnavailable(`${d} must be a directory owned by you with mode 0700`);
+            return [join(d, "signer.sock")];
+        }
+        const ep = JSON.parse(readFileSync(join(d, "endpoint.json"), "utf8"));
+        if (!Number.isInteger(ep?.port) || typeof ep?.token !== "string")
+            throw new Error("no port and token yet");
+        return [`tcp://127.0.0.1:${ep.port}`, ep.token];
+    }
+    catch (e) {
+        if (e instanceof SignerUnavailable)
+            throw e;
+        throw new SignerUnavailable(`no dev signer in ${d}: ${e.message}`);
+    }
+}
+/** 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 function routeUrl(url, frame) {
+    const host = url.hostname, dot = host.indexOf("."), first = dot < 0 ? host : host.slice(0, dot);
+    const id = String(frame.run_id ?? frame.approval_id ?? frame.analyzes ?? frame.parent?.run_id ?? ""), cut = id.indexOf(".");
+    const route = cut < 0 ? "" : id.slice(0, cut);
+    if (!route || !new RegExp("^" + first.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "-[0-9]+$").test(route))
+        return url;
+    const out = new URL(url.href);
+    out.hostname = dot < 0 ? route : route + host.slice(dot);
+    return out;
+}
+class Https {
+    agent;
+    url;
+    hello = null;
+    constructor(signer) {
+        const env = process.env, file = (p) => (p ? readFileSync(p) : undefined);
+        this.url = new URL("/v2/rpc", signer);
+        const cert = env.TRACEKIT_SIGNER_CERT; // its key in TRACEKIT_SIGNER_KEY, or in the same file
+        this.agent = new Agent({ keepAlive: true, ca: file(env.TRACEKIT_SIGNER_CA), cert: file(cert),
+            key: cert ? file(env.TRACEKIT_SIGNER_KEY || cert) : undefined });
+    }
+    /** The answer frame; ConnectionLost when the request may not have arrived, SignerUnavailable on a timeout. */
+    post(frame, timeoutMs) {
+        const body = JSON.stringify(frame), tokenFile = process.env.TRACEKIT_SIGNER_TOKEN_FILE;
+        const headers = { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) };
+        if (tokenFile) {
+            try {
+                headers.Authorization = "Bearer " + readFileSync(tokenFile, "utf8").trim(); // re-read: a rotated token is picked up
+            }
+            catch (e) {
+                throw new SignerUnavailable(`cannot read the signer token file: ${e.message}`);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const req = request(routeUrl(this.url, frame), { method: "POST", agent: this.agent, headers, timeout: timeoutMs }, (res) => {
+                let data = "";
+                res.setEncoding("utf8");
+                res.on("data", (d) => (data += d));
+                res.on("error", () => reject(new ConnectionLost()));
+                res.on("end", () => {
+                    try {
+                        const f = JSON.parse(data);
+                        if (typeof f !== "object" || f === null)
+                            throw new Error();
+                        resolve(f);
+                    }
+                    catch {
+                        reject(new ConnectionLost());
+                    }
+                });
+            });
+            req.on("timeout", () => {
+                reject(new SignerUnavailable(`no answer from the signer within ${timeoutMs / 1000}s`));
+                req.destroy();
+            });
+            req.on("error", () => reject(new ConnectionLost()));
+            req.end(body);
+        });
+    }
+    async rpc(frame, timeoutMs) {
+        if (!this.hello) {
+            const hello = await this.post({ method: "hello" }, timeoutMs);
+            if (hello.error)
+                throw new RPCError(hello.error.code, hello.error.message ?? "");
+            check(hello, this.url.origin);
+            this.hello = hello;
+        }
+        return this.post(frame, timeoutMs);
+    }
+}
+/** Methods take the request object of an RPC and return its response, or reject with RPCError (a refusal),
+ * SignerUnavailable or Incompatible. */
+export class Client {
+    signer;
+    stream = newId();
+    timeoutMs;
+    hello = null;
+    https;
+    conn = null;
+    seqs = new Map();
+    order = new Map(); // run_id -> settles once its last event so far is answered
+    inflight = new Set();
+    constructor(opts = {}) {
+        this.signer = opts.signer ?? defaultSigner();
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.https = this.signer?.startsWith("https://") ? new Https(this.signer) : null;
+    }
+    /** 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. */
+    async registerRun(agent, fields = {}, parent) {
+        return new RunHandle(this, await this.call("register_run", {
+            agent: typeof agent === "string" ? { name: agent } : agent, ...fields,
+            ...(parent ? { parent: { run_id: parent.runId, run_token: parent.runToken } } : {}),
+        }));
+    }
+    /** `request_id`, `stream` and `client_seq` are filled in when missing. */
+    call(method, req = {}) {
+        return this.waitUntil(this.send(method, { ...req }));
+    }
+    /** Resolves once every call made so far, and every promise given to waitUntil, has settled. */
+    async flush() {
+        while (this.inflight.size)
+            await Promise.allSettled([...this.inflight]);
+    }
+    /** Have flush() and close() wait for `p` too (for serverless hosts that freeze the process after a response). */
+    waitUntil(p) {
+        this.inflight.add(p);
+        const done = () => this.inflight.delete(p);
+        p.then(done, done);
+        return p;
+    }
+    /** Waits for what is in flight, then closes the connection. */
+    async close() {
+        await this.flush();
+        const conn = this.conn;
+        this.conn = null;
+        conn?.then((c) => c.sock.destroy(), () => { });
+    }
+    async send(method, req) {
+        const schema = REQUESTS[method];
+        if (!schema)
+            throw new RPCError("invalid_request", `unknown method ${method.slice(0, 64)}`);
+        if ("request_id" in schema.properties)
+            req.request_id ??= newId();
+        let claim = "client_seq" in schema.properties && !("client_seq" in req);
+        if (claim)
+            Object.assign(req, { stream: this.stream, client_seq: this.seqs.get(req.run_id) ?? 0 });
+        const used = this.seqs.get(req.run_id);
+        // the last client_seq this stream used: one the signer never received becomes its client_counter_gap
+        if (method === "close_run" && used && !("last_client_seq" in req))
+            req.last_client_seq = [{ stream: this.stream, client_seq: used - 1 }];
+        const errs = validate(schema, req);
+        if (errs.length)
+            throw new RPCError("invalid_request", errs.join("; "));
+        try {
+            JSON.stringify(req);
+        }
+        catch (e) {
+            throw new RPCError("invalid_request", `the ${method} request is not JSON: ${e.message}`);
+        }
+        const frame = () => {
+            if (claim) {
+                req.client_seq = this.seqs.get(req.run_id) ?? 0;
+                this.seqs.set(req.run_id, req.client_seq + 1);
+                claim = false;
+            }
+            return { method, ...req };
+        };
+        const timeout = this.timeoutMs + (req.timeout_ms ?? 0), deadline = Date.now() + timeout;
+        let release = () => { };
+        if (claim) {
+            try {
+                release = await this.turn(req.run_id, timeout);
+            }
+            catch (e) {
+                frame(); // used up: the signer's client_counter_gap covers a call it never saw
+                throw e;
+            }
+        }
+        try {
+            for (let i = 0; i < RETRIES; i++) {
+                const left = Math.max(deadline - Date.now(), 1);
+                let reply;
+                try {
+                    if (this.https) {
+                        reply = await this.https.rpc(frame(), left);
+                        this.hello = this.https.hello;
+                    }
+                    else if ("timeout_ms" in schema.properties) {
+                        reply = await this.poll(frame(), left);
+                    }
+                    else {
+                        const conn = await this.connection();
+                        reply = await withTimeout(conn.send(frame()), left, () => conn.sock.destroy());
+                    }
+                }
+                catch (e) {
+                    if (e instanceof ConnectionLost)
+                        continue;
+                    if (e instanceof SignerUnavailable)
+                        frame(); // used up: the signer's client_counter_gap covers a call it never saw
+                    throw e;
+                }
+                if (reply.error) {
+                    const e = reply.error;
+                    if (["run_closed", "unknown_run"].includes(e.code))
+                        this.seqs.delete(req.run_id); // no more events for it
+                    throw new RPCError(e.code, e.message ?? "", e.retry_after_ms);
+                }
+                if (method === "close_run")
+                    this.seqs.delete(req.run_id);
+                return reply;
+            }
+            throw new SignerUnavailable(`lost the connection to the signer ${RETRIES} times`);
+        }
+        finally {
+            release();
+        }
+    }
+    /** 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`. */
+    async turn(runId, ms) {
+        const prev = this.order.get(runId) ?? Promise.resolve();
+        let done;
+        const mine = new Promise((r) => (done = r)), tail = prev.then(() => mine);
+        this.order.set(runId, tail);
+        const release = () => {
+            done();
+            if (this.order.get(runId) === tail)
+                this.order.delete(runId);
+        };
+        try {
+            await withTimeout(prev, ms, () => { });
+        }
+        catch (e) {
+            release();
+            throw e;
+        }
+        return release;
+    }
+    /** One request on a connection of its own, closed after the answer. */
+    async poll(frame, timeout) {
+        const { conn } = await this.dial();
+        try {
+            return await withTimeout(conn.send(frame), timeout, () => { });
+        }
+        finally {
+            conn.sock.destroy();
+        }
+    }
+    connection() {
+        if (!this.conn) {
+            const p = this.dial().then(({ conn }) => {
+                conn.sock.on("close", () => this.conn === p && (this.conn = null));
+                return conn;
+            }, (e) => {
+                if (this.conn === p)
+                    this.conn = null;
+                throw e;
+            });
+            this.conn = p;
+        }
+        return this.conn;
+    }
+    async dial() {
+        let c;
+        if (this.signer) {
+            c = await connect(this.signer);
+        }
+        else {
+            const d = devRuntimeDir();
+            try {
+                c = await connect(...devAddress(d));
+            }
+            catch (e) {
+                if (!(e instanceof SignerUnavailable))
+                    throw e;
+                await startDevSigner();
+                c = await connect(...devAddress(d));
+            }
+        }
+        this.hello = c.hello;
+        return c;
+    }
+}
+/** `tracekit up --json`: find or start the same-user dev signer (it takes the locks, not this client). */
+function startDevSigner() {
+    const cmd = signerCommand();
+    if (!cmd)
+        return Promise.reject(new SignerUnavailable(`no dev signer, and ${INSTALL_HINT}`));
+    return new Promise((resolve, reject) => {
+        execFile(cmd[0], [...cmd.slice(1), "up", "--json"], { timeout: 30_000, env: signerEnv(cmd) }, (err, _out, stderr) => err ? reject(new SignerUnavailable(`no dev signer, and \`${cmd.join(" ")} up\` failed: ${stderr.trim() || err.message}`)) : resolve());
+    });
+}
+/** 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 function failOpen(failModes, toolClass) {
+    const modes = failModes ?? {};
+    return ((toolClass !== undefined && Object.hasOwn(modes, toolClass) ? modes[toolClass] : modes.default) ?? "closed") === "open";
+}
+const NEW_WORK = new Set(["decide", "model_event", "observe", "state_write"]); // to the current run
+const BY_CALL = new Set(["complete", "approval_request", "approval_consume"]); // to the run the call was decided in
+const KEEP = 4096; // tool calls and approvals whose run is remembered
+function remember(m, k, v) {
+    m.delete(k);
+    m.set(k, v);
+    if (m.size > KEEP)
+        m.delete(m.keys().next().value);
+}
+/** A registered run. Its methods fill in run_id and run_token; `fields` adds optional request fields. */
+export class RunHandle {
+    client;
+    runId;
+    runToken;
+    failModes;
+    registered;
+    closed = false;
+    /** 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 = null;
+    decided = new Map();
+    at = new Map(); // tool call or approval id -> its run
+    renewing = null;
+    constructor(client, registered) {
+        this.client = client;
+        this.registered = registered;
+        this.runId = registered.run_id;
+        this.runToken = registered.run_token;
+        this.failModes = registered.fail_modes;
+    }
+    /** 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() {
+        const proxy = process.env.TRACEKIT_EGRESS_PROXY;
+        if (!proxy)
+            return {};
+        const u = new URL(proxy);
+        u.username = encodeURIComponent(this.runId);
+        u.password = encodeURIComponent(this.runToken);
+        return Object.fromEntries(["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"].map((k) => [k, u.href]));
+    }
+    /** 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). */
+    async call(method, fields = {}) {
+        const key = BY_CALL.has(method) ? fields.tool_call_id : method === "approval_wait" || method === "approval_abandon" ? fields.approval_id : undefined;
+        let run = (key !== undefined && this.at.get(key)) || { run_id: this.runId, run_token: this.runToken }, out;
+        try {
+            out = await this.client.call(method, { ...run, ...fields });
+        }
+        catch (e) {
+            if (!(e instanceof RPCError) || !["run_closed", "unknown_run"].includes(e.code) || !NEW_WORK.has(method)
+                || this.renewAs === null || this.closed)
+                throw e;
+            await this.renew(run.run_id, e);
+            run = { run_id: this.runId, run_token: this.runToken };
+            out = await this.client.call(method, { ...run, ...fields }); // once: what the new run answers is the answer
+        }
+        if (method === "decide")
+            remember(this.at, fields.tool_call_id, run);
+        if (method === "approval_request" && out.approval_id)
+            remember(this.at, out.approval_id, run);
+        return out;
+    }
+    renew(closed, e) {
+        if (closed !== this.runId)
+            return Promise.resolve(); // renewed already
+        this.renewing ??= (async () => {
+            const agent = { agent: { name: this.renewAs } };
+            let r;
+            try { // linked to the closed run while it is still closing
+                r = await this.client.call("register_run", { ...agent, parent: { run_id: this.runId, run_token: this.runToken } });
+            }
+            catch (err) {
+                if (!(err instanceof RPCError))
+                    throw err;
+                r = await this.client.call("register_run", agent);
+            }
+            warn(`tracekit: the signer closed run ${this.runId} (${e.message}); recording in a new run ${r.run_id}. A server should open a run per conversation`);
+            [this.registered, this.runId, this.runToken, this.failModes] = [r, r.run_id, r.run_token, r.fail_modes];
+        })().finally(() => (this.renewing = null));
+        return this.renewing;
+    }
+    /** `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. */
+    async decide(toolCallId, tool, args, fields = {}) {
+        let d;
+        try {
+            d = await this.call("decide", { tool_call_id: toolCallId, tool, args, args_source: typeof args === "string" ? "raw" : "parsed", ...fields });
+        }
+        catch (e) {
+            if (!(e instanceof SignerUnavailable))
+                throw e;
+            const open = failOpen(this.failModes, fields.tool_class_hint);
+            warn(`tracekit: ${tool} ${open ? "runs unrecorded (fail open)" : "is denied (fail closed)"}: ${e.message}`);
+            return { decision: open ? "allow" : "deny", rule_ids: [], reason: `signer unavailable: ${e.message}`.slice(0, 1024), unavailable: true };
+        }
+        try { // a denied call is never completed: nothing to remember; others are capped, as `at` is
+            if (d.decision !== "deny")
+                remember(this.decided, toolCallId, { decision_id: d.decision_id, args_digest: argsDigest(tool, args) });
+        }
+        catch {
+            // the signer has no args digest to bind either; complete needs explicit fields
+        }
+        return d;
+    }
+    /** 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. */
+    async complete(toolCallId, status = "ok", fields = {}) {
+        const decided = this.decided.get(toolCallId);
+        this.decided.delete(toolCallId);
+        try {
+            return await this.call("complete", { tool_call_id: toolCallId, status, ...decided, ...fields });
+        }
+        catch (e) {
+            warn(`tracekit: the result of ${toolCallId} was not recorded: ${e.message}`);
+            return null;
+        }
+        finally {
+            this.at.delete(toolCallId);
+        }
+    }
+    approvalRequest(toolCallId, fields = {}) {
+        return this.call("approval_request", { tool_call_id: toolCallId, ...fields });
+    }
+    /** Waits up to `timeoutMs` (signer cap 300 s) for a decision, on a connection of its own. */
+    approvalWait(approvalId, timeoutMs) {
+        return this.call("approval_wait", { approval_id: approvalId, ...(timeoutMs === undefined ? {} : { timeout_ms: timeoutMs }) });
+    }
+    /** 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, source, trust = "untrusted", fields = {}) {
+        return this.call("observe", { value, source, trust, ...fields });
+    }
+    stateWrite(key, valueDigest, fields = {}) {
+        return this.call("state_write", { key, value_digest: valueDigest, ...fields });
+    }
+    modelEvent(provider, model, phase, fields = {}) {
+        return this.call("model_event", { provider, model, phase, ...fields });
+    }
+    async close(reason) {
+        if (!this.closed) {
+            this.renewAs = null; // a call refused as closed while this one is in flight must not register a new run
+            await this.call("close_run", reason ? { reason } : {});
+            this.closed = true;
+        }
+    }
+}
+const current = new AsyncLocalStorage();
+/** Runs `fn` with `handle` as the current run of everything it awaits. */
+export function withRun(handle, fn) {
+    return current.run(handle, fn);
+}
+export function currentRun() {
+    return current.getStore();
+}
+let instrumented = null;
+const LEAVE_MS = 2000; // the most an exiting process waits for the signer
+const once = (fn) => {
+    let p = null;
+    return () => (p ??= fn());
+};
+/** Closes `run` as the process exits, unless approvals of it are still waiting (requested, or approved and not yet
+ * consumed): then it stays open for another process to resume (`new RunHandle(client, { run_id, run_token })`) until
+ * the signer closes it after idle_s. Never rejects; waits at most LEAVE_MS. */
+async function leave(run) {
+    const work = (async () => {
+        const open = (state) => run.client.call("approval_list", { run_id: run.runId, state, limit: 1 })
+            .then((r) => r.approvals.length > 0);
+        // requested, or approved and not yet consumed; a listing that fails (no grant) waits for nothing
+        if (await Promise.all([open("requested"), open("approved")]).then((w) => w.some(Boolean), () => false))
+            warn(`tracekit: run ${run.runId} left open: approvals of it are waiting for a person or to be resumed`);
+        else
+            await run.close();
+        await run.client.close();
+    })().catch(() => { });
+    await Promise.race([work, new Promise((r) => setTimeout(r, LEAVE_MS).unref())]);
+}
+/** 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 function instrument(agent, opts = {}) {
+    const name = agent ?? process.env.TRACEKIT_AGENT ?? basename(process.argv[1] ?? "node", extname(process.argv[1] ?? ""));
+    instrumented ??= Promise.resolve().then(() => new Client(opts).registerRun(name)).then((run) => {
+        run.renewAs = name;
+        const end = once(() => leave(run));
+        process.once("beforeExit", () => void end());
+        for (const sig of ["SIGINT", "SIGTERM"])
+            process.prependOnceListener(sig, () => {
+                // run first and decide before anything is awaited: a signal another listener (the app's, a library's)
+                // handles is theirs, so the run stays as it is (beforeExit still closes it); else close, then the default action
+                if (!process.listenerCount(sig))
+                    void end().finally(() => process.kill(process.pid, sig));
+            });
+        // lean: process.exit() and an uncaught exception leave the run open until the signer's idle_s (no async on exit);
+        // close it synchronously from an exit hook if open runs pile up
+        return { run, ai: tracekitAI(run), agents: new TracekitAgents(run) };
+    }, (e) => {
+        instrumented = null;
+        throw e;
+    });
+    return instrumented;
+}