lightrace 0.1.0

package/dist/integrations/langchain.js

@@ -0,0 +1,337 @@
+/**
+ * LangChain/LangGraph integration for Lightrace.
+ *
+ * Extends `BaseCallbackHandler` from `@langchain/core` to automatically
+ * capture chains, LLM calls, tool invocations, and retriever operations
+ * as Lightrace trace observations.
+ *
+ * @example
+ * ```ts
+ * import { LightraceCallbackHandler } from "lightrace/integrations/langchain";
+ *
+ * const handler = new LightraceCallbackHandler({ userId: "user-123" });
+ * const result = await chain.invoke(inputs, { callbacks: [handler] });
+ * console.log(handler.lastTraceId);
+ * ```
+ */
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import { generateId, jsonSerializable } from "../utils.js";
+import { Lightrace } from "../client.js";
+export class LightraceCallbackHandler extends BaseCallbackHandler {
+    name = "lightrace";
+    // Run tracking
+    runs = new Map();
+    runParents = new Map();
+    completionStartTimes = new Map();
+    rootRunId = null;
+    _traceId = null;
+    // Config
+    userId;
+    sessionId;
+    traceName;
+    rootMetadata;
+    // Exporter
+    exporter = null;
+    /** The trace ID from the most recently completed root run. */
+    lastTraceId = null;
+    constructor(opts) {
+        super();
+        this.userId = opts?.userId;
+        this.sessionId = opts?.sessionId;
+        this.traceName = opts?.traceName;
+        this.rootMetadata = opts?.metadata;
+        const client = opts?.client ?? Lightrace.getInstance();
+        this.exporter = client?.getExporter() ?? null;
+    }
+    // ── helpers ──────────────────────────────────────────────────────────
+    getParentObservationId(observationId) {
+        return this.runParents.get(observationId) ?? null;
+    }
+    emit(event) {
+        this.exporter?.enqueue(event);
+    }
+    emitObservation(run, endTime, output, level, statusMessage, extra) {
+        const eventTypeMap = {
+            span: "span-create",
+            generation: "generation-create",
+            event: "event-create",
+            tool: "tool-create",
+            chain: "chain-create",
+        };
+        const obsTypeMap = {
+            span: "SPAN",
+            generation: "GENERATION",
+            event: "EVENT",
+            tool: "TOOL",
+            chain: "CHAIN",
+        };
+        const body = {
+            id: run.observationId,
+            traceId: this._traceId,
+            type: obsTypeMap[run.type] ?? run.type,
+            name: run.name,
+            startTime: run.startTime.toISOString(),
+            endTime: endTime.toISOString(),
+            input: jsonSerializable(run.input),
+            output: jsonSerializable(output),
+            metadata: run.metadata ?? null,
+            model: run.model ?? null,
+            level,
+            statusMessage,
+            parentObservationId: this.getParentObservationId(run.observationId) ?? null,
+            ...extra,
+        };
+        this.emit({
+            id: generateId(),
+            type: eventTypeMap[run.type] ?? "span-create",
+            timestamp: run.startTime.toISOString(),
+            body,
+        });
+    }
+    extractModelName(serialized) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const s = serialized;
+        return (s?.kwargs?.model_name ?? s?.kwargs?.model ?? s?.kwargs?.modelName ?? s?.name ?? undefined);
+    }
+    isAgent(serialized) {
+        const name = (serialized.id?.join("/") ?? "").toLowerCase();
+        const sName = (serialized.name ?? "").toLowerCase();
+        return name.includes("agent") || sName.includes("agent");
+    }
+    registerRun(runId, parentRunId, info) {
+        const isRoot = !this.rootRunId;
+        if (isRoot) {
+            this.rootRunId = runId;
+            this._traceId = generateId();
+            // Emit root trace-create event
+            this.emit({
+                id: generateId(),
+                type: "trace-create",
+                timestamp: info.startTime.toISOString(),
+                body: {
+                    id: this._traceId,
+                    name: this.traceName ?? info.name,
+                    timestamp: info.startTime.toISOString(),
+                    userId: this.userId,
+                    sessionId: this.sessionId,
+                    metadata: this.rootMetadata ?? null,
+                    input: jsonSerializable(info.input),
+                },
+            });
+        }
+        const observationId = generateId();
+        const runInfo = { ...info, observationId, parentRunId };
+        this.runs.set(runId, runInfo);
+        this.runParents.set(observationId, parentRunId ? this.runs.get(parentRunId)?.observationId : undefined);
+        return runInfo;
+    }
+    endRun(runId, output, level = "DEFAULT", statusMessage = null, extra) {
+        const run = this.runs.get(runId);
+        if (!run)
+            return;
+        const endTime = new Date();
+        this.emitObservation(run, endTime, output, level, statusMessage, extra);
+        // If this is the root run completing, update the trace and reset
+        if (runId === this.rootRunId) {
+            // Emit trace-create with output (update)
+            this.emit({
+                id: generateId(),
+                type: "trace-create",
+                timestamp: run.startTime.toISOString(),
+                body: {
+                    id: this._traceId,
+                    name: this.traceName ?? run.name,
+                    timestamp: run.startTime.toISOString(),
+                    output: jsonSerializable(output),
+                    userId: this.userId,
+                    sessionId: this.sessionId,
+                    metadata: this.rootMetadata ?? null,
+                },
+            });
+            this.lastTraceId = this._traceId;
+            this.rootRunId = null;
+            this._traceId = null;
+            this.runs.clear();
+            this.runParents.clear();
+            this.completionStartTimes.clear();
+        }
+        else {
+            this.runs.delete(runId);
+        }
+    }
+    // ── Chain callbacks ──────────────────────────────────────────────────
+    async handleChainStart(chain, inputs, runId, parentRunId, tags, metadata) {
+        const name = chain.name ??
+            chain.id?.[chain.id.length - 1] ??
+            "Chain";
+        const type = this.isAgent(chain) ? "chain" : "chain";
+        const mergedMetadata = { ...metadata, ...(tags?.length ? { tags } : {}) };
+        this.registerRun(runId, parentRunId, {
+            type,
+            name,
+            startTime: new Date(),
+            input: inputs,
+            metadata: Object.keys(mergedMetadata).length > 0 ? mergedMetadata : undefined,
+        });
+    }
+    async handleChainEnd(outputs, runId, _parentRunId) {
+        this.endRun(runId, outputs);
+    }
+    async handleChainError(error, runId, _parentRunId) {
+        // LangGraph GraphBubbleUp is a control flow error, not an actual error
+        if (error?.constructor?.name === "GraphBubbleUp" || error?.name === "GraphBubbleUp") {
+            this.endRun(runId, null, "DEFAULT", null);
+            return;
+        }
+        this.endRun(runId, null, "ERROR", error.message ?? String(error));
+    }
+    // ── LLM callbacks ───────────────────────────────────────────────────
+    async handleLLMStart(llm, prompts, runId, parentRunId, _extraParams, _tags, metadata) {
+        const model = this.extractModelName(llm);
+        const name = model ??
+            llm.name ??
+            llm.id?.[llm.id.length - 1] ??
+            "LLM";
+        this.registerRun(runId, parentRunId, {
+            type: "generation",
+            name,
+            startTime: new Date(),
+            input: prompts.length === 1 ? prompts[0] : prompts,
+            model,
+            metadata,
+        });
+    }
+    async handleChatModelStart(llm, messages, runId, parentRunId, _extraParams, _tags, metadata) {
+        const model = this.extractModelName(llm);
+        const name = model ??
+            llm.name ??
+            llm.id?.[llm.id.length - 1] ??
+            "ChatModel";
+        // Convert messages to a simpler role/content format
+        const formattedMessages = messages.map((msgGroup) => msgGroup.map((msg) => ({
+            role: msg._getType(),
+            content: msg.content,
+            ...(msg.name ? { name: msg.name } : {}),
+        })));
+        this.registerRun(runId, parentRunId, {
+            type: "generation",
+            name,
+            startTime: new Date(),
+            input: formattedMessages.length === 1 ? formattedMessages[0] : formattedMessages,
+            model,
+            metadata,
+        });
+    }
+    async handleLLMEnd(output, runId, _parentRunId) {
+        const extra = {};
+        // Extract token usage
+        const usage = output.llmOutput?.tokenUsage ?? output.llmOutput?.estimatedTokens ?? null;
+        if (usage) {
+            if (usage.promptTokens !== undefined)
+                extra.promptTokens = usage.promptTokens;
+            if (usage.completionTokens !== undefined)
+                extra.completionTokens = usage.completionTokens;
+            if (usage.totalTokens !== undefined)
+                extra.totalTokens = usage.totalTokens;
+        }
+        // Add TTFT if we have it
+        const ttftStart = this.completionStartTimes.get(runId);
+        const run = this.runs.get(runId);
+        if (ttftStart && run) {
+            const ttft = ttftStart.getTime() - run.startTime.getTime();
+            if (!run.metadata)
+                run.metadata = {};
+            run.metadata.timeToFirstToken = ttft;
+        }
+        // Extract output text
+        const generations = output.generations;
+        let outputText;
+        if (generations.length === 1 && generations[0].length === 1) {
+            const gen = generations[0][0];
+            // ChatGeneration has a `message` field, base Generation only has `text`
+            const genAny = gen;
+            outputText = genAny.message ?? gen.text;
+        }
+        else {
+            outputText = generations.map((g) => g.map((gg) => {
+                const ggAny = gg;
+                return ggAny.message ?? gg.text;
+            }));
+        }
+        this.endRun(runId, outputText, "DEFAULT", null, extra);
+        this.completionStartTimes.delete(runId);
+    }
+    async handleLLMNewToken(_token, _idx, runId) {
+        if (!this.completionStartTimes.has(runId)) {
+            this.completionStartTimes.set(runId, new Date());
+        }
+    }
+    async handleLLMError(error, runId, _parentRunId) {
+        this.endRun(runId, null, "ERROR", error.message ?? String(error));
+        this.completionStartTimes.delete(runId);
+    }
+    // ── Tool callbacks ──────────────────────────────────────────────────
+    async handleToolStart(tool, input, runId, parentRunId, _tags, metadata) {
+        const name = tool.name ??
+            tool.id?.[tool.id.length - 1] ??
+            "Tool";
+        // Try to parse input as JSON
+        let parsedInput = input;
+        try {
+            parsedInput = JSON.parse(input);
+        }
+        catch {
+            // keep as string
+        }
+        this.registerRun(runId, parentRunId, {
+            type: "tool",
+            name,
+            startTime: new Date(),
+            input: parsedInput,
+            metadata,
+        });
+    }
+    async handleToolEnd(output, runId, _parentRunId) {
+        // Try to parse output as JSON
+        let parsedOutput = output;
+        try {
+            parsedOutput = JSON.parse(output);
+        }
+        catch {
+            // keep as string
+        }
+        this.endRun(runId, parsedOutput);
+    }
+    async handleToolError(error, runId, _parentRunId) {
+        this.endRun(runId, null, "ERROR", error.message ?? String(error));
+    }
+    // ── Retriever callbacks ─────────────────────────────────────────────
+    async handleRetrieverStart(retriever, query, runId, parentRunId, _tags, metadata) {
+        const name = retriever.name ??
+            retriever.id?.[retriever.id.length - 1] ??
+            "Retriever";
+        this.registerRun(runId, parentRunId, {
+            type: "span",
+            name,
+            startTime: new Date(),
+            input: query,
+            metadata,
+        });
+    }
+    async handleRetrieverEnd(documents, runId, _parentRunId) {
+        const output = documents.map((doc) => ({
+            pageContent: doc.pageContent,
+            metadata: doc.metadata,
+        }));
+        this.endRun(runId, output);
+    }
+    async handleRetrieverError(error, runId, _parentRunId) {
+        this.endRun(runId, null, "ERROR", error.message ?? String(error));
+    }
+    // ── Accessors ───────────────────────────────────────────────────────
+    /** Get the current active trace ID (null if no run is active). */
+    get traceId() {
+        return this._traceId;
+    }
+}
+//# sourceMappingURL=langchain.js.map

package/dist/integrations/langchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain.js","sourceRoot":"","sources":["../../src/integrations/langchain.ts"],"names":[],"mappings":"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"}

package/dist/observation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Imperative Observation handle for span / generation / event.
+ */
+import type { UsageDetails } from "./types.js";
+import type { BatchExporter } from "./exporter.js";
+export interface ObservationOptions {
+    traceId: string;
+    type: "span" | "generation" | "event";
+    name: string;
+    exporter: BatchExporter | null;
+    startTime?: Date;
+    parentObservationId?: string;
+    input?: unknown;
+    model?: string;
+    metadata?: Record<string, unknown>;
+    usage?: UsageDetails;
+}
+export declare class Observation {
+    readonly id: string;
+    readonly traceId: string;
+    readonly type: "span" | "generation" | "event";
+    readonly name: string;
+    private readonly exporter;
+    private readonly startTime;
+    private readonly parentObservationId;
+    private input;
+    private output;
+    private model;
+    private metadata;
+    private usage;
+    private level;
+    private statusMessage;
+    private ended;
+    constructor(opts: ObservationOptions);
+    /**
+     * Update fields on the observation before ending it.
+     */
+    update(fields: {
+        output?: unknown;
+        metadata?: Record<string, unknown>;
+        usage?: UsageDetails;
+        level?: string;
+        statusMessage?: string;
+    }): this;
+    /**
+     * End the observation and emit the trace event.
+     */
+    end(): void;
+    /**
+     * Create a child span under this observation.
+     */
+    span(opts: {
+        name: string;
+        input?: unknown;
+        metadata?: Record<string, unknown>;
+    }): Observation;
+}
+//# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,qBAAa,WAAW;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAO;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,KAAK,CAAS;gBAEV,IAAI,EAAE,kBAAkB;IAcpC;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE;QACb,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,IAAI;IAWR;;OAEG;IACH,GAAG,IAAI,IAAI;IAyCX;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,WAAW;CAW/F"}

package/dist/observation.js

@@ -0,0 +1,105 @@
+import { EVENT_TYPE_MAP, OBSERVATION_TYPE_ENUM } from "./types.js";
+import { generateId, jsonSerializable } from "./utils.js";
+export class Observation {
+    id;
+    traceId;
+    type;
+    name;
+    exporter;
+    startTime;
+    parentObservationId;
+    input;
+    output;
+    model;
+    metadata;
+    usage;
+    level = "DEFAULT";
+    statusMessage;
+    ended = false;
+    constructor(opts) {
+        this.id = generateId();
+        this.traceId = opts.traceId;
+        this.type = opts.type;
+        this.name = opts.name;
+        this.exporter = opts.exporter;
+        this.startTime = opts.startTime ?? new Date();
+        this.parentObservationId = opts.parentObservationId;
+        this.input = opts.input;
+        this.model = opts.model;
+        this.metadata = opts.metadata;
+        this.usage = opts.usage;
+    }
+    /**
+     * Update fields on the observation before ending it.
+     */
+    update(fields) {
+        if (fields.output !== undefined)
+            this.output = fields.output;
+        if (fields.metadata !== undefined) {
+            this.metadata = { ...this.metadata, ...fields.metadata };
+        }
+        if (fields.usage !== undefined)
+            this.usage = fields.usage;
+        if (fields.level !== undefined)
+            this.level = fields.level;
+        if (fields.statusMessage !== undefined)
+            this.statusMessage = fields.statusMessage;
+        return this;
+    }
+    /**
+     * End the observation and emit the trace event.
+     */
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        const endTime = new Date();
+        const createType = EVENT_TYPE_MAP[this.type]?.[0] ?? "span-create";
+        const body = {
+            id: this.id,
+            traceId: this.traceId,
+            type: OBSERVATION_TYPE_ENUM[this.type] ?? this.type,
+            name: this.name,
+            startTime: this.startTime.toISOString(),
+            endTime: endTime.toISOString(),
+            input: jsonSerializable(this.input),
+            output: jsonSerializable(this.output),
+            metadata: this.metadata ?? null,
+            model: this.model ?? null,
+            level: this.level,
+            statusMessage: this.statusMessage ?? null,
+            parentObservationId: this.parentObservationId ?? null,
+        };
+        // Add usage fields for generations
+        if (this.usage) {
+            if (this.usage.promptTokens !== undefined)
+                body.promptTokens = this.usage.promptTokens;
+            if (this.usage.completionTokens !== undefined)
+                body.completionTokens = this.usage.completionTokens;
+            if (this.usage.totalTokens !== undefined)
+                body.totalTokens = this.usage.totalTokens;
+        }
+        const event = {
+            id: generateId(),
+            type: createType,
+            timestamp: this.startTime.toISOString(),
+            body,
+        };
+        this.exporter?.enqueue(event);
+    }
+    /**
+     * Create a child span under this observation.
+     */
+    span(opts) {
+        return new Observation({
+            traceId: this.traceId,
+            type: "span",
+            name: opts.name,
+            exporter: this.exporter,
+            input: opts.input,
+            metadata: opts.metadata,
+            parentObservationId: this.id,
+        });
+    }
+}
+//# sourceMappingURL=observation.js.map

package/dist/observation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.js","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgB1D,MAAM,OAAO,WAAW;IACb,EAAE,CAAS;IACX,OAAO,CAAS;IAChB,IAAI,CAAkC;IACtC,IAAI,CAAS;IACL,QAAQ,CAAuB;IAC/B,SAAS,CAAO;IAChB,mBAAmB,CAAqB;IAEjD,KAAK,CAAU;IACf,MAAM,CAAU;IAChB,KAAK,CAAqB;IAC1B,QAAQ,CAAsC;IAC9C,KAAK,CAA2B;IAChC,KAAK,GAAW,SAAS,CAAC;IAC1B,aAAa,CAAqB;IAClC,KAAK,GAAG,KAAK,CAAC;IAEtB,YAAY,IAAwB;QAClC,IAAI,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACpD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAMN;QACC,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7D,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC3D,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1D,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1D,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS;YAAE,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QAClF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,GAAG;QACD,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAElB,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC;QAEnE,MAAM,IAAI,GAA4B;YACpC,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;YACnD,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;YACvC,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE;YAC9B,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;YACnC,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC;YACrC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;YAC/B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;YACzB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI;YACzC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI;SACtD,CAAC;QAEF,mCAAmC;QACnC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS;gBAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;YACvF,IAAI,IAAI,CAAC,KAAK,CAAC,gBAAgB,KAAK,SAAS;gBAC3C,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC;YACtD,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS;gBAAE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;QACtF,CAAC;QAED,MAAM,KAAK,GAAe;YACxB,EAAE,EAAE,UAAU,EAAE;YAChB,IAAI,EAAE,UAAU;YAChB,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;YACvC,IAAI;SACL,CAAC;QAEF,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,IAA2E;QAC9E,OAAO,IAAI,WAAW,CAAC;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,mBAAmB,EAAE,IAAI,CAAC,EAAE;SAC7B,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/security.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Create HMAC-SHA256 signature for a tool invocation.
+ */
+export declare function sign(sessionToken: string, nonce: string, tool: string, inputData: unknown): string;
+/**
+ * Verify HMAC-SHA256 signature.
+ */
+export declare function verify(sessionToken: string, nonce: string, tool: string, inputData: unknown, signature: string): boolean;
+/**
+ * Tracks single-use nonces with TTL to prevent replay attacks.
+ */
+export declare class NonceTracker {
+    private seen;
+    private ttlMs;
+    constructor(ttlSeconds?: number);
+    /** Returns true if the nonce is fresh (not seen before). Marks it as used. */
+    checkAndMark(nonce: string): boolean;
+    private cleanup;
+}
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,IAAI,CAClB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,GACjB,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,MAAM,CACpB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAOT;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,KAAK,CAAS;gBAEV,UAAU,SAAK;IAI3B,8EAA8E;IAC9E,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAOpC,OAAO,CAAC,OAAO;CAMhB"}

package/dist/security.js

@@ -0,0 +1,46 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Create HMAC-SHA256 signature for a tool invocation.
+ */
+export function sign(sessionToken, nonce, tool, inputData) {
+    const payload = nonce + tool + JSON.stringify(inputData, Object.keys(inputData ?? {}).sort());
+    return createHmac("sha256", sessionToken).update(payload).digest("hex");
+}
+/**
+ * Verify HMAC-SHA256 signature.
+ */
+export function verify(sessionToken, nonce, tool, inputData, signature) {
+    const expected = sign(sessionToken, nonce, tool, inputData);
+    try {
+        return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Tracks single-use nonces with TTL to prevent replay attacks.
+ */
+export class NonceTracker {
+    seen = new Map();
+    ttlMs;
+    constructor(ttlSeconds = 60) {
+        this.ttlMs = ttlSeconds * 1000;
+    }
+    /** Returns true if the nonce is fresh (not seen before). Marks it as used. */
+    checkAndMark(nonce) {
+        this.cleanup();
+        if (this.seen.has(nonce))
+            return false;
+        this.seen.set(nonce, Date.now());
+        return true;
+    }
+    cleanup() {
+        const cutoff = Date.now() - this.ttlMs;
+        for (const [nonce, time] of this.seen) {
+            if (time < cutoff)
+                this.seen.delete(nonce);
+        }
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D;;GAEG;AACH,MAAM,UAAU,IAAI,CAClB,YAAoB,EACpB,KAAa,EACb,IAAY,EACZ,SAAkB;IAElB,MAAM,OAAO,GACX,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAE,SAAoB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5F,OAAO,UAAU,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CACpB,YAAoB,EACpB,KAAa,EACb,IAAY,EACZ,SAAkB,EAClB,SAAiB;IAEjB,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IAC5D,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,YAAY;IACf,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjC,KAAK,CAAS;IAEtB,YAAY,UAAU,GAAG,EAAE;QACzB,IAAI,CAAC,KAAK,GAAG,UAAU,GAAG,IAAI,CAAC;IACjC,CAAC;IAED,8EAA8E;IAC9E,YAAY,CAAC,KAAa;QACxB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,OAAO;QACb,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACvC,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACtC,IAAI,IAAI,GAAG,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;CACF"}

package/dist/tool-client.d.ts

@@ -0,0 +1,32 @@
+export declare class ToolClient {
+    private host;
+    private publicKey;
+    private secretKey;
+    private sdkInstanceId;
+    private heartbeatInterval;
+    private maxReconnectDelay;
+    private sessionToken;
+    private nonceTracker;
+    private running;
+    private ws;
+    private reconnectTimer;
+    private heartbeatTimer;
+    constructor(options: {
+        host: string;
+        publicKey: string;
+        secretKey: string;
+        sdkInstanceId?: string;
+        heartbeatInterval?: number;
+        maxReconnectDelay?: number;
+    });
+    private get wsUrl();
+    start(): void;
+    stop(): void;
+    private connect;
+    private cleanup;
+    private handleMessage;
+    private registerTools;
+    private startHeartbeat;
+    private handleInvoke;
+}
+//# sourceMappingURL=tool-client.d.ts.map

package/dist/tool-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-client.d.ts","sourceRoot":"","sources":["../src/tool-client.ts"],"names":[],"mappings":"AAUA,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,iBAAiB,CAAS;IAElC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,cAAc,CAA+C;gBAEzD,OAAO,EAAE;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B;IASD,OAAO,KAAK,KAAK,GAIhB;IAED,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAUZ,OAAO,CAAC,OAAO;IAmCf,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,aAAa;IAyBrB,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,cAAc;YAQR,YAAY;CAsE3B"}