feat: TypeScript SDK (agentlens-sdk) and OpenCode plugin (opencode-agentlens)

- packages/sdk-ts: BatchTransport, TraceBuilder, models, decision helpers
  Zero external deps, native fetch, ESM+CJS output
- packages/opencode-plugin: OpenCode plugin with hooks for:
  - Session lifecycle (create/idle/error/delete/diff)
  - Tool execution capture (before/after -> TOOL_CALL spans + TOOL_SELECTION decisions)
  - LLM call tracking (chat.message -> LLM_CALL spans with model/provider)
  - Permission flow (permission.ask -> ESCALATION decisions)
  - File edit events
  - Model cost estimation (Claude, GPT-4o, o3-mini pricing)

packages/sdk-ts/package.json

@@ -0,0 +1,38 @@
+{
+  "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",
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  }
+}

packages/sdk-ts/src/_registry.ts

@@ -0,0 +1,11 @@
+import type { BatchTransport } from "./transport.js";
+
+let _transport: BatchTransport | null = null;
+
+export function _setTransport(transport: BatchTransport | null): void {
+  _transport = transport;
+}
+
+export function _getTransport(): BatchTransport | null {
+  return _transport;
+}

packages/sdk-ts/src/decision.ts

@@ -0,0 +1,29 @@
+import type { DecisionPointPayload, DecisionType, JsonValue } from "./models.js";
+import { generateId, nowISO } from "./models.js";
+
+export interface CreateDecisionInput {
+  type: DecisionType;
+  chosen: JsonValue;
+  alternatives?: JsonValue[];
+  reasoning?: string;
+  contextSnapshot?: JsonValue;
+  durationMs?: number;
+  costUsd?: number;
+  parentSpanId?: string;
+  timestamp?: string;
+}
+
+export function createDecision(input: CreateDecisionInput): DecisionPointPayload {
+  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(),
+  };
+}

packages/sdk-ts/src/index.ts

@@ -0,0 +1,76 @@
+import { BatchTransport } from "./transport.js";
+import { _setTransport, _getTransport } from "./_registry.js";
+
+export interface InitOptions {
+  apiKey: string;
+  endpoint?: string;
+  maxBatchSize?: number;
+  flushInterval?: number;
+}
+
+export function init(options: InitOptions): void {
+  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,
+    }),
+  );
+}
+
+export async function shutdown(): Promise<void> {
+  const transport = _getTransport();
+  if (transport) {
+    await transport.shutdown();
+    _setTransport(null);
+  }
+}
+
+export function getClient(): BatchTransport | null {
+  return _getTransport();
+}
+
+export async function flush(): Promise<void> {
+  const transport = _getTransport();
+  if (transport) {
+    await transport.flush();
+  }
+}
+
+export {
+  TraceStatus,
+  DecisionType,
+  SpanType,
+  SpanStatus,
+  EventType,
+  generateId,
+  nowISO,
+} from "./models.js";
+
+export type {
+  JsonValue,
+  DecisionPointPayload,
+  SpanPayload,
+  EventPayload,
+  TracePayload,
+} from "./models.js";
+
+export { BatchTransport } from "./transport.js";
+export type { BatchTransportOptions } from "./transport.js";
+
+export { TraceBuilder } from "./trace.js";
+export type {
+  TraceBuilderOptions,
+  AddSpanInput,
+  AddDecisionInput,
+  AddEventInput,
+  EndOptions,
+} from "./trace.js";
+
+export { createDecision } from "./decision.js";
+export type { CreateDecisionInput } from "./decision.js";

packages/sdk-ts/src/models.ts

@@ -0,0 +1,136 @@
+import { randomUUID } from "crypto";
+
+// ---------------------------------------------------------------------------
+// JSON value type (replaces Prisma.JsonValue for the SDK)
+// ---------------------------------------------------------------------------
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+// ---------------------------------------------------------------------------
+// Enums (as const + type union pattern — NO TypeScript enum keyword)
+// ---------------------------------------------------------------------------
+
+export const TraceStatus = {
+  RUNNING: "RUNNING",
+  COMPLETED: "COMPLETED",
+  ERROR: "ERROR",
+} as const;
+export type TraceStatus = (typeof TraceStatus)[keyof typeof TraceStatus];
+
+export const DecisionType = {
+  TOOL_SELECTION: "TOOL_SELECTION",
+  ROUTING: "ROUTING",
+  RETRY: "RETRY",
+  ESCALATION: "ESCALATION",
+  MEMORY_RETRIEVAL: "MEMORY_RETRIEVAL",
+  PLANNING: "PLANNING",
+  CUSTOM: "CUSTOM",
+} as const;
+export type DecisionType = (typeof DecisionType)[keyof typeof DecisionType];
+
+export const SpanType = {
+  LLM_CALL: "LLM_CALL",
+  TOOL_CALL: "TOOL_CALL",
+  MEMORY_OP: "MEMORY_OP",
+  CHAIN: "CHAIN",
+  AGENT: "AGENT",
+  CUSTOM: "CUSTOM",
+} as const;
+export type SpanType = (typeof SpanType)[keyof typeof SpanType];
+
+export const SpanStatus = {
+  RUNNING: "RUNNING",
+  COMPLETED: "COMPLETED",
+  ERROR: "ERROR",
+} as const;
+export type SpanStatus = (typeof SpanStatus)[keyof typeof SpanStatus];
+
+export const EventType = {
+  ERROR: "ERROR",
+  RETRY: "RETRY",
+  FALLBACK: "FALLBACK",
+  CONTEXT_OVERFLOW: "CONTEXT_OVERFLOW",
+  USER_FEEDBACK: "USER_FEEDBACK",
+  CUSTOM: "CUSTOM",
+} as const;
+export type EventType = (typeof EventType)[keyof typeof EventType];
+
+// ---------------------------------------------------------------------------
+// Wire-format interfaces (camelCase, matching POST /api/traces contract)
+// ---------------------------------------------------------------------------
+
+export interface DecisionPointPayload {
+  id: string;
+  type: DecisionType;
+  chosen: JsonValue;
+  alternatives: JsonValue[];
+  reasoning?: string;
+  contextSnapshot?: JsonValue;
+  durationMs?: number;
+  costUsd?: number;
+  parentSpanId?: string;
+  timestamp: string;
+}
+
+export 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;
+}
+
+export interface EventPayload {
+  id: string;
+  spanId?: string;
+  type: EventType;
+  name: string;
+  metadata?: JsonValue;
+  timestamp: string;
+}
+
+export 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[];
+}
+
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+
+/** Generate a v4 UUID. */
+export function generateId(): string {
+  return randomUUID();
+}
+
+/** Return the current time as an ISO-8601 string. */
+export function nowISO(): string {
+  return new Date().toISOString();
+}

packages/sdk-ts/src/trace.ts

@@ -0,0 +1,185 @@
+import type {
+  TracePayload,
+  SpanPayload,
+  DecisionPointPayload,
+  EventPayload,
+  JsonValue,
+  TraceStatus,
+  SpanType,
+  SpanStatus,
+  DecisionType,
+  EventType,
+} from "./models.js";
+import {
+  generateId,
+  nowISO,
+  TraceStatus as TraceStatusValues,
+  SpanStatus as SpanStatusValues,
+} from "./models.js";
+import { _getTransport } from "./_registry.js";
+
+export interface TraceBuilderOptions {
+  sessionId?: string;
+  tags?: string[];
+  metadata?: JsonValue;
+}
+
+export 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;
+}
+
+export interface AddDecisionInput {
+  id?: string;
+  type: DecisionType;
+  chosen: JsonValue;
+  alternatives?: JsonValue[];
+  reasoning?: string;
+  contextSnapshot?: JsonValue;
+  durationMs?: number;
+  costUsd?: number;
+  parentSpanId?: string;
+  timestamp?: string;
+}
+
+export interface AddEventInput {
+  id?: string;
+  spanId?: string;
+  type: EventType;
+  name: string;
+  metadata?: JsonValue;
+  timestamp?: string;
+}
+
+export interface EndOptions {
+  status?: TraceStatus;
+  metadata?: JsonValue;
+  totalCost?: number;
+  totalTokens?: number;
+}
+
+export class TraceBuilder {
+  private readonly trace: TracePayload;
+  private readonly startMs: number;
+
+  constructor(name: string, options?: TraceBuilderOptions) {
+    this.startMs = Date.now();
+    this.trace = {
+      id: generateId(),
+      name,
+      sessionId: options?.sessionId,
+      status: TraceStatusValues.RUNNING,
+      tags: options?.tags ?? [],
+      metadata: options?.metadata,
+      startedAt: nowISO(),
+      decisionPoints: [],
+      spans: [],
+      events: [],
+    };
+  }
+
+  addSpan(input: AddSpanInput): string {
+    const id = input.id ?? generateId();
+    const span: SpanPayload = {
+      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 ?? SpanStatusValues.RUNNING,
+      statusMessage: input.statusMessage,
+      startedAt: input.startedAt ?? nowISO(),
+      endedAt: input.endedAt,
+      metadata: input.metadata,
+    };
+    this.trace.spans.push(span);
+    return id;
+  }
+
+  addDecision(input: AddDecisionInput): string {
+    const id = input.id ?? generateId();
+    const decision: DecisionPointPayload = {
+      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: AddEventInput): string {
+    const id = input.id ?? generateId();
+    const event: EventPayload = {
+      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: TraceStatus): this {
+    this.trace.status = status;
+    return this;
+  }
+
+  setMetadata(metadata: JsonValue): this {
+    this.trace.metadata = metadata;
+    return this;
+  }
+
+  toPayload(): TracePayload {
+    return { ...this.trace };
+  }
+
+  end(options?: EndOptions): TracePayload {
+    const endedAt = nowISO();
+    this.trace.endedAt = endedAt;
+    this.trace.totalDuration = Date.now() - this.startMs;
+    this.trace.status =
+      options?.status ?? TraceStatusValues.COMPLETED;
+
+    if (options?.metadata !== undefined) {
+      this.trace.metadata = options.metadata;
+    }
+    if (options?.totalCost !== undefined) {
+      this.trace.totalCost = options.totalCost;
+    }
+    if (options?.totalTokens !== undefined) {
+      this.trace.totalTokens = options.totalTokens;
+    }
+
+    const transport = _getTransport();
+    if (transport) {
+      transport.add(this.trace);
+    }
+
+    return { ...this.trace };
+  }
+}

packages/sdk-ts/src/transport.ts

@@ -0,0 +1,77 @@
+import type { TracePayload } from "./models.js";
+
+export interface BatchTransportOptions {
+  apiKey: string;
+  endpoint: string;
+  maxBatchSize?: number;
+  flushInterval?: number;
+}
+
+export class BatchTransport {
+  private readonly apiKey: string;
+  private readonly endpoint: string;
+  private readonly maxBatchSize: number;
+  private readonly flushInterval: number;
+  private buffer: TracePayload[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: BatchTransportOptions) {
+    this.apiKey = options.apiKey;
+    this.endpoint = options.endpoint.replace(/\/+$/, "");
+    this.maxBatchSize = options.maxBatchSize ?? 10;
+    this.flushInterval = options.flushInterval ?? 5_000;
+
+    this.timer = setInterval(() => {
+      void this._doFlush();
+    }, this.flushInterval);
+  }
+
+  add(trace: TracePayload): void {
+    this.buffer.push(trace);
+    if (this.buffer.length >= this.maxBatchSize) {
+      void this._doFlush();
+    }
+  }
+
+  async flush(): Promise<void> {
+    await this._doFlush();
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this._doFlush();
+  }
+
+  private async _doFlush(): Promise<void> {
+    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: unknown) {
+      const message =
+        error instanceof Error ? error.message : String(error);
+      console.warn(`AgentLens: Failed to send traces: ${message}`);
+    }
+  }
+}

packages/sdk-ts/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

packages/sdk-ts/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+});