@prefactor/sdk 0.1.0

package/dist/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@prefactor/sdk",
+  "version": "0.1.0",
+  "description": "Automatic observability for LangChain.js agents",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "example:basic": "bun examples/basic.ts",
+    "example:anthropic": "bun examples/anthropic-agent/simple-agent.ts",
+    "prepublishOnly": "bun run build && bun run test && bun run typecheck"
+  },
+  "keywords": [
+    "prefactor",
+    "observability",
+    "tracing",
+    "langchain",
+    "llm",
+    "agent",
+    "monitoring"
+  ],
+  "author": "Prefactor",
+  "license": "MIT",
+  "dependencies": {
+    "@langchain/core": "^0.3.0",
+    "@prefactor/pfid": "^0.1.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/node": "^20.0.0",
+    "bun-types": "latest",
+    "langchain": "^1.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/dist/tracing/context.d.ts

@@ -0,0 +1,53 @@
+import type { Span } from './span.js';
+/**
+ * SpanContext manages the current span in async execution contexts.
+ * This enables automatic parent-child span relationships without manual tracking.
+ *
+ * Uses Node.js AsyncLocalStorage which provides async-safe context propagation.
+ *
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan({ name: 'parent', ... });
+ *
+ * await SpanContext.runAsync(span, async () => {
+ *   // Inside this function, getCurrent() returns the parent span
+ *   const parent = SpanContext.getCurrent();
+ *
+ *   const child = tracer.startSpan({
+ *     name: 'child',
+ *     parentSpanId: parent?.spanId,
+ *     traceId: parent?.traceId,
+ *   });
+ *   // ...
+ * });
+ * ```
+ */
+export declare class SpanContext {
+    /**
+     * Get the current span from the async context
+     *
+     * @returns The current span, or undefined if no span is active
+     */
+    static getCurrent(): Span | undefined;
+    /**
+     * Run a synchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The function to execute
+     * @returns The return value of the function
+     */
+    static run<T>(span: Span, fn: () => T): T;
+    /**
+     * Run an asynchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The async function to execute
+     * @returns A promise resolving to the return value of the function
+     */
+    static runAsync<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear the current context (primarily for testing)
+     */
+    static clear(): void;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/tracing/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tracing/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAOtC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,WAAW;IACtB;;;;OAIG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI,GAAG,SAAS;IAIrC;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIzC;;;;;;OAMG;WACU,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAItE;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAGrB"}

package/dist/tracing/context.js

@@ -0,0 +1,65 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Storage for the current span in async context
+ */
+const spanStorage = new AsyncLocalStorage();
+/**
+ * SpanContext manages the current span in async execution contexts.
+ * This enables automatic parent-child span relationships without manual tracking.
+ *
+ * Uses Node.js AsyncLocalStorage which provides async-safe context propagation.
+ *
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan({ name: 'parent', ... });
+ *
+ * await SpanContext.runAsync(span, async () => {
+ *   // Inside this function, getCurrent() returns the parent span
+ *   const parent = SpanContext.getCurrent();
+ *
+ *   const child = tracer.startSpan({
+ *     name: 'child',
+ *     parentSpanId: parent?.spanId,
+ *     traceId: parent?.traceId,
+ *   });
+ *   // ...
+ * });
+ * ```
+ */
+export class SpanContext {
+    /**
+     * Get the current span from the async context
+     *
+     * @returns The current span, or undefined if no span is active
+     */
+    static getCurrent() {
+        return spanStorage.getStore();
+    }
+    /**
+     * Run a synchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The function to execute
+     * @returns The return value of the function
+     */
+    static run(span, fn) {
+        return spanStorage.run(span, fn);
+    }
+    /**
+     * Run an asynchronous function with the given span as the current context
+     *
+     * @param span - The span to set as current
+     * @param fn - The async function to execute
+     * @returns A promise resolving to the return value of the function
+     */
+    static async runAsync(span, fn) {
+        return spanStorage.run(span, fn);
+    }
+    /**
+     * Clear the current context (primarily for testing)
+     */
+    static clear() {
+        spanStorage.disable();
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/tracing/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tracing/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;GAEG;AACH,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,WAAW;IACtB;;;;OAIG;IACH,MAAM,CAAC,UAAU;QACf,OAAO,WAAW,CAAC,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAI,IAAU,EAAE,EAAW;QACnC,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAI,IAAU,EAAE,EAAoB;QACvD,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK;QACV,WAAW,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/tracing/span.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Types of spans that can be traced
+ */
+export declare enum SpanType {
+    AGENT = "agent",
+    LLM = "llm",
+    TOOL = "tool",
+    CHAIN = "chain",
+    RETRIEVER = "retriever"
+}
+/**
+ * Status of a span
+ */
+export declare enum SpanStatus {
+    RUNNING = "running",
+    SUCCESS = "success",
+    ERROR = "error"
+}
+/**
+ * Token usage information for LLM calls
+ */
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Error information captured when a span fails
+ */
+export interface ErrorInfo {
+    errorType: string;
+    message: string;
+    stacktrace: string;
+}
+/**
+ * A span represents a single operation in a trace
+ */
+export interface Span {
+    /** Unique identifier for this span */
+    spanId: string;
+    /** ID of the parent span, or null if this is a root span */
+    parentSpanId: string | null;
+    /** Trace ID shared by all spans in a single trace */
+    traceId: string;
+    /** Human-readable name for this span */
+    name: string;
+    /** Type of operation this span represents */
+    spanType: SpanType;
+    /** Start time in milliseconds since Unix epoch */
+    startTime: number;
+    /** End time in milliseconds since Unix epoch, or null if still running */
+    endTime: number | null;
+    /** Current status of the span */
+    status: SpanStatus;
+    /** Input data for this operation */
+    inputs: Record<string, unknown>;
+    /** Output data from this operation, or null if not completed */
+    outputs: Record<string, unknown> | null;
+    /** Token usage for LLM calls, or null if not applicable */
+    tokenUsage: TokenUsage | null;
+    /** Error information if the span failed, or null if successful */
+    error: ErrorInfo | null;
+    /** Additional metadata about this span */
+    metadata: Record<string, unknown>;
+    /** Tags for categorizing and filtering spans */
+    tags: string[];
+}
+//# sourceMappingURL=span.d.ts.map

package/dist/tracing/span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../../src/tracing/span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,UAAU;IACf,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,KAAK,UAAU;IACf,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,oBAAY,UAAU;IACpB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IAEf,4DAA4D;IAC5D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IAEnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAElB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAExC,2DAA2D;IAC3D,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAE9B,kEAAkE;IAClE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAExB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,gDAAgD;IAChD,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB"}

package/dist/tracing/span.js

@@ -0,0 +1,21 @@
+/**
+ * Types of spans that can be traced
+ */
+export var SpanType;
+(function (SpanType) {
+    SpanType["AGENT"] = "agent";
+    SpanType["LLM"] = "llm";
+    SpanType["TOOL"] = "tool";
+    SpanType["CHAIN"] = "chain";
+    SpanType["RETRIEVER"] = "retriever";
+})(SpanType || (SpanType = {}));
+/**
+ * Status of a span
+ */
+export var SpanStatus;
+(function (SpanStatus) {
+    SpanStatus["RUNNING"] = "running";
+    SpanStatus["SUCCESS"] = "success";
+    SpanStatus["ERROR"] = "error";
+})(SpanStatus || (SpanStatus = {}));
+//# sourceMappingURL=span.js.map

package/dist/tracing/span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.js","sourceRoot":"","sources":["../../src/tracing/span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,QAMX;AAND,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,uBAAW,CAAA;IACX,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,mCAAuB,CAAA;AACzB,CAAC,EANW,QAAQ,KAAR,QAAQ,QAMnB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,UAIX;AAJD,WAAY,UAAU;IACpB,iCAAmB,CAAA;IACnB,iCAAmB,CAAA;IACnB,6BAAe,CAAA;AACjB,CAAC,EAJW,UAAU,KAAV,UAAU,QAIrB"}

package/dist/tracing/tracer.d.ts

@@ -0,0 +1,100 @@
+import { type Partition } from '@prefactor/pfid';
+import type { Transport } from '../transport/base.js';
+import type { Span, SpanType, TokenUsage } from './span.js';
+/**
+ * Options for starting a new span
+ */
+export interface StartSpanOptions {
+    /** Name of the span */
+    name: string;
+    /** Type of operation this span represents */
+    spanType: SpanType;
+    /** Input data for this operation */
+    inputs: Record<string, unknown>;
+    /** ID of the parent span (optional) */
+    parentSpanId?: string;
+    /** Trace ID to use (optional, will generate if not provided) */
+    traceId?: string;
+    /** Additional metadata (optional) */
+    metadata?: Record<string, unknown>;
+    /** Tags for categorizing the span (optional) */
+    tags?: string[];
+}
+/**
+ * Options for ending a span
+ */
+export interface EndSpanOptions {
+    /** Output data from the operation */
+    outputs?: Record<string, unknown>;
+    /** Error that occurred (if any) */
+    error?: Error;
+    /** Token usage information (for LLM calls) */
+    tokenUsage?: TokenUsage;
+}
+/**
+ * Tracer manages the lifecycle of spans.
+ *
+ * The tracer is responsible for:
+ * - Creating spans with unique IDs
+ * - Managing span lifecycle (start/end)
+ * - Delegating to the transport layer for span emission
+ * - Handling agent instance lifecycle
+ *
+ * @example
+ * ```typescript
+ * const tracer = new Tracer(transport);
+ *
+ * const span = tracer.startSpan({
+ *   name: 'llm-call',
+ *   spanType: SpanType.LLM,
+ *   inputs: { prompt: 'Hello' }
+ * });
+ *
+ * try {
+ *   // ... do work ...
+ *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });
+ * } catch (error) {
+ *   tracer.endSpan(span, { error });
+ * }
+ * ```
+ */
+export declare class Tracer {
+    private transport;
+    private partition;
+    /**
+     * Initialize the tracer.
+     *
+     * @param transport - The transport to use for emitting spans
+     * @param partition - The partition for ID generation. If not provided, a random partition will be generated.
+     */
+    constructor(transport: Transport, partition?: Partition);
+    /**
+     * Start a new span
+     *
+     * @param options - Span configuration options
+     * @returns The created span
+     */
+    startSpan(options: StartSpanOptions): Span;
+    /**
+     * End a span and emit it to the transport
+     *
+     * @param span - The span to end
+     * @param options - End span options (outputs, error, token usage)
+     */
+    endSpan(span: Span, options?: EndSpanOptions): void;
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance(): void;
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance(): void;
+    /**
+     * Close the tracer and flush any pending spans
+     *
+     * @returns Promise that resolves when the tracer is closed
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracing/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/tracing/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,mCAAmC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd,8CAA8C;IAC9C,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM;IASL,OAAO,CAAC,SAAS;IAR7B,OAAO,CAAC,SAAS,CAAY;IAE7B;;;;;OAKG;gBACiB,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,SAAS;IAI/D;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAkC1C;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IA6BnD;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAQ1B;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAQ3B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/tracing/tracer.js

@@ -0,0 +1,151 @@
+import { generate, generatePartition } from '@prefactor/pfid';
+import { SpanStatus } from './span.js';
+/**
+ * Tracer manages the lifecycle of spans.
+ *
+ * The tracer is responsible for:
+ * - Creating spans with unique IDs
+ * - Managing span lifecycle (start/end)
+ * - Delegating to the transport layer for span emission
+ * - Handling agent instance lifecycle
+ *
+ * @example
+ * ```typescript
+ * const tracer = new Tracer(transport);
+ *
+ * const span = tracer.startSpan({
+ *   name: 'llm-call',
+ *   spanType: SpanType.LLM,
+ *   inputs: { prompt: 'Hello' }
+ * });
+ *
+ * try {
+ *   // ... do work ...
+ *   tracer.endSpan(span, { outputs: { response: 'Hi!' } });
+ * } catch (error) {
+ *   tracer.endSpan(span, { error });
+ * }
+ * ```
+ */
+export class Tracer {
+    transport;
+    partition;
+    /**
+     * Initialize the tracer.
+     *
+     * @param transport - The transport to use for emitting spans
+     * @param partition - The partition for ID generation. If not provided, a random partition will be generated.
+     */
+    constructor(transport, partition) {
+        this.transport = transport;
+        this.partition = partition ?? generatePartition();
+    }
+    /**
+     * Start a new span
+     *
+     * @param options - Span configuration options
+     * @returns The created span
+     */
+    startSpan(options) {
+        const spanId = generate(this.partition);
+        const traceId = options.traceId ?? generate(this.partition);
+        const span = {
+            spanId,
+            parentSpanId: options.parentSpanId ?? null,
+            traceId,
+            name: options.name,
+            spanType: options.spanType,
+            startTime: Date.now(),
+            endTime: null,
+            status: SpanStatus.RUNNING,
+            inputs: options.inputs,
+            outputs: null,
+            tokenUsage: null,
+            error: null,
+            metadata: options.metadata ?? {},
+            tags: options.tags ?? [],
+        };
+        // AGENT spans are emitted immediately for real-time tracking
+        // They will be finished later with finishSpan()
+        if (options.spanType === 'agent') {
+            try {
+                this.transport.emit(span);
+            }
+            catch (error) {
+                console.error('Failed to emit agent span:', error);
+            }
+        }
+        return span;
+    }
+    /**
+     * End a span and emit it to the transport
+     *
+     * @param span - The span to end
+     * @param options - End span options (outputs, error, token usage)
+     */
+    endSpan(span, options) {
+        span.endTime = Date.now();
+        span.outputs = options?.outputs ?? null;
+        span.tokenUsage = options?.tokenUsage ?? null;
+        if (options?.error) {
+            span.status = SpanStatus.ERROR;
+            span.error = {
+                errorType: options.error.constructor.name,
+                message: options.error.message,
+                stacktrace: options.error.stack ?? '',
+            };
+        }
+        else {
+            span.status = SpanStatus.SUCCESS;
+        }
+        try {
+            // AGENT spans use finishSpan API (they were already emitted on start)
+            // Other span types are emitted here
+            if (span.spanType === 'agent') {
+                this.transport.finishSpan(span.spanId, span.endTime);
+            }
+            else {
+                this.transport.emit(span);
+            }
+        }
+        catch (error) {
+            console.error('Failed to emit/finish span:', error);
+        }
+    }
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance() {
+        try {
+            this.transport.startAgentInstance();
+        }
+        catch (error) {
+            console.error('Failed to start agent instance:', error);
+        }
+    }
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance() {
+        try {
+            this.transport.finishAgentInstance();
+        }
+        catch (error) {
+            console.error('Failed to finish agent instance:', error);
+        }
+    }
+    /**
+     * Close the tracer and flush any pending spans
+     *
+     * @returns Promise that resolves when the tracer is closed
+     */
+    async close() {
+        try {
+            await this.transport.close();
+        }
+        catch (error) {
+            console.error('Failed to close transport:', error);
+        }
+    }
+}
+//# sourceMappingURL=tracer.js.map

package/dist/tracing/tracer.js.map

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

package/dist/transport/base.d.ts

@@ -0,0 +1,38 @@
+import type { Span } from '../tracing/span.js';
+/**
+ * Transport interface for emitting spans to different backends
+ *
+ * Transports are responsible for sending span data to a destination
+ * (e.g., stdout, HTTP API). They implement the strategy pattern to allow
+ * pluggable backends.
+ */
+export interface Transport {
+    /**
+     * Emit a span to the transport destination
+     *
+     * @param span - The span to emit
+     */
+    emit(span: Span): void;
+    /**
+     * Finish a previously emitted span (for long-running spans like AGENT spans)
+     *
+     * @param spanId - ID of the span to finish
+     * @param endTime - End time in milliseconds since Unix epoch
+     */
+    finishSpan(spanId: string, endTime: number): void;
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance(): void;
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance(): void;
+    /**
+     * Close the transport and flush any pending data
+     *
+     * @returns Promise that resolves when the transport is fully closed
+     */
+    close(): void | Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/transport/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/transport/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAEvB;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;OAEG;IACH,kBAAkB,IAAI,IAAI,CAAC;IAE3B;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAAC;IAE5B;;;;OAIG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B"}

package/dist/transport/base.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base.js.map

package/dist/transport/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/transport/base.ts"],"names":[],"mappings":""}

package/dist/transport/http.d.ts

@@ -0,0 +1,86 @@
+import type { Transport } from './base.js';
+import type { HttpTransportConfig } from '../config.js';
+import type { Span } from '../tracing/span.js';
+/**
+ * HTTP transport sends spans to a remote API endpoint.
+ *
+ * Features:
+ * - Queue-based async processing
+ * - Exponential backoff retry logic
+ * - Span ID mapping (SDK ID → backend ID)
+ * - Agent instance lifecycle management
+ * - Graceful shutdown with timeout
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpTransport({
+ *   apiUrl: 'https://api.prefactor.ai',
+ *   apiToken: process.env.PREFACTOR_API_TOKEN!,
+ * });
+ * ```
+ */
+export declare class HttpTransport implements Transport {
+    private config;
+    private queue;
+    private processing;
+    private closed;
+    private agentInstanceId;
+    private spanIdMap;
+    constructor(config: HttpTransportConfig);
+    /**
+     * Emit a span (adds to queue for async processing)
+     *
+     * @param span - The span to emit
+     */
+    emit(span: Span): void;
+    /**
+     * Finish a previously emitted span (for AGENT spans)
+     *
+     * @param spanId - ID of the span to finish
+     * @param endTime - End time in milliseconds since Unix epoch
+     */
+    finishSpan(spanId: string, endTime: number): void;
+    /**
+     * Signal the start of an agent instance execution
+     */
+    startAgentInstance(): void;
+    /**
+     * Signal the completion of an agent instance execution
+     */
+    finishAgentInstance(): void;
+    /**
+     * Start background queue processing
+     */
+    private startProcessing;
+    /**
+     * Send a span to the API
+     */
+    private sendSpan;
+    /**
+     * Transform span to backend API format (snake_case)
+     */
+    private transformSpanToApiFormat;
+    /**
+     * Ensure an agent instance is registered
+     */
+    private ensureAgentRegistered;
+    /**
+     * Start agent instance execution
+     */
+    private startAgentInstanceHttp;
+    /**
+     * Finish agent instance execution
+     */
+    private finishAgentInstanceHttp;
+    /**
+     * Finish a span via HTTP
+     */
+    private finishSpanHttp;
+    /**
+     * Close the transport and wait for queue to drain
+     *
+     * @returns Promise that resolves when transport is closed
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=http.d.ts.map