@uncoil.dev/sdk 0.0.0-stage → 0.6.0

package/dist/integrations/auto.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+exports.uninit = uninit;
+const providers_1 = require("./providers");
+const TARGETS = [
+    { provider: "openai", endpoint: "chat.completions.create", module: "openai/resources/chat/completions", exportName: "Completions" },
+    { provider: "openai", endpoint: "responses.create", module: "openai/resources/responses/responses", exportName: "Responses" },
+    { provider: "anthropic", endpoint: "messages.create", module: "@anthropic-ai/sdk/resources/messages", exportName: "Messages" },
+    { provider: "anthropic", endpoint: "beta.messages.create", module: "@anthropic-ai/sdk/resources/beta/messages/messages", exportName: "Messages" },
+];
+const restore = [];
+// A real dynamic import (tsc would turn `import()` into `require` in this CommonJS build).
+const esmImport = new Function("name", "return import(name)");
+function patch(cls, target, options) {
+    const original = cls?.prototype?.create;
+    if (typeof original !== "function" || original.__uncoil)
+        return;
+    const patched = function (...args) {
+        if ((0, providers_1.isInsideWrapped)())
+            return original.apply(this, args);
+        return (0, providers_1.traced)(target.provider, target.endpoint, (params) => original.apply(this, [params, ...args.slice(1)]), args[0], options, false);
+    };
+    patched.__uncoil = true;
+    cls.prototype.create = patched;
+    restore.push(() => { cls.prototype.create = original; });
+}
+/**
+ * One-line setup: call `init()` once at startup and every OpenAI and Anthropic call your app makes is traced.
+ * It patches the installed `openai` and `@anthropic-ai/sdk` packages (skipping any that are missing), so no
+ * client has to be wrapped by hand. Both the CommonJS and the ES-module build are patched; the ES-module one
+ * lands a moment later, so `await init().ready` if your very first call happens at once.
+ * Call the returned function to switch it off again.
+ *
+ * For LangChain / LangGraph add `new UncoilLangGraphHandler()` to `callbacks`; for the Vercel AI SDK use
+ * `uncoilMiddleware()`. Use these OR `init()` for the same model calls, not both, or they are recorded twice.
+ */
+function init(options = {}) {
+    uninit();
+    const pending = [];
+    for (const target of TARGETS) {
+        try {
+            patch(require(target.module)[target.exportName], target, options);
+        }
+        catch { /* package not installed */ }
+        pending.push(esmImport(target.module).then((mod) => patch(mod[target.exportName], target, options)).catch(() => { }));
+    }
+    return Object.assign(() => uninit(), { ready: Promise.all(pending).then(() => undefined) });
+}
+/** Switch off everything `init()` switched on. */
+function uninit() {
+    while (restore.length)
+        restore.pop()();
+}

package/dist/integrations/langgraph.d.ts

@@ -0,0 +1,24 @@
+import { type IntegrationOptions } from "./observation";
+/** Structural LangChain/LangGraph callback handler; no mandatory framework dependency for SDK users. */
+export declare class UncoilLangGraphHandler {
+    private options;
+    name: string;
+    lc_serializable: boolean;
+    raiseError: boolean;
+    awaitHandlers: boolean;
+    private runs;
+    constructor(options?: IntegrationOptions);
+    private start;
+    private end;
+    handleChainStart(chain: any, input: unknown, id: string, parent?: string, _tags?: string[], _metadata?: any, _type?: string, name?: string): void;
+    handleChainEnd(output: unknown, id: string): void;
+    handleChainError(error: unknown, id: string): void;
+    handleToolStart(tool: any, input: unknown, id: string, parent?: string, _tags?: string[], _metadata?: any, name?: string): void;
+    handleToolEnd(output: unknown, id: string): void;
+    handleToolError(error: unknown, id: string): void;
+    handleLLMStart(llm: any, input: unknown, id: string, parent?: string, extra?: any): void;
+    handleChatModelStart(llm: any, messages: unknown, id: string, parent?: string, extra?: any): void;
+    handleLLMNewToken(_token: string, _idx: unknown, id: string): void;
+    handleLLMEnd(output: any, id: string): void;
+    handleLLMError(error: unknown, id: string): void;
+}

package/dist/integrations/langgraph.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UncoilLangGraphHandler = void 0;
+const index_1 = require("../index");
+const observation_1 = require("./observation");
+/** Structural LangChain/LangGraph callback handler; no mandatory framework dependency for SDK users. */
+class UncoilLangGraphHandler {
+    constructor(options = {}) {
+        this.options = options;
+        this.name = "uncoil";
+        this.lc_serializable = false;
+        this.raiseError = false;
+        this.awaitHandlers = true;
+        this.runs = new Map();
+    }
+    start(type, name, input, id, parent, model = "") {
+        if (this.runs.has(id))
+            return;
+        const ancestor = parent ? this.runs.get(parent) : undefined;
+        const context = (0, index_1.currentTraceContext)();
+        const outer = !ancestor && context?.runId && context.runId !== "unknown" ? context : undefined;
+        this.runs.set(id, (0, observation_1.observation)("langgraph", model, input, this.options, {
+            runId: ancestor?.runId ?? outer?.runId ?? id,
+            parentSpanId: ancestor?.id ?? outer?.spanId,
+            spanId: id,
+            root: !ancestor && !outer,
+            type,
+            name,
+        }));
+    }
+    end(id, output, error) {
+        const run = this.runs.get(id);
+        if (!run)
+            return;
+        run.finish(output, error);
+        this.runs.delete(id);
+    }
+    handleChainStart(chain, input, id, parent, _tags, _metadata, _type, name) {
+        this.start("agent", name ?? chain?.name ?? chain?.id?.at(-1) ?? "graph", input, id, parent);
+    }
+    handleChainEnd(output, id) {
+        this.end(id, output);
+    }
+    handleChainError(error, id) {
+        this.end(id, undefined, error);
+    }
+    handleToolStart(tool, input, id, parent, _tags, _metadata, name) {
+        this.start("tool_call", name ?? tool?.name ?? tool?.id?.at(-1) ?? "tool", input, id, parent);
+    }
+    handleToolEnd(output, id) {
+        this.end(id, output);
+    }
+    handleToolError(error, id) {
+        this.end(id, undefined, error);
+    }
+    handleLLMStart(llm, input, id, parent, extra) {
+        this.start("llm_call", extra?.invocation_params?.model ?? llm?.name ?? "model", input, id, parent, extra?.invocation_params?.model ?? "");
+    }
+    handleChatModelStart(llm, messages, id, parent, extra) {
+        this.handleLLMStart(llm, messages, id, parent, extra);
+    }
+    handleLLMNewToken(_token, _idx, id) {
+        this.runs.get(id)?.token();
+    }
+    handleLLMEnd(output, id) {
+        const run = this.runs.get(id);
+        const generation = output?.generations?.[0]?.[0];
+        const usage = output?.llmOutput?.tokenUsage ?? generation?.message?.usage_metadata;
+        if (usage)
+            run?.usage({
+                input_tokens: usage.input_tokens ?? usage.promptTokens,
+                output_tokens: usage.output_tokens ?? usage.completionTokens,
+            });
+        this.end(id, output);
+    }
+    handleLLMError(error, id) {
+        this.end(id, undefined, error);
+    }
+}
+exports.UncoilLangGraphHandler = UncoilLangGraphHandler;

package/dist/integrations/observation.d.ts

@@ -0,0 +1,31 @@
+import { UncoilClient, type SpanData } from "../index";
+export type IntegrationOptions = {
+    client?: UncoilClient;
+    name?: string;
+    captureInput?: boolean;
+    captureOutput?: boolean;
+    calculateCost?: (usage: {
+        provider: string;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        usage: Record<string, unknown>;
+    }) => number;
+};
+export declare function observation(provider: string, model: string, input: unknown, options: IntegrationOptions, scope?: {
+    runId: string;
+    parentSpanId?: string;
+    spanId?: string;
+    root?: boolean;
+    type?: string;
+    name?: string;
+}): {
+    id: string;
+    runId: string;
+    data: SpanData;
+    started: number;
+    usage(raw?: Record<string, unknown>, actualModel?: string): void;
+    token(): void;
+    finish(output?: unknown, error?: unknown, cancelled?: boolean): void;
+};
+export type Observation = ReturnType<typeof observation>;

package/dist/integrations/observation.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observation = observation;
+const node_crypto_1 = require("node:crypto");
+const index_1 = require("../index");
+function observation(provider, model, input, options, scope) {
+    const context = (0, index_1.currentTraceContext)(), inheritedRun = (0, index_1.currentRunId)();
+    const implicit = !scope && inheritedRun === "unknown";
+    const runId = scope?.runId ?? (implicit ? (0, node_crypto_1.randomUUID)() : inheritedRun);
+    const id = scope?.spanId ?? (0, node_crypto_1.randomUUID)(), rootId = implicit ? (0, node_crypto_1.randomUUID)() : undefined;
+    const client = options.client ?? context?.client ?? new index_1.UncoilClient();
+    const start = Date.now();
+    let ended = false;
+    const data = {
+        runId,
+        spanId: id,
+        parentSpanId: scope?.parentSpanId ?? rootId ?? context?.spanId,
+        spanType: scope?.type ?? "llm_call",
+        toolName: scope?.name ?? `${provider}.${model || "call"}`,
+        modelId: model,
+        traceName: context?.traceName ?? options.name ?? provider,
+        input: options.captureInput === false ? "[not captured]" : input,
+        metadata: { provider, costKnown: false },
+        createdAt: new Date(start).toISOString(),
+    };
+    const safeSend = (value) => {
+        try {
+            void client.ingest(value).catch(() => { });
+        }
+        catch {
+            /* Telemetry cannot change application behavior. */
+        }
+    };
+    return {
+        id,
+        runId,
+        data,
+        started: start,
+        usage(raw = {}, actualModel = model) {
+            data.modelId = actualModel;
+            data.inputTokens = Number(raw.input_tokens ?? raw.prompt_tokens ?? 0);
+            if (provider === "anthropic")
+                data.inputTokens += Number(raw.cache_creation_input_tokens ?? 0) + Number(raw.cache_read_input_tokens ?? 0);
+            data.outputTokens = Number(raw.output_tokens ?? raw.completion_tokens ?? 0);
+            data.metadata = { ...data.metadata, usage: raw };
+            if (options.calculateCost)
+                try {
+                    const cost = options.calculateCost({
+                        provider,
+                        model: actualModel,
+                        inputTokens: data.inputTokens,
+                        outputTokens: data.outputTokens,
+                        usage: raw,
+                    });
+                    if (Number.isFinite(cost) && cost >= 0) {
+                        data.costUsd = cost;
+                        data.metadata.costKnown = true;
+                    }
+                }
+                catch {
+                    data.metadata.costKnown = false;
+                }
+        },
+        token() {
+            data.ttftMs ?? (data.ttftMs = Date.now() - start);
+        },
+        finish(output, error, cancelled = false) {
+            if (ended)
+                return;
+            ended = true;
+            data.latencyMs = Date.now() - start;
+            data.output =
+                options.captureOutput === false ? "[not captured]" : (output ?? "");
+            if (error !== undefined || cancelled) {
+                data.errorType = cancelled
+                    ? "AbortError"
+                    : error instanceof Error
+                        ? error.name
+                        : "Error";
+                data.errorMessage = (0, index_1.integrationPayload)(cancelled
+                    ? "Stream cancelled before completion"
+                    : error instanceof Error
+                        ? error.message
+                        : String(error));
+            }
+            data.metadata = { ...data.metadata, cancelled };
+            if (scope?.root)
+                data.spanType = data.errorType ? "error" : "run_end";
+            safeSend(data);
+            if (implicit)
+                safeSend({
+                    runId,
+                    spanId: rootId,
+                    spanType: data.errorType ? "error" : "run_end",
+                    toolName: options.name ?? provider,
+                    traceName: data.traceName,
+                    input: data.input,
+                    output: data.output,
+                    latencyMs: data.latencyMs,
+                    createdAt: data.createdAt,
+                    metadata: { provider, implicitRoot: true },
+                    ...(data.errorType
+                        ? { errorType: data.errorType, errorMessage: data.errorMessage }
+                        : {}),
+                });
+        },
+    };
+}

package/dist/integrations/providers.d.ts

@@ -0,0 +1,7 @@
+import { type IntegrationOptions } from "./observation";
+export type { IntegrationOptions } from "./observation";
+export declare const isInsideWrapped: () => boolean;
+/** Record one provider call. `call` receives the (possibly adjusted) params and returns the provider's result. */
+export declare function traced(provider: string, endpoint: string, call: (params: any) => any, rawParams: any, options: IntegrationOptions, markWrapped?: boolean): any;
+export declare function wrapOpenAI<T extends object>(client: T, options?: IntegrationOptions): T;
+export declare function wrapAnthropic<T extends object>(client: T, options?: IntegrationOptions): T;

package/dist/integrations/providers.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInsideWrapped = void 0;
+exports.traced = traced;
+exports.wrapOpenAI = wrapOpenAI;
+exports.wrapAnthropic = wrapAnthropic;
+const observation_1 = require("./observation");
+const wrapped = new WeakSet();
+function capture(obs, value) {
+    const result = value.response ?? value.message ?? value;
+    if (result.usage && value.type !== "message_delta")
+        obs.usage(result.usage, result.model ?? obs.data.modelId);
+    if (result.model)
+        obs.data.modelId = result.model;
+    const delta = value.choices?.[0]?.delta?.content ??
+        value.delta?.text ??
+        (value.type === "response.output_text.delta" ? value.delta : undefined);
+    if (typeof delta === "string" && delta)
+        obs.token();
+    if (value.type === "message_start")
+        obs.usage(value.message?.usage, value.message?.model);
+    if (value.type === "message_delta" && value.usage)
+        obs.usage({ ...(obs.data.metadata?.usage ?? {}), ...Object.fromEntries(Object.entries(value.usage).filter(([, value]) => value != null)) });
+    const finishReason = value.choices?.[0]?.finish_reason ??
+        value.delta?.stop_reason ??
+        result.stop_reason ??
+        (value.type === "response.completed" ? "completed" : undefined);
+    if (finishReason)
+        obs.data.metadata = { ...obs.data.metadata, finishReason };
+    if (value.type === "response.failed" || value.type === "error") {
+        const e = new Error(value.error?.message ??
+            value.response?.error?.message ??
+            "Provider stream failed");
+        e.name = value.error?.type ?? "ProviderError";
+        obs.finish(undefined, e);
+    }
+    return delta ?? "";
+}
+function observeStream(stream, obs, provider) {
+    let text = "";
+    const collect = (event) => {
+        const delta = capture(obs, event);
+        if (typeof delta === "string")
+            text = (text + delta).slice(0, 10000);
+    };
+    // SDK event-emitter helpers consume their own stream. Observe events without iterating it twice.
+    if (typeof stream.on === "function") {
+        const emitter = stream;
+        emitter.on(provider === "anthropic" ? "streamEvent" : "chunk", collect);
+        if (provider === "openai")
+            emitter.on("event", collect);
+        emitter.on("end", () => obs.finish(text));
+        emitter.on("error", (error) => obs.finish(text, error));
+        emitter.on("abort", () => obs.finish(text, undefined, true));
+        return stream;
+    }
+    return new Proxy(stream, {
+        get(target, key) {
+            if (key === Symbol.asyncIterator)
+                return async function* () {
+                    let complete = false;
+                    try {
+                        for await (const event of target) {
+                            collect(event);
+                            yield event;
+                        }
+                        complete = true;
+                    }
+                    catch (error) {
+                        obs.finish(text, error);
+                        throw error;
+                    }
+                    finally {
+                        obs.finish(text, undefined, !complete);
+                    }
+                };
+            const value = Reflect.get(target, key, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+/** Preserve APIPromise helpers and stream/controller identity. Do not eagerly parse raw HTTP responses. */
+function observeResult(result, obs, provider) {
+    let parsed;
+    const consume = (value) => {
+        if (value && typeof value[Symbol.asyncIterator] === "function")
+            return observeStream(value, obs, provider);
+        capture(obs, value ?? {});
+        obs.finish(value?.choices ?? value?.output ?? value?.content ?? value);
+        return value;
+    };
+    if (result && typeof result.then === "function")
+        return new Proxy(result, {
+            get(target, key) {
+                const parse = () => (parsed ?? (parsed = Promise.resolve(target)
+                    .then(consume)
+                    .catch((error) => {
+                    obs.finish(undefined, error);
+                    throw error;
+                })));
+                if (key === "then")
+                    return (ok, fail) => parse().then(ok, fail);
+                if (key === "catch")
+                    return (fail) => parse().catch(fail);
+                if (key === "finally")
+                    return (done) => parse().finally(done);
+                if (key === "withResponse")
+                    return async (...args) => {
+                        try {
+                            const full = await target.withResponse(...args);
+                            return { ...full, data: await parse() };
+                        }
+                        catch (error) {
+                            obs.finish(undefined, error);
+                            throw error;
+                        }
+                    };
+                if (key === "asResponse")
+                    return async (...args) => {
+                        try {
+                            const response = await target.asResponse(...args);
+                            obs.finish("[raw response not consumed]");
+                            return response;
+                        }
+                        catch (error) {
+                            obs.finish(undefined, error);
+                            throw error;
+                        }
+                    };
+                const value = Reflect.get(target, key, target);
+                return typeof value === "function" ? value.bind(target) : value;
+            },
+        });
+    if (result && typeof result[Symbol.asyncIterator] === "function")
+        return observeStream(result, obs, provider);
+    return consume(result);
+}
+/** True while a wrapped client is calling the provider, so auto-instrumentation does not record the call twice. */
+let insideWrapped = false;
+const isInsideWrapped = () => insideWrapped;
+exports.isInsideWrapped = isInsideWrapped;
+/** Record one provider call. `call` receives the (possibly adjusted) params and returns the provider's result. */
+function traced(provider, endpoint, call, rawParams, options, markWrapped = true) {
+    const params = { ...(rawParams ?? {}) };
+    if (provider === "openai" &&
+        endpoint.startsWith("chat.") &&
+        params.stream &&
+        params.stream_options?.include_usage === undefined)
+        params.stream_options = { ...params.stream_options, include_usage: true };
+    const obs = (0, observation_1.observation)(provider, params.model ?? "", params.system
+        ? [{ role: "system", content: params.system }, ...(params.messages ?? [])]
+        : params.instructions
+            ? { instructions: params.instructions, input: params.input }
+            : (params.messages ?? params.input ?? params.prompt ?? ""), options);
+    const before = insideWrapped;
+    if (markWrapped)
+        insideWrapped = true;
+    try {
+        return observeResult(call(params), obs, provider);
+    }
+    catch (error) {
+        obs.finish(undefined, error);
+        throw error;
+    }
+    finally {
+        insideWrapped = before;
+    }
+}
+function wrap(client, provider, options) {
+    if (wrapped.has(client))
+        return client;
+    const cache = new WeakMap();
+    const proxy = (target, path) => {
+        const existing = cache.get(target);
+        if (existing)
+            return existing;
+        const result = new Proxy(target, {
+            get(obj, key) {
+                const value = Reflect.get(obj, key, obj);
+                const next = [...path, String(key)];
+                const endpoint = next.join(".");
+                const allowed = provider === "openai"
+                    ? [
+                        "chat.completions.create",
+                        "chat.completions.stream",
+                        "responses.create",
+                        "responses.stream",
+                    ]
+                    : [
+                        "messages.create",
+                        "messages.stream",
+                        "beta.messages.create",
+                        "beta.messages.stream",
+                    ];
+                if (typeof value === "function" && allowed.includes(endpoint))
+                    return (...args) => traced(provider, endpoint, (params) => value.apply(obj, [params, ...args.slice(1)]), args[0], options);
+                if (value &&
+                    typeof value === "object" &&
+                    (path.length === 0 ||
+                        [
+                            "chat",
+                            "chat.completions",
+                            "responses",
+                            "messages",
+                            "beta",
+                            "beta.messages",
+                        ].includes(next.join("."))))
+                    return proxy(value, next);
+                return typeof value === "function" ? value.bind(obj) : value;
+            },
+        });
+        cache.set(target, result);
+        return result;
+    };
+    const result = proxy(client, []);
+    wrapped.add(result);
+    return result;
+}
+function wrapOpenAI(client, options = {}) {
+    return wrap(client, "openai", options);
+}
+function wrapAnthropic(client, options = {}) {
+    return wrap(client, "anthropic", options);
+}

package/dist/integrations/tools.d.ts

@@ -0,0 +1,10 @@
+import { type IntegrationOptions } from "./observation";
+/**
+ * Trace any set of tools. Works with plain functions and with tool objects that carry an `execute`
+ * function (the Vercel AI SDK, OpenAI Agents and most agent frameworks use that shape):
+ *
+ *   const tools = traceTools({ searchDocs, sendEmail });
+ *
+ * The returned object has the same keys and behaves the same; each call is recorded as a tool step.
+ */
+export declare function traceTools<T extends Record<string, any>>(tools: T, options?: IntegrationOptions): T;

package/dist/integrations/tools.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceTools = traceTools;
+const observation_1 = require("./observation");
+/**
+ * Trace any set of tools. Works with plain functions and with tool objects that carry an `execute`
+ * function (the Vercel AI SDK, OpenAI Agents and most agent frameworks use that shape):
+ *
+ *   const tools = traceTools({ searchDocs, sendEmail });
+ *
+ * The returned object has the same keys and behaves the same; each call is recorded as a tool step.
+ */
+function traceTools(tools, options = {}) {
+    const traced = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        if (typeof tool === "function")
+            traced[name] = wrapTool(name, tool, options);
+        else if (tool && typeof tool.execute === "function") {
+            const copy = Object.create(Object.getPrototypeOf(tool), Object.getOwnPropertyDescriptors(tool));
+            copy.execute = wrapTool(name, tool.execute.bind(tool), options);
+            traced[name] = copy;
+        }
+        else
+            traced[name] = tool;
+    }
+    return traced;
+}
+function wrapTool(name, fn, options) {
+    return function (...args) {
+        const obs = (0, observation_1.observation)("tool", name, args.length > 1 ? args : args[0], options);
+        obs.data.spanType = "tool_call";
+        obs.data.toolName = name;
+        obs.data.modelId = undefined;
+        let outcome;
+        try {
+            outcome = fn.apply(this, args);
+        }
+        catch (error) {
+            obs.finish(undefined, error);
+            throw error;
+        }
+        if (outcome && typeof outcome.then === "function") {
+            return outcome.then((value) => { obs.finish(value); return value; }, (error) => { obs.finish(undefined, error); throw error; });
+        }
+        obs.finish(outcome);
+        return outcome;
+    };
+}

package/dist/integrations/vercel-ai.d.ts

@@ -0,0 +1,24 @@
+import { type IntegrationOptions } from "./observation";
+type Value = Record<string, any>;
+/**
+ * One-line tracing for the Vercel AI SDK. Pass it to `wrapLanguageModel`:
+ *
+ *   const model = wrapLanguageModel({ model: openai("gpt-4o"), middleware: uncoilMiddleware() });
+ *
+ * Every `generateText`, `streamText` or `generateObject` call made with that model becomes an Uncoil step.
+ */
+export declare function uncoilMiddleware(options?: IntegrationOptions): {
+    wrapGenerate({ doGenerate, params, model }: {
+        doGenerate: () => Promise<Value>;
+        params: unknown;
+        model?: Value;
+    }): Promise<Value>;
+    wrapStream({ doStream, params, model }: {
+        doStream: () => Promise<Value>;
+        params: unknown;
+        model?: Value;
+    }): Promise<{
+        stream: any;
+    }>;
+};
+export {};