feat(agent-opencode): hooks-based activity detection

.changeset/opencode-activity-hooks.md

@@ -0,0 +1,27 @@
+---
+"@aoagents/ao-plugin-agent-opencode": minor
+---
+
+Replace OpenCode terminal-regex activity detection with platform-event hooks.
+
+OpenCode exposes a plugin/event system (`.opencode/plugins/`) that streams 25+
+lifecycle events. Until now, AO inferred activity by regex-matching OpenCode's
+rendered terminal output — and `waiting_input` had no authoritative source at
+all, only a fragile prompt heuristic.
+
+This release pivots OpenCode to the same hook-driven model as Claude Code and
+Codex:
+
+- `setupWorkspaceHooks` installs an auto-loaded activity plugin into the
+  workspace's `.opencode/plugins/` and excludes it from git (worktree-aware
+  `info/exclude`) so it never lands in the agent's PRs.
+- The plugin maps `permission.asked` → `waiting_input`, `session.error` →
+  `blocked`, `session.idle` → `ready`, and tool/file/message events → `active`,
+  writing them to `.ao/activity.jsonl` with `source: "hook"`. It no-ops without
+  `AO_SESSION_ID` and honors `AO_OPENCODE_HOOK_ACTIVITY=0` as an opt-out.
+- `getActivityState` now prefers fresh hook entries over the polled
+  `opencode session list` API for every state; the session-list API remains the
+  fallback when no hook entry exists.
+- `recordActivity` is removed — the plugin is the sole JSONL writer, so
+  terminal-derived writes can no longer shadow authoritative hook events. The
+  terminal `detectActivity` classifier remains as the lifecycle's last resort.

packages/plugins/agent-opencode/src/activity-plugin.integration.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { OPENCODE_ACTIVITY_PLUGIN } from "./activity-plugin.js";
+
+/**
+ * Executes the real generated OpenCode activity plugin against synthetic
+ * events and asserts the JSONL it writes. This proves the event→state mapping
+ * and the env-based guards work, not just that the string contains markers.
+ */
+
+interface OpenCodeEvent {
+  type: string;
+}
+
+type PluginHooks = {
+  event?: (input: { event: OpenCodeEvent }) => Promise<void> | void;
+};
+
+type PluginFactory = (ctx: {
+  directory?: string;
+  worktree?: string;
+}) => Promise<PluginHooks>;
+
+let workDir: string;
+let pluginUrl: string;
+// Snapshot only the env keys these tests mutate, so we can restore them
+// individually rather than reassigning process.env wholesale (which loses
+// Node's special env getter/setter behavior).
+const MUTATED_ENV_KEYS = ["AO_SESSION_ID", "AO_OPENCODE_HOOK_ACTIVITY"] as const;
+const savedEnv = new Map(MUTATED_ENV_KEYS.map((k) => [k, process.env[k]] as const));
+
+async function loadPlugin(): Promise<PluginFactory> {
+  // Write the generated plugin to a temp .mjs file and import it so we exercise
+  // the exact source AO ships, as ESM (matching opencode's Bun loader).
+  const pluginPath = join(workDir, "ao-activity.mjs");
+  await writeFile(pluginPath, OPENCODE_ACTIVITY_PLUGIN, "utf8");
+  // Cache-bust so each test gets a fresh module instance (dedup state resets).
+  pluginUrl = `${pathToFileURL(pluginPath).href}?t=${Date.now()}-${Math.random()}`;
+  const mod = (await import(pluginUrl)) as Record<string, PluginFactory>;
+  const factory = Object.values(mod).find((v) => typeof v === "function");
+  if (!factory) throw new Error("plugin has no exported factory function");
+  return factory;
+}
+
+async function readEntries(): Promise<Array<Record<string, unknown>>> {
+  const logPath = join(workDir, ".ao", "activity.jsonl");
+  let raw: string;
+  try {
+    raw = await readFile(logPath, "utf8");
+  } catch {
+    return [];
+  }
+  return raw
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), "ao-oc-plugin-"));
+  await mkdir(workDir, { recursive: true });
+  process.env["AO_SESSION_ID"] = "sess-xyz";
+  delete process.env["AO_OPENCODE_HOOK_ACTIVITY"];
+});
+
+afterEach(async () => {
+  for (const [key, value] of savedEnv) {
+    if (value === undefined) Reflect.deleteProperty(process.env, key);
+    else process.env[key] = value;
+  }
+  await rm(workDir, { recursive: true, force: true });
+});
+
+describe("OpenCode activity plugin — event mapping", () => {
+  it("writes waiting_input on permission.asked", async () => {
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    await hooks.event!({ event: { type: "permission.asked" } });
+
+    const entries = await readEntries();
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({
+      state: "waiting_input",
+      source: "hook",
+      sessionId: "sess-xyz",
+    });
+  });
+
+  it("writes blocked on session.error", async () => {
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    await hooks.event!({ event: { type: "session.error" } });
+
+    const entries = await readEntries();
+    expect(entries[0]).toMatchObject({ state: "blocked", source: "hook" });
+  });
+
+  it("writes ready on session.idle (never idle — AO age-decay handles idle)", async () => {
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    await hooks.event!({ event: { type: "session.idle" } });
+
+    const entries = await readEntries();
+    expect(entries[0]).toMatchObject({ state: "ready", source: "hook" });
+  });
+
+  it("writes active on tool execution", async () => {
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    await hooks.event!({ event: { type: "tool.execute.before" } });
+
+    const entries = await readEntries();
+    expect(entries[0]).toMatchObject({ state: "active", source: "hook" });
+  });
+
+  it("ignores unrelated events", async () => {
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    await hooks.event!({ event: { type: "lsp.updated" } });
+    await hooks.event!({ event: { type: "todo.updated" } });
+
+    expect(await readEntries()).toHaveLength(0);
+  });
+
+  it("no-ops entirely when AO_SESSION_ID is unset (manual opencode runs don't bleed)", async () => {
+    delete process.env["AO_SESSION_ID"];
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    // event handler should be absent or a no-op
+    if (hooks.event) {
+      await hooks.event({ event: { type: "permission.asked" } });
+    }
+    expect(await readEntries()).toHaveLength(0);
+  });
+
+  it("no-ops when AO_OPENCODE_HOOK_ACTIVITY=0 (opt-out)", async () => {
+    process.env["AO_OPENCODE_HOOK_ACTIVITY"] = "0";
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    if (hooks.event) {
+      await hooks.event({ event: { type: "permission.asked" } });
+    }
+    expect(await readEntries()).toHaveLength(0);
+  });
+
+  it("deduplicates rapid active events but always writes actionable states", async () => {
+    const factory = await loadPlugin();
+    const hooks = await factory({ directory: workDir });
+    await hooks.event!({ event: { type: "tool.execute.before" } });
+    await hooks.event!({ event: { type: "message.updated" } });
+    await hooks.event!({ event: { type: "tool.execute.after" } });
+    // actionable always writes through, even back-to-back
+    await hooks.event!({ event: { type: "permission.asked" } });
+
+    const entries = await readEntries();
+    const active = entries.filter((e) => e.state === "active");
+    const waiting = entries.filter((e) => e.state === "waiting_input");
+    expect(active).toHaveLength(1);
+    expect(waiting).toHaveLength(1);
+  });
+});

packages/plugins/agent-opencode/src/activity-plugin.ts

@@ -0,0 +1,133 @@
+/**
+ * OpenCode activity plugin install + the plugin source itself.
+ *
+ * OpenCode auto-loads any `.js`/`.ts` file under `.opencode/plugins/` at
+ * startup and invokes the exported factory with `{ directory, worktree, ... }`.
+ * AO installs a plugin there that subscribes to OpenCode's event stream and
+ * maps the relevant lifecycle events to AO activity states, replacing fragile
+ * terminal-regex inference. `permission.asked` is the only authoritative source
+ * of `waiting_input` OpenCode exposes.
+ */
+import { isWindows } from "@aoagents/ao-core";
+import { execFile } from "node:child_process";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** Filename of the auto-loaded OpenCode plugin AO installs per workspace. */
+const OPENCODE_PLUGIN_FILENAME = "ao-activity.js";
+
+/** Relative path used for the git-exclude entry that keeps the plugin out of PRs. */
+const OPENCODE_PLUGIN_EXCLUDE_PATH = `.opencode/plugins/${OPENCODE_PLUGIN_FILENAME}`;
+
+/**
+ * Source of the OpenCode plugin that writes authoritative activity events to
+ * `.ao/activity.jsonl` with `source: "hook"`.
+ *
+ * Guards mirror the Codex hook updater: it no-ops unless `AO_SESSION_ID` is set
+ * (so a human running `opencode` in the same worktree never writes AO entries)
+ * and honors `AO_OPENCODE_HOOK_ACTIVITY=0` as an opt-out. `idle` is never
+ * written — AO's age-decay derives idle from a stale `ready`/`active` entry.
+ */
+export const OPENCODE_ACTIVITY_PLUGIN = `// Agent Orchestrator activity plugin — auto-generated. Do not edit.
+import { appendFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+export const AoActivity = async ({ directory, worktree }) => {
+  const sessionId = process.env.AO_SESSION_ID;
+  if (!sessionId || process.env.AO_OPENCODE_HOOK_ACTIVITY === "0") return {};
+
+  const base = directory || worktree || process.cwd();
+  const logPath = join(base, ".ao", "activity.jsonl");
+
+  let lastActiveWrite = 0;
+
+  const write = async (state, trigger) => {
+    try {
+      await mkdir(dirname(logPath), { recursive: true });
+      const entry = { ts: new Date().toISOString(), state, source: "hook", sessionId };
+      if (trigger && (state === "waiting_input" || state === "blocked")) {
+        entry.trigger = trigger;
+      }
+      await appendFile(logPath, JSON.stringify(entry) + "\\n", "utf8");
+    } catch {
+      // Best-effort: activity logging must never break the agent.
+    }
+  };
+
+  return {
+    event: async ({ event }) => {
+      const type = event && event.type;
+      switch (type) {
+        case "permission.asked":
+          return write("waiting_input", "permission.asked");
+        case "session.error":
+          return write("blocked", "session.error");
+        case "session.idle":
+          return write("ready", "session.idle");
+        case "tool.execute.before":
+        case "tool.execute.after":
+        case "file.edited":
+        case "message.updated":
+        case "message.part.updated": {
+          // Coalesce high-frequency streaming events to bound JSONL growth.
+          const now = Date.now();
+          if (now - lastActiveWrite < 5000) return;
+          lastActiveWrite = now;
+          return write("active");
+        }
+        default:
+          return;
+      }
+    },
+  };
+};
+`;
+
+/**
+ * Append a pattern to the workspace's git exclude file (worktree-aware via
+ * `git rev-parse --git-path`), idempotently. Best-effort: keeping the plugin
+ * out of the agent's PRs is a nicety, not a correctness requirement.
+ */
+async function addToGitExclude(workspacePath: string, pattern: string): Promise<void> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", workspacePath, "rev-parse", "--git-path", "info/exclude"],
+      {
+        timeout: 10_000,
+        ...(isWindows() ? { shell: true, windowsHide: true } : {}),
+      },
+    );
+    const rel = stdout.trim();
+    if (!rel) return;
+    const excludePath = isAbsolute(rel) ? rel : join(workspacePath, rel);
+
+    let existing = "";
+    try {
+      existing = await readFile(excludePath, "utf8");
+    } catch {
+      // No exclude file yet — we'll create it below.
+    }
+    if (existing.split("\n").some((line) => line.trim() === pattern)) return;
+
+    await mkdir(dirname(excludePath), { recursive: true });
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await appendFile(excludePath, `${prefix}${pattern}\n`, "utf8");
+  } catch {
+    // Best-effort only.
+  }
+}
+
+/**
+ * Install the activity plugin into the workspace's `.opencode/plugins/` dir and
+ * exclude it from git so it never appears in the agent's PRs.
+ */
+export async function installOpenCodeActivityPlugin(workspacePath: string): Promise<void> {
+  const pluginDir = join(workspacePath, ".opencode", "plugins");
+  await mkdir(pluginDir, { recursive: true });
+  await writeFile(join(pluginDir, OPENCODE_PLUGIN_FILENAME), OPENCODE_ACTIVITY_PLUGIN, "utf8");
+  await addToGitExclude(workspacePath, OPENCODE_PLUGIN_EXCLUDE_PATH);
+}