oh-my-openagent 4.5.12 → 4.7.0

package/.agents/skills/opencode-qa/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: opencode-qa
+description: "QA opencode itself, per case: verify the CLI/terminal (opencode run, db, serve, export), prove a specific plugin hook/action/event fired via the SSE event stream, smoke-test the TUI under tmux, and investigate sessions in opencode's SQLite DB by id, title/name, or message text. Ships tested helper scripts (each with a --self-test) plus per-domain references. Use whenever someone wants to QA, smoke-test, verify, or debug opencode's CLI, HTTP server, plugin hooks/events, or TUI, or to find/inspect opencode sessions in the database. Triggers: opencode qa, qa opencode, test opencode, verify opencode hook, opencode session db, find opencode session by id/name/text, opencode tui test, opencode server health, opencode event stream."
+---
+
+# opencode QA
+
+QA the opencode coding agent itself. This skill maps each QA need to a tested
+helper script and a deep reference. Every script ships a `--self-test` that
+asserts its scenario against the live machine, so the scripts are both the QA
+tools and their own regression checks.
+
+Verified against opencode v1.15.13 (bun 1.3.12, macOS). Confirm the installed
+version with `opencode --version`; the surface is stable but always sanity
+check a flag with `opencode <cmd> --help`.
+
+## Golden rules (read before running anything)
+
+- READS of the live DB are safe and intended. Investigating sessions (Case D)
+  only reads `~/.local/share/opencode/opencode.db`.
+- Anything that SPAWNS opencode (serve, run, the TUI) must use an isolated XDG
+  sandbox so QA never writes junk sessions into the real DB. The bundled
+  scripts already do this; if you run opencode by hand for QA, set
+  `XDG_DATA_HOME` / `XDG_CONFIG_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` to
+  temp dirs first.
+- Global text search over the `part` table is a multi-GB scan. Always scope it
+  (`--session`, `--recent`, or `--since`). The text script refuses an
+  unbounded scan on purpose.
+- The opencode source repo (`packages/opencode`) tests itself with `bun test`
+  and CANNOT run tests from the repo root. See `references/testing-harness.md`.
+
+## Setup
+
+Scripts live next to this file under `scripts/`. Invoke them from this skill
+directory (or with their absolute path):
+
+```bash
+cd <this-skill-dir>                        # .agents/skills/opencode-qa
+bash scripts/lib/common.sh --self-check    # confirm the harness + deps
+```
+
+`common.sh` provides the shared harness (DB path, SQL escaping, isolated XDG
+sandbox, free port, server start/stop, and an EXIT-trap cleanup). It requires
+`opencode`, `sqlite3`, `curl`, `jq`, and `tmux` on PATH.
+
+## Router: pick your case
+
+| You want to... | Case | Script | Reference |
+|---|---|---|---|
+| Run opencode non-interactively / check a CLI command | A | `opencode run --format json` (inline) | `references/cli-commands.md` |
+| Find a session by its id | D | `scripts/db-session-by-id.sh <ses_id>` | `references/db-investigation.md` |
+| Find sessions by title/name | D | `scripts/db-session-by-name.sh "<text>"` | `references/db-investigation.md` |
+| Find sessions by message text | D | `scripts/db-session-by-text.sh --recent N "<text>"` | `references/db-investigation.md` |
+| Export a whole session as JSON | D | `scripts/export-roundtrip.sh <ses_id>` | `references/db-investigation.md` |
+| Check the HTTP server / an endpoint | B | `scripts/server-smoke.sh` | `references/server-api.md` |
+| Prove a hook / action / event fired | B | `scripts/sse-hook-probe.sh` | `references/events-hooks.md` |
+| Smoke-test the TUI | C | `scripts/tui-smoke.sh` | `references/tui-tmux.md` |
+| Write/run a test in the opencode source | - | (bun test) | `references/testing-harness.md` |
+| Drive opencode from a Bun/TS script | - | (SDK) | `references/sdk.md` |
+
+## Case A: CLI / terminal works
+
+The canonical scriptable, non-interactive entry is `opencode run`. JSON mode
+emits one event per line so you can assert on it.
+
+```bash
+# stream structured events (types: text, tool_use, step_start, step_finish, reasoning, error)
+opencode run "list files in src" --format json
+# run a slash command
+opencode run --command commit
+# resume the last session
+opencode run -c "continue"
+# target an already-running server instead of booting one
+opencode run "explain auth" --attach http://127.0.0.1:4096 -p "$OPENCODE_SERVER_PASSWORD"
+```
+
+Other QA-useful commands: `opencode db path`, `opencode debug paths`,
+`opencode session list --format json`, `opencode models --verbose`. Full flag
+detail in `references/cli-commands.md`.
+
+## Case B: a specific hook, action, or event
+
+opencode publishes lifecycle events over Server-Sent Events at `GET /event`.
+Plugins observe the same events via the `event` hook, so seeing an event on the
+wire proves a hook would fire.
+
+```bash
+# prove the SSE plumbing works (isolated server, asserts server.connected)
+bash scripts/sse-hook-probe.sh --self-test
+
+# watch a REAL server for a specific event while you trigger an action
+bash scripts/sse-hook-probe.sh --attach http://127.0.0.1:4096 \
+  --password "$OPENCODE_SERVER_PASSWORD" --directory "$PWD" \
+  --event message.part.updated --timeout 30
+```
+
+Trigger an action over HTTP (fire-and-forget so the stream is not blocked):
+
+```bash
+curl -X POST -u opencode:$OPENCODE_SERVER_PASSWORD -H 'Content-Type: application/json' \
+  -d '{"parts":[{"type":"text","text":"say hi"}]}' \
+  "http://127.0.0.1:4096/session/<ses_id>/prompt_async?directory=$PWD"
+```
+
+A real prompt needs a configured provider, so run the watch-and-trigger pattern
+against your real server, not the isolated sandbox. Event-type catalog, the 21
+plugin hook points, and how to load a local plugin: `references/events-hooks.md`.
+Server start, auth, and routes: `references/server-api.md`.
+
+## Case C: the TUI
+
+```bash
+bash scripts/tui-smoke.sh --self-test
+```
+
+This launches the TUI under tmux in an isolated sandbox, confirms it renders
+(`capture-pane`), confirms `send-keys` reaches the composer, tears the tmux
+session down, and verifies the real DB session count is unchanged.
+
+Honest verdict: tmux is fine for SMOKE (did it boot, render, accept a key) but
+fragile for asserting conversation output (the TUI is a 60fps full-screen app).
+For real behavior assertions use Case A (`opencode run`), Case B (server API +
+SSE), or the TUI control HTTP API (`POST /tui/append-prompt`,
+`POST /tui/submit-prompt`, `POST /tui/execute-command`). Details and the manual
+tmux recipe: `references/tui-tmux.md`.
+
+## Case D: investigate sessions in the DB
+
+Read-only against the live SQLite DB. The `session` table is small (title and
+id lookups are instant); message text lives in the multi-GB `part` table, so
+text search must be scoped.
+
+```bash
+# by id
+bash scripts/db-session-by-id.sh ses_3a4ee6335ffedFB8f76BPU1Eb3
+# by title / name (newest first; second arg = limit)
+bash scripts/db-session-by-name.sh "auth refactor" 20
+# by message text - scope with --session, --recent N, or --since "<window>"
+bash scripts/db-session-by-text.sh --session ses_3a4e... "ULTRAWORK"
+bash scripts/db-session-by-text.sh --recent 50 "permission denied"
+bash scripts/db-session-by-text.sh --since "7 days" --limit 50 "TODO"
+# export an entire session as clean JSON
+bash scripts/export-roundtrip.sh ses_3a4e... > session.json
+```
+
+Ad hoc queries: `opencode db "<SQL>" --format json`. Schema, tested query
+shapes with timings, the legacy `message`/`part` vs V2 `session_message`
+distinction, and the 25 GB caveat: `references/db-investigation.md`.
+
+## Scripts index
+
+Run any script with `--self-test` to verify it against the live machine, or
+`-h` for usage. DB-read scripts are read-only; serve/sse/tui scripts use an
+isolated sandbox and clean up on exit.
+
+| Script | Case | Self-test asserts |
+|---|---|---|
+| `scripts/lib/common.sh --self-check` | - | deps present, DB path resolves, SQL escaping, free port, sandbox auto-removed |
+| `scripts/db-session-by-id.sh` | D | id round-trips for a real session |
+| `scripts/db-session-by-name.sh` | D | a derived title needle returns >=1 row |
+| `scripts/db-session-by-text.sh` | D | scoped search hits; unbounded scan refused; bounded search <30s |
+| `scripts/export-roundtrip.sh` | D | export stdout is valid JSON and `.info.id` round-trips |
+| `scripts/server-smoke.sh` | B | `/global/health` healthy, `/doc` >=100 paths, no-auth -> 401 |
+| `scripts/sse-hook-probe.sh` | B | `/event` opens and delivers `server.connected` |
+| `scripts/tui-smoke.sh` | C | TUI renders under tmux, tears down, real DB untouched |
+
+## Risks and caveats
+
+- 25 GB part table: never run an unbounded text scan. Use `--session`,
+  `--recent`, or `--since`. A naive `JOIN ... WHERE session.time_created >= X`
+  scans oldest-first and can take ~50s; the scripts use an `IN`-subquery on the
+  newest sessions (~20ms).
+- `opencode export` writes its banner to STDERR; pipe with `2>/dev/null` before
+  `jq` or you will get a parse error.
+- The server enforces auth only when `OPENCODE_SERVER_PASSWORD` is set;
+  otherwise it runs unsecured. Authenticated calls use `-u opencode:$PASS`.
+  Unauthenticated calls to a secured server return HTTP 401.
+- Installed binary vs dev source: cite dev source paths for internals but
+  verify flags against the installed `opencode <cmd> --help`.
+- Isolation: any QA that spawns opencode must use an isolated XDG sandbox so it
+  never pollutes the real DB. Prove it by comparing
+  `sqlite3 "$(opencode db path)" "SELECT count(*) FROM session"` before and
+  after.
+- TUI output assertions are fragile; use the API for real assertions.
+
+## References
+
+- `references/cli-commands.md` - every QA-relevant opencode subcommand and flag
+- `references/db-investigation.md` - DB schema, tested queries, the 25 GB caveat
+- `references/server-api.md` - server start, auth, route catalog, /doc
+- `references/events-hooks.md` - SSE endpoints, event types, plugin hooks
+- `references/tui-tmux.md` - tmux recipe, isolation, TUI control API
+- `references/testing-harness.md` - how opencode tests itself (bun test)
+- `references/sdk.md` - the @opencode-ai/sdk client (reference only)

package/.agents/skills/opencode-qa/references/cli-commands.md

@@ -0,0 +1,188 @@
+# opencode CLI for QA (Case A: terminal works)
+
+The installed binary is `opencode` (v1.15.13). From the source repo you can also run `bun run --conditions=browser ./src/index.ts <cmd>` inside `packages/opencode`. The canonical non-interactive QA entry is `opencode run --format json`.
+
+## Global flags
+
+```
+--print-logs
+--log-level DEBUG|INFO|WARN|ERROR
+--pure                    (run without external plugins)
+-h, --help
+-v, --version
+```
+
+## `opencode run` (non-interactive QA core)
+
+Positional message. Key flags:
+
+```
+-m, --model <provider/model>
+--agent <name>
+-s, --session <ses_...>
+-c, --continue
+--fork
+--format default|json
+-f, --file <path>
+--title
+--attach <url>
+-p, --password
+-u, --username
+--dir
+--variant
+--thinking
+-i, --interactive
+--dangerously-skip-permissions
+--command <slash-cmd>
+```
+
+`--format json` emits NDJSON, one JSON object per line, each shaped like:
+
+```json
+{"type":"...", "timestamp":<ms>, "sessionID":"ses_...", ...}
+```
+
+`type` is one of: `text`, `tool_use`, `step_start`, `step_finish`, `reasoning`, `error`. The process exits when the session goes idle.
+
+Validation rules:
+
+- `-i` cannot combine with `--command` or `--format json`
+- `--fork` needs `-c` or `-s`
+
+Examples:
+
+```bash
+opencode run "list the files in src" --format json
+```
+
+```bash
+opencode run --command commit
+```
+
+```bash
+opencode run -c "continue the previous task"
+```
+
+```bash
+opencode run "explain auth" --attach http://127.0.0.1:4096 -p "$OPENCODE_SERVER_PASSWORD"
+```
+
+## `opencode db` (database tools)
+
+```bash
+opencode db path
+```
+
+Prints the active DB file path.
+
+```bash
+opencode db "<SQL>" --format json
+```
+
+Runs a query and prints JSON rows. Use `--format tsv` (default) for TSV output.
+
+```bash
+opencode db
+```
+
+Opens an interactive sqlite3 shell.
+
+```bash
+opencode db migrate
+```
+
+Migrates legacy JSON storage into SQLite.
+
+Bundled scripts for session investigation:
+
+- `scripts/db-session-by-id.sh`
+- `scripts/db-session-by-name.sh`
+- `scripts/db-session-by-text.sh`
+- `scripts/export-roundtrip.sh`
+
+Full detail in `references/db-investigation.md`.
+
+## `opencode session`
+
+```bash
+opencode session list --format json
+```
+
+Lists sessions as JSON.
+
+```bash
+opencode session delete <ses_id>
+```
+
+Deletes one session.
+
+## `opencode export [sessionID]`
+
+Prints "Exporting session: ..." to STDERR and a clean JSON document `{info:{...}, messages:[...]}` to STDOUT. Always redirect STDERR before piping to jq.
+
+Example:
+
+```bash
+opencode export ses_3a4e... 2>/dev/null | jq '.info.id'
+```
+
+Bundled wrapper:
+
+```bash
+scripts/export-roundtrip.sh <ses_id>
+```
+
+## `opencode serve`
+
+Starts a headless HTTP server.
+
+Flags:
+
+```
+--port            (0 = pick 4096 then a free port)
+--hostname        (default 127.0.0.1)
+--mdns
+--mdns-domain
+--cors
+```
+
+On start it prints:
+
+```
+opencode server listening on http://<host>:<port>
+```
+
+Set `OPENCODE_SERVER_PASSWORD` to require auth. See `references/server-api.md`.
+
+Bundled smoke test:
+
+```bash
+scripts/server-smoke.sh
+```
+
+## `opencode debug`
+
+Useful subcommands:
+
+```bash
+opencode debug paths    # data/config/cache/state dirs
+opencode debug info     # version, OS, terminal, plugins
+```
+
+Others: `config`, `lsp`, `ripgrep`, `file`, `skill`, `snapshot`, `agent`, `v2`, `wait`.
+
+## Other commands
+
+```bash
+opencode models [provider] --verbose
+opencode stats
+opencode providers list          # alias: auth
+opencode mcp list
+opencode generate                # prints the OpenAPI JSON spec
+```
+
+## Installed binary vs dev source (IMPORTANT note box)
+
+The installed `opencode` (v1.15.13) matches the dev source in `packages/opencode`. When citing internals, cite dev source paths but always verify a flag against `opencode <cmd> --help` on the installed binary, since the dev branch can drift ahead.
+
+For DB internals see `references/db-investigation.md`; for the HTTP server see `references/server-api.md`.

package/.agents/skills/opencode-qa/references/db-investigation.md

@@ -0,0 +1,197 @@
+# Investigating opencode sessions in the DB (Case D)
+
+## Table of Contents
+
+- [Where the data lives](#where-the-data-lives)
+- [Access methods](#access-methods)
+- [Schema (the tables that matter)](#schema-the-tables-that-matter)
+- [Time conversion](#time-conversion)
+- [Tested query patterns](#tested-query-patterns)
+- [The 25 GB caveat](#the-25-gb-caveat)
+- [Verifying read-only](#verifying-read-only)
+
+## Where the data lives
+
+Active DB path: `opencode db path` (on this machine `~/.local/share/opencode/opencode.db`).
+
+Derived from XDG data dir + "opencode" + "opencode.db" (or "opencode-<channel>.db" on non-stable channels). Override via env `OPENCODE_DB` (`:memory:`, absolute, or relative-to-data).
+
+It is large (tens of GB) because the `part` table stores tool output. The `session` table is small (~21k rows; full scans are milliseconds).
+
+## Access methods
+
+Preferred: `opencode db "<SQL>" --format json` (WAL-safe; resolves the active DB). `--format tsv` default. Bare `opencode db` opens an interactive sqlite3 shell. `opencode db path` prints the file.
+
+Raw fallback for EXPLAIN/perf: `sqlite3 "$(opencode db path)" "<SQL>"`. Reads are safe alongside a running opencode (WAL allows concurrent readers).
+
+## Schema (the tables that matter)
+
+Note the ACTIVE storage in v1.15.13 is the LEGACY pair `message` + `part`; the V2 `session_message` table exists but is EMPTY in this version (a recent session showed 43 message rows, 169 part rows, 0 session_message). Document both but make clear `message`/`part` is what holds current data.
+
+### `session`
+
+| Column | Notes |
+|--------|-------|
+| id | PK, 'ses_' prefix |
+| project_id | FK |
+| parent_id | |
+| slug | |
+| directory | |
+| title | NOT NULL |
+| version | |
+| agent | |
+| model | JSON {providerID, modelID} |
+| cost | |
+| tokens_input | |
+| tokens_output | |
+| tokens_reasoning | |
+| tokens_cache_read | |
+| tokens_cache_write | |
+| metadata | JSON |
+| time_created | epoch MILLISECONDS |
+| time_updated | epoch MILLISECONDS |
+| time_archived | |
+
+Indexes: project_id, parent_id, workspace_id. NO index on title or time_created.
+
+### `message` (legacy)
+
+| Column | Notes |
+|--------|-------|
+| id | 'msg_' prefix |
+| session_id | FK -> session, cascade |
+| time_created | |
+| time_updated | |
+| data | JSON: {role, time:{created}, summary:{title}, agent, model:{providerID,modelID}, variant} |
+
+### `part` (legacy)
+
+| Column | Notes |
+|--------|-------|
+| id | 'prt_' prefix |
+| message_id | FK -> message, cascade |
+| session_id | denormalized; index part_session_idx |
+| data | JSON |
+
+Part types seen: text, reasoning, tool, step-start, step-finish. A text part is `{"type":"text","text":"..."}`.
+
+### Other tables
+
+`session_message` (V2, currently empty), `todo`, `project`, `permission`, `session_share`, `workspace`, `event`.
+
+## Time conversion
+
+`time_created`/`time_updated` are epoch milliseconds. Convert:
+
+```sql
+datetime(time_created/1000,'unixepoch')
+```
+
+## Tested query patterns
+
+### 1. By id (instant)
+
+Script: `scripts/db-session-by-id.sh <ses_id>`
+
+```sql
+SELECT
+  id,
+  slug,
+  title,
+  directory,
+  agent,
+  json_extract(model,'$.modelID') AS model,
+  json_extract(model,'$.providerID') AS provider,
+  cost,
+  tokens_input,
+  tokens_output,
+  datetime(time_created/1000,'unixepoch') AS created,
+  datetime(time_updated/1000,'unixepoch') AS updated
+FROM session
+WHERE id='<ses_id>'
+```
+
+### 2. By name/title (0.006s over 21k rows)
+
+Script: `scripts/db-session-by-name.sh "<substr>" [limit]`
+
+```sql
+SELECT
+  id,
+  title,
+  datetime(time_created/1000,'unixepoch') AS created
+FROM session
+WHERE title LIKE '%<substr>%'
+ORDER BY time_created DESC
+LIMIT <N>
+```
+
+### 3. By message text
+
+Script: `scripts/db-session-by-text.sh (--session <id>|--recent <N>|--since "<window>") [--limit N] "<text>"`
+
+CRITICAL performance note: text lives in `part.data` JSON, and `part` is the multi-GB table, so an UNBOUNDED text scan is refused by the script. Always scope it.
+
+#### Scoped within one session (indexed, ~0.017s)
+
+```sql
+SELECT
+  p.session_id,
+  p.id,
+  substr(json_extract(p.data,'$.text'),1,120)
+FROM part p
+WHERE p.session_id='<id>'
+  AND json_extract(p.data,'$.type')='text'
+  AND json_extract(p.data,'$.text') LIKE '%<text>%'
+LIMIT 50
+```
+
+#### Bounded to the N most-recent sessions (worst-case ~0.02s)
+
+```sql
+SELECT
+  p.session_id,
+  p.id,
+  substr(json_extract(p.data,'$.text'),1,120)
+FROM part p
+WHERE p.session_id IN (
+  SELECT id FROM session ORDER BY time_created DESC LIMIT <N>
+)
+  AND json_extract(p.data,'$.type')='text'
+  AND json_extract(p.data,'$.text') LIKE '%<text>%'
+LIMIT 50
+```
+
+#### AVOID this naive form (took ~50s)
+
+A JOIN `FROM session s JOIN part p ON p.session_id=s.id WHERE s.time_created >= X ...` scans oldest sessions first. The IN-subquery (newest-first, drives `part_session_idx`) is the right shape because it lets SQLite use the index on `part.session_id` with a small, ordered set of recent session IDs, rather than scanning the entire `part` table from the oldest sessions upward.
+
+### 4. Full export
+
+Script: `scripts/export-roundtrip.sh <ses_id>` wraps `opencode export <id> 2>/dev/null` -> clean JSON `{info:{id,slug,projectID,directory,title,tokens,time,...}, messages:[...]}` (banner goes to stderr).
+
+### 5. Listing recent sessions
+
+```sql
+SELECT
+  id,
+  title,
+  datetime(time_created/1000,'unixepoch') created
+FROM session
+ORDER BY time_created DESC
+LIMIT 100
+```
+
+## The 25 GB caveat
+
+Global text search over all parts is a full scan of the largest table and can take a long time. The bundled script refuses it; you must pass `--session`, `--recent`, or `--since`. Title search (`session` table) is always cheap.
+
+## Verifying read-only
+
+All Case D operations are reads. To prove a QA pass did not mutate the DB, compare before and after:
+
+```bash
+sqlite3 "$(opencode db path)" "SELECT count(*) FROM session"
+```
+
+These queries are exactly what the `scripts/db-*.sh` helpers run; each ships a `--self-test`.

package/.agents/skills/opencode-qa/references/events-hooks.md

@@ -0,0 +1,110 @@
+# QAing opencode hooks, actions, and events (Case B)
+
+opencode publishes lifecycle events over Server-Sent Events. Plugins observe the SAME events via the `event` hook, so confirming an event on the wire proves a hook would fire. The bundled probe is `scripts/sse-hook-probe.sh`.
+
+## Table of Contents
+
+- [The two SSE endpoints](#the-two-sse-endpoints)
+- [Watch the stream](#watch-the-stream)
+- [Important event types](#important-event-types)
+- [Hook-fired recipe (watch + trigger + assert)](#hook-fired-recipe-watch--trigger--assert)
+- [Plugin hooks (the 21 hook points a plugin can implement)](#plugin-hooks-the-21-hook-points-a-plugin-can-implement)
+- [Loading a local plugin for QA](#loading-a-local-plugin-for-qa)
+
+## The two SSE endpoints
+
+- GET /event?directory=<dir> - per-instance stream; the FIRST event is `server.connected`, a `server.heartbeat` arrives every 10s, and the stream ends on `server.instance.disposed`.
+- GET /global/event - all events, no instance filter.
+- Frames look like `data: {"type":"...","properties":{...}}` (one per line). Consume with `curl -N`.
+
+## Watch the stream
+
+```
+curl -N -u opencode:$PASS "http://127.0.0.1:4096/event?directory=$PWD"
+```
+
+Bundled, with assertions + auto-teardown:
+
+```
+scripts/sse-hook-probe.sh --self-test
+```
+
+(spawns an isolated server, asserts server.connected)
+
+```
+scripts/sse-hook-probe.sh --attach http://127.0.0.1:4096 --password "$PASS" --directory "$PWD" --event message.part.updated --timeout 30
+```
+
+(watch your real server for a specific event)
+
+## Important event types (type - properties)
+
+- `session.created` / `session.updated` / `session.deleted` (sessionID, info)
+- `message.updated` (sessionID, info)
+- `message.removed` (sessionID, messageID)
+- `message.part.updated` (sessionID, part, time)
+- `message.part.delta` (sessionID, messageID, partID, field, delta)
+- `message.part.removed`
+- `permission.asked` (id, sessionID, permission, tool?)
+- `permission.replied`
+- `session.error` (sessionID?, error)
+- `session.diff` (sessionID, diff)
+- `question.asked` / `question.replied` / `question.rejected`
+- `file.watcher.updated` (file, event)
+- `project.updated`
+- `lsp.updated`
+- `pty.created` / `pty.updated` / `pty.exited` / `pty.deleted`
+- `server.connected`
+- `server.heartbeat`
+- `server.instance.disposed`
+- `global.disposed`
+- `plugin.added`
+
+## Hook-fired recipe (watch + trigger + assert)
+
+Two-shell pattern (or use the script):
+
+```
+# shell 1: watch (kill with Ctrl-C when done)
+curl -N -u opencode:$PASS "http://127.0.0.1:4096/event?directory=$PWD" \
+  | grep --line-buffered '"type":"message.part.updated"'
+
+# shell 2: trigger an action (fire-and-forget)
+curl -X POST -u opencode:$PASS -H 'Content-Type: application/json' \
+  -d '{"parts":[{"type":"text","text":"say hi"}]}' \
+  "http://127.0.0.1:4096/session/<ses_id>/prompt_async?directory=$PWD"
+```
+
+A `message.part.updated` (text/tool) confirms the prompt action drove the model and any tool/permission hook path. Note: a real prompt requires a configured provider/auth, so this runs against your real server, not the isolated sandbox (the sandbox only proves the SSE plumbing via server.connected).
+
+## Plugin hooks (the 21 hook points a plugin can implement)
+
+`event`, `config`, `tool`, `auth`, `provider`, `chat.message`, `chat.params`, `chat.headers`, `permission.ask`, `command.execute.before`, `tool.execute.before`, `tool.execute.after`, `tool.definition`, `shell.env`, `experimental.chat.messages.transform`, `experimental.chat.system.transform`, `experimental.session.compacting`, `experimental.compaction.autocontinue`, `experimental.text.complete`.
+
+- A plugin is a module default-exporting `{ id?, server: (input, options) => Promise<Hooks> }`.
+- Minimal example implementing `event` and `tool.execute.before` that console.log the activity:
+
+```typescript
+export default {
+  id: "qa-logger",
+  async server(input, options) {
+    return {
+      event: async (event) => {
+        console.log("[event]", event.type, event.properties);
+      },
+      "tool.execute.before": async (tool, args, context) => {
+        console.log("[tool.before]", tool.name, args);
+      },
+    };
+  },
+};
+```
+
+## Loading a local plugin for QA
+
+- Add an absolute path or npm spec to the opencode config `plugin` / `plugin_origins` array (project `.opencode/` config or user config), then restart opencode. On load it emits `plugin.added`.
+- To QA a hook: load the plugin, watch /event (or the plugin's own logging), trigger the relevant action, and assert.
+
+---
+
+Pair this with references/server-api.md (how to start the server, auth, prompt routes).