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/opencode-plugin/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "opencode-agentlens",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for AgentLens — trace your coding agent's decisions, tool calls, and sessions",
+  "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"
+  },
+  "dependencies": {
+    "agentlens-sdk": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.53",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.1.0"
+  },
+  "keywords": [
+    "opencode",
+    "agentlens",
+    "observability",
+    "tracing",
+    "coding-agent"
+  ],
+  "license": "MIT"
+}

packages/opencode-plugin/src/config.ts

@@ -0,0 +1,41 @@
+export interface PluginConfig {
+  apiKey: string;
+  endpoint: string;
+  enabled: boolean;
+  /** Opt-in: capture full message content in traces */
+  captureContent: boolean;
+  /** Maximum characters for tool output before truncation */
+  maxOutputLength: number;
+  /** Milliseconds between automatic flushes */
+  flushInterval: number;
+  /** Maximum traces per batch */
+  maxBatchSize: number;
+}
+
+export function loadConfig(): PluginConfig {
+  const apiKey = process.env["AGENTLENS_API_KEY"] ?? "";
+
+  if (!apiKey) {
+    console.warn(
+      "[agentlens] AGENTLENS_API_KEY not set — plugin will be disabled",
+    );
+  }
+
+  return {
+    apiKey,
+    endpoint:
+      process.env["AGENTLENS_ENDPOINT"] ?? "https://agentlens.vectry.tech",
+    enabled: (process.env["AGENTLENS_ENABLED"] ?? "true") === "true",
+    captureContent:
+      (process.env["AGENTLENS_CAPTURE_CONTENT"] ?? "false") === "true",
+    maxOutputLength: parseInt(
+      process.env["AGENTLENS_MAX_OUTPUT_LENGTH"] ?? "2000",
+      10,
+    ),
+    flushInterval: parseInt(
+      process.env["AGENTLENS_FLUSH_INTERVAL"] ?? "5000",
+      10,
+    ),
+    maxBatchSize: parseInt(process.env["AGENTLENS_BATCH_SIZE"] ?? "10", 10),
+  };
+}

packages/opencode-plugin/src/index.ts

@@ -0,0 +1,146 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { JsonValue } from "agentlens-sdk";
+import { init, flush, EventType as EventTypeValues } from "agentlens-sdk";
+import { loadConfig } from "./config.js";
+import { SessionState } from "./state.js";
+import { truncate, safeJsonValue } from "./utils.js";
+
+const plugin: Plugin = async ({ project, directory, worktree }) => {
+  const config = loadConfig();
+
+  if (!config.enabled || !config.apiKey) {
+    console.log("[agentlens] Plugin disabled — missing AGENTLENS_API_KEY");
+    return {};
+  }
+
+  init({
+    apiKey: config.apiKey,
+    endpoint: config.endpoint,
+    flushInterval: config.flushInterval,
+    maxBatchSize: config.maxBatchSize,
+  });
+
+  const state = new SessionState();
+
+  return {
+    event: async ({ event }) => {
+      const type = event.type;
+      const props = (event as Record<string, unknown>).properties as
+        | Record<string, unknown>
+        | undefined;
+
+      if (type === "session.created" && props?.["id"]) {
+        state.startSession(String(props["id"]), {
+          project: project.id,
+          directory,
+          worktree,
+        });
+      }
+
+      if (type === "session.idle") {
+        const sessionId = props?.["sessionID"] ?? props?.["id"];
+        if (sessionId) await flush();
+      }
+
+      if (type === "session.error") {
+        const sessionId = String(props?.["sessionID"] ?? props?.["id"] ?? "");
+        if (sessionId) {
+          const trace = state.getTrace(sessionId);
+          if (trace) {
+            trace.addEvent({
+              type: EventTypeValues.ERROR,
+              name: String(props?.["error"] ?? "session error"),
+              metadata: safeJsonValue(props) as JsonValue,
+            });
+          }
+        }
+      }
+
+      if (type === "session.deleted") {
+        const sessionId = String(props?.["sessionID"] ?? props?.["id"] ?? "");
+        if (sessionId) state.endSession(sessionId);
+      }
+
+      if (type === "session.diff") {
+        const sessionId = String(props?.["sessionID"] ?? props?.["id"] ?? "");
+        if (sessionId) {
+          const trace = state.getTrace(sessionId);
+          if (trace) {
+            trace.setMetadata({
+              diff: truncate(String(props?.["diff"] ?? ""), 5000),
+            });
+          }
+        }
+      }
+
+      if (type === "file.edited") {
+        const sessionId = String(props?.["sessionID"] ?? props?.["id"] ?? "");
+        const trace = sessionId ? state.getTrace(sessionId) : undefined;
+        if (trace) {
+          trace.addEvent({
+            type: EventTypeValues.CUSTOM,
+            name: "file.edited",
+            metadata: safeJsonValue({
+              filePath: props?.["filePath"],
+            }) as JsonValue,
+          });
+        }
+      }
+    },
+
+    "tool.execute.before": async (input, output) => {
+      state.startToolCall(
+        input.callID,
+        input.tool,
+        output.args as unknown,
+        input.sessionID,
+      );
+    },
+
+    "tool.execute.after": async (input, output) => {
+      state.endToolCall(
+        input.callID,
+        truncate(output.output ?? "", config.maxOutputLength),
+        output.title ?? input.tool,
+        output.metadata as unknown,
+      );
+    },
+
+    "chat.message": async (input) => {
+      if (input.model) {
+        state.recordLLMCall(input.sessionID, {
+          model: input.model,
+          agent: input.agent,
+          messageID: input.messageID,
+        });
+      }
+    },
+
+    "chat.params": async (input, output) => {
+      const trace = state.getTrace(input.sessionID);
+      if (trace) {
+        trace.addEvent({
+          type: EventTypeValues.CUSTOM,
+          name: "chat.params",
+          metadata: safeJsonValue({
+            agent: input.agent,
+            model: input.model.id,
+            provider: input.provider.info.id,
+            temperature: output.temperature,
+            topP: output.topP,
+            topK: output.topK,
+          }) as JsonValue,
+        });
+      }
+    },
+
+    "permission.ask": async (input, output) => {
+      state.recordPermission(input.sessionID, input, output.status);
+    },
+  };
+};
+
+export default plugin;
+export { plugin as AgentLensPlugin };
+export type { PluginConfig } from "./config.js";
+export { loadConfig } from "./config.js";

packages/opencode-plugin/src/state.ts

@@ -0,0 +1,183 @@
+import {
+  TraceBuilder,
+  SpanType,
+  SpanStatus,
+  DecisionType,
+  nowISO,
+} from "agentlens-sdk";
+import type { JsonValue, TraceStatus } from "agentlens-sdk";
+import { extractToolMetadata, safeJsonValue } from "./utils.js";
+
+interface ToolCallState {
+  startTime: number;
+  tool: string;
+  args: unknown;
+  sessionID: string;
+}
+
+export class SessionState {
+  private traces = new Map<string, TraceBuilder>();
+  private toolCalls = new Map<string, ToolCallState>();
+  private rootSpans = new Map<string, string>();
+
+  startSession(
+    sessionId: string,
+    metadata?: Record<string, unknown>,
+  ): TraceBuilder {
+    const trace = new TraceBuilder("opencode-session", {
+      sessionId,
+      tags: ["opencode", "coding-agent"],
+      metadata: metadata ? (safeJsonValue(metadata) as JsonValue) : undefined,
+    });
+
+    const rootSpanId = trace.addSpan({
+      name: "session",
+      type: SpanType.AGENT,
+      startedAt: nowISO(),
+      metadata: metadata ? (safeJsonValue(metadata) as JsonValue) : undefined,
+    });
+
+    this.traces.set(sessionId, trace);
+    this.rootSpans.set(sessionId, rootSpanId);
+    return trace;
+  }
+
+  getTrace(sessionId: string): TraceBuilder | undefined {
+    return this.traces.get(sessionId);
+  }
+
+  endSession(sessionId: string, status?: TraceStatus): void {
+    const trace = this.traces.get(sessionId);
+    if (!trace) return;
+
+    const rootSpanId = this.rootSpans.get(sessionId);
+    if (rootSpanId) {
+      trace.addSpan({
+        id: rootSpanId,
+        name: "session",
+        type: SpanType.AGENT,
+        status: status === "ERROR" ? SpanStatus.ERROR : SpanStatus.COMPLETED,
+        endedAt: nowISO(),
+      });
+    }
+
+    trace.end({ status: status ?? "COMPLETED" });
+    this.traces.delete(sessionId);
+    this.rootSpans.delete(sessionId);
+  }
+
+  startToolCall(
+    callID: string,
+    tool: string,
+    args: unknown,
+    sessionID: string,
+  ): void {
+    this.toolCalls.set(callID, {
+      startTime: Date.now(),
+      tool,
+      args,
+      sessionID,
+    });
+  }
+
+  endToolCall(
+    callID: string,
+    output: string,
+    title: string,
+    metadata: unknown,
+  ): void {
+    const call = this.toolCalls.get(callID);
+    if (!call) return;
+    this.toolCalls.delete(callID);
+
+    const trace = this.traces.get(call.sessionID);
+    if (!trace) return;
+
+    const durationMs = Date.now() - call.startTime;
+    const rootSpanId = this.rootSpans.get(call.sessionID);
+    const toolMeta = extractToolMetadata(call.tool, call.args);
+
+    trace.addSpan({
+      name: title,
+      type: SpanType.TOOL_CALL,
+      parentSpanId: rootSpanId,
+      input: safeJsonValue(call.args),
+      output: output as JsonValue,
+      durationMs,
+      status: SpanStatus.COMPLETED,
+      startedAt: new Date(call.startTime).toISOString(),
+      endedAt: nowISO(),
+      metadata: safeJsonValue({ ...toolMeta, rawMetadata: metadata }),
+    });
+
+    trace.addDecision({
+      type: DecisionType.TOOL_SELECTION,
+      chosen: call.tool as JsonValue,
+      alternatives: [],
+      reasoning: title,
+      durationMs,
+      parentSpanId: rootSpanId,
+    });
+  }
+
+  recordLLMCall(
+    sessionId: string,
+    options: {
+      model?: { providerID: string; modelID: string };
+      agent?: string;
+      messageID?: string;
+    },
+  ): void {
+    const trace = this.traces.get(sessionId);
+    if (!trace) return;
+
+    const rootSpanId = this.rootSpans.get(sessionId);
+    const agentName = options.agent ?? "assistant";
+    const modelName = options.model?.modelID ?? "unknown";
+
+    trace.addSpan({
+      name: `${agentName} → ${modelName}`,
+      type: SpanType.LLM_CALL,
+      parentSpanId: rootSpanId,
+      status: SpanStatus.COMPLETED,
+      startedAt: nowISO(),
+      endedAt: nowISO(),
+      metadata: safeJsonValue({
+        provider: options.model?.providerID,
+        model: options.model?.modelID,
+        agent: options.agent,
+        messageID: options.messageID,
+      }),
+    });
+  }
+
+  recordPermission(
+    sessionId: string,
+    permission: unknown,
+    status: string,
+  ): void {
+    const trace = this.traces.get(sessionId);
+    if (!trace) return;
+
+    const rootSpanId = this.rootSpans.get(sessionId);
+    const p = permission as Record<string, unknown> | null;
+    const title = (p?.["title"] as string) ?? "permission";
+    const permType = (p?.["type"] as string) ?? "unknown";
+
+    trace.addDecision({
+      type: DecisionType.ESCALATION,
+      chosen: safeJsonValue({ action: status }),
+      alternatives: [
+        "allow" as JsonValue,
+        "deny" as JsonValue,
+        "ask" as JsonValue,
+      ],
+      reasoning: `${permType}: ${title}`,
+      parentSpanId: rootSpanId,
+    });
+  }
+
+  getRootSpanId(sessionId: string): string | undefined {
+    return this.rootSpans.get(sessionId);
+  }
+}

packages/opencode-plugin/src/utils.ts

@@ -0,0 +1,97 @@
+import type { JsonValue } from "agentlens-sdk";
+
+export function truncate(str: string, maxLength: number): string {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + "... [truncated]";
+}
+
+export function extractToolMetadata(
+  tool: string,
+  args: unknown,
+): Record<string, unknown> {
+  const a = args as Record<string, unknown> | null | undefined;
+  if (!a || typeof a !== "object") return {};
+
+  switch (tool) {
+    case "read":
+    case "mcp_read":
+      return { filePath: a["filePath"] };
+
+    case "write":
+    case "mcp_write":
+      return { filePath: a["filePath"] };
+
+    case "edit":
+    case "mcp_edit":
+      return { filePath: a["filePath"] };
+
+    case "bash":
+    case "mcp_bash":
+      return {
+        command: truncate(String(a["command"] ?? ""), 200),
+      };
+
+    case "glob":
+    case "mcp_glob":
+      return { pattern: a["pattern"] };
+
+    case "grep":
+    case "mcp_grep":
+      return { pattern: a["pattern"], path: a["path"] };
+
+    case "task":
+    case "mcp_task":
+      return {
+        category: a["category"],
+        description: a["description"],
+      };
+
+    default:
+      return {};
+  }
+}
+
+const MODEL_COSTS: Record<string, { input: number; output: number }> = {
+  "claude-opus-4-20250514": { input: 15, output: 75 },
+  "claude-sonnet-4-20250514": { input: 3, output: 15 },
+  "claude-haiku-3-20250307": { input: 0.25, output: 1.25 },
+  "gpt-4o": { input: 2.5, output: 10 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10, output: 30 },
+  "o3-mini": { input: 1.1, output: 4.4 },
+};
+
+export function getModelCost(
+  modelId: string,
+): { input: number; output: number } | undefined {
+  const direct = MODEL_COSTS[modelId];
+  if (direct) return direct;
+
+  for (const [key, cost] of Object.entries(MODEL_COSTS)) {
+    if (modelId.includes(key)) return cost;
+  }
+  return undefined;
+}
+
+/** Coerce arbitrary values into SDK-compatible `JsonValue`, stringifying unknowns. */
+export function safeJsonValue(value: unknown): JsonValue {
+  if (value === null || value === undefined) return null;
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => safeJsonValue(v));
+  }
+  if (typeof value === "object") {
+    const result: Record<string, JsonValue> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      result[k] = safeJsonValue(v);
+    }
+    return result;
+  }
+  return String(value);
+}

packages/opencode-plugin/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/opencode-plugin/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,
+});