@brutalsystems/birddog-opencode 0.1.0 → 0.1.2

package/README.md

@@ -49,7 +49,17 @@ 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.
+and the old code keeps running.
+
+A specifier is better but not immune: opencode resolves it once into
+`~/.cache/opencode/packages/@brutalsystems/birddog-opencode@latest` and does
+not revisit it, so a new release is not picked up until that directory is
+removed. Check what is actually loaded rather than assuming:
+
+```sh
+grep plugin_version ~/.birddog/opencode/*.json
+rm -rf ~/.cache/opencode/packages/@brutalsystems/birddog-opencode@latest
+```
 
 To install by hand anyway, note that opencode's loader globs
 `{plugin,plugins}/*.{ts,js}` one level deep only, so it is two copies:

package/birddog-lib/plugin.ts

@@ -1,11 +1,25 @@
 import { Registry } from './registry.js';
 import { SessionTracker, type ToolEvent } from './state.js';
 
+/** Transport is the bit of opencode's client birddog needs: one read. */
+export interface Transport {
+  get(args: { url: string }): Promise<{ data?: unknown; response?: { status?: number } }>;
+}
+
 export interface PluginOptions {
   dir: string;
   pid: number;
   pluginVersion: string;
   log: (line: string) => void;
+
+  /**
+   * transport reads opencode's own session list at startup, so a session that
+   * already existed when the plugin loaded is still observed.
+   */
+  transport?: Transport;
+
+  /** directory this process serves; adoption is limited to it. */
+  directory?: string;
   /** 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;
@@ -63,6 +77,23 @@ export function startPlugin(opts: PluginOptions): PluginHooks {
     }
   };
 
+  // Resolve sessions that events name but the tracker does not know. This is
+  // how a session created before the plugin loaded — every muster launch —
+  // becomes visible at all. Driven by events rather than by listing, so
+  // opencode's session history is never pulled in.
+  const resolveUnknown = async (): Promise<void> => {
+    if (!opts.transport) return;
+    for (const id of tracker.takeUnknown()) {
+      const res = await opts.transport.get({ url: `/session/${id}` });
+      if ((res.response?.status ?? 0) !== 200 || typeof res.data !== 'object' || res.data == null) {
+        opts.log(`[birddog] event=resolve.failed session=${id} status=${res.response?.status ?? 0}`);
+        continue;
+      }
+      tracker.adoptOne(res.data);
+      opts.log(`[birddog] event=adopted session=${id}`);
+    }
+  };
+
   const heartbeat = opts.heartbeatMs ?? defaultHeartbeatMs;
   let timer: ReturnType<typeof setInterval> | undefined;
   if (heartbeat > 0) {
@@ -75,6 +106,7 @@ export function startPlugin(opts: PluginOptions): PluginHooks {
     event: (arg) =>
       guard('event', async () => {
         tracker.apply(arg?.event);
+        await resolveUnknown();
         await publish();
       }),
 
@@ -84,6 +116,7 @@ export function startPlugin(opts: PluginOptions): PluginHooks {
     'tool.execute.before': (input) =>
       guard('tool.before', async () => {
         tracker.toolStarted(asToolEvent(input));
+        await resolveUnknown();
         await publish();
       }),
 

package/birddog-lib/registry.ts

@@ -25,6 +25,14 @@ export class Registry {
 
   private now: () => Date;
 
+  /**
+   * Identifies this plugin instance. opencode instantiates the plugin twice
+   * in one process, so the pid is shared and cannot say who wrote a record —
+   * and sweeping by pid made the second instance delete the first's records
+   * for sessions that were still running.
+   */
+  private readonly instanceId = `inst-${randomBytes(6).toString('hex')}`;
+
   constructor(
     private dir: string,
     private ctx: RegistryContext,
@@ -56,6 +64,7 @@ export class Registry {
     const record: RegistryRecord = {
       ...session,
       pid: this.ctx.pid,
+      instance_id: this.instanceId,
       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
@@ -76,9 +85,10 @@ export class Registry {
   /**
    * 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.
+   * Only this instance's own records. Another opencode process keeps its
+   * sessions in the same directory, and so does the second plugin instance in
+   * this one — sweeping either would blind birddog to sessions that are
+   * running perfectly well.
    */
   private async sweep(live: Set<string>): Promise<void> {
     const entries = await readdir(this.dir);
@@ -89,7 +99,7 @@ export class Registry {
       if (live.has(sessionID)) continue;
 
       const path = join(this.dir, name);
-      let record: { pid?: unknown };
+      let record: { instance_id?: unknown };
       try {
         record = JSON.parse(await readFile(path, 'utf8'));
       } catch {
@@ -97,7 +107,7 @@ export class Registry {
         // cannot parse it either, and will not report a session from it.
         continue;
       }
-      if (record.pid !== this.ctx.pid) continue;
+      if (record.instance_id !== this.instanceId) continue;
 
       try {
         await unlink(path);

package/birddog-lib/state.ts

@@ -32,6 +32,9 @@ export class SessionTracker {
    *  silently narrowing what is reported. */
   unattributed = 0;
 
+  /** Sessions named by events that are not tracked yet. */
+  private unknown = new Set<string>();
+
   constructor(private now: () => Date = () => new Date()) {}
 
   /** Every tracked session, oldest id first for stable output. */
@@ -43,6 +46,33 @@ export class SessionTracker {
     return this.sessions.get(sessionID)?.snapshot;
   }
 
+  /**
+   * adoptOne records a session the tracker never saw begin.
+   *
+   * Driven by takeUnknown, so only sessions this process actually emits
+   * events for are ever adopted. Fetching opencode's whole session list
+   * instead would pull in its entire history — a hundred sessions that ended
+   * days ago — and republish them under this process's pid with a fresh
+   * heartbeat, which is precisely how birddog decides something is live.
+   */
+  adoptOne(session: unknown): void {
+    const info = asRecord(session);
+    if (!info || typeof info.id !== 'string') return;
+    if (this.sessions.has(info.id)) return;
+    this.upsert(info);
+  }
+
+  /**
+   * takeUnknown returns the sessions named by events that this tracker does
+   * not know, and forgets them. The caller is expected to go and resolve
+   * them; asking again must not repeat work already in flight.
+   */
+  takeUnknown(): string[] {
+    const ids = [...this.unknown];
+    this.unknown.clear();
+    return ids;
+  }
+
   /** 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. */
@@ -78,12 +108,16 @@ export class SessionTracker {
         return;
       }
 
+      // The shape below was captured from opencode 1.18.31 rather than
+      // inferred. `permission` is the kind being asked for ("bash", "edit"),
+      // a plain string — not an object carrying the id. The id is top level
+      // on asked, and comes back as `requestID` on replied.
       case 'permission.asked':
-        this.permissionAsked(props.sessionID, asRecord(props.permission)?.id);
+        this.permissionAsked(props);
         return;
 
       case 'permission.replied':
-        this.permissionReplied(props.sessionID, asRecord(props.permission)?.id);
+        this.permissionReplied(props.sessionID, props.requestID);
         return;
 
       default:
@@ -163,14 +197,22 @@ export class SessionTracker {
     });
   }
 
-  private permissionAsked(sessionID: unknown, permissionID: unknown): void {
-    const tracked = this.resolve(sessionID);
+  private permissionAsked(props: Record<string, unknown>): void {
+    const tracked = this.resolve(props.sessionID);
     if (!tracked) return;
 
     const pending: PendingPermission = {
-      id: typeof permissionID === 'string' ? permissionID : 'unknown',
+      id: typeof props.id === 'string' ? props.id : 'unknown',
       asked_at: this.stamp(),
     };
+    if (typeof props.permission === 'string') {
+      pending.type = props.permission;
+    }
+    const detail = requestDetail(asRecord(props.metadata));
+    if (detail !== undefined) {
+      pending.detail = detail;
+    }
+
     tracked.snapshot.pending_permission = pending;
     this.touch(tracked);
   }
@@ -191,6 +233,18 @@ export class SessionTracker {
   private setBaseState(sessionID: unknown, state: SessionState): void {
     const tracked = this.resolve(sessionID);
     if (!tracked) return;
+
+    if (state === 'idle') {
+      // An idle session is not running a tool. Without this, a completion
+      // that never arrives leaves the session reporting running_tool
+      // forever — which happens because opencode instantiates the plugin
+      // twice and the tool hooks do not reliably reach both instances.
+      //
+      // A pending permission is not cleared here: it outranks idle, and is
+      // the usual reason a session sits idle with work still to do.
+      tracked.runningTools.clear();
+    }
+
     tracked.snapshot.state = state;
     this.touch(tracked);
   }
@@ -203,7 +257,11 @@ export class SessionTracker {
       return undefined;
     }
     const tracked = this.sessions.get(sessionID);
-    if (!tracked) this.unattributed++;
+    if (!tracked) {
+      this.unattributed++;
+      // Worth resolving: an event naming it means this process is serving it.
+      this.unknown.add(sessionID);
+    }
     return tracked;
   }
 
@@ -248,6 +306,37 @@ function oldest(tools: Map<string, CurrentTool>): CurrentTool {
   return chosen as CurrentTool;
 }
 
+/**
+ * requestDetail summarises what a request is asking to do, so an alert can
+ * say "waiting to run rm test.tst" rather than only "waiting on approval".
+ *
+ * Deliberately narrow: metadata also carries the full diff of an edit, which
+ * can be thousands of lines. birddog records evidence, not payloads.
+ */
+const MAX_DETAIL = 200;
+
+function requestDetail(metadata: Record<string, unknown> | undefined): string | undefined {
+  if (!metadata) return undefined;
+  const value = metadata.command ?? metadata.filepath;
+  if (typeof value !== 'string' || value === '') return undefined;
+  return value.length > MAX_DETAIL ? `${value.slice(0, MAX_DETAIL)}…` : value;
+}
+
+/**
+ * sameDirectory compares two paths allowing for macOS reporting /tmp as
+ * /private/tmp, which would otherwise make every launch under /tmp adopt
+ * nothing at all.
+ */
+function sameDirectory(a: unknown, b: string): boolean {
+  if (typeof a !== 'string') return false;
+  return normalise(a) === normalise(b);
+}
+
+function normalise(p: string): string {
+  const trimmed = p.replace(/\/+$/, '');
+  return trimmed.startsWith('/private/') ? trimmed.slice('/private'.length) : trimmed;
+}
+
 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

@@ -6,6 +6,17 @@ export type SessionState = 'active' | 'idle' | 'waiting_input' | 'running_tool';
 export interface PendingPermission {
   id: string;
   asked_at: string;
+
+  /** What kind of approval is being asked for: "bash", "edit", and so on. */
+  type?: string;
+
+  /**
+   * What it is asking to do — the command, or the file being edited.
+   *
+   * Bounded on purpose: an edit request carries a full diff, and birddog
+   * records evidence rather than payloads.
+   */
+  detail?: string;
 }
 
 /** The tool a session is currently running. */
@@ -31,6 +42,14 @@ export interface SessionSnapshot {
 /** A record on disk: a snapshot plus who wrote it. */
 export interface RegistryRecord extends SessionSnapshot {
   pid: number;
+
+  /**
+   * Which plugin instance wrote this. opencode instantiates the plugin twice
+   * in one process, so a pid does not identify the writer — and sweeping by
+   * pid makes one instance delete the other's live records.
+   */
+  instance_id: string;
+
   plugin_version: string;
   updated_at: string;
 }

package/birddog.ts

@@ -26,9 +26,9 @@ 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';
+const VERSION = '0.1.2';
 
-export const Birddog = async () => {
+export const Birddog = async (input?: { client?: { _client?: unknown } }) => {
   const logPath = pluginLogPath(process.env, homedir());
 
   // console.error would land in the TUI opencode is drawing its interface on,
@@ -71,10 +71,23 @@ export const Birddog = async () => {
     }
   };
 
+  // opencode hands the plugin its own client. The transport underneath is
+  // what lets birddog ask which sessions already exist, rather than only
+  // learning about ones that begin after it loads.
+  const transport = input?.client?._client;
+  const usable =
+    transport && typeof (transport as { get?: unknown }).get === 'function'
+      ? (transport as { get(args: { url: string }): Promise<{ data?: unknown; response?: { status?: number } }> })
+      : undefined;
+  if (!usable) {
+    log('[birddog] event=transport.missing detail=cannot read existing sessions');
+  }
+
   return startPlugin({
     dir: sessionsDir(process.env, homedir()),
     pid: process.pid,
     pluginVersion: VERSION,
     log,
+    ...(usable ? { transport: usable } : {}),
   });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/birddog-opencode",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",