opencode-agent-trace-plugin

Plugin-only Agent Trace logging for OpenCode. This repository no longer ships a telemetry gateway or SSE fanout service.

Architecture

1. OpenCode loads plugin/trace-logger.ts.
2. Plugin captures tool/session/message/command lifecycle events.
3. Events are batched and written to project Postgres.
4. Canonical records follow the Agent Trace record structure (version, id, timestamp, files, conversations, ranges).

Install

npm install
npm run build

Install From Another Repo (Recommended)

In your OpenCode service repository:

# From npm (preferred)
npm i opencode-agent-trace-plugin

# Or from GitHub ref/tag
npm i github:<org>/opencode-logging#v0.2.0

Create a local plugin shim file (for example ./.opencode/plugins/agent-trace.mjs):

export { TraceLoggerPlugin as default } from "opencode-agent-trace-plugin/trace-logger";

Then register the shim in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["./.opencode/plugins/agent-trace.mjs"]
}

Configure OpenCode

Copy opencode.example.json into your project as opencode.json and adjust plugin path if needed:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["./plugin/trace-logger.ts"]
}

Environment Variables

AGENT_TRACE_ENABLED=true
DATABASE_URL=postgres://user:pass@host:5432/db
AGENT_TRACE_DATABASE_URL=postgres://user:pass@host:5432/db # optional override
AGENT_TRACE_BATCH_SIZE=50
AGENT_TRACE_FLUSH_MS=500
AGENT_TRACE_RETRY_MAX=5
AGENT_TRACE_REDACTION=on
AGENT_TRACE_SPEC_VERSION=0.1.0
AGENT_TRACE_TOOL_NAME=opencode
AGENT_TRACE_TOOL_VERSION=local

Database Migrations

Run SQL migrations against your existing project Postgres:

psql "$DATABASE_URL" -f sql/001_agent_trace_tables.sql
psql "$DATABASE_URL" -f sql/002_agent_trace_indexes.sql

If installing as a dependency from another repo, run migrations from node_modules:

psql "$DATABASE_URL" -f node_modules/opencode-agent-trace-plugin/sql/001_agent_trace_tables.sql
psql "$DATABASE_URL" -f node_modules/opencode-agent-trace-plugin/sql/002_agent_trace_indexes.sql

Captured Hooks

• tool.execute.before
• tool.execute.after
• event stream for:
  • session.created
  • session.updated
  • session.error
  • message.created
  • message.updated
  • message.part.updated
  • command.executed

Record Semantics

• Contributor default: ai
• Model IDs normalized to provider/model when possible
• VCS metadata attempts git rev-parse HEAD
• File ranges prefer explicit line data, then content localization, then fallback line spans
• Hashes are currently stored as blake2s:<digest> using Node's built-in crypto support
• Implementation metadata is namespaced under io.opencode.*

Privacy and Reliability

• Optional redaction masks common secret/token patterns before persistence
• Writes are batched with bounded in-memory queue
• Retry with exponential backoff on transient DB failures
• Event dedupe via agent_trace_dedupe(event_id)

Development

npm run typecheck
npm run test
npm run build

Release Checklist

npm run typecheck
npm run test
npm version patch   # or minor/major
git push --follow-tags

Example Emitted Record

{
  "version": "0.1.0",
  "id": "7d53ed3a-6d5e-4f20-b49f-0be03f0c62ac",
  "timestamp": "2026-02-16T10:00:00.000Z",
  "vcs": {
    "type": "git",
    "revision": "abc123..."
  },
  "tool": {
    "name": "opencode",
    "version": "local"
  },
  "files": [
    {
      "path": "src/app.ts",
      "conversations": [
        {
          "contributor": {
            "type": "ai",
            "model_id": "openai/gpt-4o"
          },
          "ranges": [
            {
              "start_line": 12,
              "end_line": 20,
              "content_hash": "blake2s:..."
            }
          ]
        }
      ]
    }
  ],
  "metadata": {
    "io.opencode.event_name": "tool.execute.after"
  }
}

Spec Tracking

• Track Agent Trace upstream changes as additive updates where possible.
• For breaking changes, bump AGENT_TRACE_SPEC_VERSION and add a SQL/data migration.
• Keep backwards parsers for prior versions during rollout windows.