build out OTel plugin with full telemetry, modular structure, and docs

- Implement OTLP/gRPC export for metrics and log events mirroring Claude Code telemetry
- Add session, message, permission, activity event handlers in src/handlers/
- Add src/types.ts, src/config.ts, src/otel.ts, src/probe.ts, src/util.ts
- Add root index.ts re-export for local plugin path
- Fix double-counting, async shutdown, log level gating, memory leaks
- Add README.md, AGENTS.md, CONTRIBUTING.md

Author: dialupdisaster

AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+Instructions for AI agents working in this repository.
+
+## Build & typecheck
+
+Always run after making changes:
+
+```bash
+bun run typecheck
+```
+
+There is no separate build step needed for local development. For publishing:
+
+```bash
+bun run build
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+## Project layout
+
+```
+src/
+├── index.ts              — Plugin entrypoint
+├── types.ts              — Shared types
+├── config.ts             — Env config and log level
+├── otel.ts               — OTel SDK setup and instruments
+├── probe.ts              — OTLP endpoint TCP probe
+├── util.ts               — errorSummary, setBoundedMap
+└── handlers/
+    ├── session.ts        — Session lifecycle events
+    ├── message.ts        — LLM message and tool part events
+    ├── permission.ts     — Tool permission events
+    └── activity.ts       — File diffs and git commits
+```
+
+## Key conventions
+
+- **Bun over Node** — use `bun`, `bun test`, `bun run`. Never use `node`, `npx`, `jest`, or `vitest`.
+- **No comments** unless explicitly requested.
+- **No `sdk-node`** — the OTel Node SDK meta-package is intentionally excluded; use individual packages.
+- **`HandlerContext`** — all event handlers receive a `HandlerContext` (defined in `src/types.ts`). Do not import `client` or OTel globals directly inside handlers; thread them through the context.
+- **`setBoundedMap`** — always use this instead of `Map.set` for `pendingToolSpans` and `pendingPermissions` to prevent unbounded growth.
+- **Single source of truth for tokens/cost** — token and cost counters are incremented only in `message.updated` (`src/handlers/message.ts`), never in `step-finish`.
+- **Shutdown** — OTel providers are flushed via `SIGTERM`/`SIGINT`/`beforeExit`. Do not use `process.on("exit")` for async flushing.
+- **`OPENCODE_ENABLE_TELEMETRY`** — all OTel instrumentation is gated on this env var. The plugin always loads regardless; only telemetry is disabled when unset.

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+## Prerequisites
+
+- [Bun](https://bun.sh) v1.0+
+- An opencode installation for manual testing
+
+## Getting started
+
+```bash
+git clone https://github.com/devtheops/opencode-plugin-otel
+cd opencode-plugin-otel
+bun install
+```
+
+## Development workflow
+
+Point your local opencode config at the repo so changes are picked up immediately without a build step. In `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["/path/to/opencode-plugin-otel/index.ts"]
+}
+```
+
+opencode loads TypeScript natively via Bun, so there is no build step required during development.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `bun run typecheck` | Type-check all sources without emitting |
+| `bun test` | Run the test suite |
+| `bun run build` | Compile to `dist/` for publishing |
+
+## Project structure
+
+```
+src/
+├── index.ts              — Plugin entrypoint, wires everything together
+├── types.ts              — Shared types (Level, HandlerContext, Instruments, etc.)
+├── config.ts             — Environment config loading and log level resolution
+├── otel.ts               — OTel SDK setup, resource construction, instrument creation
+├── probe.ts              — TCP connectivity probe for the OTLP endpoint
+├── util.ts               — Utility functions (errorSummary, setBoundedMap)
+└── handlers/
+    ├── session.ts        — session.created / session.idle / session.error
+    ├── message.ts        — message.updated / message.part.updated
+    ├── permission.ts     — permission.updated / permission.replied
+    └── activity.ts       — session.diff / command.executed
+```
+
+## Testing locally with a collector
+
+The easiest way to verify telemetry is being emitted is to run a local OpenTelemetry collector:
+
+```bash
+docker run --rm -p 4317:4317 \
+  otel/opentelemetry-collector:latest
+```
+
+Then set `OPENCODE_ENABLE_TELEMETRY=1` and start opencode. The collector will print received spans and metrics to stdout.
+
+## Submitting changes
+
+1. Fork the repo and create a branch: `git checkout -b my-feature`
+2. Make your changes and ensure `bun run typecheck` passes
+3. Open a pull request with a clear description of what changed and why
+
+## Releasing
+
+Releases are handled via GitHub Actions. See [the release workflow](.github/workflows/release.yml). To cut a release, push a version tag:
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```

README.md

@@ -1,15 +1,92 @@
 # opencode-plugin-otel
 
-To install dependencies:
+An [opencode](https://opencode.ai) plugin that exports telemetry via OpenTelemetry (OTLP/gRPC), mirroring the same signals as [Claude Code's monitoring](https://code.claude.com/docs/en/monitoring-usage).
+
+## What it instruments
+
+### Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `opencode.session.count` | Counter — incremented on each `session.created` event |
+| `opencode.token.usage` | Counter — per token type: `input`, `output`, `reasoning`, `cacheRead`, `cacheCreation` |
+| `opencode.cost.usage` | Counter — USD cost per completed assistant message |
+| `opencode.lines_of_code.count` | Counter — lines added/removed per `session.diff` event |
+| `opencode.commit.count` | Counter — git commits detected via bash tool |
+| `opencode.tool.duration` | Histogram — tool execution time in milliseconds |
+
+### Log events
+
+| Event | Description |
+|-------|-------------|
+| `session.created` | Session started |
+| `session.idle` | Session went idle |
+| `session.error` | Session error |
+| `user_prompt` | User sent a message (includes `prompt_length`, `model`, `agent`) |
+| `api_request` | Completed assistant message (tokens, cost, duration) |
+| `api_error` | Failed assistant message (error summary, duration) |
+| `tool_result` | Tool completed or errored (duration, success, output size) |
+| `tool_decision` | Permission prompt answered (accept/reject) |
+| `commit` | Git commit detected |
+
+## Installation
+
+Add the plugin to your opencode config at `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-plugin-otel"]
+}
+```
+
+Or point directly at a local checkout for development:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["/path/to/opencode-plugin-otel/index.ts"]
+}
+```
+
+## Configuration
+
+All configuration is via environment variables. Set them in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.).
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_ENABLE_TELEMETRY` | _(unset)_ | Set to any non-empty value to enable the plugin |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | gRPC OTLP collector endpoint |
+| `OTEL_EXPORTER_OTLP_HEADERS` | _(none)_ | Comma-separated `key=value` auth headers, e.g. `api-key=abc123` |
+| `OTEL_METRIC_EXPORT_INTERVAL` | `60000` | Metrics export interval in milliseconds |
+| `OTEL_LOGS_EXPORT_INTERVAL` | `5000` | Logs export interval in milliseconds |
+| `OTEL_RESOURCE_ATTRIBUTES` | _(none)_ | Extra resource attributes, e.g. `team=platform,env=prod` |
+
+### Quick start
 
 ```bash
-bun install
+export OPENCODE_ENABLE_TELEMETRY=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+opencode
 ```
 
-To run:
+### Datadog example
 
 ```bash
-bun run index.ts
+export OPENCODE_ENABLE_TELEMETRY=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com
+export OTEL_EXPORTER_OTLP_HEADERS=dd-api-key=YOUR_API_KEY
+export OTEL_RESOURCE_ATTRIBUTES=team=platform,env=prod
 ```
 
-This project was created using `bun init` in bun v1.3.10. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### Honeycomb example
+
+```bash
+export OPENCODE_ENABLE_TELEMETRY=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+export OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=YOUR_API_KEY
+```
+
+## Local development
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).