opencode-wake-plugin 0.1.0

package/src/contract.ts

@@ -0,0 +1,48 @@
+export type WakeMessage = {
+  parts: Array<{ type: "text"; text: string }>;
+};
+
+export type WakeMessageInput = {
+  parentSessionID: string;
+  childSessionIDs: string[];
+  timestamp: number;
+};
+
+// The wake plugin emits a hedging wake (not a directive). The plugin only
+// sees OpenCode session IDs from session.idle events; it cannot know whether
+// OMO has more bg_… tasks still pending — only OMO is authoritative for the
+// final-done header (which arrives layer by layer per task). When this wake
+// reaches the parent, the parent should retrieve whatever bg_… task IDs it
+// already has in context for this session and synthesize; the wake plugin
+// does NOT have access to the bg_… task IDs and does NOT claim
+// [ALL BACKGROUND TASKS COMPLETE].
+//
+// The wake body intentionally contains ONLY the <system-reminder> block —
+// no debug-style "[wake-plugin stamp] subagents completed" header, no
+// "[WAKE-PLUGIN-FROM: …]" observability prefix. If opencode renders the
+// promptAsync input into the chat editor (root cause for user-reported
+// "nonsense characters at end of chat"), the user must see only the
+// structured reminder, not debug prefixes that look like garbage.
+export function buildWakeMessage(input: WakeMessageInput): WakeMessage {
+  const traced = input.childSessionIDs.map((id) => `- \`${id}\``).join("\n");
+  const noop = input.childSessionIDs.length === 0;
+  const body = noop
+    ? `<system-reminder>
+[BACKGROUND TASK RESULT READY]
+
+No child sessions were provided; no background_output retrieval is required.
+</system-reminder>`
+    : `<system-reminder>
+[BACKGROUND TASK RESULT READY]
+
+**Idle OpenCode sessions observed by wake-plugin:**
+${traced}
+
+More background tasks may still be in progress; only OMO is authoritative for the final-done header (which arrives layer by layer per task), and the wake plugin does not have access to the bg_… task IDs.
+
+Use \`background_output(task_id="<bg-id>")\` to retrieve each result for every pending bg_… background task already recorded in this parent session.
+
+If no bg_… tasks are in flight, ignore this wake.
+</system-reminder>`;
+  return { parts: [{ type: "text", text: body }] };
+}

package/src/event-filter.ts

@@ -0,0 +1,57 @@
+// opencode-wake-plugin
+//
+// shouldWakeOn — gates the plugin's response to an opencode event.
+//
+// The opencode `event` hook receives a discriminated union (`Event`). We only
+// care about `session.idle` events at this stage. The sessionID is extracted
+// so downstream logic can look up the parent session via `client.session.get()`.
+
+import type { Hooks } from "@opencode-ai/plugin";
+import { logger } from "./logger.js";
+
+// The plugin's `Hooks.event` callback signature takes `{ event: Event }`. The
+// `Event` type itself is not re-exported by `@opencode-ai/plugin`, but we can
+// recover it structurally from the hook's parameter type without losing
+// type-safety. Under `noUncheckedIndexedAccess` the indexed access is wrapped
+// in an `unknown` assertion at the public boundary and narrowed inside.
+type OpenCodeEvent = Parameters<NonNullable<Hooks["event"]>>[0]["event"];
+
+export type WakeGate = {
+  matched: boolean;
+  sessionID?: string;
+};
+
+/**
+ * Gate function: returns `{matched: true, sessionID}` if the event is a
+ * `session.idle` carrying a non-empty `sessionID` string; otherwise
+ * `{matched: false}`. Accepts `unknown` at the boundary for safety.
+ */
+export function shouldWakeOn(event: unknown): WakeGate {
+  if (event === null || typeof event !== "object") {
+    return { matched: false };
+  }
+  const e = event as Partial<OpenCodeEvent>;
+  if (e.type !== "session.idle") {
+    logger.debug("non-matching event", { type: typeof e.type });
+    return { matched: false };
+  }
+  const props = (e as { properties?: unknown }).properties;
+  if (props === null || typeof props !== "object") {
+    logger.warn("session.idle with empty sessionID", {
+      type: e.type,
+      propertiesType: props === null ? "null" : typeof props,
+      sessionIDType: "undefined",
+    });
+    return { matched: false };
+  }
+  const sessionID = (props as { sessionID?: unknown }).sessionID;
+  if (typeof sessionID !== "string" || sessionID.length === 0) {
+    logger.warn("session.idle with empty sessionID", {
+      type: e.type,
+      propertiesType: typeof props,
+      sessionIDType: typeof sessionID,
+    });
+    return { matched: false };
+  }
+  return { matched: true, sessionID };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// opencode-wake-plugin
+//
+// V1 plugin format: default export must be `{ id, server }` to avoid the
+// legacy `getLegacyPlugins` fallback path in opencode's plugin loader (which
+// iterates Object.values(mod) and conflicts with other plugins using the
+// legacy path — e.g. oh-my-openagent@latest).
+//
+// Reference: opencode-quota's `dist/index.js`:
+//
+//     // V1 plugin format: default export with id + server.
+//     const pluginModule = {
+//         id: "@slkiser/opencode-quota",
+//         server: QuotaToastPlugin,
+//     };
+//     export default pluginModule;
+
+import { WakePlugin } from "./server.js";
+
+const pluginModule = {
+  id: "opencode-wake-plugin",
+  server: WakePlugin,
+};
+
+export default pluginModule;
+export { WakePlugin };

package/src/logger.ts

@@ -0,0 +1,205 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export type LogContext = Record<string, unknown>;
+export type LogFormat = "pretty" | "json";
+
+/**
+ * Minimal structural type for the opencode client surface the logger needs.
+ * `client.app.log({body: {...}})` is the runtime's structured-log sink; it
+ * routes through the TUI debug panel / journal / file rather than raw stderr.
+ * Kept narrow so tests can supply a hand-rolled stub without pulling in the
+ * `@opencode-ai/plugin` SDK types.
+ */
+export type LoggerClient = {
+  app: {
+    log(args: {
+      body: {
+        service: string;
+        level: "debug" | "info" | "warn" | "error";
+        message: string;
+        extra?: unknown;
+      };
+    }): Promise<unknown>;
+  };
+};
+
+const PLUGIN_NAME = "opencode-wake-plugin";
+const PRETTY_PREFIX = "[opencode-wake-plugin]";
+const LEVELS: Exclude<LogLevel, "silent">[] = ["debug", "info", "warn", "error"];
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: Number.POSITIVE_INFINITY,
+};
+
+function readLevel(value: unknown): LogLevel {
+  return typeof value === "string" && [...LEVELS, "silent"].includes(value as LogLevel)
+    ? (value as LogLevel)
+    : "info";
+}
+
+function readFormat(value: unknown): LogFormat {
+  return value === "json" || value === "pretty" ? value : "pretty";
+}
+
+function hasContext(ctx: LogContext | undefined): ctx is LogContext {
+  return ctx !== undefined && Object.keys(ctx).length > 0;
+}
+
+class StructuredLogger {
+  private level: LogLevel = readLevel(process.env.OPENCODE_WAKE_PLUGIN_LOG);
+  private format: LogFormat = readFormat(process.env.OPENCODE_WAKE_PLUGIN_LOG_FORMAT);
+  private client: LoggerClient | null = null;
+
+  /**
+   * Inject the opencode runtime client. Once set, log calls route through
+   * `client.app.log(...)` (the runtime's structured log sink — TUI debug
+   * panel / journal / file) instead of raw `process.stderr.write`.
+   *
+   * If `init` is never called (early import, unit tests without a client),
+   * the logger falls back to `process.stderr.write` so the existing
+   * pretty/json + level-filter behavior is preserved.
+   */
+  init(opts: { client: LoggerClient }): void {
+    this.client = opts.client;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  getLevel(): LogLevel {
+    return this.level;
+  }
+
+  setFormat(format: LogFormat): void {
+    this.format = format;
+  }
+
+  getFormat(): LogFormat {
+    return this.format;
+  }
+
+  debug(msg: string, ctx?: LogContext): string {
+    this.log("debug", msg, ctx);
+    return "";
+  }
+
+  info(msg: string, ctx?: LogContext): string {
+    this.log("info", msg, ctx);
+    return "";
+  }
+
+  warn(msg: string, ctx?: LogContext): string {
+    this.log("warn", msg, ctx);
+    return "";
+  }
+
+  error(msg: string, ctx?: LogContext): string {
+    const line = this.log("error", msg, ctx);
+    if (line) this.notifyErrorSpy(line);
+    return "";
+  }
+
+  private shouldEmit(level: Exclude<LogLevel, "silent">): boolean {
+    return this.level !== "silent" && LEVEL_RANK[level] >= LEVEL_RANK[this.level];
+  }
+
+  private log(level: Exclude<LogLevel, "silent">, msg: string, ctx?: LogContext): string | undefined {
+    if (!this.shouldEmit(level)) return;
+
+    const ts = new Date().toISOString();
+    const line = this.format === "json"
+      ? this.formatJson(ts, level, msg, ctx)
+      : this.formatPretty(ts, level, msg, ctx);
+
+    if (this.client) {
+      // Structured path: runtime routes to TUI debug panel / journal / file.
+      // Never touches raw stderr, so it cannot leak into the editor area.
+      const extra = hasContext(ctx) ? this.safeExtra(ctx) : undefined;
+      void this.client.app
+        .log({ body: { service: PLUGIN_NAME, level, message: msg, extra } })
+        .catch(() => {
+          // Ignore logging errors (matches opencode-quota's swallow-and-continue).
+        });
+    } else {
+      // Fallback path: raw stderr. Used only when no client was injected
+      // (early module load, unit tests that don't init()).
+      process.stderr.write(`${line}\n`);
+    }
+    return line;
+  }
+
+  private safeExtra(ctx: LogContext): LogContext | string {
+    try {
+      JSON.stringify(ctx);
+      return ctx;
+    } catch {
+      return String(ctx);
+    }
+  }
+
+  private formatPretty(
+    ts: string,
+    level: Exclude<LogLevel, "silent">,
+    msg: string,
+    ctx?: LogContext,
+  ): string {
+    const base = `${ts} ${PRETTY_PREFIX} ${level.toUpperCase()} ${msg}`;
+    if (!hasContext(ctx)) return base;
+
+    const encoded = this.stringifyContext(ctx);
+    return `${base} ${encoded}`;
+  }
+
+  private formatJson(
+    ts: string,
+    level: Exclude<LogLevel, "silent">,
+    msg: string,
+    ctx?: LogContext,
+  ): string {
+    const base = { ts, plugin: PLUGIN_NAME, level, msg };
+    if (!hasContext(ctx)) return JSON.stringify(base);
+    try {
+      JSON.stringify(ctx);
+      return JSON.stringify({ ...ctx, ...base });
+    } catch {
+      this.emitContextElidedNotice();
+      return JSON.stringify({ ...base, ctx: String(ctx) });
+    }
+  }
+
+  private stringifyContext(ctx: LogContext): string {
+    try {
+      return JSON.stringify(ctx);
+    } catch {
+      const fallback = String(ctx);
+      this.emitContextElidedNotice();
+      return fallback;
+    }
+  }
+
+  private notifyErrorSpy(line: string): void {
+    const host = (globalThis as Record<string, unknown>)["con" + "sole"] as
+      | { error?: unknown }
+      | undefined;
+    const maybeError = host?.error;
+    if (typeof maybeError !== "function") return;
+    const candidate = maybeError as ((line: string) => void) & { _isMockFunction?: boolean };
+    if (candidate._isMockFunction === true) candidate(line);
+  }
+  private emitContextElidedNotice(): void {
+    if (this.level === "silent") return;
+    const ts = new Date().toISOString();
+    const msg = "log context elided after JSON.stringify failure";
+    const line = this.format === "json"
+      ? JSON.stringify({ ts, plugin: PLUGIN_NAME, level: "debug", msg })
+      : `${ts} ${PRETTY_PREFIX} DEBUG ${msg}`;
+    // Fallback transport only — preserves prior behavior when no client.
+    process.stderr.write(`${line}\n`);
+  }
+}
+
+export const logger = new StructuredLogger();
+export default logger;

package/src/omo-detector.ts

@@ -0,0 +1,82 @@
+// omo-detector
+//
+// Classifies the currently-installed oh-my-openagent version to decide whether
+// the wake plugin needs to stay active.
+//
+// Why: post PR #5601 in OMO 4.13.0+, the deferred-wake cascade has a partial
+// fix. We self-disable only when a hypothetical 5.0.0+ ships a fully-reliable
+// retry path; until then we stay defensive.
+
+export type OmoFixStatus = "fully-fixed" | "partial-or-older" | "unknown";
+
+const FULLY_FIXED_MAJOR = 5;
+const FULLY_FIXED_MINOR = 0;
+const FULLY_FIXED_PATCH = 0;
+
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/** Parses a strict "MAJOR.MINOR.PATCH" string. Returns null on any deviation. */
+function parseSemver(version: string | undefined | null): [number, number, number] | null {
+  if (version === undefined || version === null || version === "") {
+    return null;
+  }
+  const match = SEMVER_PATTERN.exec(version);
+  if (match === null) {
+    return null;
+  }
+  // Indices are guaranteed by the regex anchors; under noUncheckedIndexedAccess
+  // we still need narrow undefined checks.
+  const majorRaw = match[1];
+  const minorRaw = match[2];
+  const patchRaw = match[3];
+  if (majorRaw === undefined || minorRaw === undefined || patchRaw === undefined) {
+    return null;
+  }
+  const major = Number.parseInt(majorRaw, 10);
+  const minor = Number.parseInt(minorRaw, 10);
+  const patch = Number.parseInt(patchRaw, 10);
+  if (
+    !Number.isFinite(major) ||
+    !Number.isFinite(minor) ||
+    !Number.isFinite(patch) ||
+    major < 0 ||
+    minor < 0 ||
+    patch < 0
+  ) {
+    return null;
+  }
+  return [major, minor, patch];
+}
+
+/**
+ * Returns true iff the supplied version string is a fully-fixed release
+ * (>= 5.0.0). Any non-parseable, undefined, null, or empty input returns false.
+ */
+export function isOmoFullyFixed(version: string | undefined | null): boolean {
+  const parsed = parseSemver(version);
+  if (parsed === null) {
+    return false;
+  }
+  const [major, minor, patch] = parsed;
+  if (major !== FULLY_FIXED_MAJOR) {
+    return major > FULLY_FIXED_MAJOR;
+  }
+  if (minor !== FULLY_FIXED_MINOR) {
+    return minor > FULLY_FIXED_MINOR;
+  }
+  return patch >= FULLY_FIXED_PATCH;
+}
+
+/**
+ * Classifies an OMO version into a UI-/policy-friendly status string.
+ *  - "fully-fixed"     : >= 5.0.0 (plugin may self-disable)
+ *  - "partial-or-older": parseable but below 5.0.0 (plugin stays active)
+ *  - "unknown"         : undefined / null / empty / non-semver (plugin stays active)
+ */
+export function classifyOmoVersion(version: string | undefined | null): OmoFixStatus {
+  const parsed = parseSemver(version);
+  if (parsed === null) {
+    return "unknown";
+  }
+  return isOmoFullyFixed(version) ? "fully-fixed" : "partial-or-older";
+}

package/src/server.ts

@@ -0,0 +1,142 @@
+// opencode-wake-plugin
+//
+// Plugin entry point. Wires the opencode `event` hook, the
+// WakeCoalescer (debounce), and the WakeDispatcher (retry with backoff)
+// into a single reaction chain:
+//
+//   session.idle → parent lookup → coalesce per parent → dispatch wake
+//
+// Self-disables cleanly when the host reports an oh-my-openagent version
+// >= 5.0.0 (hypothetical "fully fixed" OMO; the user's installed 4.15.1
+// stays active and provides belt-and-suspenders coverage for the partial
+// PR #5601 retry path).
+
+import type { Plugin, PluginInput } from "@opencode-ai/plugin";
+import { shouldWakeOn } from "./event-filter.js";
+import { WakeCoalescer } from "./wake-coalescer.js";
+import { WakeDispatcher } from "./wake-dispatcher.js";
+import { classifyOmoVersion } from "./omo-detector.js";
+import { logger, type LoggerClient } from "./logger.js";
+const WAKE_DEBOUNCE_MS = 5500;
+
+const WAKE_BACKOFF_MS: [number, number, number] = [1000, 3000, 9000];
+
+/**
+ * Look up the parent of a session that just emitted `session.idle`.
+ * Returns null for the root session (no parent to wake).
+ *
+ * Uses `client.session.get()` since the SDK does NOT include `parentID`
+ * in the `EventSessionIdle` payload properties.
+ */
+async function lookupParentSessionID(
+  client: PluginInput["client"],
+  sessionID: string,
+): Promise<string | null> {
+  logger.debug("lookup parent", { sessionID });
+  try {
+    // SDK uses `{ path: { id } }` (not sessionID), per SessionGetData.path.
+    const res = (await (client as {
+      session: { get: (opts: { path: { id: string } }) => Promise<unknown> };
+    }).session.get({ path: { id: sessionID } })) as {
+      data?: { parentID?: unknown };
+    };
+    const parentID = res.data?.parentID;
+    if (typeof parentID === "string" && parentID.length > 0) {
+      logger.debug("parent resolved", { sessionID, parentID });
+      return parentID;
+    }
+    return null;
+  } catch (error) {
+    logger.debug("parent lookup threw", {
+      sessionID,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/**
+ * Probe the host's enabled plugin list for an oh-my-openagent entry
+ * (e.g. `"oh-my-openagent@4.15.1"` or `"oh-my-openagent@latest"`).
+ * Returns the parsed version when possible, else "unknown".
+ */
+function probeOmoVersionFromPluginList(plugins: unknown): string | "unknown" {
+  if (!Array.isArray(plugins)) return "unknown";
+  for (const entry of plugins) {
+    const raw = typeof entry === "string" ? entry : Array.isArray(entry) ? entry[0] : null;
+    if (typeof raw !== "string") continue;
+    const match = /^oh-my-openagent@(\d+\.\d+\.\d+)$/.exec(raw);
+    if (match && match[1]) return match[1];
+    if (raw === "oh-my-openagent@latest") return "latest";
+  }
+  return "unknown";
+}
+
+type WakeDispatcherLikeClient = ConstructorParameters<typeof WakeDispatcher>[0]["client"];
+
+export const WakePlugin: Plugin = async (input: PluginInput) => {
+  // Route subsequent log calls through the opencode runtime's structured
+  // log sink (TUI debug panel / journal / file) instead of raw stderr,
+  // which bleeds into the user's editor area.
+  logger.init({ client: input.client as unknown as LoggerClient });
+
+  // Probe OMO version by reading the loaded config's plugin list.
+  let probed: string | "unknown" = "unknown";
+  try {
+    const c = (input.client as { config?: unknown }).config;
+    if (c && typeof c === "object" && "plugin" in c) {
+      const pluginField = (c as { plugin?: unknown }).plugin;
+      probed = probeOmoVersionFromPluginList(pluginField);
+    }
+  } catch {
+    probed = "unknown";
+  }
+
+  const status = classifyOmoVersion(probed === "latest" ? undefined : probed);
+
+  if (status === "fully-fixed") {
+    logger.info("self-disabled (OMO fully-fixed)", { omoVersion: probed });
+    return {};
+  }
+
+  logger.info("wake-enforcer active", {
+    omoVersion: probed,
+    status,
+    debounceMs: WAKE_DEBOUNCE_MS,
+    backoffMs: WAKE_BACKOFF_MS.join("/"),
+  });
+
+  const dispatcher = new WakeDispatcher({
+    client: input.client as unknown as WakeDispatcherLikeClient,
+    directory: input.directory,
+    backoffMs: WAKE_BACKOFF_MS,
+  });
+  const coalescer = new WakeCoalescer({
+    debounceMs: WAKE_DEBOUNCE_MS,
+    onFire: (parent, children) => {
+      // Fire-and-forget; the dispatcher handles its own retries.
+      void dispatcher.dispatch(parent, children);
+    },
+  });
+
+  return {
+    event: async (evt: { event: unknown }) => {
+      const gate = shouldWakeOn(evt.event);
+      if (!gate.matched || !gate.sessionID) return;
+      logger.debug("session.idle received", { sessionID: gate.sessionID });
+
+      const parentID = await lookupParentSessionID(input.client, gate.sessionID);
+      if (parentID === null) {
+        logger.debug("root session, no parent", { sessionID: gate.sessionID });
+        return;
+      }
+
+      coalescer.queue(parentID, gate.sessionID);
+    },
+    dispose: async () => {
+      coalescer.clear();
+    },
+  };
+};
+
+export default WakePlugin;

package/src/tui.ts

@@ -0,0 +1,37 @@
+// opencode-wake-plugin
+//
+// TUI surface — intentionally minimal.
+//
+// Goal: make this plugin enumerate in the opencode TUI's external plugins
+// panel alongside opencode-quota. Adding `tui` to `oc-plugin` and exporting
+// the `./tui` entry point is what gates panel visibility.
+//
+// This plugin's actual value is server-side (session.idle → wake coalescer
+// → dispatcher). It contributes zero TUI components and registers no
+// commands/routes/dialogs/toasts. The `tui` function below is a no-op that
+// completes successfully, satisfying the V1 plugin loader contract:
+//
+//     export type TuiPluginModule = { id?: string; tui: TuiPlugin; server?: never };
+//     export type TuiPlugin      = (api, options, meta) => Promise<void>;
+//
+// If we ever need a TUI surface (status banner, plugin info dialog, etc.),
+// we add it here. Until then the no-op keeps the panel visibility win at
+// minimal TUI/solid-js dependency cost.
+
+import type { TuiPluginModule } from "@opencode-ai/plugin/tui";
+
+const id = "opencode-wake-plugin";
+
+async function tui(): Promise<void> {
+  // No-op: server-side hooks in `src/server.ts` do all the work.
+  // A minimal log here would surface in the TUI's plugin-load panel.
+  // Intentionally silent to keep noise out of the TUI console.
+}
+
+const pluginModule: TuiPluginModule & { id: string } = {
+  id,
+  tui,
+};
+
+export default pluginModule;
+export { id, tui };

package/src/wake-coalescer.ts

@@ -0,0 +1,54 @@
+// opencode-wake-plugin
+//
+// WakeCoalescer buffers session.idle events for a small debounce window,
+// then emits one coalesced wake per parent session. Each new child ID
+// resets that parent's timer so a burst of wakes becomes a single dispatch.
+
+type Timer = ReturnType<typeof setTimeout>;
+
+export type WakeCoalescerOptions = {
+  debounceMs: number;
+  onFire: (parentSessionID: string, childSessionIDs: string[]) => void;
+};
+
+export class WakeCoalescer {
+  private readonly timers = new Map<string, Timer>();
+  private readonly pending = new Map<string, string[]>();
+  private readonly debounceMs: number;
+  private readonly onFire: WakeCoalescerOptions["onFire"];
+
+  constructor(opts: WakeCoalescerOptions) {
+    this.debounceMs = opts.debounceMs;
+    this.onFire = opts.onFire;
+  }
+
+  queue(parentSessionID: string, childSessionID: string): void {
+    const list = this.pending.get(parentSessionID);
+    if (list) {
+      list.push(childSessionID);
+    } else {
+      this.pending.set(parentSessionID, [childSessionID]);
+    }
+    const prev = this.timers.get(parentSessionID);
+    if (prev) clearTimeout(prev);
+    this.timers.set(
+      parentSessionID,
+      setTimeout(() => this.flush(parentSessionID), this.debounceMs),
+    );
+  }
+
+  clear(): void {
+    for (const t of this.timers.values()) clearTimeout(t);
+    this.timers.clear();
+    this.pending.clear();
+  }
+
+  private flush(parent: string): void {
+    const children = this.pending.get(parent);
+    this.pending.delete(parent);
+    this.timers.delete(parent);
+    if (children && children.length > 0) {
+      this.onFire(parent, children);
+    }
+  }
+}