@brutalsystems/birddog-opencode 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Williams
+
+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,102 @@
+# birddog — opencode plugin
+
+Makes a live opencode session observable by
+[birddog](https://github.com/BrutalSystems/birddog).
+
+A default `opencode` TUI opens no TCP port and writes no port file, lockfile or
+pid file. Nothing outside the process can find it. This plugin closes that gap
+from the inside: it publishes one JSON record per live session to
+`~/.birddog/opencode/`, and birddog reads them.
+
+**Without this plugin there is nothing to observe** — an opencode session is
+invisible to birddog even when birddog is installed.
+
+## What it reports
+
+| | |
+|---|---|
+| `active` / `idle` | from `session.status` and `session.idle` |
+| `running_tool` | a tool is executing, with its name and start time |
+| `waiting_input` | a permission request is outstanding, with its id |
+| session identity | id, slug, title, working directory, opencode version |
+
+opencode is the only runtime where birddog can see a permission request at
+all. For every other provider it reports input-request visibility as
+*unavailable* — which is not the same as reporting that there is none.
+
+## What it does not do
+
+It observes. It sends no prompts, approves no requests, changes no tool
+arguments, and never throws.
+
+That last one is load-bearing. opencode's `tool.execute.before` hook can
+**block a tool** by throwing — that is how its own env-protection example
+works. Every hook here is guarded, so a failure inside birddog costs birddog
+its visibility and never costs the session its work.
+
+## Install
+
+Prefer letting [muster](https://github.com/BrutalSystems/muster) install it at
+launch, by npm specifier:
+
+```toml
+[plugins.birddog]
+npm = "@brutalsystems/birddog-opencode"
+```
+
+```sh
+muster run opencode --plugin birddog --prompt '...'
+```
+
+A copied file goes stale in silence — the package updates, the copy does not,
+and the old code keeps running. A specifier has no copy to go stale.
+
+To install by hand anyway, note that opencode's loader globs
+`{plugin,plugins}/*.{ts,js}` one level deep only, so it is two copies:
+
+```sh
+mkdir -p ~/.config/opencode/plugin
+cp birddog.ts ~/.config/opencode/plugin/
+cp -r birddog-lib ~/.config/opencode/plugin/
+```
+
+`birddog-lib/` is never globbed by the loader, which is the point of the
+name: `~/.config/opencode/plugin/` is shared with every other plugin, so a
+directory called `lib/` would be ambiguous.
+
+## Verify it is loaded
+
+```sh
+ls ~/.birddog/opencode/          # one ses_*.json per live session
+birddog discover                 # the sessions birddog can now see
+```
+
+If nothing appears, check `~/.birddog/opencode-plugin.log`. The plugin cannot
+print to the terminal: `console.error` would land in the TUI opencode is
+drawing its interface on, and nowhere readable afterwards.
+
+Confirm the loaded version matches what is installed — a hand-copied plugin
+lagging its package is the failure the npm specifier exists to prevent:
+
+```sh
+grep plugin_version ~/.birddog/opencode/*.json
+```
+
+## Requirements
+
+- opencode 1.18.31 (verified; other versions untested)
+- Node 22 or later
+
+## Where the records go
+
+`~/.birddog/opencode/<session_id>.json`, owner-only, written by rename so a
+reader never sees a half-written record. Set `BIRDDOG_HOME` to move both
+halves somewhere else.
+
+Each record carries the writing process's pid and a heartbeat, which is how
+birddog tells a session that has gone quiet from a process that died —
+including when the pid has since been reused by something else.
+
+## License
+
+MIT

package/birddog-lib/paths.ts

@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+
+/**
+ * Where the plugin publishes, and birddog reads.
+ *
+ * BIRDDOG_HOME is honoured so a test, or an operator running two setups, can
+ * point both halves at the same alternative directory.
+ */
+export function birddogHome(env: Record<string, string | undefined>, home: string): string {
+  return env.BIRDDOG_HOME && env.BIRDDOG_HOME.length > 0 ? env.BIRDDOG_HOME : join(home, '.birddog');
+}
+
+/** One record per live opencode session. */
+export function sessionsDir(env: Record<string, string | undefined>, home: string): string {
+  return join(birddogHome(env, home), 'opencode');
+}
+
+/**
+ * Deliberately beside the records, not among them: birddog scans that
+ * directory and sweeps it, and a log file dropped in would confuse both.
+ */
+export function pluginLogPath(env: Record<string, string | undefined>, home: string): string {
+  return join(birddogHome(env, home), 'opencode-plugin.log');
+}
+
+export function sessionFile(dir: string, sessionID: string): string {
+  return join(dir, `${sessionID}.json`);
+}

package/birddog-lib/plugin.ts

@@ -0,0 +1,113 @@
+import { Registry } from './registry.js';
+import { SessionTracker, type ToolEvent } from './state.js';
+
+export interface PluginOptions {
+  dir: string;
+  pid: number;
+  pluginVersion: string;
+  log: (line: string) => void;
+  /** How often to republish so birddog can tell a quiet session from a dead
+   *  process. Zero disables the timer, which is what tests want. */
+  heartbeatMs?: number;
+}
+
+export interface PluginHooks {
+  event: (arg: { event: unknown }) => Promise<void>;
+  'tool.execute.before': (input: unknown, output: unknown) => Promise<void>;
+  'tool.execute.after': (input: unknown, output: unknown) => Promise<void>;
+  stop: () => void;
+}
+
+/** defaultHeartbeatMs republishes often enough that a dead process is noticed
+ *  promptly, rarely enough to cost nothing on a session doing real work. */
+const defaultHeartbeatMs = 15_000;
+
+/**
+ * startPlugin wires the tracker to the registry.
+ *
+ * Every hook returned here is guarded. opencode's `tool.execute.before` can
+ * block a tool by throwing — that is how its own env-protection example works
+ * — so a throw from birddog would turn a monitoring failure into the agent's
+ * failure. birddog observes; it does not get a vote on whether work proceeds.
+ */
+export function startPlugin(opts: PluginOptions): PluginHooks {
+  const tracker = new SessionTracker();
+  const registry = new Registry(opts.dir, { pid: opts.pid, pluginVersion: opts.pluginVersion });
+
+  opts.log(`[birddog] event=started version=${opts.pluginVersion} pid=${opts.pid} dir=${opts.dir}`);
+
+  let lastReported: string | undefined;
+  const publish = async (): Promise<void> => {
+    await registry.publish(tracker.all());
+    if (registry.lastError && registry.lastError !== lastReported) {
+      // Logged once per distinct failure: a broken disk should not fill the
+      // log with the same line on every tool call.
+      opts.log(`[birddog] event=publish.failed detail=${registry.lastError}`);
+      lastReported = registry.lastError;
+    } else if (!registry.lastError) {
+      lastReported = undefined;
+    }
+  };
+
+  // guard is the boundary. Nothing inside the plugin may reach opencode as an
+  // exception, including a bug in birddog's own code.
+  const guard = async (what: string, fn: () => Promise<void>): Promise<void> => {
+    try {
+      await fn();
+    } catch (err) {
+      try {
+        opts.log(`[birddog] event=${what}.failed detail=${err instanceof Error ? err.message : String(err)}`);
+      } catch {
+        // Even logging must not throw into the host.
+      }
+    }
+  };
+
+  const heartbeat = opts.heartbeatMs ?? defaultHeartbeatMs;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  if (heartbeat > 0) {
+    timer = setInterval(() => void guard('heartbeat', publish), heartbeat);
+    // Never keep opencode alive on birddog's account.
+    timer.unref?.();
+  }
+
+  return {
+    event: (arg) =>
+      guard('event', async () => {
+        tracker.apply(arg?.event);
+        await publish();
+      }),
+
+    // input carries the tool and session; output carries the arguments the
+    // tool is about to run with. birddog reads neither's arguments and
+    // changes nothing in them.
+    'tool.execute.before': (input) =>
+      guard('tool.before', async () => {
+        tracker.toolStarted(asToolEvent(input));
+        await publish();
+      }),
+
+    'tool.execute.after': (input) =>
+      guard('tool.after', async () => {
+        tracker.toolFinished(asToolEvent(input));
+        await publish();
+      }),
+
+    stop: () => {
+      if (timer) clearInterval(timer);
+    },
+  };
+}
+
+/** asToolEvent reads only the fields needed to attribute the call. The hook's
+ *  payload shape is undocumented, so anything absent makes the event
+ *  unattributable rather than attributed to a guess. */
+function asToolEvent(input: unknown): ToolEvent {
+  if (typeof input !== 'object' || input === null) return {};
+  const o = input as Record<string, unknown>;
+  const event: ToolEvent = {};
+  if (typeof o.sessionID === 'string') event.sessionID = o.sessionID;
+  if (typeof o.tool === 'string') event.tool = o.tool;
+  if (typeof o.callID === 'string') event.callID = o.callID;
+  return event;
+}

package/birddog-lib/registry.ts

@@ -0,0 +1,109 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sessionFile } from './paths.js';
+import type { RegistryRecord, SessionSnapshot } from './types.js';
+
+export interface RegistryContext {
+  pid: number;
+  pluginVersion: string;
+  now?: () => Date;
+}
+
+/**
+ * The plugin's half of the contract: one JSON record per live session, which
+ * birddog reads and never writes.
+ *
+ * Nothing here can fail loudly. The plugin runs inside opencode's worker
+ * thread, so a problem writing these records must cost birddog its visibility
+ * and never cost the session its work — the failure is recorded on lastError
+ * for the log instead of thrown at the host.
+ */
+export class Registry {
+  /** lastError is how a failure is surfaced without throwing. */
+  lastError?: string;
+
+  private now: () => Date;
+
+  constructor(
+    private dir: string,
+    private ctx: RegistryContext,
+  ) {
+    this.now = ctx.now ?? (() => new Date());
+  }
+
+  /** publish writes a record for every live session and removes the records
+   *  of sessions that have ended. */
+  async publish(sessions: SessionSnapshot[]): Promise<void> {
+    try {
+      await mkdir(this.dir, { recursive: true, mode: 0o700 });
+      // mkdir respects umask, so the mode is set explicitly.
+      await chmod(this.dir, 0o700);
+
+      const live = new Set<string>();
+      for (const session of sessions) {
+        live.add(session.session_id);
+        await this.write(session);
+      }
+      await this.sweep(live);
+      delete this.lastError;
+    } catch (err) {
+      this.lastError = err instanceof Error ? err.message : String(err);
+    }
+  }
+
+  private async write(session: SessionSnapshot): Promise<void> {
+    const record: RegistryRecord = {
+      ...session,
+      pid: this.ctx.pid,
+      plugin_version: this.ctx.pluginVersion,
+      // A heartbeat, not decoration: it is how birddog tells a session that
+      // has gone quiet from a process that died, including when the pid has
+      // since been reused by something else entirely.
+      updated_at: `${this.now().toISOString().slice(0, 19)}Z`,
+    };
+
+    const final = sessionFile(this.dir, session.session_id);
+    // Temp then rename: a reader can catch a file at any moment, and a
+    // half-written record is worse than a slightly stale one. The suffix
+    // carries the pid and a random token, because two writes inside one
+    // process would otherwise collide on the same name.
+    const temp = `${final}.${this.ctx.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    await writeFile(temp, JSON.stringify(record, null, 2), { mode: 0o600 });
+    await rename(temp, final);
+  }
+
+  /**
+   * sweep removes the records of sessions that have ended.
+   *
+   * Only this process's own records: another opencode process keeps its
+   * sessions in the same directory, and sweeping those would blind birddog to
+   * every session but ours.
+   */
+  private async sweep(live: Set<string>): Promise<void> {
+    const entries = await readdir(this.dir);
+
+    for (const name of entries) {
+      if (!name.endsWith('.json')) continue;
+      const sessionID = name.slice(0, -'.json'.length);
+      if (live.has(sessionID)) continue;
+
+      const path = join(this.dir, name);
+      let record: { pid?: unknown };
+      try {
+        record = JSON.parse(await readFile(path, 'utf8'));
+      } catch {
+        // Unreadable, so unattributable. Leaving it costs nothing: birddog
+        // cannot parse it either, and will not report a session from it.
+        continue;
+      }
+      if (record.pid !== this.ctx.pid) continue;
+
+      try {
+        await unlink(path);
+      } catch {
+        // Already gone, or not ours to remove.
+      }
+    }
+  }
+}

package/birddog-lib/state.ts

@@ -0,0 +1,253 @@
+import type { CurrentTool, PendingPermission, SessionSnapshot, SessionState } from './types.js';
+
+/**
+ * The plugin's view of the sessions in this opencode process.
+ *
+ * Pure: it holds no handles and performs no I/O, so every transition below is
+ * testable without opencode running. It only ever reads what opencode reports.
+ * Nothing here can act on a session.
+ */
+
+/** What opencode hands a tool hook. The shape is not documented, so every
+ *  field is optional and anything missing means the event is not attributable
+ *  rather than attributable to a guess. */
+export interface ToolEvent {
+  sessionID?: string;
+  tool?: string;
+  callID?: string;
+}
+
+interface Tracked {
+  snapshot: SessionSnapshot;
+  /** Outstanding tool calls by id. A session is working until the last one
+   *  finishes: clearing on the first would report a busy session as free. */
+  runningTools: Map<string, CurrentTool>;
+}
+
+export class SessionTracker {
+  private sessions = new Map<string, Tracked>();
+
+  /** unattributed counts events that named no session birddog knows. It is a
+   *  diagnostic, not an error: it says coverage is incomplete rather than
+   *  silently narrowing what is reported. */
+  unattributed = 0;
+
+  constructor(private now: () => Date = () => new Date()) {}
+
+  /** Every tracked session, oldest id first for stable output. */
+  all(): SessionSnapshot[] {
+    return [...this.sessions.values()].map((t) => t.snapshot);
+  }
+
+  get(sessionID: string): SessionSnapshot | undefined {
+    return this.sessions.get(sessionID)?.snapshot;
+  }
+
+  /** apply folds one opencode event into the view. It never throws: opencode
+   *  is handing us its event stream, and a plugin that throws into it is a
+   *  plugin interfering with the session it is supposed to be watching. */
+  apply(event: unknown): void {
+    const e = asRecord(event);
+    if (!e) return;
+    const props = asRecord(e.properties) ?? {};
+
+    switch (e.type) {
+      case 'session.created':
+      case 'session.updated':
+        this.upsert(props.info);
+        return;
+
+      case 'session.deleted': {
+        // Read leniently: a delete needs nothing but an id, and refusing a
+        // sparse payload leaves a session birddog keeps reporting as live.
+        const id = asRecord(props.info)?.id;
+        if (typeof id === 'string') this.sessions.delete(id);
+        return;
+      }
+
+      case 'session.idle':
+        this.setBaseState(props.sessionID, 'idle');
+        return;
+
+      case 'session.status': {
+        // Only "idle" is idle. Anything opencode adds later is "not free",
+        // which is the safe reading — claiming idle wrongly invites a nudge
+        // nobody wanted.
+        const type = asRecord(props.status)?.type;
+        this.setBaseState(props.sessionID, type === 'idle' ? 'idle' : 'active');
+        return;
+      }
+
+      case 'permission.asked':
+        this.permissionAsked(props.sessionID, asRecord(props.permission)?.id);
+        return;
+
+      case 'permission.replied':
+        this.permissionReplied(props.sessionID, asRecord(props.permission)?.id);
+        return;
+
+      default:
+        return;
+    }
+  }
+
+  /** toolStarted records a tool beginning. Called from tool.execute.before,
+   *  which must never throw — see the plugin entry point. */
+  toolStarted(event: ToolEvent): void {
+    const tracked = this.resolve(event.sessionID);
+    if (!tracked) return;
+
+    const call = event.callID ?? `${event.tool ?? 'tool'}-${tracked.runningTools.size}`;
+    tracked.runningTools.set(call, {
+      name: event.tool ?? 'unknown',
+      started_at: this.stamp(),
+    });
+    this.touch(tracked);
+  }
+
+  /** toolFinished records a tool completing. A completion with no matching
+   *  start is dropped rather than decremented, so a stray one cannot leave a
+   *  session reporting work forever. */
+  toolFinished(event: ToolEvent): void {
+    const tracked = this.resolve(event.sessionID);
+    if (!tracked) return;
+
+    if (event.callID !== undefined) {
+      tracked.runningTools.delete(event.callID);
+    } else {
+      // No call id: clear one matching entry by name, if there is one.
+      for (const [id, tool] of tracked.runningTools) {
+        if (tool.name === event.tool) {
+          tracked.runningTools.delete(id);
+          break;
+        }
+      }
+    }
+    this.touch(tracked);
+  }
+
+  private upsert(raw: unknown): void {
+    const info = asRecord(raw);
+    if (!info) return;
+    const { id, slug, title, directory, version } = info;
+    if (
+      typeof id !== 'string' ||
+      typeof slug !== 'string' ||
+      typeof title !== 'string' ||
+      typeof directory !== 'string' ||
+      typeof version !== 'string'
+    ) {
+      // Not enough to describe a session. Reporting a partial one would put
+      // a target in birddog's listing that nobody could identify.
+      return;
+    }
+
+    const existing = this.sessions.get(id);
+    if (existing) {
+      Object.assign(existing.snapshot, { slug, title, directory, opencode_version: version });
+      this.touch(existing);
+      return;
+    }
+
+    this.sessions.set(id, {
+      snapshot: {
+        session_id: id,
+        slug,
+        title,
+        directory,
+        opencode_version: version,
+        state: 'active',
+        last_activity_at: this.stamp(),
+      },
+      runningTools: new Map(),
+    });
+  }
+
+  private permissionAsked(sessionID: unknown, permissionID: unknown): void {
+    const tracked = this.resolve(sessionID);
+    if (!tracked) return;
+
+    const pending: PendingPermission = {
+      id: typeof permissionID === 'string' ? permissionID : 'unknown',
+      asked_at: this.stamp(),
+    };
+    tracked.snapshot.pending_permission = pending;
+    this.touch(tracked);
+  }
+
+  private permissionReplied(sessionID: unknown, permissionID: unknown): void {
+    const tracked = this.resolve(sessionID);
+    if (!tracked) return;
+
+    const pending = tracked.snapshot.pending_permission;
+    // A reply naming a different request must not clear the one still
+    // waiting, or a session stays blocked while reporting that it is not.
+    if (pending && typeof permissionID === 'string' && pending.id !== permissionID) return;
+
+    delete tracked.snapshot.pending_permission;
+    this.touch(tracked);
+  }
+
+  private setBaseState(sessionID: unknown, state: SessionState): void {
+    const tracked = this.resolve(sessionID);
+    if (!tracked) return;
+    tracked.snapshot.state = state;
+    this.touch(tracked);
+  }
+
+  /** resolve finds the session an event belongs to, counting the ones that
+   *  cannot be attributed instead of guessing at the most recent. */
+  private resolve(sessionID: unknown): Tracked | undefined {
+    if (typeof sessionID !== 'string') {
+      this.unattributed++;
+      return undefined;
+    }
+    const tracked = this.sessions.get(sessionID);
+    if (!tracked) this.unattributed++;
+    return tracked;
+  }
+
+  /** touch recomputes the reported state and the activity stamp.
+   *
+   *  Precedence: waiting on a human outranks everything — it is what an
+   *  orchestrator most needs to hear, and a tool running underneath does not
+   *  make the session unblocked. A running tool outranks the base state,
+   *  because work in progress is not silence. */
+  private touch(tracked: Tracked): void {
+    const { snapshot, runningTools } = tracked;
+
+    if (snapshot.pending_permission) {
+      snapshot.state = 'waiting_input';
+      delete snapshot.current_tool;
+    } else if (runningTools.size > 0) {
+      snapshot.state = 'running_tool';
+      snapshot.current_tool = oldest(runningTools);
+    } else {
+      delete snapshot.current_tool;
+      if (snapshot.state === 'waiting_input' || snapshot.state === 'running_tool') {
+        // The thing that explained the state is over; the session is working
+        // again until opencode says otherwise.
+        snapshot.state = 'active';
+      }
+    }
+    snapshot.last_activity_at = this.stamp();
+  }
+
+  private stamp(): string {
+    return `${this.now().toISOString().slice(0, 19)}Z`;
+  }
+}
+
+/** oldest returns the longest-running tool, which is the one worth naming. */
+function oldest(tools: Map<string, CurrentTool>): CurrentTool {
+  let chosen: CurrentTool | undefined;
+  for (const tool of tools.values()) {
+    if (!chosen || tool.started_at < chosen.started_at) chosen = tool;
+  }
+  // The map is non-empty at every call site.
+  return chosen as CurrentTool;
+}
+
+function asRecord(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === 'object' && v !== null ? (v as Record<string, unknown>) : undefined;
+}

package/birddog-lib/types.ts

@@ -0,0 +1,36 @@
+/** Runtime states, matching birddog's own vocabulary so the Go adapter that
+ *  reads these records needs no translation table of its own. */
+export type SessionState = 'active' | 'idle' | 'waiting_input' | 'running_tool';
+
+/** What is known about one outstanding permission request. */
+export interface PendingPermission {
+  id: string;
+  asked_at: string;
+}
+
+/** The tool a session is currently running. */
+export interface CurrentTool {
+  name: string;
+  started_at: string;
+}
+
+/** One session, as the plugin sees it. */
+export interface SessionSnapshot {
+  session_id: string;
+  slug: string;
+  title: string;
+  directory: string;
+  opencode_version: string;
+
+  state: SessionState;
+  pending_permission?: PendingPermission;
+  current_tool?: CurrentTool;
+  last_activity_at: string;
+}
+
+/** A record on disk: a snapshot plus who wrote it. */
+export interface RegistryRecord extends SessionSnapshot {
+  pid: number;
+  plugin_version: string;
+  updated_at: string;
+}

package/birddog.ts

@@ -0,0 +1,80 @@
+/**
+ * birddog — opencode plugin.
+ *
+ * Publishes this opencode process's session state to `~/.birddog/opencode/`,
+ * where birddog reads it. A default opencode TUI opens no port and writes no
+ * pid file, so nothing outside the process can find it; this plugin is the
+ * only way an opencode session is observable at all.
+ *
+ * It is read-only with respect to the session. It reports what opencode tells
+ * it and never acts: no prompts, no approvals, no changes to a tool's
+ * arguments, and no exception that could block one.
+ *
+ * WARNING: opencode's loader invokes EVERY exported function in this file as
+ * a plugin, and does not descend into subdirectories. Export exactly one
+ * thing, and never a `default`. All logic lives in ./birddog-lib/.
+ */
+import { appendFileSync, chmodSync, mkdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { pluginLogPath, sessionsDir } from './birddog-lib/paths.js';
+import { startPlugin } from './birddog-lib/plugin.js';
+
+/** Rotated past this: small enough to stay cheap to read, big enough to hold
+ *  a long session's diagnostics. */
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+/** version is kept in step with package.json by scripts/sync-version.mjs, and
+ *  a test asserts they agree. */
+const VERSION = '0.1.0';
+
+export const Birddog = async () => {
+  const logPath = pluginLogPath(process.env, homedir());
+
+  // console.error would land in the TUI opencode is drawing its interface on,
+  // and nowhere an operator can read afterwards. A file is the only way a
+  // failure is visible once the session ends.
+  //
+  // This runs on opencode's worker thread, so the steady state is one syscall
+  // per line: the mkdir, the chmod and the size check happen on the first
+  // write only. The sink must not throw either — a logging failure must never
+  // reach the host.
+  let logBytes = -1;
+  let tightened = false;
+  const log = (line: string) => {
+    try {
+      const data = `${line}\n`;
+      if (logBytes < 0) {
+        mkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });
+        try {
+          logBytes = statSync(logPath).size;
+        } catch {
+          logBytes = 0;
+        }
+      }
+      if (logBytes >= MAX_LOG_BYTES) {
+        // Truncate rather than rotate: these are diagnostics, not a record
+        // anyone is entitled to keep.
+        logBytes = 0;
+      }
+      appendFileSync(logPath, data, { mode: 0o600 });
+      logBytes += Buffer.byteLength(data, 'utf8');
+      if (!tightened) {
+        // `mode` on appendFileSync only applies when the file is created, so
+        // a pre-existing world-readable log is tightened here too.
+        chmodSync(logPath, 0o600);
+        tightened = true;
+      }
+    } catch {
+      // Nowhere left to report it. Losing a log line is not worth disturbing
+      // the session over.
+    }
+  };
+
+  return startPlugin({
+    dir: sessionsDir(process.env, homedir()),
+    pid: process.pid,
+    pluginVersion: VERSION,
+    log,
+  });
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@brutalsystems/birddog-opencode",
+  "version": "0.0.0",
+  "description": "opencode plugin for birddog — publishes a session's state so birddog can observe it from outside. Read-only: it reports, and never acts on the session.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "birddog",
+    "agents",
+    "monitoring",
+    "observability"
+  ],
+  "license": "MIT",
+  "author": "Mike Williams",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrutalSystems/birddog.git",
+    "directory": "plugins/opencode"
+  },
+  "homepage": "https://github.com/BrutalSystems/birddog#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./birddog.ts",
+  "exports": {
+    ".": "./birddog.ts",
+    "./server": "./birddog.ts"
+  },
+  "files": [
+    "birddog.ts",
+    "birddog-lib",
+    "README.md",
+    "LICENSE"
+  ]
+}