opencode-tracekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiqi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# TraceKit (OpenCode Tracepoint Plugin)
+
+TraceKit 是一个面向 OpenCode 的可观测性插件，支持：
+
+- 自动拦截 `tool/skill` 调用并记录 span（start/end）
+- 在任意 agent 和 skill 中显式打点（`trace.emit`）
+- 记录自定义指标（`trace.counter`）与业务阶段（`trace.span`）
+- 将 trace 以 `ndjson` 落盘，并支持离线导出和分析
+
+安装与接入步骤见：`plugins/tracekit/docs/installation.md`
+发布到 npm 见：`plugins/tracekit/docs/publish.md`
+
+## npm 安装（发布后）
+
+```bash
+npm install opencode-tracekit
+```
+
+## 目录结构
+
+```text
+plugins/tracekit/
+  index.ts
+  src/
+    tracekit_plugin.ts
+    trace_record.ts
+    ndjson_writer.ts
+    span_context.ts
+    hooks_tool.ts
+    hooks_session.ts
+    tools_trace_emit.ts
+    tools_trace_counter.ts
+    tools_trace_span.ts
+    analyzer.ts
+    exporter.ts
+    cli.ts
+```
+
+## 快速接入
+
+```ts
+import { createTraceKitPlugin } from "./plugins/tracekit";
+
+const tracekit = createTraceKitPlugin({
+  outPath: "./trace.ndjson",
+  includeCounterTool: true,
+  includeSpanTool: true,
+});
+
+// 伪代码：把 hooks / tools 注册给 OpenCode runtime
+opencode.registerPlugin({
+  hooks: tracekit.hooks,
+  tools: tracekit.tools,
+  shutdown: tracekit.shutdown,
+});
+```
+
+## 在 Agent / Skill 中插入 trace 点
+
+### Tracepoint
+
+```json
+{
+  "tool": "trace.emit",
+  "args": {
+    "name": "agent.plan.generated",
+    "level": "info",
+    "attrs": { "agent": "planner", "stepCount": 4 }
+  }
+}
+```
+
+### 自定义 Span（业务阶段）
+
+```json
+{ "tool": "trace.span", "args": { "op": "start", "name": "ipd.phase.spec" } }
+{ "tool": "trace.emit", "args": { "name": "spec.ready" } }
+{ "tool": "trace.span", "args": { "op": "end", "status": "ok" } }
+```
+
+### Counter
+
+```json
+{
+  "tool": "trace.counter",
+  "args": {
+    "name": "spec.requirements.count",
+    "value": 23
+  }
+}
+```
+
+## 导出与分析
+
+```bash
+# 统计分析
+node dist/cli.js analyze ./trace.ndjson
+
+# 导出 JSON
+node dist/cli.js export ./trace.ndjson --out ./trace.json --format json
+
+# 导出 CSV
+node dist/cli.js export ./trace.ndjson --out ./trace.csv --format csv
+```
+
+## Record 协议
+
+参考 `src/trace_record.ts`，核心事件类型：
+
+- `capture_start` / `capture_end`
+- `session`
+- `span_start` / `span_end`
+- `tracepoint`
+- `marker`
+- `counter`

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { createTraceKitPlugin } from "./src/tracekit_plugin.js";
+export { createTraceKitPlugin };
+export default createTraceKitPlugin;
+export type { TraceKitConfig, TraceKitPlugin } from "./src/tracekit_plugin.js";
+export type { TraceRecord } from "./src/trace_record.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+import { createTraceKitPlugin } from "./src/tracekit_plugin.js";
+export { createTraceKitPlugin };
+export default createTraceKitPlugin;

package/dist/src/analyzer.d.ts

@@ -0,0 +1,20 @@
+import type { TraceRecord } from "./trace_record.js";
+export interface TraceSummary {
+    totalRecords: number;
+    totalSessions: number;
+    totalSpans: number;
+    errorSpans: number;
+    totalTracepoints: number;
+    totalCounters: number;
+    avgSpanDurationMs: number;
+    p95SpanDurationMs: number;
+    topSlowSpans: Array<{
+        name: string;
+        count: number;
+        avgDurationMs: number;
+        errorRate: number;
+    }>;
+}
+export declare function loadTrace(path: string): Promise<TraceRecord[]>;
+export declare function analyzeTrace(records: TraceRecord[]): TraceSummary;
+export declare function saveSummary(path: string, summary: TraceSummary): Promise<void>;

package/dist/src/analyzer.js

@@ -0,0 +1,68 @@
+import { createReadStream } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+export async function loadTrace(path) {
+    const records = [];
+    const rl = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+    for await (const line of rl) {
+        const text = line.trim();
+        if (!text)
+            continue;
+        const parsed = JSON.parse(text);
+        records.push(parsed);
+    }
+    return records;
+}
+export function analyzeTrace(records) {
+    const sessions = new Set();
+    const spans = records.filter((r) => r.type === "span_end");
+    const spanStarts = new Map();
+    for (const record of records) {
+        if ("sessionId" in record && record.sessionId)
+            sessions.add(record.sessionId);
+        if (record.type === "span_start")
+            spanStarts.set(record.spanId, record);
+    }
+    const durations = [];
+    const stats = new Map();
+    let errorSpans = 0;
+    for (const end of spans) {
+        if (end.status === "error")
+            errorSpans += 1;
+        if (typeof end.durationMs === "number")
+            durations.push(end.durationMs);
+        const name = spanStarts.get(end.spanId)?.name ?? String(end.attrs?.toolName ?? "unknown");
+        const current = stats.get(name) ?? { count: 0, totalDuration: 0, errors: 0 };
+        current.count += 1;
+        current.totalDuration += end.durationMs ?? 0;
+        if (end.status === "error")
+            current.errors += 1;
+        stats.set(name, current);
+    }
+    durations.sort((a, b) => a - b);
+    const avg = durations.length ? durations.reduce((a, b) => a + b, 0) / durations.length : 0;
+    const p95 = durations.length ? durations[Math.min(durations.length - 1, Math.floor(durations.length * 0.95))] : 0;
+    const topSlowSpans = [...stats.entries()]
+        .map(([name, s]) => ({
+        name,
+        count: s.count,
+        avgDurationMs: s.count ? s.totalDuration / s.count : 0,
+        errorRate: s.count ? s.errors / s.count : 0,
+    }))
+        .sort((a, b) => b.avgDurationMs - a.avgDurationMs)
+        .slice(0, 10);
+    return {
+        totalRecords: records.length,
+        totalSessions: sessions.size,
+        totalSpans: spans.length,
+        errorSpans,
+        totalTracepoints: records.filter((r) => r.type === "tracepoint").length,
+        totalCounters: records.filter((r) => r.type === "counter").length,
+        avgSpanDurationMs: avg,
+        p95SpanDurationMs: p95,
+        topSlowSpans,
+    };
+}
+export async function saveSummary(path, summary) {
+    await writeFile(path, JSON.stringify(summary, null, 2), "utf8");
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { analyzeTrace, loadTrace } from "./analyzer.js";
+import { exportTrace } from "./exporter.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const cmd = args[0];
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        printHelp();
+        return;
+    }
+    if (cmd === "analyze") {
+        const input = args[1];
+        if (!input)
+            throw new Error("missing input trace file path");
+        const summaryPath = readFlag(args, "--summary");
+        const records = await loadTrace(input);
+        const summary = analyzeTrace(records);
+        if (summaryPath) {
+            const fs = await import("node:fs/promises");
+            await fs.writeFile(summaryPath, JSON.stringify(summary, null, 2), "utf8");
+        }
+        process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+        return;
+    }
+    if (cmd === "export") {
+        const input = args[1];
+        const out = readFlag(args, "--out");
+        const format = (readFlag(args, "--format") ?? "json");
+        if (!input || !out)
+            throw new Error("usage: tracectl export <trace.ndjson> --out <file> [--format json|csv]");
+        const records = await loadTrace(input);
+        await exportTrace(out, records, format);
+        process.stdout.write(`exported ${records.length} records to ${out} (${format})\n`);
+        return;
+    }
+    throw new Error(`unknown command: ${cmd}`);
+}
+function readFlag(args, key) {
+    const idx = args.indexOf(key);
+    if (idx < 0)
+        return undefined;
+    return args[idx + 1];
+}
+function printHelp() {
+    process.stdout.write([
+        "tracectl - TraceKit helper",
+        "",
+        "Commands:",
+        "  tracectl analyze <trace.ndjson> [--summary summary.json]",
+        "  tracectl export <trace.ndjson> --out <file> [--format json|csv]",
+        "",
+    ].join("\n"));
+}
+main().catch((err) => {
+    process.stderr.write(`tracectl failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/src/exporter.d.ts

@@ -0,0 +1,3 @@
+import type { TraceRecord } from "./trace_record.js";
+export type TraceExportFormat = "json" | "csv";
+export declare function exportTrace(path: string, records: TraceRecord[], format: TraceExportFormat): Promise<void>;

package/dist/src/exporter.js

@@ -0,0 +1,47 @@
+import { writeFile } from "node:fs/promises";
+export async function exportTrace(path, records, format) {
+    if (format === "json") {
+        await writeFile(path, JSON.stringify(records, null, 2), "utf8");
+        return;
+    }
+    const header = [
+        "type",
+        "ts",
+        "sessionId",
+        "spanId",
+        "parentSpanId",
+        "name",
+        "kind",
+        "status",
+        "durationMs",
+        "level",
+        "value",
+    ];
+    const rows = records.map((r) => {
+        const base = r;
+        return [
+            base.type,
+            base.ts,
+            base.sessionId,
+            base.spanId,
+            base.parentSpanId,
+            base.name ?? base.label,
+            base.kind,
+            base.status,
+            base.durationMs,
+            base.level,
+            base.value,
+        ]
+            .map(toCsvCell)
+            .join(",");
+    });
+    await writeFile(path, `${header.join(",")}\n${rows.join("\n")}\n`, "utf8");
+}
+function toCsvCell(value) {
+    if (value === undefined || value === null)
+        return "";
+    const str = String(value);
+    if (!str.includes(",") && !str.includes('"') && !str.includes("\n"))
+        return str;
+    return `"${str.replace(/"/g, '""')}"`;
+}

package/dist/src/hooks_session.d.ts

@@ -0,0 +1,18 @@
+import type { NDJSONWriter } from "./ndjson_writer.js";
+import type { SpanContext } from "./span_context.js";
+export interface SessionStartEvent {
+    ts?: number;
+    sessionId: string;
+    parentSessionId?: string;
+    label?: string;
+    attrs?: Record<string, unknown>;
+}
+export interface SessionEndEvent {
+    ts?: number;
+    sessionId: string;
+    attrs?: Record<string, unknown>;
+}
+export declare function makeSessionHooks(writer: NDJSONWriter, ctx: SpanContext): {
+    onSessionStart: (ev: SessionStartEvent) => void;
+    onSessionEnd: (ev: SessionEndEvent) => void;
+};

package/dist/src/hooks_session.js

@@ -0,0 +1,24 @@
+export function makeSessionHooks(writer, ctx) {
+    function onSessionStart(ev) {
+        writer.write({
+            type: "session",
+            op: "upsert",
+            ts: ev.ts ?? Date.now(),
+            sessionId: ev.sessionId,
+            parentSessionId: ev.parentSessionId,
+            label: ev.label,
+            attrs: ev.attrs,
+        });
+    }
+    function onSessionEnd(ev) {
+        writer.write({
+            type: "marker",
+            ts: ev.ts ?? Date.now(),
+            sessionId: ev.sessionId,
+            label: "session.completed",
+            attrs: ev.attrs,
+        });
+        ctx.clear(ev.sessionId);
+    }
+    return { onSessionStart, onSessionEnd };
+}

package/dist/src/hooks_tool.d.ts

@@ -0,0 +1,27 @@
+import type { NDJSONWriter } from "./ndjson_writer.js";
+import type { SpanContext } from "./span_context.js";
+import type { TraceUsage } from "./trace_record.js";
+export interface ToolStartEvent {
+    ts?: number;
+    sessionId?: string;
+    agentId?: string;
+    toolName?: string;
+    toolCallId?: string;
+    input?: unknown;
+    attrs?: Record<string, unknown>;
+}
+export interface ToolEndEvent {
+    ts?: number;
+    sessionId?: string;
+    agentId?: string;
+    toolName?: string;
+    toolCallId?: string;
+    output?: unknown;
+    error?: unknown;
+    usage?: TraceUsage;
+    attrs?: Record<string, unknown>;
+}
+export declare function makeToolHooks(writer: NDJSONWriter, ctx: SpanContext): {
+    onToolStart: (ev: ToolStartEvent) => void;
+    onToolEnd: (ev: ToolEndEvent) => void;
+};

package/dist/src/hooks_tool.js

@@ -0,0 +1,62 @@
+import { asRecord, id, preview, safeError } from "./utils.js";
+export function makeToolHooks(writer, ctx) {
+    function onToolStart(ev) {
+        const ts = ev.ts ?? Date.now();
+        const sessionId = ev.sessionId ?? ev.agentId ?? "unknown-session";
+        const spanId = ev.toolCallId ?? id();
+        const parentSpanId = ctx.current(sessionId)?.spanId;
+        const isSkill = ev.toolName === "skill";
+        const skillInput = asRecord(ev.input);
+        const attrs = {
+            toolName: ev.toolName ?? "unknown-tool",
+            inputPreview: preview(ev.input),
+            ...ev.attrs,
+        };
+        if (isSkill) {
+            attrs.skill = {
+                name: skillInput?.name,
+                path: skillInput?.path,
+                version: skillInput?.version,
+            };
+        }
+        writer.write({
+            type: "span_start",
+            ts,
+            spanId,
+            sessionId,
+            parentSpanId,
+            kind: isSkill ? "skill" : "tool",
+            name: isSkill ? `skill:${String(skillInput?.name ?? "unknown")}` : String(ev.toolName ?? "unknown-tool"),
+            attrs,
+        });
+        ctx.push(sessionId, {
+            spanId,
+            kind: isSkill ? "skill" : "tool",
+            name: String(ev.toolName ?? "unknown-tool"),
+            startedAt: ts,
+        });
+    }
+    function onToolEnd(ev) {
+        const ts = ev.ts ?? Date.now();
+        const sessionId = ev.sessionId ?? ev.agentId ?? "unknown-session";
+        const spanId = ev.toolCallId ?? ctx.current(sessionId)?.spanId ?? "unknown-span";
+        const frame = ctx.pop(sessionId, spanId);
+        writer.write({
+            type: "span_end",
+            ts,
+            spanId,
+            sessionId,
+            status: ev.error ? "error" : "ok",
+            durationMs: frame ? ts - frame.startedAt : undefined,
+            tokensIn: ev.usage?.promptTokens,
+            tokensOut: ev.usage?.completionTokens,
+            attrs: {
+                toolName: ev.toolName ?? frame?.name ?? "unknown-tool",
+                outputPreview: preview(ev.output),
+                error: ev.error ? safeError(ev.error) : undefined,
+                ...ev.attrs,
+            },
+        });
+    }
+    return { onToolStart, onToolEnd };
+}

package/dist/src/ndjson_writer.d.ts

@@ -0,0 +1,13 @@
+import type { TraceRecord } from "./trace_record.js";
+export declare class NDJSONWriter {
+    private readonly path;
+    private stream?;
+    private queue;
+    private opened;
+    constructor(path: string);
+    open(): Promise<void>;
+    write(record: TraceRecord): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private writeLine;
+}

package/dist/src/ndjson_writer.js

@@ -0,0 +1,61 @@
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createWriteStream } from "node:fs";
+export class NDJSONWriter {
+    path;
+    stream;
+    queue = Promise.resolve();
+    opened = false;
+    constructor(path) {
+        this.path = path;
+    }
+    async open() {
+        if (this.opened)
+            return;
+        await mkdir(dirname(this.path), { recursive: true });
+        this.stream = createWriteStream(this.path, { flags: "a" });
+        this.opened = true;
+    }
+    write(record) {
+        this.queue = this.queue.then(async () => {
+            if (!this.opened)
+                await this.open();
+            const line = `${JSON.stringify(record)}\n`;
+            await this.writeLine(line);
+        });
+        return this.queue;
+    }
+    async flush() {
+        await this.queue;
+    }
+    async close() {
+        await this.queue;
+        if (!this.stream)
+            return;
+        await new Promise((resolve, reject) => {
+            this.stream.end((err) => {
+                if (err)
+                    return reject(err);
+                resolve();
+            });
+        });
+        this.stream = undefined;
+        this.opened = false;
+    }
+    async writeLine(line) {
+        await new Promise((resolve, reject) => {
+            if (!this.stream)
+                return reject(new Error("NDJSON stream not opened"));
+            const ok = this.stream.write(line, "utf8", (err) => {
+                if (err)
+                    return reject(err);
+            });
+            if (ok) {
+                resolve();
+            }
+            else {
+                this.stream.once("drain", resolve);
+            }
+        });
+    }
+}

package/dist/src/plugin_types.d.ts

@@ -0,0 +1,11 @@
+export interface TraceToolRuntime {
+    sessionId?: string;
+    agentId?: string;
+    ts?: number;
+}
+export interface TraceToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, runtime: TraceToolRuntime) => Promise<Record<string, unknown>>;
+}

package/dist/src/plugin_types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/span_context.d.ts

@@ -0,0 +1,14 @@
+import type { TraceKind } from "./trace_record.js";
+export interface SpanFrame {
+    spanId: string;
+    kind: TraceKind;
+    name: string;
+    startedAt: number;
+}
+export declare class SpanContext {
+    private readonly stackBySession;
+    push(sessionId: string, frame: SpanFrame): void;
+    pop(sessionId: string, spanId: string): SpanFrame | undefined;
+    current(sessionId: string): SpanFrame | undefined;
+    clear(sessionId: string): void;
+}

package/dist/src/span_context.js

@@ -0,0 +1,27 @@
+export class SpanContext {
+    stackBySession = new Map();
+    push(sessionId, frame) {
+        const stack = this.stackBySession.get(sessionId) ?? [];
+        stack.push(frame);
+        this.stackBySession.set(sessionId, stack);
+    }
+    pop(sessionId, spanId) {
+        const stack = this.stackBySession.get(sessionId);
+        if (!stack?.length)
+            return undefined;
+        const top = stack[stack.length - 1];
+        if (top.spanId === spanId)
+            return stack.pop();
+        const idx = stack.findIndex((item) => item.spanId === spanId);
+        if (idx < 0)
+            return undefined;
+        return stack.splice(idx, 1)[0];
+    }
+    current(sessionId) {
+        const stack = this.stackBySession.get(sessionId);
+        return stack?.[stack.length - 1];
+    }
+    clear(sessionId) {
+        this.stackBySession.delete(sessionId);
+    }
+}

package/dist/src/tools_trace_counter.d.ts

@@ -0,0 +1,3 @@
+import type { NDJSONWriter } from "./ndjson_writer.js";
+import type { TraceToolDefinition } from "./plugin_types.js";
+export declare function makeTraceCounterTool(writer: NDJSONWriter): TraceToolDefinition;

package/dist/src/tools_trace_counter.js

@@ -0,0 +1,26 @@
+export function makeTraceCounterTool(writer) {
+    return {
+        name: "trace.counter",
+        description: "Emit a numeric counter metric for current session.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                value: { type: "number" },
+                attrs: { type: "object" },
+            },
+            required: ["name", "value"],
+        },
+        async handler(args, runtime) {
+            writer.write({
+                type: "counter",
+                ts: runtime.ts ?? Date.now(),
+                sessionId: runtime.sessionId ?? runtime.agentId ?? "unknown-session",
+                name: String(args.name),
+                value: Number(args.value),
+                attrs: args.attrs ?? {},
+            });
+            return { ok: true };
+        },
+    };
+}

package/dist/src/tools_trace_emit.d.ts

@@ -0,0 +1,4 @@
+import type { NDJSONWriter } from "./ndjson_writer.js";
+import type { SpanContext } from "./span_context.js";
+import type { TraceToolDefinition } from "./plugin_types.js";
+export declare function makeTraceEmitTool(writer: NDJSONWriter, ctx: SpanContext): TraceToolDefinition;

package/dist/src/tools_trace_emit.js

@@ -0,0 +1,33 @@
+import { id } from "./utils.js";
+export function makeTraceEmitTool(writer, ctx) {
+    return {
+        name: "trace.emit",
+        description: "Emit a tracepoint event that is attached to the current active span.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                level: { type: "string", enum: ["info", "warn", "error"], default: "info" },
+                attrs: { type: "object" },
+                links: { type: "array" },
+            },
+            required: ["name"],
+        },
+        async handler(args, runtime) {
+            const sessionId = String(runtime.sessionId ?? runtime.agentId ?? "unknown-session");
+            const tpId = id();
+            writer.write({
+                type: "tracepoint",
+                ts: runtime.ts ?? Date.now(),
+                tpId,
+                sessionId,
+                parentSpanId: ctx.current(sessionId)?.spanId,
+                name: String(args.name),
+                level: args.level ?? "info",
+                attrs: args.attrs ?? {},
+                links: args.links ?? [],
+            });
+            return { ok: true, tpId };
+        },
+    };
+}

package/dist/src/tools_trace_span.d.ts

@@ -0,0 +1,4 @@
+import type { NDJSONWriter } from "./ndjson_writer.js";
+import type { SpanContext } from "./span_context.js";
+import type { TraceToolDefinition } from "./plugin_types.js";
+export declare function makeTraceSpanTool(writer: NDJSONWriter, ctx: SpanContext): TraceToolDefinition;

package/dist/src/tools_trace_span.js

@@ -0,0 +1,56 @@
+import { id } from "./utils.js";
+export function makeTraceSpanTool(writer, ctx) {
+    return {
+        name: "trace.span",
+        description: "Start or end a manual span to capture custom business phases.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                op: { type: "string", enum: ["start", "end"] },
+                spanId: { type: "string" },
+                name: { type: "string" },
+                kind: { type: "string", enum: ["manual", "message", "model", "tool", "skill"], default: "manual" },
+                status: { type: "string", enum: ["ok", "error", "unknown"], default: "ok" },
+                attrs: { type: "object" },
+            },
+            required: ["op"],
+        },
+        async handler(args, runtime) {
+            const ts = runtime.ts ?? Date.now();
+            const sessionId = String(runtime.sessionId ?? runtime.agentId ?? "unknown-session");
+            const op = String(args.op);
+            if (op === "start") {
+                const spanId = String(args.spanId ?? id());
+                const parentSpanId = ctx.current(sessionId)?.spanId;
+                const kind = args.kind ?? "manual";
+                const name = String(args.name ?? "manual-span");
+                writer.write({
+                    type: "span_start",
+                    ts,
+                    spanId,
+                    sessionId,
+                    parentSpanId,
+                    kind,
+                    name,
+                    attrs: args.attrs ?? {},
+                });
+                ctx.push(sessionId, { spanId, kind, name, startedAt: ts });
+                return { ok: true, spanId };
+            }
+            const explicitSpanId = args.spanId ? String(args.spanId) : undefined;
+            const currentSpanId = ctx.current(sessionId)?.spanId;
+            const spanId = explicitSpanId ?? currentSpanId ?? id();
+            const frame = currentSpanId ? ctx.pop(sessionId, spanId) : undefined;
+            writer.write({
+                type: "span_end",
+                ts,
+                spanId,
+                sessionId,
+                status: args.status ?? "ok",
+                durationMs: frame ? ts - frame.startedAt : undefined,
+                attrs: args.attrs ?? {},
+            });
+            return { ok: true, spanId };
+        },
+    };
+}

package/dist/src/trace_record.d.ts

@@ -0,0 +1,67 @@
+export type TraceLevel = "info" | "warn" | "error";
+export type TraceKind = "tool" | "skill" | "model" | "message" | "manual";
+export type TraceStatus = "ok" | "error" | "unknown";
+export type TraceRecord = {
+    type: "capture_start";
+    captureId: string;
+    ts: number;
+    attrs?: Record<string, unknown>;
+} | {
+    type: "capture_end";
+    captureId: string;
+    ts: number;
+} | {
+    type: "session";
+    op: "upsert";
+    ts: number;
+    sessionId: string;
+    parentSessionId?: string;
+    label?: string;
+    attrs?: Record<string, unknown>;
+} | {
+    type: "span_start";
+    ts: number;
+    spanId: string;
+    sessionId: string;
+    parentSpanId?: string;
+    kind: TraceKind;
+    name: string;
+    attrs?: Record<string, unknown>;
+} | {
+    type: "span_end";
+    ts: number;
+    spanId: string;
+    sessionId: string;
+    status: TraceStatus;
+    durationMs?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    attrs?: Record<string, unknown>;
+} | {
+    type: "tracepoint";
+    ts: number;
+    tpId: string;
+    sessionId: string;
+    parentSpanId?: string;
+    name: string;
+    level: TraceLevel;
+    attrs?: Record<string, unknown>;
+    links?: Array<Record<string, unknown>>;
+} | {
+    type: "marker";
+    ts: number;
+    label: string;
+    sessionId?: string;
+    attrs?: Record<string, unknown>;
+} | {
+    type: "counter";
+    ts: number;
+    name: string;
+    sessionId?: string;
+    value: number;
+    attrs?: Record<string, unknown>;
+};
+export interface TraceUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+}

package/dist/src/trace_record.js

@@ -0,0 +1 @@
+export {};

package/dist/src/tracekit_plugin.d.ts

@@ -0,0 +1,31 @@
+import { type SessionEndEvent, type SessionStartEvent } from "./hooks_session.js";
+import { type ToolEndEvent, type ToolStartEvent } from "./hooks_tool.js";
+import type { TraceToolDefinition } from "./plugin_types.js";
+export interface TraceKitConfig {
+    enabled?: boolean;
+    outPath?: string;
+    includeCounterTool?: boolean;
+    includeSpanTool?: boolean;
+    attrs?: Record<string, unknown>;
+}
+export interface TraceKitPlugin {
+    hooks: {
+        onToolStart: (ev: ToolStartEvent) => void;
+        onToolEnd: (ev: ToolEndEvent) => void;
+        onSessionStart: (ev: SessionStartEvent) => void;
+        onSessionEnd: (ev: SessionEndEvent) => void;
+    };
+    tools: TraceToolDefinition[];
+    shutdown: () => Promise<void>;
+    api: {
+        emitTracepoint: (input: {
+            sessionId: string;
+            name: string;
+            level?: "info" | "warn" | "error";
+            attrs?: Record<string, unknown>;
+            links?: Array<Record<string, unknown>>;
+            ts?: number;
+        }) => Promise<string>;
+    };
+}
+export declare function createTraceKitPlugin(config?: TraceKitConfig): TraceKitPlugin;

package/dist/src/tracekit_plugin.js

@@ -0,0 +1,68 @@
+import { resolve } from "node:path";
+import { NDJSONWriter } from "./ndjson_writer.js";
+import { SpanContext } from "./span_context.js";
+import { makeSessionHooks } from "./hooks_session.js";
+import { makeToolHooks } from "./hooks_tool.js";
+import { makeTraceCounterTool } from "./tools_trace_counter.js";
+import { makeTraceEmitTool } from "./tools_trace_emit.js";
+import { makeTraceSpanTool } from "./tools_trace_span.js";
+import { id } from "./utils.js";
+export function createTraceKitPlugin(config = {}) {
+    const enabled = config.enabled ?? true;
+    const outPath = resolve(config.outPath ?? "./trace.ndjson");
+    const writer = new NDJSONWriter(outPath);
+    const ctx = new SpanContext();
+    const captureId = id();
+    if (enabled) {
+        writer.write({
+            type: "capture_start",
+            captureId,
+            ts: Date.now(),
+            attrs: {
+                plugin: "tracekit",
+                outPath,
+                ...config.attrs,
+            },
+        });
+    }
+    const toolHooks = makeToolHooks(writer, ctx);
+    const sessionHooks = makeSessionHooks(writer, ctx);
+    const tools = [makeTraceEmitTool(writer, ctx)];
+    if (config.includeCounterTool ?? true)
+        tools.push(makeTraceCounterTool(writer));
+    if (config.includeSpanTool ?? true)
+        tools.push(makeTraceSpanTool(writer, ctx));
+    return {
+        hooks: {
+            onToolStart: enabled ? toolHooks.onToolStart : () => undefined,
+            onToolEnd: enabled ? toolHooks.onToolEnd : () => undefined,
+            onSessionStart: enabled ? sessionHooks.onSessionStart : () => undefined,
+            onSessionEnd: enabled ? sessionHooks.onSessionEnd : () => undefined,
+        },
+        tools,
+        shutdown: async () => {
+            if (!enabled)
+                return;
+            await writer.write({ type: "capture_end", captureId, ts: Date.now() });
+            await writer.flush();
+            await writer.close();
+        },
+        api: {
+            emitTracepoint: async (input) => {
+                const tpId = id();
+                await writer.write({
+                    type: "tracepoint",
+                    ts: input.ts ?? Date.now(),
+                    tpId,
+                    sessionId: input.sessionId,
+                    parentSpanId: ctx.current(input.sessionId)?.spanId,
+                    name: input.name,
+                    level: input.level ?? "info",
+                    attrs: input.attrs ?? {},
+                    links: input.links ?? [],
+                });
+                return tpId;
+            },
+        },
+    };
+}

package/dist/src/utils.d.ts

@@ -0,0 +1,7 @@
+export declare function now(): number;
+export declare function id(): string;
+export declare function safeError(err: unknown): Record<string, unknown>;
+export declare function safeStringify(input: unknown): string;
+export declare function redactSecrets(raw: string): string;
+export declare function preview(input: unknown, max?: number): string;
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;

package/dist/src/utils.js

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+const SECRET_PATTERNS = [
+    /sk-[a-zA-Z0-9]{20,}/g,
+    /api[_-]?key["']?\s*[:=]\s*["'][^"']+["']/gi,
+    /authorization["']?\s*[:=]\s*["'][^"']+["']/gi,
+    /password["']?\s*[:=]\s*["'][^"']+["']/gi,
+];
+export function now() {
+    return Date.now();
+}
+export function id() {
+    return randomUUID();
+}
+export function safeError(err) {
+    if (err instanceof Error) {
+        return {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+        };
+    }
+    return { value: String(err) };
+}
+export function safeStringify(input) {
+    try {
+        return JSON.stringify(input);
+    }
+    catch {
+        return String(input);
+    }
+}
+export function redactSecrets(raw) {
+    let result = raw;
+    for (const pattern of SECRET_PATTERNS) {
+        result = result.replace(pattern, "[REDACTED]");
+    }
+    return result;
+}
+export function preview(input, max = 800) {
+    const compact = redactSecrets(safeStringify(input));
+    return compact.length > max ? `${compact.slice(0, max)}...` : compact;
+}
+export function asRecord(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    return value;
+}

package/docs/installation.md

@@ -0,0 +1,123 @@
+# TraceKit 安装指南（OpenCode）
+
+本文用于在 OpenCode 中安装并启用 `tracekit` 插件，让你可以采集 `agent/skill/tool` 的 trace。
+
+## 1. 前置条件
+
+- Node.js `>= 20`
+- OpenCode 可用的插件注册入口（代码注册或配置注册）
+
+## 2. 安装方式
+
+### 方式 A：项目内源码安装（推荐）
+
+适合你当前这个仓库，最快可用。
+
+```bash
+cd plugins/tracekit
+npm install
+npm run build
+```
+
+然后在 OpenCode 启动代码里注册：
+
+```ts
+import { createTraceKitPlugin } from "./plugins/tracekit/dist/index.js";
+
+const tracekit = createTraceKitPlugin({
+  outPath: "./trace.ndjson",
+  includeCounterTool: true,
+  includeSpanTool: true,
+});
+
+opencode.registerPlugin({
+  hooks: tracekit.hooks,
+  tools: tracekit.tools,
+  shutdown: tracekit.shutdown,
+});
+```
+
+### 方式 B：独立目录安装（多项目复用）
+
+把 `plugins/tracekit` 放到你的公共插件目录，再在各项目的 OpenCode 启动入口中 `import` 该目录的 `dist/index.js` 注册即可。
+
+```bash
+cd /path/to/tracekit
+npm install
+npm run build
+```
+
+### 方式 C：npm 包安装（最简）
+
+发布后可直接安装：
+
+```bash
+npm install opencode-tracekit
+```
+
+在 OpenCode 配置中按包名启用（示例）：
+
+```json
+{
+  "plugin": ["opencode-tracekit"]
+}
+```
+
+## 3. 启动后验证
+
+1. 启动 OpenCode 会话，执行一次会触发 tool/skill 的任务。  
+2. 检查是否生成 `trace.ndjson`。  
+3. 检查是否有以下记录类型：
+- `capture_start`
+- `span_start` / `span_end`
+- `tracepoint`（调用 `trace.emit` 后出现）
+
+你也可以用内置 CLI 验证：
+
+```bash
+cd plugins/tracekit
+node dist/src/cli.js analyze ./trace.ndjson
+```
+
+## 4. 在 Agent/Skill 中使用打点工具
+
+```json
+{ "tool": "trace.emit", "args": { "name": "agent.plan.generated", "level": "info" } }
+```
+
+```json
+{ "tool": "trace.span", "args": { "op": "start", "name": "ipd.phase.spec" } }
+```
+
+```json
+{ "tool": "trace.counter", "args": { "name": "token.estimate", "value": 128 } }
+```
+
+## 5. 导出与分析
+
+```bash
+cd plugins/tracekit
+
+# 分析
+node dist/src/cli.js analyze ./trace.ndjson
+
+# 导出 JSON
+node dist/src/cli.js export ./trace.ndjson --out ./trace.json --format json
+
+# 导出 CSV
+node dist/src/cli.js export ./trace.ndjson --out ./trace.csv --format csv
+```
+
+## 6. 常见问题
+
+- 没有生成 `trace.ndjson`：
+  - 确认 `createTraceKitPlugin({ enabled: true })`
+  - 确认插件已真正注册到 OpenCode runtime
+  - 确认进程结束前调用了 `shutdown`
+
+- 有 `span_start` 没有 `span_end`：
+  - 检查 runtime 是否正确触发了 `onToolEnd`
+  - 检查 `toolCallId` 是否在 start/end 事件里一致
+
+- `trace.emit` 不可用：
+  - 检查 `tools: tracekit.tools` 是否传入 runtime

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "opencode-tracekit",
+  "version": "0.1.0",
+  "description": "Tracepoint and tracing plugin for OpenCode (agent/skill/tool spans, emit/export/analyze).",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "tracectl": "dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs/installation.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "opencode",
+    "trace",
+    "tracepoint",
+    "plugin",
+    "observability"
+  ],
+  "author": "jiqi",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  }
+}