@m_keshav/agenttrace 0.3.0

package/dist/cjs/client.d.ts

@@ -0,0 +1,11 @@
+export declare class IngestClient {
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly otlpExporterUrl;
+    constructor(apiUrl: string, apiKey?: string, timeoutMs?: number, otlpExporterUrl?: string);
+    static fromEnv(): IngestClient | null;
+    ingest(payload: Record<string, unknown>): Promise<void>;
+    private _ingestCustom;
+    private _ingestOtlp;
+}

package/dist/cjs/client.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngestClient = void 0;
+function _dtToNs(dt) {
+    return String(Math.floor(dt.getTime() * 1_000_000));
+}
+function _uuidToHex(u) {
+    return u.replace(/-/g, "");
+}
+function _buildOtlpEnvelope(runs, spans, serviceName = "agenttrace") {
+    const runMap = new Map(runs.map((r) => [r["run_id"], r]));
+    const traceSpans = new Map();
+    for (const span of spans) {
+        const traceId = _uuidToHex(span["run_id"]);
+        if (!traceSpans.has(traceId)) {
+            traceSpans.set(traceId, []);
+        }
+        const attrs = [
+            { key: "span.type", value: { stringValue: span["span_type"] } },
+            {
+                key: "input.value",
+                value: { stringValue: span["input_json"] ? JSON.stringify(span["input_json"]) : "" },
+            },
+            {
+                key: "output.value",
+                value: { stringValue: span["output_json"] ? JSON.stringify(span["output_json"]) : "" },
+            },
+        ];
+        const meta = span["metadata_json"];
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                attrs.push({ key: k, value: { stringValue: String(v) } });
+            }
+        }
+        if (span["error"]) {
+            attrs.push({ key: "error.message", value: { stringValue: span["error"] } });
+        }
+        traceSpans.get(traceId).push({
+            traceId,
+            spanId: _uuidToHex(span["span_id"]),
+            parentSpanId: span["parent_span_id"] ? _uuidToHex(span["parent_span_id"]) : "",
+            name: span["name"],
+            startTimeUnixNano: _dtToNs(new Date(span["start_time"])),
+            endTimeUnixNano: _dtToNs(new Date(span["end_time"])),
+            attributes: attrs,
+            status: span["error"] ? { code: 2 } : {},
+        });
+    }
+    const resourceSpans = [];
+    for (const [traceId, spanList] of traceSpans) {
+        const run = runMap.get(traceId);
+        resourceSpans.push({
+            resource: {
+                attributes: [{ key: "service.name", value: { stringValue: serviceName } }],
+            },
+            scopeSpans: [{ spans: spanList }],
+        });
+    }
+    return { resourceSpans };
+}
+class IngestClient {
+    apiUrl;
+    apiKey;
+    timeoutMs;
+    otlpExporterUrl;
+    constructor(apiUrl, apiKey, timeoutMs = 5000, otlpExporterUrl) {
+        this.apiUrl = apiUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
+        this.otlpExporterUrl = otlpExporterUrl;
+    }
+    static fromEnv() {
+        const apiUrl = process.env.AGENTTRACE_API_URL;
+        if (!apiUrl) {
+            return null;
+        }
+        const apiKey = process.env.AGENTTRACE_API_KEY;
+        const otlpExporterUrl = process.env.AGENTTRACE_OTLP_EXPORTER_URL;
+        return new IngestClient(apiUrl, apiKey || undefined, 5000, otlpExporterUrl || undefined);
+    }
+    async ingest(payload) {
+        if (this.otlpExporterUrl) {
+            await this._ingestOtlp(payload);
+        }
+        else {
+            await this._ingestCustom(payload);
+        }
+    }
+    async _ingestCustom(payload) {
+        const url = `${this.apiUrl}/v1/ingest`;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`Ingest failed: ${response.status} ${response.statusText}`);
+        }
+    }
+    async _ingestOtlp(payload) {
+        const runs = payload["runs"] ?? [];
+        const spans = payload["spans"] ?? [];
+        const serviceName = runs[0]?.["name"] ?? "agenttrace";
+        const otlpPayload = _buildOtlpEnvelope(runs, spans, serviceName);
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetch(this.otlpExporterUrl, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(otlpPayload),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`OTLP ingest failed: ${response.status} ${response.statusText}`);
+        }
+    }
+}
+exports.IngestClient = IngestClient;

package/dist/cjs/contracts.d.ts

@@ -0,0 +1,36 @@
+export type SpanType = "llm" | "tool" | "retrieval" | "chain" | "agent";
+export interface Run {
+    runId: string;
+    name: string;
+    createdAt: Date;
+    metadataJson: Record<string, unknown>;
+}
+export interface Span {
+    spanId: string;
+    runId: string;
+    parentSpanId: string | null;
+    spanType: SpanType;
+    name: string;
+    startTime: Date;
+    endTime: Date;
+    durationMs: number;
+    inputJson: unknown;
+    outputJson: unknown;
+    error: string | null;
+    metadataJson: Record<string, unknown>;
+}
+export declare function validateRun(run: Run): void;
+export declare function validateSpan(span: Span): void;
+/**
+ * Builds a payload for streaming use: skips cross-reference validation so
+ * individual spans can be sent without their run or parent spans in the same
+ * payload (they were already sent in earlier calls).
+ */
+export declare function buildStreamingPayload(run: Run | null, spans: Span[]): {
+    runs: Record<string, unknown>[];
+    spans: Record<string, unknown>[];
+};
+export declare function buildIngestPayload(runs: Run[], spans: Span[]): {
+    runs: Record<string, unknown>[];
+    spans: Record<string, unknown>[];
+};

package/dist/cjs/contracts.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRun = validateRun;
+exports.validateSpan = validateSpan;
+exports.buildStreamingPayload = buildStreamingPayload;
+exports.buildIngestPayload = buildIngestPayload;
+function ensureJsonSerializable(value, fieldName) {
+    try {
+        JSON.stringify(value);
+    }
+    catch {
+        throw new Error(`${fieldName} must be JSON serializable`);
+    }
+}
+function validateRun(run) {
+    if (!run.name) {
+        throw new Error("run.name must be non-empty");
+    }
+    ensureJsonSerializable(run.metadataJson, "run.metadataJson");
+}
+function validateSpan(span) {
+    if (!span.name) {
+        throw new Error("span.name must be non-empty");
+    }
+    if (span.durationMs < 0) {
+        throw new Error("span.durationMs must be >= 0");
+    }
+    ensureJsonSerializable(span.inputJson, "span.inputJson");
+    ensureJsonSerializable(span.outputJson, "span.outputJson");
+    ensureJsonSerializable(span.metadataJson, "span.metadataJson");
+    if (span.startTime > span.endTime) {
+        throw new Error("span.startTime must be <= span.endTime");
+    }
+}
+function runToDict(run) {
+    validateRun(run);
+    return {
+        run_id: run.runId,
+        name: run.name,
+        created_at: run.createdAt.toISOString(),
+        metadata_json: run.metadataJson,
+    };
+}
+function spanToDict(span) {
+    validateSpan(span);
+    return {
+        span_id: span.spanId,
+        run_id: span.runId,
+        parent_span_id: span.parentSpanId,
+        span_type: span.spanType,
+        name: span.name,
+        start_time: span.startTime.toISOString(),
+        end_time: span.endTime.toISOString(),
+        duration_ms: span.durationMs,
+        input_json: span.inputJson,
+        output_json: span.outputJson,
+        error: span.error,
+        metadata_json: span.metadataJson,
+    };
+}
+/**
+ * Builds a payload for streaming use: skips cross-reference validation so
+ * individual spans can be sent without their run or parent spans in the same
+ * payload (they were already sent in earlier calls).
+ */
+function buildStreamingPayload(run, spans) {
+    return {
+        runs: run ? [runToDict(run)] : [],
+        spans: spans.map(spanToDict),
+    };
+}
+function buildIngestPayload(runs, spans) {
+    const runIds = new Set(runs.map((r) => r.runId));
+    const spanIdsByRun = new Map();
+    for (const span of spans) {
+        validateSpan(span);
+        if (!spanIdsByRun.has(span.runId)) {
+            spanIdsByRun.set(span.runId, new Set());
+        }
+        spanIdsByRun.get(span.runId).add(span.spanId);
+    }
+    for (const span of spans) {
+        if (!runIds.has(span.runId)) {
+            throw new Error(`span ${span.spanId} references unknown run_id ${span.runId}`);
+        }
+        if (span.parentSpanId &&
+            !spanIdsByRun.get(span.runId)?.has(span.parentSpanId)) {
+            throw new Error(`span ${span.spanId} has parent_span_id ${span.parentSpanId} not found in run ${span.runId}`);
+        }
+    }
+    return {
+        runs: runs.map(runToDict),
+        spans: spans.map(spanToDict),
+    };
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,3 @@
+export { IngestClient } from "./client.js";
+export { type Run, type Span, type SpanType, buildIngestPayload, } from "./contracts.js";
+export { RunTraceContext, TraceAPI, trace } from "./trace.js";

package/dist/cjs/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trace = exports.TraceAPI = exports.RunTraceContext = exports.buildIngestPayload = exports.IngestClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "IngestClient", { enumerable: true, get: function () { return client_js_1.IngestClient; } });
+var contracts_js_1 = require("./contracts.js");
+Object.defineProperty(exports, "buildIngestPayload", { enumerable: true, get: function () { return contracts_js_1.buildIngestPayload; } });
+var trace_js_1 = require("./trace.js");
+Object.defineProperty(exports, "RunTraceContext", { enumerable: true, get: function () { return trace_js_1.RunTraceContext; } });
+Object.defineProperty(exports, "TraceAPI", { enumerable: true, get: function () { return trace_js_1.TraceAPI; } });
+Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return trace_js_1.trace; } });

package/dist/cjs/trace.d.ts

@@ -0,0 +1,37 @@
+import { type Span, type SpanType } from "./contracts.js";
+export declare class RunTraceContext {
+    private readonly _run;
+    private readonly _spans;
+    private _flushed;
+    private _flushError;
+    private _streamClient;
+    private _runStreamed;
+    constructor(name: string, metadata?: Record<string, unknown>);
+    get runId(): string;
+    get spans(): ReadonlyArray<Span>;
+    get flushError(): Error | null;
+    addSpan(opts: {
+        spanType: SpanType;
+        name: string;
+        startTime: Date;
+        endTime: Date;
+        inputJson: unknown;
+        outputJson: unknown;
+        error?: string | null;
+        metadataJson?: Record<string, unknown>;
+        parentSpanId?: string | null;
+        spanId?: string;
+    }): Span;
+    private _streamSpan;
+    buildPayload(): {
+        runs: Record<string, unknown>[];
+        spans: Record<string, unknown>[];
+    };
+    flush(): Promise<void>;
+    run<T>(callback: (ctx: RunTraceContext) => T | Promise<T>): Promise<T>;
+}
+export declare class TraceAPI {
+    run<T>(name: string, callback: (ctx: RunTraceContext) => T | Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+    current(): RunTraceContext | null;
+}
+export declare const trace: TraceAPI;

package/dist/cjs/trace.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trace = exports.TraceAPI = exports.RunTraceContext = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = require("node:crypto");
+const client_js_1 = require("./client.js");
+const contracts_js_1 = require("./contracts.js");
+const asyncLocalStorage = new node_async_hooks_1.AsyncLocalStorage();
+class RunTraceContext {
+    _run;
+    _spans = [];
+    _flushed = false;
+    _flushError = null;
+    _streamClient = undefined; // undefined = not yet resolved
+    _runStreamed = false;
+    constructor(name, metadata) {
+        this._run = {
+            runId: (0, node_crypto_1.randomUUID)(),
+            name,
+            createdAt: new Date(),
+            metadataJson: metadata ?? {},
+        };
+    }
+    get runId() {
+        return this._run.runId;
+    }
+    get spans() {
+        return [...this._spans];
+    }
+    get flushError() {
+        return this._flushError;
+    }
+    addSpan(opts) {
+        const spanId = opts.spanId ?? (0, node_crypto_1.randomUUID)();
+        const parentSpanId = opts.parentSpanId ?? null;
+        const durationMs = opts.endTime.getTime() - opts.startTime.getTime();
+        const span = {
+            spanId,
+            runId: this._run.runId,
+            parentSpanId,
+            spanType: opts.spanType,
+            name: opts.name,
+            startTime: opts.startTime,
+            endTime: opts.endTime,
+            durationMs,
+            inputJson: opts.inputJson,
+            outputJson: opts.outputJson,
+            error: opts.error ?? null,
+            metadataJson: opts.metadataJson ?? {},
+        };
+        (0, contracts_js_1.validateSpan)(span);
+        this._spans.push(span);
+        this._streamSpan(span);
+        return span;
+    }
+    _streamSpan(span) {
+        if (this._streamClient === undefined) {
+            this._streamClient = client_js_1.IngestClient.fromEnv();
+        }
+        if (!this._streamClient)
+            return;
+        // Include the run only on the first streaming call so the backend can
+        // commit the run row before any spans arrive. Subsequent calls omit it.
+        const runToSend = this._runStreamed ? null : this._run;
+        this._runStreamed = true;
+        const payload = (0, contracts_js_1.buildStreamingPayload)(runToSend, [span]);
+        this._streamClient.ingest(payload).catch(() => {
+            // Streaming is best-effort; errors are silently dropped.
+        });
+    }
+    buildPayload() {
+        return (0, contracts_js_1.buildIngestPayload)([this._run], this._spans);
+    }
+    async flush() {
+        if (this._flushed)
+            return;
+        const client = client_js_1.IngestClient.fromEnv();
+        if (!client) {
+            this._flushed = true;
+            return;
+        }
+        const payload = this.buildPayload();
+        await client.ingest(payload);
+        this._flushed = true;
+    }
+    async run(callback) {
+        return asyncLocalStorage.run(this, async () => {
+            let result;
+            try {
+                result = await callback(this);
+            }
+            catch (err) {
+                const now = new Date();
+                this.addSpan({
+                    spanType: "agent",
+                    name: "run_error",
+                    startTime: now,
+                    endTime: now,
+                    inputJson: {},
+                    outputJson: {},
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                try {
+                    await this.flush();
+                }
+                catch (flushErr) {
+                    this._flushError =
+                        flushErr instanceof Error ? flushErr : new Error(String(flushErr));
+                }
+                throw err;
+            }
+            try {
+                await this.flush();
+            }
+            catch (flushErr) {
+                this._flushError =
+                    flushErr instanceof Error ? flushErr : new Error(String(flushErr));
+            }
+            return result;
+        });
+    }
+}
+exports.RunTraceContext = RunTraceContext;
+class TraceAPI {
+    async run(name, callback, metadata) {
+        const ctx = new RunTraceContext(name, metadata);
+        return ctx.run(callback);
+    }
+    current() {
+        return asyncLocalStorage.getStore() ?? null;
+    }
+}
+exports.TraceAPI = TraceAPI;
+exports.trace = new TraceAPI();

package/dist/esm/client.d.ts

@@ -0,0 +1,11 @@
+export declare class IngestClient {
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly otlpExporterUrl;
+    constructor(apiUrl: string, apiKey?: string, timeoutMs?: number, otlpExporterUrl?: string);
+    static fromEnv(): IngestClient | null;
+    ingest(payload: Record<string, unknown>): Promise<void>;
+    private _ingestCustom;
+    private _ingestOtlp;
+}

package/dist/esm/client.js

@@ -0,0 +1,125 @@
+function _dtToNs(dt) {
+    return String(Math.floor(dt.getTime() * 1_000_000));
+}
+function _uuidToHex(u) {
+    return u.replace(/-/g, "");
+}
+function _buildOtlpEnvelope(runs, spans, serviceName = "agenttrace") {
+    const runMap = new Map(runs.map((r) => [r["run_id"], r]));
+    const traceSpans = new Map();
+    for (const span of spans) {
+        const traceId = _uuidToHex(span["run_id"]);
+        if (!traceSpans.has(traceId)) {
+            traceSpans.set(traceId, []);
+        }
+        const attrs = [
+            { key: "span.type", value: { stringValue: span["span_type"] } },
+            {
+                key: "input.value",
+                value: { stringValue: span["input_json"] ? JSON.stringify(span["input_json"]) : "" },
+            },
+            {
+                key: "output.value",
+                value: { stringValue: span["output_json"] ? JSON.stringify(span["output_json"]) : "" },
+            },
+        ];
+        const meta = span["metadata_json"];
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                attrs.push({ key: k, value: { stringValue: String(v) } });
+            }
+        }
+        if (span["error"]) {
+            attrs.push({ key: "error.message", value: { stringValue: span["error"] } });
+        }
+        traceSpans.get(traceId).push({
+            traceId,
+            spanId: _uuidToHex(span["span_id"]),
+            parentSpanId: span["parent_span_id"] ? _uuidToHex(span["parent_span_id"]) : "",
+            name: span["name"],
+            startTimeUnixNano: _dtToNs(new Date(span["start_time"])),
+            endTimeUnixNano: _dtToNs(new Date(span["end_time"])),
+            attributes: attrs,
+            status: span["error"] ? { code: 2 } : {},
+        });
+    }
+    const resourceSpans = [];
+    for (const [traceId, spanList] of traceSpans) {
+        const run = runMap.get(traceId);
+        resourceSpans.push({
+            resource: {
+                attributes: [{ key: "service.name", value: { stringValue: serviceName } }],
+            },
+            scopeSpans: [{ spans: spanList }],
+        });
+    }
+    return { resourceSpans };
+}
+export class IngestClient {
+    apiUrl;
+    apiKey;
+    timeoutMs;
+    otlpExporterUrl;
+    constructor(apiUrl, apiKey, timeoutMs = 5000, otlpExporterUrl) {
+        this.apiUrl = apiUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.timeoutMs = timeoutMs;
+        this.otlpExporterUrl = otlpExporterUrl;
+    }
+    static fromEnv() {
+        const apiUrl = process.env.AGENTTRACE_API_URL;
+        if (!apiUrl) {
+            return null;
+        }
+        const apiKey = process.env.AGENTTRACE_API_KEY;
+        const otlpExporterUrl = process.env.AGENTTRACE_OTLP_EXPORTER_URL;
+        return new IngestClient(apiUrl, apiKey || undefined, 5000, otlpExporterUrl || undefined);
+    }
+    async ingest(payload) {
+        if (this.otlpExporterUrl) {
+            await this._ingestOtlp(payload);
+        }
+        else {
+            await this._ingestCustom(payload);
+        }
+    }
+    async _ingestCustom(payload) {
+        const url = `${this.apiUrl}/v1/ingest`;
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`Ingest failed: ${response.status} ${response.statusText}`);
+        }
+    }
+    async _ingestOtlp(payload) {
+        const runs = payload["runs"] ?? [];
+        const spans = payload["spans"] ?? [];
+        const serviceName = runs[0]?.["name"] ?? "agenttrace";
+        const otlpPayload = _buildOtlpEnvelope(runs, spans, serviceName);
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const response = await fetch(this.otlpExporterUrl, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(otlpPayload),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`OTLP ingest failed: ${response.status} ${response.statusText}`);
+        }
+    }
+}

package/dist/esm/contracts.d.ts

@@ -0,0 +1,36 @@
+export type SpanType = "llm" | "tool" | "retrieval" | "chain" | "agent";
+export interface Run {
+    runId: string;
+    name: string;
+    createdAt: Date;
+    metadataJson: Record<string, unknown>;
+}
+export interface Span {
+    spanId: string;
+    runId: string;
+    parentSpanId: string | null;
+    spanType: SpanType;
+    name: string;
+    startTime: Date;
+    endTime: Date;
+    durationMs: number;
+    inputJson: unknown;
+    outputJson: unknown;
+    error: string | null;
+    metadataJson: Record<string, unknown>;
+}
+export declare function validateRun(run: Run): void;
+export declare function validateSpan(span: Span): void;
+/**
+ * Builds a payload for streaming use: skips cross-reference validation so
+ * individual spans can be sent without their run or parent spans in the same
+ * payload (they were already sent in earlier calls).
+ */
+export declare function buildStreamingPayload(run: Run | null, spans: Span[]): {
+    runs: Record<string, unknown>[];
+    spans: Record<string, unknown>[];
+};
+export declare function buildIngestPayload(runs: Run[], spans: Span[]): {
+    runs: Record<string, unknown>[];
+    spans: Record<string, unknown>[];
+};

package/dist/esm/contracts.js

@@ -0,0 +1,89 @@
+function ensureJsonSerializable(value, fieldName) {
+    try {
+        JSON.stringify(value);
+    }
+    catch {
+        throw new Error(`${fieldName} must be JSON serializable`);
+    }
+}
+export function validateRun(run) {
+    if (!run.name) {
+        throw new Error("run.name must be non-empty");
+    }
+    ensureJsonSerializable(run.metadataJson, "run.metadataJson");
+}
+export function validateSpan(span) {
+    if (!span.name) {
+        throw new Error("span.name must be non-empty");
+    }
+    if (span.durationMs < 0) {
+        throw new Error("span.durationMs must be >= 0");
+    }
+    ensureJsonSerializable(span.inputJson, "span.inputJson");
+    ensureJsonSerializable(span.outputJson, "span.outputJson");
+    ensureJsonSerializable(span.metadataJson, "span.metadataJson");
+    if (span.startTime > span.endTime) {
+        throw new Error("span.startTime must be <= span.endTime");
+    }
+}
+function runToDict(run) {
+    validateRun(run);
+    return {
+        run_id: run.runId,
+        name: run.name,
+        created_at: run.createdAt.toISOString(),
+        metadata_json: run.metadataJson,
+    };
+}
+function spanToDict(span) {
+    validateSpan(span);
+    return {
+        span_id: span.spanId,
+        run_id: span.runId,
+        parent_span_id: span.parentSpanId,
+        span_type: span.spanType,
+        name: span.name,
+        start_time: span.startTime.toISOString(),
+        end_time: span.endTime.toISOString(),
+        duration_ms: span.durationMs,
+        input_json: span.inputJson,
+        output_json: span.outputJson,
+        error: span.error,
+        metadata_json: span.metadataJson,
+    };
+}
+/**
+ * Builds a payload for streaming use: skips cross-reference validation so
+ * individual spans can be sent without their run or parent spans in the same
+ * payload (they were already sent in earlier calls).
+ */
+export function buildStreamingPayload(run, spans) {
+    return {
+        runs: run ? [runToDict(run)] : [],
+        spans: spans.map(spanToDict),
+    };
+}
+export function buildIngestPayload(runs, spans) {
+    const runIds = new Set(runs.map((r) => r.runId));
+    const spanIdsByRun = new Map();
+    for (const span of spans) {
+        validateSpan(span);
+        if (!spanIdsByRun.has(span.runId)) {
+            spanIdsByRun.set(span.runId, new Set());
+        }
+        spanIdsByRun.get(span.runId).add(span.spanId);
+    }
+    for (const span of spans) {
+        if (!runIds.has(span.runId)) {
+            throw new Error(`span ${span.spanId} references unknown run_id ${span.runId}`);
+        }
+        if (span.parentSpanId &&
+            !spanIdsByRun.get(span.runId)?.has(span.parentSpanId)) {
+            throw new Error(`span ${span.spanId} has parent_span_id ${span.parentSpanId} not found in run ${span.runId}`);
+        }
+    }
+    return {
+        runs: runs.map(runToDict),
+        spans: spans.map(spanToDict),
+    };
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export { IngestClient } from "./client.js";
+export { type Run, type Span, type SpanType, buildIngestPayload, } from "./contracts.js";
+export { RunTraceContext, TraceAPI, trace } from "./trace.js";

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { IngestClient } from "./client.js";
+export { buildIngestPayload, } from "./contracts.js";
+export { RunTraceContext, TraceAPI, trace } from "./trace.js";

package/dist/esm/trace.d.ts

@@ -0,0 +1,37 @@
+import { type Span, type SpanType } from "./contracts.js";
+export declare class RunTraceContext {
+    private readonly _run;
+    private readonly _spans;
+    private _flushed;
+    private _flushError;
+    private _streamClient;
+    private _runStreamed;
+    constructor(name: string, metadata?: Record<string, unknown>);
+    get runId(): string;
+    get spans(): ReadonlyArray<Span>;
+    get flushError(): Error | null;
+    addSpan(opts: {
+        spanType: SpanType;
+        name: string;
+        startTime: Date;
+        endTime: Date;
+        inputJson: unknown;
+        outputJson: unknown;
+        error?: string | null;
+        metadataJson?: Record<string, unknown>;
+        parentSpanId?: string | null;
+        spanId?: string;
+    }): Span;
+    private _streamSpan;
+    buildPayload(): {
+        runs: Record<string, unknown>[];
+        spans: Record<string, unknown>[];
+    };
+    flush(): Promise<void>;
+    run<T>(callback: (ctx: RunTraceContext) => T | Promise<T>): Promise<T>;
+}
+export declare class TraceAPI {
+    run<T>(name: string, callback: (ctx: RunTraceContext) => T | Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+    current(): RunTraceContext | null;
+}
+export declare const trace: TraceAPI;

package/dist/esm/trace.js

@@ -0,0 +1,129 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { IngestClient } from "./client.js";
+import { buildIngestPayload, buildStreamingPayload, validateSpan, } from "./contracts.js";
+const asyncLocalStorage = new AsyncLocalStorage();
+export class RunTraceContext {
+    _run;
+    _spans = [];
+    _flushed = false;
+    _flushError = null;
+    _streamClient = undefined; // undefined = not yet resolved
+    _runStreamed = false;
+    constructor(name, metadata) {
+        this._run = {
+            runId: randomUUID(),
+            name,
+            createdAt: new Date(),
+            metadataJson: metadata ?? {},
+        };
+    }
+    get runId() {
+        return this._run.runId;
+    }
+    get spans() {
+        return [...this._spans];
+    }
+    get flushError() {
+        return this._flushError;
+    }
+    addSpan(opts) {
+        const spanId = opts.spanId ?? randomUUID();
+        const parentSpanId = opts.parentSpanId ?? null;
+        const durationMs = opts.endTime.getTime() - opts.startTime.getTime();
+        const span = {
+            spanId,
+            runId: this._run.runId,
+            parentSpanId,
+            spanType: opts.spanType,
+            name: opts.name,
+            startTime: opts.startTime,
+            endTime: opts.endTime,
+            durationMs,
+            inputJson: opts.inputJson,
+            outputJson: opts.outputJson,
+            error: opts.error ?? null,
+            metadataJson: opts.metadataJson ?? {},
+        };
+        validateSpan(span);
+        this._spans.push(span);
+        this._streamSpan(span);
+        return span;
+    }
+    _streamSpan(span) {
+        if (this._streamClient === undefined) {
+            this._streamClient = IngestClient.fromEnv();
+        }
+        if (!this._streamClient)
+            return;
+        // Include the run only on the first streaming call so the backend can
+        // commit the run row before any spans arrive. Subsequent calls omit it.
+        const runToSend = this._runStreamed ? null : this._run;
+        this._runStreamed = true;
+        const payload = buildStreamingPayload(runToSend, [span]);
+        this._streamClient.ingest(payload).catch(() => {
+            // Streaming is best-effort; errors are silently dropped.
+        });
+    }
+    buildPayload() {
+        return buildIngestPayload([this._run], this._spans);
+    }
+    async flush() {
+        if (this._flushed)
+            return;
+        const client = IngestClient.fromEnv();
+        if (!client) {
+            this._flushed = true;
+            return;
+        }
+        const payload = this.buildPayload();
+        await client.ingest(payload);
+        this._flushed = true;
+    }
+    async run(callback) {
+        return asyncLocalStorage.run(this, async () => {
+            let result;
+            try {
+                result = await callback(this);
+            }
+            catch (err) {
+                const now = new Date();
+                this.addSpan({
+                    spanType: "agent",
+                    name: "run_error",
+                    startTime: now,
+                    endTime: now,
+                    inputJson: {},
+                    outputJson: {},
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                try {
+                    await this.flush();
+                }
+                catch (flushErr) {
+                    this._flushError =
+                        flushErr instanceof Error ? flushErr : new Error(String(flushErr));
+                }
+                throw err;
+            }
+            try {
+                await this.flush();
+            }
+            catch (flushErr) {
+                this._flushError =
+                    flushErr instanceof Error ? flushErr : new Error(String(flushErr));
+            }
+            return result;
+        });
+    }
+}
+export class TraceAPI {
+    async run(name, callback, metadata) {
+        const ctx = new RunTraceContext(name, metadata);
+        return ctx.run(callback);
+    }
+    current() {
+        return asyncLocalStorage.getStore() ?? null;
+    }
+}
+export const trace = new TraceAPI();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@m_keshav/agenttrace",
+  "version": "0.3.0",
+  "description": "TypeScript SDK for AgentTrace – capture and ingest agent execution traces",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/esm/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "testcontainers": "^12.0.4",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}