agentlens-sdk 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# agentlens-sdk
+
+TypeScript SDK for AgentLens — Agent observability that traces decisions, not just API calls.
+
+[![npm version](https://img.shields.io/npm/v/agentlens-sdk.svg)](https://www.npmjs.com/package/agentlens-sdk)
+[![license](https://img.shields.io/npm/l/agentlens-sdk.svg)](https://github.com/repi/agentlens/blob/main/LICENSE)
+
+## Install
+
+```bash
+npm install agentlens-sdk
+```
+
+## Quick Start
+
+```typescript
+import { init, TraceBuilder, shutdown } from "agentlens-sdk";
+
+// Initialize the SDK
+init({
+  apiKey: "your-api-key",
+  endpoint: "https://agentlens.vectry.tech/api",
+});
+
+// Create a trace
+const trace = new TraceBuilder("agent-run-123", "My Agent Task");
+
+// Add a span (tool call, LLM call, etc.)
+trace.addSpan({
+  name: "search-documents",
+  type: "tool",
+  input: { query: "quarterly report" },
+  output: { results: 5 },
+});
+
+// Record a decision point
+trace.addDecision({
+  name: "select-tool",
+  type: "tool_selection",
+  options: ["search", "calculate", "summarize"],
+  selected: "search",
+  reasoning: "User asked for document lookup",
+});
+
+// Finalize and send
+await trace.end();
+
+// Flush remaining data before exit
+await shutdown();
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|---|---|
+| `init(options)` | Initialize the SDK with your API key and configuration. |
+| `shutdown()` | Flush pending data and shut down the transport. |
+| `flush()` | Manually flush the current batch without shutting down. |
+| `getClient()` | Return the initialized client instance. |
+
+### TraceBuilder
+
+The primary interface for constructing traces.
+
+```typescript
+const trace = new TraceBuilder(traceId: string, name: string);
+
+trace.addSpan(span: SpanPayload);       // Add a span to the trace
+trace.addDecision(decision: DecisionPointPayload); // Record a decision point
+trace.end(): Promise<void>;             // Finalize and send the trace
+```
+
+### Standalone Helpers
+
+| Function | Description |
+|---|---|
+| `createDecision(decision)` | Create and send a standalone decision point outside a trace. |
+
+## Types
+
+Core payload types used throughout the SDK:
+
+- **`TracePayload`** — Top-level trace structure containing spans and metadata.
+- **`SpanPayload`** — Individual unit of work (tool call, LLM request, retrieval, etc.).
+- **`DecisionPointPayload`** — A recorded decision: what options existed, what was chosen, and why.
+- **`EventPayload`** — Discrete event within a span or trace.
+- **`JsonValue`** — Flexible JSON-compatible value type for inputs/outputs.
+
+## Enums
+
+| Enum | Values |
+|---|---|
+| `TraceStatus` | Status of the overall trace (e.g., running, completed, failed). |
+| `SpanType` | Category of span (e.g., tool, llm, retrieval). |
+| `SpanStatus` | Status of an individual span. |
+| `DecisionType` | Category of decision (e.g., tool_selection, routing). |
+| `EventType` | Category of event within a span. |
+
+## Configuration
+
+Pass `InitOptions` to `init()`:
+
+```typescript
+init({
+  apiKey: "your-api-key",       // Required. Your AgentLens API key.
+  endpoint: "https://...",      // API endpoint. Defaults to AgentLens cloud.
+  maxBatchSize: 100,            // Max items per batch before auto-flush.
+  flushInterval: 5000,          // Auto-flush interval in milliseconds.
+});
+```
+
+## Transport
+
+The SDK ships with `BatchTransport`, which batches payloads and flushes them on an interval or when the batch size threshold is reached. This is used internally by `init()` — you typically do not need to instantiate it directly.
+
+## Documentation
+
+Full documentation: [agentlens.vectry.tech/docs/typescript-sdk](https://agentlens.vectry.tech/docs/typescript-sdk)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,320 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BatchTransport: () => BatchTransport,
+  DecisionType: () => DecisionType,
+  EventType: () => EventType,
+  SpanStatus: () => SpanStatus,
+  SpanType: () => SpanType,
+  TraceBuilder: () => TraceBuilder,
+  TraceStatus: () => TraceStatus,
+  createDecision: () => createDecision,
+  flush: () => flush,
+  generateId: () => generateId,
+  getClient: () => getClient,
+  init: () => init,
+  nowISO: () => nowISO,
+  shutdown: () => shutdown
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/transport.ts
+var BatchTransport = class {
+  apiKey;
+  endpoint;
+  maxBatchSize;
+  flushInterval;
+  buffer = [];
+  timer = null;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.endpoint = options.endpoint.replace(/\/+$/, "");
+    this.maxBatchSize = options.maxBatchSize ?? 10;
+    this.flushInterval = options.flushInterval ?? 5e3;
+    this.timer = setInterval(() => {
+      void this._doFlush();
+    }, this.flushInterval);
+  }
+  add(trace) {
+    this.buffer.push(trace);
+    if (this.buffer.length >= this.maxBatchSize) {
+      void this._doFlush();
+    }
+  }
+  async flush() {
+    await this._doFlush();
+  }
+  async shutdown() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this._doFlush();
+  }
+  async _doFlush() {
+    if (this.buffer.length === 0) {
+      return;
+    }
+    const batch = this.buffer.splice(0, this.buffer.length);
+    try {
+      const response = await fetch(`${this.endpoint}/api/traces`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ traces: batch })
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        console.warn(
+          `AgentLens: Failed to send traces (HTTP ${response.status}): ${text.slice(0, 200)}`
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`AgentLens: Failed to send traces: ${message}`);
+    }
+  }
+};
+
+// src/_registry.ts
+var _transport = null;
+function _setTransport(transport) {
+  _transport = transport;
+}
+function _getTransport() {
+  return _transport;
+}
+
+// src/models.ts
+var import_crypto = require("crypto");
+var TraceStatus = {
+  RUNNING: "RUNNING",
+  COMPLETED: "COMPLETED",
+  ERROR: "ERROR"
+};
+var DecisionType = {
+  TOOL_SELECTION: "TOOL_SELECTION",
+  ROUTING: "ROUTING",
+  RETRY: "RETRY",
+  ESCALATION: "ESCALATION",
+  MEMORY_RETRIEVAL: "MEMORY_RETRIEVAL",
+  PLANNING: "PLANNING",
+  CUSTOM: "CUSTOM"
+};
+var SpanType = {
+  LLM_CALL: "LLM_CALL",
+  TOOL_CALL: "TOOL_CALL",
+  MEMORY_OP: "MEMORY_OP",
+  CHAIN: "CHAIN",
+  AGENT: "AGENT",
+  CUSTOM: "CUSTOM"
+};
+var SpanStatus = {
+  RUNNING: "RUNNING",
+  COMPLETED: "COMPLETED",
+  ERROR: "ERROR"
+};
+var EventType = {
+  ERROR: "ERROR",
+  RETRY: "RETRY",
+  FALLBACK: "FALLBACK",
+  CONTEXT_OVERFLOW: "CONTEXT_OVERFLOW",
+  USER_FEEDBACK: "USER_FEEDBACK",
+  CUSTOM: "CUSTOM"
+};
+function generateId() {
+  return (0, import_crypto.randomUUID)();
+}
+function nowISO() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/trace.ts
+var TraceBuilder = class {
+  trace;
+  startMs;
+  constructor(name, options) {
+    this.startMs = Date.now();
+    this.trace = {
+      id: generateId(),
+      name,
+      sessionId: options?.sessionId,
+      status: TraceStatus.RUNNING,
+      tags: options?.tags ?? [],
+      metadata: options?.metadata,
+      startedAt: nowISO(),
+      decisionPoints: [],
+      spans: [],
+      events: []
+    };
+  }
+  addSpan(input) {
+    const id = input.id ?? generateId();
+    const span = {
+      id,
+      parentSpanId: input.parentSpanId,
+      name: input.name,
+      type: input.type,
+      input: input.input,
+      output: input.output,
+      tokenCount: input.tokenCount,
+      costUsd: input.costUsd,
+      durationMs: input.durationMs,
+      status: input.status ?? SpanStatus.RUNNING,
+      statusMessage: input.statusMessage,
+      startedAt: input.startedAt ?? nowISO(),
+      endedAt: input.endedAt,
+      metadata: input.metadata
+    };
+    this.trace.spans.push(span);
+    return id;
+  }
+  addDecision(input) {
+    const id = input.id ?? generateId();
+    const decision = {
+      id,
+      type: input.type,
+      chosen: input.chosen,
+      alternatives: input.alternatives ?? [],
+      reasoning: input.reasoning,
+      contextSnapshot: input.contextSnapshot,
+      durationMs: input.durationMs,
+      costUsd: input.costUsd,
+      parentSpanId: input.parentSpanId,
+      timestamp: input.timestamp ?? nowISO()
+    };
+    this.trace.decisionPoints.push(decision);
+    return id;
+  }
+  addEvent(input) {
+    const id = input.id ?? generateId();
+    const event = {
+      id,
+      spanId: input.spanId,
+      type: input.type,
+      name: input.name,
+      metadata: input.metadata,
+      timestamp: input.timestamp ?? nowISO()
+    };
+    this.trace.events.push(event);
+    return id;
+  }
+  setStatus(status) {
+    this.trace.status = status;
+    return this;
+  }
+  setMetadata(metadata) {
+    this.trace.metadata = metadata;
+    return this;
+  }
+  toPayload() {
+    return { ...this.trace };
+  }
+  end(options) {
+    const endedAt = nowISO();
+    this.trace.endedAt = endedAt;
+    this.trace.totalDuration = Date.now() - this.startMs;
+    this.trace.status = options?.status ?? TraceStatus.COMPLETED;
+    if (options?.metadata !== void 0) {
+      this.trace.metadata = options.metadata;
+    }
+    if (options?.totalCost !== void 0) {
+      this.trace.totalCost = options.totalCost;
+    }
+    if (options?.totalTokens !== void 0) {
+      this.trace.totalTokens = options.totalTokens;
+    }
+    const transport = _getTransport();
+    if (transport) {
+      transport.add(this.trace);
+    }
+    return { ...this.trace };
+  }
+};
+
+// src/decision.ts
+function createDecision(input) {
+  return {
+    id: generateId(),
+    type: input.type,
+    chosen: input.chosen,
+    alternatives: input.alternatives ?? [],
+    reasoning: input.reasoning,
+    contextSnapshot: input.contextSnapshot,
+    durationMs: input.durationMs,
+    costUsd: input.costUsd,
+    parentSpanId: input.parentSpanId,
+    timestamp: input.timestamp ?? nowISO()
+  };
+}
+
+// src/index.ts
+function init(options) {
+  const existing = _getTransport();
+  if (existing) {
+    void existing.shutdown();
+  }
+  _setTransport(
+    new BatchTransport({
+      apiKey: options.apiKey,
+      endpoint: options.endpoint ?? "https://agentlens.vectry.tech",
+      maxBatchSize: options.maxBatchSize,
+      flushInterval: options.flushInterval
+    })
+  );
+}
+async function shutdown() {
+  const transport = _getTransport();
+  if (transport) {
+    await transport.shutdown();
+    _setTransport(null);
+  }
+}
+function getClient() {
+  return _getTransport();
+}
+async function flush() {
+  const transport = _getTransport();
+  if (transport) {
+    await transport.flush();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BatchTransport,
+  DecisionType,
+  EventType,
+  SpanStatus,
+  SpanType,
+  TraceBuilder,
+  TraceStatus,
+  createDecision,
+  flush,
+  generateId,
+  getClient,
+  init,
+  nowISO,
+  shutdown
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/transport.ts","../src/_registry.ts","../src/models.ts","../src/trace.ts","../src/decision.ts"],"sourcesContent":["import { BatchTransport } from \"./transport.js\";\nimport { _setTransport, _getTransport } from \"./_registry.js\";\n\nexport interface InitOptions {\n  apiKey: string;\n  endpoint?: string;\n  maxBatchSize?: number;\n  flushInterval?: number;\n}\n\nexport function init(options: InitOptions): void {\n  const existing = _getTransport();\n  if (existing) {\n    void existing.shutdown();\n  }\n  _setTransport(\n    new BatchTransport({\n      apiKey: options.apiKey,\n      endpoint: options.endpoint ?? \"https://agentlens.vectry.tech\",\n      maxBatchSize: options.maxBatchSize,\n      flushInterval: options.flushInterval,\n    }),\n  );\n}\n\nexport async function shutdown(): Promise<void> {\n  const transport = _getTransport();\n  if (transport) {\n    await transport.shutdown();\n    _setTransport(null);\n  }\n}\n\nexport function getClient(): BatchTransport | null {\n  return _getTransport();\n}\n\nexport async function flush(): Promise<void> {\n  const transport = _getTransport();\n  if (transport) {\n    await transport.flush();\n  }\n}\n\nexport {\n  TraceStatus,\n  DecisionType,\n  SpanType,\n  SpanStatus,\n  EventType,\n  generateId,\n  nowISO,\n} from \"./models.js\";\n\nexport type {\n  JsonValue,\n  DecisionPointPayload,\n  SpanPayload,\n  EventPayload,\n  TracePayload,\n} from \"./models.js\";\n\nexport { BatchTransport } from \"./transport.js\";\nexport type { BatchTransportOptions } from \"./transport.js\";\n\nexport { TraceBuilder } from \"./trace.js\";\nexport type {\n  TraceBuilderOptions,\n  AddSpanInput,\n  AddDecisionInput,\n  AddEventInput,\n  EndOptions,\n} from \"./trace.js\";\n\nexport { createDecision } from \"./decision.js\";\nexport type { CreateDecisionInput } from \"./decision.js\";\n","import type { TracePayload } from \"./models.js\";\n\nexport interface BatchTransportOptions {\n  apiKey: string;\n  endpoint: string;\n  maxBatchSize?: number;\n  flushInterval?: number;\n}\n\nexport class BatchTransport {\n  private readonly apiKey: string;\n  private readonly endpoint: string;\n  private readonly maxBatchSize: number;\n  private readonly flushInterval: number;\n  private buffer: TracePayload[] = [];\n  private timer: ReturnType<typeof setInterval> | null = null;\n\n  constructor(options: BatchTransportOptions) {\n    this.apiKey = options.apiKey;\n    this.endpoint = options.endpoint.replace(/\\/+$/, \"\");\n    this.maxBatchSize = options.maxBatchSize ?? 10;\n    this.flushInterval = options.flushInterval ?? 5_000;\n\n    this.timer = setInterval(() => {\n      void this._doFlush();\n    }, this.flushInterval);\n  }\n\n  add(trace: TracePayload): void {\n    this.buffer.push(trace);\n    if (this.buffer.length >= this.maxBatchSize) {\n      void this._doFlush();\n    }\n  }\n\n  async flush(): Promise<void> {\n    await this._doFlush();\n  }\n\n  async shutdown(): Promise<void> {\n    if (this.timer !== null) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n    await this._doFlush();\n  }\n\n  private async _doFlush(): Promise<void> {\n    if (this.buffer.length === 0) {\n      return;\n    }\n\n    const batch = this.buffer.splice(0, this.buffer.length);\n\n    try {\n      const response = await fetch(`${this.endpoint}/api/traces`, {\n        method: \"POST\",\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          \"Content-Type\": \"application/json\",\n        },\n        body: JSON.stringify({ traces: batch }),\n      });\n\n      if (!response.ok) {\n        const text = await response.text().catch(() => \"\");\n        console.warn(\n          `AgentLens: Failed to send traces (HTTP ${response.status}): ${text.slice(0, 200)}`,\n        );\n      }\n    } catch (error: unknown) {\n      const message =\n        error instanceof Error ? error.message : String(error);\n      console.warn(`AgentLens: Failed to send traces: ${message}`);\n    }\n  }\n}\n","import type { BatchTransport } from \"./transport.js\";\n\nlet _transport: BatchTransport | null = null;\n\nexport function _setTransport(transport: BatchTransport | null): void {\n  _transport = transport;\n}\n\nexport function _getTransport(): BatchTransport | null {\n  return _transport;\n}\n","import { randomUUID } from \"crypto\";\n\n// ---------------------------------------------------------------------------\n// JSON value type (replaces Prisma.JsonValue for the SDK)\n// ---------------------------------------------------------------------------\n\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n// ---------------------------------------------------------------------------\n// Enums (as const + type union pattern — NO TypeScript enum keyword)\n// ---------------------------------------------------------------------------\n\nexport const TraceStatus = {\n  RUNNING: \"RUNNING\",\n  COMPLETED: \"COMPLETED\",\n  ERROR: \"ERROR\",\n} as const;\nexport type TraceStatus = (typeof TraceStatus)[keyof typeof TraceStatus];\n\nexport const DecisionType = {\n  TOOL_SELECTION: \"TOOL_SELECTION\",\n  ROUTING: \"ROUTING\",\n  RETRY: \"RETRY\",\n  ESCALATION: \"ESCALATION\",\n  MEMORY_RETRIEVAL: \"MEMORY_RETRIEVAL\",\n  PLANNING: \"PLANNING\",\n  CUSTOM: \"CUSTOM\",\n} as const;\nexport type DecisionType = (typeof DecisionType)[keyof typeof DecisionType];\n\nexport const SpanType = {\n  LLM_CALL: \"LLM_CALL\",\n  TOOL_CALL: \"TOOL_CALL\",\n  MEMORY_OP: \"MEMORY_OP\",\n  CHAIN: \"CHAIN\",\n  AGENT: \"AGENT\",\n  CUSTOM: \"CUSTOM\",\n} as const;\nexport type SpanType = (typeof SpanType)[keyof typeof SpanType];\n\nexport const SpanStatus = {\n  RUNNING: \"RUNNING\",\n  COMPLETED: \"COMPLETED\",\n  ERROR: \"ERROR\",\n} as const;\nexport type SpanStatus = (typeof SpanStatus)[keyof typeof SpanStatus];\n\nexport const EventType = {\n  ERROR: \"ERROR\",\n  RETRY: \"RETRY\",\n  FALLBACK: \"FALLBACK\",\n  CONTEXT_OVERFLOW: \"CONTEXT_OVERFLOW\",\n  USER_FEEDBACK: \"USER_FEEDBACK\",\n  CUSTOM: \"CUSTOM\",\n} as const;\nexport type EventType = (typeof EventType)[keyof typeof EventType];\n\n// ---------------------------------------------------------------------------\n// Wire-format interfaces (camelCase, matching POST /api/traces contract)\n// ---------------------------------------------------------------------------\n\nexport interface DecisionPointPayload {\n  id: string;\n  type: DecisionType;\n  chosen: JsonValue;\n  alternatives: JsonValue[];\n  reasoning?: string;\n  contextSnapshot?: JsonValue;\n  durationMs?: number;\n  costUsd?: number;\n  parentSpanId?: string;\n  timestamp: string;\n}\n\nexport interface SpanPayload {\n  id: string;\n  parentSpanId?: string;\n  name: string;\n  type: SpanType;\n  input?: JsonValue;\n  output?: JsonValue;\n  tokenCount?: number;\n  costUsd?: number;\n  durationMs?: number;\n  status: SpanStatus;\n  statusMessage?: string;\n  startedAt: string;\n  endedAt?: string;\n  metadata?: JsonValue;\n}\n\nexport interface EventPayload {\n  id: string;\n  spanId?: string;\n  type: EventType;\n  name: string;\n  metadata?: JsonValue;\n  timestamp: string;\n}\n\nexport interface TracePayload {\n  id: string;\n  name: string;\n  sessionId?: string;\n  status: TraceStatus;\n  tags: string[];\n  metadata?: JsonValue;\n  totalCost?: number;\n  totalTokens?: number;\n  totalDuration?: number;\n  startedAt: string;\n  endedAt?: string;\n  decisionPoints: DecisionPointPayload[];\n  spans: SpanPayload[];\n  events: EventPayload[];\n}\n\n// ---------------------------------------------------------------------------\n// Helper functions\n// ---------------------------------------------------------------------------\n\n/** Generate a v4 UUID. */\nexport function generateId(): string {\n  return randomUUID();\n}\n\n/** Return the current time as an ISO-8601 string. */\nexport function nowISO(): string {\n  return new Date().toISOString();\n}\n","import type {\n  TracePayload,\n  SpanPayload,\n  DecisionPointPayload,\n  EventPayload,\n  JsonValue,\n  TraceStatus,\n  SpanType,\n  SpanStatus,\n  DecisionType,\n  EventType,\n} from \"./models.js\";\nimport {\n  generateId,\n  nowISO,\n  TraceStatus as TraceStatusValues,\n  SpanStatus as SpanStatusValues,\n} from \"./models.js\";\nimport { _getTransport } from \"./_registry.js\";\n\nexport interface TraceBuilderOptions {\n  sessionId?: string;\n  tags?: string[];\n  metadata?: JsonValue;\n}\n\nexport interface AddSpanInput {\n  id?: string;\n  parentSpanId?: string;\n  name: string;\n  type: SpanType;\n  input?: JsonValue;\n  output?: JsonValue;\n  tokenCount?: number;\n  costUsd?: number;\n  durationMs?: number;\n  status?: SpanStatus;\n  statusMessage?: string;\n  startedAt?: string;\n  endedAt?: string;\n  metadata?: JsonValue;\n}\n\nexport interface AddDecisionInput {\n  id?: string;\n  type: DecisionType;\n  chosen: JsonValue;\n  alternatives?: JsonValue[];\n  reasoning?: string;\n  contextSnapshot?: JsonValue;\n  durationMs?: number;\n  costUsd?: number;\n  parentSpanId?: string;\n  timestamp?: string;\n}\n\nexport interface AddEventInput {\n  id?: string;\n  spanId?: string;\n  type: EventType;\n  name: string;\n  metadata?: JsonValue;\n  timestamp?: string;\n}\n\nexport interface EndOptions {\n  status?: TraceStatus;\n  metadata?: JsonValue;\n  totalCost?: number;\n  totalTokens?: number;\n}\n\nexport class TraceBuilder {\n  private readonly trace: TracePayload;\n  private readonly startMs: number;\n\n  constructor(name: string, options?: TraceBuilderOptions) {\n    this.startMs = Date.now();\n    this.trace = {\n      id: generateId(),\n      name,\n      sessionId: options?.sessionId,\n      status: TraceStatusValues.RUNNING,\n      tags: options?.tags ?? [],\n      metadata: options?.metadata,\n      startedAt: nowISO(),\n      decisionPoints: [],\n      spans: [],\n      events: [],\n    };\n  }\n\n  addSpan(input: AddSpanInput): string {\n    const id = input.id ?? generateId();\n    const span: SpanPayload = {\n      id,\n      parentSpanId: input.parentSpanId,\n      name: input.name,\n      type: input.type,\n      input: input.input,\n      output: input.output,\n      tokenCount: input.tokenCount,\n      costUsd: input.costUsd,\n      durationMs: input.durationMs,\n      status: input.status ?? SpanStatusValues.RUNNING,\n      statusMessage: input.statusMessage,\n      startedAt: input.startedAt ?? nowISO(),\n      endedAt: input.endedAt,\n      metadata: input.metadata,\n    };\n    this.trace.spans.push(span);\n    return id;\n  }\n\n  addDecision(input: AddDecisionInput): string {\n    const id = input.id ?? generateId();\n    const decision: DecisionPointPayload = {\n      id,\n      type: input.type,\n      chosen: input.chosen,\n      alternatives: input.alternatives ?? [],\n      reasoning: input.reasoning,\n      contextSnapshot: input.contextSnapshot,\n      durationMs: input.durationMs,\n      costUsd: input.costUsd,\n      parentSpanId: input.parentSpanId,\n      timestamp: input.timestamp ?? nowISO(),\n    };\n    this.trace.decisionPoints.push(decision);\n    return id;\n  }\n\n  addEvent(input: AddEventInput): string {\n    const id = input.id ?? generateId();\n    const event: EventPayload = {\n      id,\n      spanId: input.spanId,\n      type: input.type,\n      name: input.name,\n      metadata: input.metadata,\n      timestamp: input.timestamp ?? nowISO(),\n    };\n    this.trace.events.push(event);\n    return id;\n  }\n\n  setStatus(status: TraceStatus): this {\n    this.trace.status = status;\n    return this;\n  }\n\n  setMetadata(metadata: JsonValue): this {\n    this.trace.metadata = metadata;\n    return this;\n  }\n\n  toPayload(): TracePayload {\n    return { ...this.trace };\n  }\n\n  end(options?: EndOptions): TracePayload {\n    const endedAt = nowISO();\n    this.trace.endedAt = endedAt;\n    this.trace.totalDuration = Date.now() - this.startMs;\n    this.trace.status =\n      options?.status ?? TraceStatusValues.COMPLETED;\n\n    if (options?.metadata !== undefined) {\n      this.trace.metadata = options.metadata;\n    }\n    if (options?.totalCost !== undefined) {\n      this.trace.totalCost = options.totalCost;\n    }\n    if (options?.totalTokens !== undefined) {\n      this.trace.totalTokens = options.totalTokens;\n    }\n\n    const transport = _getTransport();\n    if (transport) {\n      transport.add(this.trace);\n    }\n\n    return { ...this.trace };\n  }\n}\n","import type { DecisionPointPayload, DecisionType, JsonValue } from \"./models.js\";\nimport { generateId, nowISO } from \"./models.js\";\n\nexport interface CreateDecisionInput {\n  type: DecisionType;\n  chosen: JsonValue;\n  alternatives?: JsonValue[];\n  reasoning?: string;\n  contextSnapshot?: JsonValue;\n  durationMs?: number;\n  costUsd?: number;\n  parentSpanId?: string;\n  timestamp?: string;\n}\n\nexport function createDecision(input: CreateDecisionInput): DecisionPointPayload {\n  return {\n    id: generateId(),\n    type: input.type,\n    chosen: input.chosen,\n    alternatives: input.alternatives ?? [],\n    reasoning: input.reasoning,\n    contextSnapshot: input.contextSnapshot,\n    durationMs: input.durationMs,\n    costUsd: input.costUsd,\n    parentSpanId: input.parentSpanId,\n    timestamp: input.timestamp ?? nowISO(),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,205 @@
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+declare const TraceStatus: {
+    readonly RUNNING: "RUNNING";
+    readonly COMPLETED: "COMPLETED";
+    readonly ERROR: "ERROR";
+};
+type TraceStatus = (typeof TraceStatus)[keyof typeof TraceStatus];
+declare const DecisionType: {
+    readonly TOOL_SELECTION: "TOOL_SELECTION";
+    readonly ROUTING: "ROUTING";
+    readonly RETRY: "RETRY";
+    readonly ESCALATION: "ESCALATION";
+    readonly MEMORY_RETRIEVAL: "MEMORY_RETRIEVAL";
+    readonly PLANNING: "PLANNING";
+    readonly CUSTOM: "CUSTOM";
+};
+type DecisionType = (typeof DecisionType)[keyof typeof DecisionType];
+declare const SpanType: {
+    readonly LLM_CALL: "LLM_CALL";
+    readonly TOOL_CALL: "TOOL_CALL";
+    readonly MEMORY_OP: "MEMORY_OP";
+    readonly CHAIN: "CHAIN";
+    readonly AGENT: "AGENT";
+    readonly CUSTOM: "CUSTOM";
+};
+type SpanType = (typeof SpanType)[keyof typeof SpanType];
+declare const SpanStatus: {
+    readonly RUNNING: "RUNNING";
+    readonly COMPLETED: "COMPLETED";
+    readonly ERROR: "ERROR";
+};
+type SpanStatus = (typeof SpanStatus)[keyof typeof SpanStatus];
+declare const EventType: {
+    readonly ERROR: "ERROR";
+    readonly RETRY: "RETRY";
+    readonly FALLBACK: "FALLBACK";
+    readonly CONTEXT_OVERFLOW: "CONTEXT_OVERFLOW";
+    readonly USER_FEEDBACK: "USER_FEEDBACK";
+    readonly CUSTOM: "CUSTOM";
+};
+type EventType = (typeof EventType)[keyof typeof EventType];
+interface DecisionPointPayload {
+    id: string;
+    type: DecisionType;
+    chosen: JsonValue;
+    alternatives: JsonValue[];
+    reasoning?: string;
+    contextSnapshot?: JsonValue;
+    durationMs?: number;
+    costUsd?: number;
+    parentSpanId?: string;
+    timestamp: string;
+}
+interface SpanPayload {
+    id: string;
+    parentSpanId?: string;
+    name: string;
+    type: SpanType;
+    input?: JsonValue;
+    output?: JsonValue;
+    tokenCount?: number;
+    costUsd?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    statusMessage?: string;
+    startedAt: string;
+    endedAt?: string;
+    metadata?: JsonValue;
+}
+interface EventPayload {
+    id: string;
+    spanId?: string;
+    type: EventType;
+    name: string;
+    metadata?: JsonValue;
+    timestamp: string;
+}
+interface TracePayload {
+    id: string;
+    name: string;
+    sessionId?: string;
+    status: TraceStatus;
+    tags: string[];
+    metadata?: JsonValue;
+    totalCost?: number;
+    totalTokens?: number;
+    totalDuration?: number;
+    startedAt: string;
+    endedAt?: string;
+    decisionPoints: DecisionPointPayload[];
+    spans: SpanPayload[];
+    events: EventPayload[];
+}
+/** Generate a v4 UUID. */
+declare function generateId(): string;
+/** Return the current time as an ISO-8601 string. */
+declare function nowISO(): string;
+
+interface BatchTransportOptions {
+    apiKey: string;
+    endpoint: string;
+    maxBatchSize?: number;
+    flushInterval?: number;
+}
+declare class BatchTransport {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly maxBatchSize;
+    private readonly flushInterval;
+    private buffer;
+    private timer;
+    constructor(options: BatchTransportOptions);
+    add(trace: TracePayload): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private _doFlush;
+}
+
+interface TraceBuilderOptions {
+    sessionId?: string;
+    tags?: string[];
+    metadata?: JsonValue;
+}
+interface AddSpanInput {
+    id?: string;
+    parentSpanId?: string;
+    name: string;
+    type: SpanType;
+    input?: JsonValue;
+    output?: JsonValue;
+    tokenCount?: number;
+    costUsd?: number;
+    durationMs?: number;
+    status?: SpanStatus;
+    statusMessage?: string;
+    startedAt?: string;
+    endedAt?: string;
+    metadata?: JsonValue;
+}
+interface AddDecisionInput {
+    id?: string;
+    type: DecisionType;
+    chosen: JsonValue;
+    alternatives?: JsonValue[];
+    reasoning?: string;
+    contextSnapshot?: JsonValue;
+    durationMs?: number;
+    costUsd?: number;
+    parentSpanId?: string;
+    timestamp?: string;
+}
+interface AddEventInput {
+    id?: string;
+    spanId?: string;
+    type: EventType;
+    name: string;
+    metadata?: JsonValue;
+    timestamp?: string;
+}
+interface EndOptions {
+    status?: TraceStatus;
+    metadata?: JsonValue;
+    totalCost?: number;
+    totalTokens?: number;
+}
+declare class TraceBuilder {
+    private readonly trace;
+    private readonly startMs;
+    constructor(name: string, options?: TraceBuilderOptions);
+    addSpan(input: AddSpanInput): string;
+    addDecision(input: AddDecisionInput): string;
+    addEvent(input: AddEventInput): string;
+    setStatus(status: TraceStatus): this;
+    setMetadata(metadata: JsonValue): this;
+    toPayload(): TracePayload;
+    end(options?: EndOptions): TracePayload;
+}
+
+interface CreateDecisionInput {
+    type: DecisionType;
+    chosen: JsonValue;
+    alternatives?: JsonValue[];
+    reasoning?: string;
+    contextSnapshot?: JsonValue;
+    durationMs?: number;
+    costUsd?: number;
+    parentSpanId?: string;
+    timestamp?: string;
+}
+declare function createDecision(input: CreateDecisionInput): DecisionPointPayload;
+
+interface InitOptions {
+    apiKey: string;
+    endpoint?: string;
+    maxBatchSize?: number;
+    flushInterval?: number;
+}
+declare function init(options: InitOptions): void;
+declare function shutdown(): Promise<void>;
+declare function getClient(): BatchTransport | null;
+declare function flush(): Promise<void>;
+
+export { type AddDecisionInput, type AddEventInput, type AddSpanInput, BatchTransport, type BatchTransportOptions, type CreateDecisionInput, type DecisionPointPayload, DecisionType, type EndOptions, type EventPayload, EventType, type InitOptions, type JsonValue, type SpanPayload, SpanStatus, SpanType, TraceBuilder, type TraceBuilderOptions, type TracePayload, TraceStatus, createDecision, flush, generateId, getClient, init, nowISO, shutdown };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+declare const TraceStatus: {
+    readonly RUNNING: "RUNNING";
+    readonly COMPLETED: "COMPLETED";
+    readonly ERROR: "ERROR";
+};
+type TraceStatus = (typeof TraceStatus)[keyof typeof TraceStatus];
+declare const DecisionType: {
+    readonly TOOL_SELECTION: "TOOL_SELECTION";
+    readonly ROUTING: "ROUTING";
+    readonly RETRY: "RETRY";
+    readonly ESCALATION: "ESCALATION";
+    readonly MEMORY_RETRIEVAL: "MEMORY_RETRIEVAL";
+    readonly PLANNING: "PLANNING";
+    readonly CUSTOM: "CUSTOM";
+};
+type DecisionType = (typeof DecisionType)[keyof typeof DecisionType];
+declare const SpanType: {
+    readonly LLM_CALL: "LLM_CALL";
+    readonly TOOL_CALL: "TOOL_CALL";
+    readonly MEMORY_OP: "MEMORY_OP";
+    readonly CHAIN: "CHAIN";
+    readonly AGENT: "AGENT";
+    readonly CUSTOM: "CUSTOM";
+};
+type SpanType = (typeof SpanType)[keyof typeof SpanType];
+declare const SpanStatus: {
+    readonly RUNNING: "RUNNING";
+    readonly COMPLETED: "COMPLETED";
+    readonly ERROR: "ERROR";
+};
+type SpanStatus = (typeof SpanStatus)[keyof typeof SpanStatus];
+declare const EventType: {
+    readonly ERROR: "ERROR";
+    readonly RETRY: "RETRY";
+    readonly FALLBACK: "FALLBACK";
+    readonly CONTEXT_OVERFLOW: "CONTEXT_OVERFLOW";
+    readonly USER_FEEDBACK: "USER_FEEDBACK";
+    readonly CUSTOM: "CUSTOM";
+};
+type EventType = (typeof EventType)[keyof typeof EventType];
+interface DecisionPointPayload {
+    id: string;
+    type: DecisionType;
+    chosen: JsonValue;
+    alternatives: JsonValue[];
+    reasoning?: string;
+    contextSnapshot?: JsonValue;
+    durationMs?: number;
+    costUsd?: number;
+    parentSpanId?: string;
+    timestamp: string;
+}
+interface SpanPayload {
+    id: string;
+    parentSpanId?: string;
+    name: string;
+    type: SpanType;
+    input?: JsonValue;
+    output?: JsonValue;
+    tokenCount?: number;
+    costUsd?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    statusMessage?: string;
+    startedAt: string;
+    endedAt?: string;
+    metadata?: JsonValue;
+}
+interface EventPayload {
+    id: string;
+    spanId?: string;
+    type: EventType;
+    name: string;
+    metadata?: JsonValue;
+    timestamp: string;
+}
+interface TracePayload {
+    id: string;
+    name: string;
+    sessionId?: string;
+    status: TraceStatus;
+    tags: string[];
+    metadata?: JsonValue;
+    totalCost?: number;
+    totalTokens?: number;
+    totalDuration?: number;
+    startedAt: string;
+    endedAt?: string;
+    decisionPoints: DecisionPointPayload[];
+    spans: SpanPayload[];
+    events: EventPayload[];
+}
+/** Generate a v4 UUID. */
+declare function generateId(): string;
+/** Return the current time as an ISO-8601 string. */
+declare function nowISO(): string;
+
+interface BatchTransportOptions {
+    apiKey: string;
+    endpoint: string;
+    maxBatchSize?: number;
+    flushInterval?: number;
+}
+declare class BatchTransport {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly maxBatchSize;
+    private readonly flushInterval;
+    private buffer;
+    private timer;
+    constructor(options: BatchTransportOptions);
+    add(trace: TracePayload): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private _doFlush;
+}
+
+interface TraceBuilderOptions {
+    sessionId?: string;
+    tags?: string[];
+    metadata?: JsonValue;
+}
+interface AddSpanInput {
+    id?: string;
+    parentSpanId?: string;
+    name: string;
+    type: SpanType;
+    input?: JsonValue;
+    output?: JsonValue;
+    tokenCount?: number;
+    costUsd?: number;
+    durationMs?: number;
+    status?: SpanStatus;
+    statusMessage?: string;
+    startedAt?: string;
+    endedAt?: string;
+    metadata?: JsonValue;
+}
+interface AddDecisionInput {
+    id?: string;
+    type: DecisionType;
+    chosen: JsonValue;
+    alternatives?: JsonValue[];
+    reasoning?: string;
+    contextSnapshot?: JsonValue;
+    durationMs?: number;
+    costUsd?: number;
+    parentSpanId?: string;
+    timestamp?: string;
+}
+interface AddEventInput {
+    id?: string;
+    spanId?: string;
+    type: EventType;
+    name: string;
+    metadata?: JsonValue;
+    timestamp?: string;
+}
+interface EndOptions {
+    status?: TraceStatus;
+    metadata?: JsonValue;
+    totalCost?: number;
+    totalTokens?: number;
+}
+declare class TraceBuilder {
+    private readonly trace;
+    private readonly startMs;
+    constructor(name: string, options?: TraceBuilderOptions);
+    addSpan(input: AddSpanInput): string;
+    addDecision(input: AddDecisionInput): string;
+    addEvent(input: AddEventInput): string;
+    setStatus(status: TraceStatus): this;
+    setMetadata(metadata: JsonValue): this;
+    toPayload(): TracePayload;
+    end(options?: EndOptions): TracePayload;
+}
+
+interface CreateDecisionInput {
+    type: DecisionType;
+    chosen: JsonValue;
+    alternatives?: JsonValue[];
+    reasoning?: string;
+    contextSnapshot?: JsonValue;
+    durationMs?: number;
+    costUsd?: number;
+    parentSpanId?: string;
+    timestamp?: string;
+}
+declare function createDecision(input: CreateDecisionInput): DecisionPointPayload;
+
+interface InitOptions {
+    apiKey: string;
+    endpoint?: string;
+    maxBatchSize?: number;
+    flushInterval?: number;
+}
+declare function init(options: InitOptions): void;
+declare function shutdown(): Promise<void>;
+declare function getClient(): BatchTransport | null;
+declare function flush(): Promise<void>;
+
+export { type AddDecisionInput, type AddEventInput, type AddSpanInput, BatchTransport, type BatchTransportOptions, type CreateDecisionInput, type DecisionPointPayload, DecisionType, type EndOptions, type EventPayload, EventType, type InitOptions, type JsonValue, type SpanPayload, SpanStatus, SpanType, TraceBuilder, type TraceBuilderOptions, type TracePayload, TraceStatus, createDecision, flush, generateId, getClient, init, nowISO, shutdown };

package/dist/index.js

@@ -0,0 +1,280 @@
+// src/transport.ts
+var BatchTransport = class {
+  apiKey;
+  endpoint;
+  maxBatchSize;
+  flushInterval;
+  buffer = [];
+  timer = null;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.endpoint = options.endpoint.replace(/\/+$/, "");
+    this.maxBatchSize = options.maxBatchSize ?? 10;
+    this.flushInterval = options.flushInterval ?? 5e3;
+    this.timer = setInterval(() => {
+      void this._doFlush();
+    }, this.flushInterval);
+  }
+  add(trace) {
+    this.buffer.push(trace);
+    if (this.buffer.length >= this.maxBatchSize) {
+      void this._doFlush();
+    }
+  }
+  async flush() {
+    await this._doFlush();
+  }
+  async shutdown() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this._doFlush();
+  }
+  async _doFlush() {
+    if (this.buffer.length === 0) {
+      return;
+    }
+    const batch = this.buffer.splice(0, this.buffer.length);
+    try {
+      const response = await fetch(`${this.endpoint}/api/traces`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ traces: batch })
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        console.warn(
+          `AgentLens: Failed to send traces (HTTP ${response.status}): ${text.slice(0, 200)}`
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`AgentLens: Failed to send traces: ${message}`);
+    }
+  }
+};
+
+// src/_registry.ts
+var _transport = null;
+function _setTransport(transport) {
+  _transport = transport;
+}
+function _getTransport() {
+  return _transport;
+}
+
+// src/models.ts
+import { randomUUID } from "crypto";
+var TraceStatus = {
+  RUNNING: "RUNNING",
+  COMPLETED: "COMPLETED",
+  ERROR: "ERROR"
+};
+var DecisionType = {
+  TOOL_SELECTION: "TOOL_SELECTION",
+  ROUTING: "ROUTING",
+  RETRY: "RETRY",
+  ESCALATION: "ESCALATION",
+  MEMORY_RETRIEVAL: "MEMORY_RETRIEVAL",
+  PLANNING: "PLANNING",
+  CUSTOM: "CUSTOM"
+};
+var SpanType = {
+  LLM_CALL: "LLM_CALL",
+  TOOL_CALL: "TOOL_CALL",
+  MEMORY_OP: "MEMORY_OP",
+  CHAIN: "CHAIN",
+  AGENT: "AGENT",
+  CUSTOM: "CUSTOM"
+};
+var SpanStatus = {
+  RUNNING: "RUNNING",
+  COMPLETED: "COMPLETED",
+  ERROR: "ERROR"
+};
+var EventType = {
+  ERROR: "ERROR",
+  RETRY: "RETRY",
+  FALLBACK: "FALLBACK",
+  CONTEXT_OVERFLOW: "CONTEXT_OVERFLOW",
+  USER_FEEDBACK: "USER_FEEDBACK",
+  CUSTOM: "CUSTOM"
+};
+function generateId() {
+  return randomUUID();
+}
+function nowISO() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/trace.ts
+var TraceBuilder = class {
+  trace;
+  startMs;
+  constructor(name, options) {
+    this.startMs = Date.now();
+    this.trace = {
+      id: generateId(),
+      name,
+      sessionId: options?.sessionId,
+      status: TraceStatus.RUNNING,
+      tags: options?.tags ?? [],
+      metadata: options?.metadata,
+      startedAt: nowISO(),
+      decisionPoints: [],
+      spans: [],
+      events: []
+    };
+  }
+  addSpan(input) {
+    const id = input.id ?? generateId();
+    const span = {
+      id,
+      parentSpanId: input.parentSpanId,
+      name: input.name,
+      type: input.type,
+      input: input.input,
+      output: input.output,
+      tokenCount: input.tokenCount,
+      costUsd: input.costUsd,
+      durationMs: input.durationMs,
+      status: input.status ?? SpanStatus.RUNNING,
+      statusMessage: input.statusMessage,
+      startedAt: input.startedAt ?? nowISO(),
+      endedAt: input.endedAt,
+      metadata: input.metadata
+    };
+    this.trace.spans.push(span);
+    return id;
+  }
+  addDecision(input) {
+    const id = input.id ?? generateId();
+    const decision = {
+      id,
+      type: input.type,
+      chosen: input.chosen,
+      alternatives: input.alternatives ?? [],
+      reasoning: input.reasoning,
+      contextSnapshot: input.contextSnapshot,
+      durationMs: input.durationMs,
+      costUsd: input.costUsd,
+      parentSpanId: input.parentSpanId,
+      timestamp: input.timestamp ?? nowISO()
+    };
+    this.trace.decisionPoints.push(decision);
+    return id;
+  }
+  addEvent(input) {
+    const id = input.id ?? generateId();
+    const event = {
+      id,
+      spanId: input.spanId,
+      type: input.type,
+      name: input.name,
+      metadata: input.metadata,
+      timestamp: input.timestamp ?? nowISO()
+    };
+    this.trace.events.push(event);
+    return id;
+  }
+  setStatus(status) {
+    this.trace.status = status;
+    return this;
+  }
+  setMetadata(metadata) {
+    this.trace.metadata = metadata;
+    return this;
+  }
+  toPayload() {
+    return { ...this.trace };
+  }
+  end(options) {
+    const endedAt = nowISO();
+    this.trace.endedAt = endedAt;
+    this.trace.totalDuration = Date.now() - this.startMs;
+    this.trace.status = options?.status ?? TraceStatus.COMPLETED;
+    if (options?.metadata !== void 0) {
+      this.trace.metadata = options.metadata;
+    }
+    if (options?.totalCost !== void 0) {
+      this.trace.totalCost = options.totalCost;
+    }
+    if (options?.totalTokens !== void 0) {
+      this.trace.totalTokens = options.totalTokens;
+    }
+    const transport = _getTransport();
+    if (transport) {
+      transport.add(this.trace);
+    }
+    return { ...this.trace };
+  }
+};
+
+// src/decision.ts
+function createDecision(input) {
+  return {
+    id: generateId(),
+    type: input.type,
+    chosen: input.chosen,
+    alternatives: input.alternatives ?? [],
+    reasoning: input.reasoning,
+    contextSnapshot: input.contextSnapshot,
+    durationMs: input.durationMs,
+    costUsd: input.costUsd,
+    parentSpanId: input.parentSpanId,
+    timestamp: input.timestamp ?? nowISO()
+  };
+}
+
+// src/index.ts
+function init(options) {
+  const existing = _getTransport();
+  if (existing) {
+    void existing.shutdown();
+  }
+  _setTransport(
+    new BatchTransport({
+      apiKey: options.apiKey,
+      endpoint: options.endpoint ?? "https://agentlens.vectry.tech",
+      maxBatchSize: options.maxBatchSize,
+      flushInterval: options.flushInterval
+    })
+  );
+}
+async function shutdown() {
+  const transport = _getTransport();
+  if (transport) {
+    await transport.shutdown();
+    _setTransport(null);
+  }
+}
+function getClient() {
+  return _getTransport();
+}
+async function flush() {
+  const transport = _getTransport();
+  if (transport) {
+    await transport.flush();
+  }
+}
+export {
+  BatchTransport,
+  DecisionType,
+  EventType,
+  SpanStatus,
+  SpanType,
+  TraceBuilder,
+  TraceStatus,
+  createDecision,
+  flush,
+  generateId,
+  getClient,
+  init,
+  nowISO,
+  shutdown
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transport.ts","../src/_registry.ts","../src/models.ts","../src/trace.ts","../src/decision.ts","../src/index.ts"],"sourcesContent":["import type { TracePayload } from \"./models.js\";\n\nexport interface BatchTransportOptions {\n  apiKey: string;\n  endpoint: string;\n  maxBatchSize?: number;\n  flushInterval?: number;\n}\n\nexport class BatchTransport {\n  private readonly apiKey: string;\n  private readonly endpoint: string;\n  private readonly maxBatchSize: number;\n  private readonly flushInterval: number;\n  private buffer: TracePayload[] = [];\n  private timer: ReturnType<typeof setInterval> | null = null;\n\n  constructor(options: BatchTransportOptions) {\n    this.apiKey = options.apiKey;\n    this.endpoint = options.endpoint.replace(/\\/+$/, \"\");\n    this.maxBatchSize = options.maxBatchSize ?? 10;\n    this.flushInterval = options.flushInterval ?? 5_000;\n\n    this.timer = setInterval(() => {\n      void this._doFlush();\n    }, this.flushInterval);\n  }\n\n  add(trace: TracePayload): void {\n    this.buffer.push(trace);\n    if (this.buffer.length >= this.maxBatchSize) {\n      void this._doFlush();\n    }\n  }\n\n  async flush(): Promise<void> {\n    await this._doFlush();\n  }\n\n  async shutdown(): Promise<void> {\n    if (this.timer !== null) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n    await this._doFlush();\n  }\n\n  private async _doFlush(): Promise<void> {\n    if (this.buffer.length === 0) {\n      return;\n    }\n\n    const batch = this.buffer.splice(0, this.buffer.length);\n\n    try {\n      const response = await fetch(`${this.endpoint}/api/traces`, {\n        method: \"POST\",\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          \"Content-Type\": \"application/json\",\n        },\n        body: JSON.stringify({ traces: batch }),\n      });\n\n      if (!response.ok) {\n        const text = await response.text().catch(() => \"\");\n        console.warn(\n          `AgentLens: Failed to send traces (HTTP ${response.status}): ${text.slice(0, 200)}`,\n        );\n      }\n    } catch (error: unknown) {\n      const message =\n        error instanceof Error ? error.message : String(error);\n      console.warn(`AgentLens: Failed to send traces: ${message}`);\n    }\n  }\n}\n","import type { BatchTransport } from \"./transport.js\";\n\nlet _transport: BatchTransport | null = null;\n\nexport function _setTransport(transport: BatchTransport | null): void {\n  _transport = transport;\n}\n\nexport function _getTransport(): BatchTransport | null {\n  return _transport;\n}\n","import { randomUUID } from \"crypto\";\n\n// ---------------------------------------------------------------------------\n// JSON value type (replaces Prisma.JsonValue for the SDK)\n// ---------------------------------------------------------------------------\n\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\n// ---------------------------------------------------------------------------\n// Enums (as const + type union pattern — NO TypeScript enum keyword)\n// ---------------------------------------------------------------------------\n\nexport const TraceStatus = {\n  RUNNING: \"RUNNING\",\n  COMPLETED: \"COMPLETED\",\n  ERROR: \"ERROR\",\n} as const;\nexport type TraceStatus = (typeof TraceStatus)[keyof typeof TraceStatus];\n\nexport const DecisionType = {\n  TOOL_SELECTION: \"TOOL_SELECTION\",\n  ROUTING: \"ROUTING\",\n  RETRY: \"RETRY\",\n  ESCALATION: \"ESCALATION\",\n  MEMORY_RETRIEVAL: \"MEMORY_RETRIEVAL\",\n  PLANNING: \"PLANNING\",\n  CUSTOM: \"CUSTOM\",\n} as const;\nexport type DecisionType = (typeof DecisionType)[keyof typeof DecisionType];\n\nexport const SpanType = {\n  LLM_CALL: \"LLM_CALL\",\n  TOOL_CALL: \"TOOL_CALL\",\n  MEMORY_OP: \"MEMORY_OP\",\n  CHAIN: \"CHAIN\",\n  AGENT: \"AGENT\",\n  CUSTOM: \"CUSTOM\",\n} as const;\nexport type SpanType = (typeof SpanType)[keyof typeof SpanType];\n\nexport const SpanStatus = {\n  RUNNING: \"RUNNING\",\n  COMPLETED: \"COMPLETED\",\n  ERROR: \"ERROR\",\n} as const;\nexport type SpanStatus = (typeof SpanStatus)[keyof typeof SpanStatus];\n\nexport const EventType = {\n  ERROR: \"ERROR\",\n  RETRY: \"RETRY\",\n  FALLBACK: \"FALLBACK\",\n  CONTEXT_OVERFLOW: \"CONTEXT_OVERFLOW\",\n  USER_FEEDBACK: \"USER_FEEDBACK\",\n  CUSTOM: \"CUSTOM\",\n} as const;\nexport type EventType = (typeof EventType)[keyof typeof EventType];\n\n// ---------------------------------------------------------------------------\n// Wire-format interfaces (camelCase, matching POST /api/traces contract)\n// ---------------------------------------------------------------------------\n\nexport interface DecisionPointPayload {\n  id: string;\n  type: DecisionType;\n  chosen: JsonValue;\n  alternatives: JsonValue[];\n  reasoning?: string;\n  contextSnapshot?: JsonValue;\n  durationMs?: number;\n  costUsd?: number;\n  parentSpanId?: string;\n  timestamp: string;\n}\n\nexport interface SpanPayload {\n  id: string;\n  parentSpanId?: string;\n  name: string;\n  type: SpanType;\n  input?: JsonValue;\n  output?: JsonValue;\n  tokenCount?: number;\n  costUsd?: number;\n  durationMs?: number;\n  status: SpanStatus;\n  statusMessage?: string;\n  startedAt: string;\n  endedAt?: string;\n  metadata?: JsonValue;\n}\n\nexport interface EventPayload {\n  id: string;\n  spanId?: string;\n  type: EventType;\n  name: string;\n  metadata?: JsonValue;\n  timestamp: string;\n}\n\nexport interface TracePayload {\n  id: string;\n  name: string;\n  sessionId?: string;\n  status: TraceStatus;\n  tags: string[];\n  metadata?: JsonValue;\n  totalCost?: number;\n  totalTokens?: number;\n  totalDuration?: number;\n  startedAt: string;\n  endedAt?: string;\n  decisionPoints: DecisionPointPayload[];\n  spans: SpanPayload[];\n  events: EventPayload[];\n}\n\n// ---------------------------------------------------------------------------\n// Helper functions\n// ---------------------------------------------------------------------------\n\n/** Generate a v4 UUID. */\nexport function generateId(): string {\n  return randomUUID();\n}\n\n/** Return the current time as an ISO-8601 string. */\nexport function nowISO(): string {\n  return new Date().toISOString();\n}\n","import type {\n  TracePayload,\n  SpanPayload,\n  DecisionPointPayload,\n  EventPayload,\n  JsonValue,\n  TraceStatus,\n  SpanType,\n  SpanStatus,\n  DecisionType,\n  EventType,\n} from \"./models.js\";\nimport {\n  generateId,\n  nowISO,\n  TraceStatus as TraceStatusValues,\n  SpanStatus as SpanStatusValues,\n} from \"./models.js\";\nimport { _getTransport } from \"./_registry.js\";\n\nexport interface TraceBuilderOptions {\n  sessionId?: string;\n  tags?: string[];\n  metadata?: JsonValue;\n}\n\nexport interface AddSpanInput {\n  id?: string;\n  parentSpanId?: string;\n  name: string;\n  type: SpanType;\n  input?: JsonValue;\n  output?: JsonValue;\n  tokenCount?: number;\n  costUsd?: number;\n  durationMs?: number;\n  status?: SpanStatus;\n  statusMessage?: string;\n  startedAt?: string;\n  endedAt?: string;\n  metadata?: JsonValue;\n}\n\nexport interface AddDecisionInput {\n  id?: string;\n  type: DecisionType;\n  chosen: JsonValue;\n  alternatives?: JsonValue[];\n  reasoning?: string;\n  contextSnapshot?: JsonValue;\n  durationMs?: number;\n  costUsd?: number;\n  parentSpanId?: string;\n  timestamp?: string;\n}\n\nexport interface AddEventInput {\n  id?: string;\n  spanId?: string;\n  type: EventType;\n  name: string;\n  metadata?: JsonValue;\n  timestamp?: string;\n}\n\nexport interface EndOptions {\n  status?: TraceStatus;\n  metadata?: JsonValue;\n  totalCost?: number;\n  totalTokens?: number;\n}\n\nexport class TraceBuilder {\n  private readonly trace: TracePayload;\n  private readonly startMs: number;\n\n  constructor(name: string, options?: TraceBuilderOptions) {\n    this.startMs = Date.now();\n    this.trace = {\n      id: generateId(),\n      name,\n      sessionId: options?.sessionId,\n      status: TraceStatusValues.RUNNING,\n      tags: options?.tags ?? [],\n      metadata: options?.metadata,\n      startedAt: nowISO(),\n      decisionPoints: [],\n      spans: [],\n      events: [],\n    };\n  }\n\n  addSpan(input: AddSpanInput): string {\n    const id = input.id ?? generateId();\n    const span: SpanPayload = {\n      id,\n      parentSpanId: input.parentSpanId,\n      name: input.name,\n      type: input.type,\n      input: input.input,\n      output: input.output,\n      tokenCount: input.tokenCount,\n      costUsd: input.costUsd,\n      durationMs: input.durationMs,\n      status: input.status ?? SpanStatusValues.RUNNING,\n      statusMessage: input.statusMessage,\n      startedAt: input.startedAt ?? nowISO(),\n      endedAt: input.endedAt,\n      metadata: input.metadata,\n    };\n    this.trace.spans.push(span);\n    return id;\n  }\n\n  addDecision(input: AddDecisionInput): string {\n    const id = input.id ?? generateId();\n    const decision: DecisionPointPayload = {\n      id,\n      type: input.type,\n      chosen: input.chosen,\n      alternatives: input.alternatives ?? [],\n      reasoning: input.reasoning,\n      contextSnapshot: input.contextSnapshot,\n      durationMs: input.durationMs,\n      costUsd: input.costUsd,\n      parentSpanId: input.parentSpanId,\n      timestamp: input.timestamp ?? nowISO(),\n    };\n    this.trace.decisionPoints.push(decision);\n    return id;\n  }\n\n  addEvent(input: AddEventInput): string {\n    const id = input.id ?? generateId();\n    const event: EventPayload = {\n      id,\n      spanId: input.spanId,\n      type: input.type,\n      name: input.name,\n      metadata: input.metadata,\n      timestamp: input.timestamp ?? nowISO(),\n    };\n    this.trace.events.push(event);\n    return id;\n  }\n\n  setStatus(status: TraceStatus): this {\n    this.trace.status = status;\n    return this;\n  }\n\n  setMetadata(metadata: JsonValue): this {\n    this.trace.metadata = metadata;\n    return this;\n  }\n\n  toPayload(): TracePayload {\n    return { ...this.trace };\n  }\n\n  end(options?: EndOptions): TracePayload {\n    const endedAt = nowISO();\n    this.trace.endedAt = endedAt;\n    this.trace.totalDuration = Date.now() - this.startMs;\n    this.trace.status =\n      options?.status ?? TraceStatusValues.COMPLETED;\n\n    if (options?.metadata !== undefined) {\n      this.trace.metadata = options.metadata;\n    }\n    if (options?.totalCost !== undefined) {\n      this.trace.totalCost = options.totalCost;\n    }\n    if (options?.totalTokens !== undefined) {\n      this.trace.totalTokens = options.totalTokens;\n    }\n\n    const transport = _getTransport();\n    if (transport) {\n      transport.add(this.trace);\n    }\n\n    return { ...this.trace };\n  }\n}\n","import type { DecisionPointPayload, DecisionType, JsonValue } from \"./models.js\";\nimport { generateId, nowISO } from \"./models.js\";\n\nexport interface CreateDecisionInput {\n  type: DecisionType;\n  chosen: JsonValue;\n  alternatives?: JsonValue[];\n  reasoning?: string;\n  contextSnapshot?: JsonValue;\n  durationMs?: number;\n  costUsd?: number;\n  parentSpanId?: string;\n  timestamp?: string;\n}\n\nexport function createDecision(input: CreateDecisionInput): DecisionPointPayload {\n  return {\n    id: generateId(),\n    type: input.type,\n    chosen: input.chosen,\n    alternatives: input.alternatives ?? [],\n    reasoning: input.reasoning,\n    contextSnapshot: input.contextSnapshot,\n    durationMs: input.durationMs,\n    costUsd: input.costUsd,\n    parentSpanId: input.parentSpanId,\n    timestamp: input.timestamp ?? nowISO(),\n  };\n}\n","import { BatchTransport } from \"./transport.js\";\nimport { _setTransport, _getTransport } from \"./_registry.js\";\n\nexport interface InitOptions {\n  apiKey: string;\n  endpoint?: string;\n  maxBatchSize?: number;\n  flushInterval?: number;\n}\n\nexport function init(options: InitOptions): void {\n  const existing = _getTransport();\n  if (existing) {\n    void existing.shutdown();\n  }\n  _setTransport(\n    new BatchTransport({\n      apiKey: options.apiKey,\n      endpoint: options.endpoint ?? \"https://agentlens.vectry.tech\",\n      maxBatchSize: options.maxBatchSize,\n      flushInterval: options.flushInterval,\n    }),\n  );\n}\n\nexport async function shutdown(): Promise<void> {\n  const transport = _getTransport();\n  if (transport) {\n    await transport.shutdown();\n    _setTransport(null);\n  }\n}\n\nexport function getClient(): BatchTransport | null {\n  return _getTransport();\n}\n\nexport async function flush(): Promise<void> {\n  const transport = _getTransport();\n  if (transport) {\n    await transport.flush();\n  }\n}\n\nexport {\n  TraceStatus,\n  DecisionType,\n  SpanType,\n  SpanStatus,\n  EventType,\n  generateId,\n  nowISO,\n} from \"./models.js\";\n\nexport type {\n  JsonValue,\n  DecisionPointPayload,\n  SpanPayload,\n  EventPayload,\n  TracePayload,\n} from \"./models.js\";\n\nexport { BatchTransport } from \"./transport.js\";\nexport type { BatchTransportOptions } from \"./transport.js\";\n\nexport { TraceBuilder } from \"./trace.js\";\nexport type {\n  TraceBuilderOptions,\n  AddSpanInput,\n  AddDecisionInput,\n  AddEventInput,\n  EndOptions,\n} from \"./trace.js\";\n\nexport { createDecision } from \"./decision.js\";\nexport type { CreateDecisionInput } from \"./decision.js\";\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "agentlens-sdk",
+  "version": "0.1.0",
+  "description": "AgentLens TypeScript SDK — Agent observability that traces decisions, not just API calls.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Vectry <hunter@repi.fun>",
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.repi.fun/repi/agentlens",
+    "directory": "packages/sdk-ts"
+  },
+  "homepage": "https://agentlens.vectry.tech",
+  "bugs": {
+    "url": "https://gitea.repi.fun/repi/agentlens/issues"
+  },
+  "keywords": [
+    "agentlens",
+    "observability",
+    "tracing",
+    "ai-agents",
+    "sdk",
+    "typescript"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  }
+}