opencode-discipline 0.2.2 → 0.3.0

package/README.md

@@ -28,6 +28,39 @@ It provides:
 bun run build
 ```
 
+## Notifications (optional)
+
+On startup, the plugin shows a small in-app toast: `opencode-discipline vX is running`.
+
+You can enable milestone notifications for key planning events:
+
+- `Need your answers` (agent question prompts)
+- `Plan is ready` (Wave 4 handoff stage)
+- `OpenCode has finished` (Build agent completion)
+
+Set one environment variable before running OpenCode:
+
+```bash
+export OPENCODE_DISCIPLINE_NOTIFY=metadata
+```
+
+Supported modes:
+
+- `off`
+- `metadata` (emit structured notification metadata)
+- `os` (default; desktop notification via `osascript`/`notify-send`/PowerShell)
+- `both` (metadata + OS)
+
+Optional custom command hook:
+
+```bash
+export OPENCODE_DISCIPLINE_NOTIFY_COMMAND='terminal-notifier -title "{title}" -message "{message}"'
+```
+
+Template variables: `{event}`, `{title}`, `{message}`, `{sessionID}`.
+
+Build completion notifications are emitted automatically when OpenCode reports the Build session as idle (`session.idle`).
+
 ## Test
 
 ```bash

package/dist/index.js

@@ -6915,8 +6915,9 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // src/index.ts
-import { accessSync, constants, existsSync as existsSync2 } from "fs";
+import { accessSync, constants, existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
 import { basename as basename2, dirname, relative, resolve as resolve2 } from "path";
+import { spawn } from "child_process";
 import { fileURLToPath } from "url";
 
 // node_modules/@opencode-ai/plugin/node_modules/zod/v4/classic/external.js
@@ -19585,6 +19586,29 @@ class WaveStateManager {
     this.persist(nextState);
     return nextState;
   }
+  isAcceptedBuildSession(sessionID) {
+    for (const state of this.states.values()) {
+      if (state.acceptedBySessionID === sessionID) {
+        return true;
+      }
+    }
+    if (!existsSync(this.stateDir)) {
+      return false;
+    }
+    const entries = readdirSync2(this.stateDir).filter((entry) => entry.endsWith(".json"));
+    for (const entry of entries) {
+      try {
+        const path = join(this.stateDir, entry);
+        const parsed = JSON.parse(readFileSync2(path, "utf8"));
+        if (parsed.acceptedBySessionID === sessionID) {
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+    return false;
+  }
   persist(state) {
     this.ensureDir();
     const filePath = join(this.stateDir, `${state.planName}.json`);
@@ -19627,6 +19651,155 @@ var WAVE_NEXT_STEPS = {
   3: "writing the plan file",
   4: "plan review and refinement"
 };
+var PLUGIN_DISPLAY_NAME = "opencode-discipline";
+var startupToastShown = false;
+function parseNotificationMode(raw) {
+  const value = raw?.trim().toLowerCase();
+  if (!value) {
+    return "os";
+  }
+  if (value === "off" || value === "0" || value === "false" || value === "disabled") {
+    return "off";
+  }
+  if (value === "metadata") {
+    return "metadata";
+  }
+  if (value === "both" || value === "all") {
+    return "both";
+  }
+  return "os";
+}
+function readPluginVersion(pluginDir) {
+  try {
+    const packageJsonPath = resolve2(pluginDir, "../package.json");
+    const packageJson = JSON.parse(readFileSync3(packageJsonPath, "utf8"));
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function showStartupToast(client, directory, version2) {
+  if (startupToastShown) {
+    return;
+  }
+  const tuiApi = client.tui;
+  if (!tuiApi || typeof tuiApi.showToast !== "function") {
+    return;
+  }
+  try {
+    await tuiApi.showToast({
+      query: { directory },
+      body: {
+        title: "Discipline Plugin",
+        message: `${PLUGIN_DISPLAY_NAME} v${version2} is running`,
+        variant: "info",
+        duration: 3000
+      }
+    });
+    startupToastShown = true;
+  } catch {}
+}
+function escapeAppleScriptString(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"");
+}
+function escapePowerShellString(value) {
+  return value.replaceAll("'", "''");
+}
+
+class NotificationManager {
+  mode;
+  commandTemplate;
+  sentKeys = new Map;
+  constructor() {
+    this.mode = parseNotificationMode(process.env.OPENCODE_DISCIPLINE_NOTIFY);
+    this.commandTemplate = process.env.OPENCODE_DISCIPLINE_NOTIFY_COMMAND?.trim();
+  }
+  notify(input) {
+    if (this.mode === "off") {
+      return;
+    }
+    if (this.isSent(input.sessionID, input.dedupeKey)) {
+      return;
+    }
+    this.markSent(input.sessionID, input.dedupeKey);
+    if (this.mode === "metadata" || this.mode === "both") {
+      this.emitMetadata(input);
+    }
+    if (this.mode === "os" || this.mode === "both") {
+      this.emitOsNotification(input);
+    }
+  }
+  isSent(sessionID, key) {
+    const keys = this.sentKeys.get(sessionID);
+    return keys?.has(key) ?? false;
+  }
+  markSent(sessionID, key) {
+    const keys = this.sentKeys.get(sessionID) ?? new Set;
+    keys.add(key);
+    this.sentKeys.set(sessionID, keys);
+  }
+  emitMetadata(input) {
+    if (!input.toolContext || typeof input.toolContext !== "object") {
+      return;
+    }
+    const maybeMetadata = input.toolContext.metadata;
+    if (typeof maybeMetadata !== "function") {
+      return;
+    }
+    try {
+      maybeMetadata({
+        type: "discipline.notification",
+        event: input.event,
+        title: input.title,
+        message: input.message,
+        sessionID: input.sessionID,
+        createdAt: new Date().toISOString()
+      });
+    } catch {}
+  }
+  emitOsNotification(input) {
+    if (this.commandTemplate) {
+      const command = this.commandTemplate.replaceAll("{event}", input.event).replaceAll("{title}", input.title).replaceAll("{message}", input.message).replaceAll("{sessionID}", input.sessionID);
+      this.spawnDetached(process.platform === "win32" ? "cmd.exe" : "sh", process.platform === "win32" ? ["/d", "/s", "/c", command] : ["-lc", command]);
+      return;
+    }
+    if (process.platform === "darwin") {
+      const script = `display notification "${escapeAppleScriptString(input.message)}" with title "${escapeAppleScriptString(input.title)}"`;
+      this.spawnDetached("osascript", ["-e", script]);
+      return;
+    }
+    if (process.platform === "linux") {
+      this.spawnDetached("notify-send", [input.title, input.message]);
+      return;
+    }
+    if (process.platform === "win32") {
+      const script = [
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "$notify = New-Object System.Windows.Forms.NotifyIcon",
+        "$notify.Icon = [System.Drawing.SystemIcons]::Information",
+        "$notify.BalloonTipTitle = '",
+        escapePowerShellString(input.title),
+        "'",
+        "$notify.BalloonTipText = '",
+        escapePowerShellString(input.message),
+        "'",
+        "$notify.Visible = $true",
+        "$notify.ShowBalloonTip(4000)"
+      ].join(" ");
+      this.spawnDetached("powershell", ["-NoProfile", "-Command", script]);
+    }
+  }
+  spawnDetached(command, args) {
+    try {
+      const child = spawn(command, args, {
+        stdio: "ignore",
+        detached: true
+      });
+      child.on("error", () => {});
+      child.unref();
+    } catch {}
+  }
+}
 function hasStringProp(obj, key) {
   return key in obj && typeof obj[key] === "string";
 }
@@ -19642,6 +19815,41 @@ function extractSessionID(result) {
   }
   return;
 }
+function extractSessionIDFromHookInput(input) {
+  if (!input || typeof input !== "object") {
+    return;
+  }
+  if (hasStringProp(input, "sessionID")) {
+    return input.sessionID;
+  }
+  if (hasStringProp(input, "id")) {
+    return input.id;
+  }
+  const value = input;
+  const path = value.path;
+  if (path && typeof path === "object" && hasStringProp(path, "id")) {
+    return path.id;
+  }
+  const session = value.session;
+  if (session && typeof session === "object" && hasStringProp(session, "id")) {
+    return session.id;
+  }
+  return;
+}
+function extractAgentFromHookInput(input) {
+  if (!input || typeof input !== "object") {
+    return;
+  }
+  if (hasStringProp(input, "agent")) {
+    return input.agent.toLowerCase();
+  }
+  const value = input;
+  const session = value.session;
+  if (session && typeof session === "object" && hasStringProp(session, "agent")) {
+    return session.agent.toLowerCase();
+  }
+  return;
+}
 function getWaveLabel(wave) {
   return WAVE_NAMES[wave];
 }
@@ -19664,6 +19872,7 @@ function isBlockedEnvRead(filePath) {
   return fileName.startsWith(".env.");
 }
 function buildWaveStateSystemBlock(wave, planName) {
+  const advanceGuidance = wave === 1 ? "Call `advance_wave` only after Wave 1 interview + checklist work is complete." : wave === 2 ? "Call `advance_wave` only after the Wave 2 Oracle check has completed and gap analysis is done." : wave === 3 ? "Call `advance_wave` only after the plan file is written and Wave 3 is complete." : "Do not call `advance_wave` again unless you are truly done with Wave 4 and ready for handoff decisions.";
   return [
     "## \uD83D\uDD12 Discipline Plugin \u2014 Wave State",
     "",
@@ -19677,7 +19886,7 @@ function buildWaveStateSystemBlock(wave, planName) {
     "- Wave 3 (Plan Generation): NOW write the plan to tasks/plans/{planName}.md using the structured template.",
     "- Wave 4 (Review): Self-review the plan. Delegate to @oracle for high-stakes decisions. Edit the plan if needed.",
     "",
-    `**You are in Wave ${wave}. Call \`advance_wave\` to move to the next wave.**`,
+    `**You are in Wave ${wave}.** ${advanceGuidance}`,
     "**Writing to tasks/plans/*.md is BLOCKED until Wave 3.**"
   ].join(`
 `);
@@ -19687,7 +19896,8 @@ function buildWave2OraclePrompt() {
     "## MANDATORY: Wave 2 Oracle Check",
     "Before you can advance to Wave 3, delegate to `@oracle` once for a gap-analysis sanity check.",
     'Use the Task tool with `subagent_type: "oracle"` and summarize the result in your analysis.',
-    "Wave 2 -> 3 is enforced: `advance_wave` will fail until this Oracle check is completed."
+    "Wave 2 -> 3 is enforced: `advance_wave` will fail until this Oracle check is completed.",
+    "Do NOT retry `advance_wave` until the Oracle task returns successfully."
   ].join(`
 `);
 }
@@ -19908,6 +20118,25 @@ async function handleCompacting(ctx, input, output) {
   }
   output.context.push(buildCompactionContext(state));
 }
+async function handleSessionIdle(ctx, input, _output) {
+  const sessionID = extractSessionIDFromHookInput(input);
+  if (!sessionID) {
+    return;
+  }
+  const agent = extractAgentFromHookInput(input);
+  const isBuildIdle = agent === "build" || ctx.manager.isAcceptedBuildSession(sessionID);
+  if (!isBuildIdle) {
+    return;
+  }
+  ctx.notifications.notify({
+    sessionID,
+    event: "coding_complete",
+    title: "OpenCode has finished",
+    message: "The Build agent is done and OpenCode is ready for input.",
+    dedupeKey: "session-idle-coding-complete",
+    toolContext: input
+  });
+}
 async function handleSystemTransform(ctx, input, output) {
   const sessionID = input.sessionID;
   const state = sessionID ? ctx.manager.getState(sessionID) : undefined;
@@ -19929,6 +20158,15 @@ async function handleSystemTransform(ctx, input, output) {
   if (state.wave === 4) {
     const planFilePath = resolve2(ctx.worktree, `tasks/plans/${state.planName}.md`);
     if (existsSync2(planFilePath)) {
+      if (sessionID) {
+        ctx.notifications.notify({
+          sessionID,
+          event: "plan_ready",
+          title: "Plan is ready",
+          message: `tasks/plans/${state.planName}.md is ready for handoff review.`,
+          dedupeKey: "wave-4-plan-ready"
+        });
+      }
       output.system.push(buildPlanHandoffPrompt(state.planName));
     }
   }
@@ -19969,6 +20207,19 @@ async function handleToolExecuteBefore(ctx, input, output) {
   }
 }
 async function handleToolExecuteAfter(ctx, input, output) {
+  if (input.tool === "question") {
+    const condensed = output.output.replace(/\s+/g, " ").trim();
+    const questionText = condensed.length > 180 ? `${condensed.slice(0, 177)}...` : condensed;
+    ctx.notifications.notify({
+      sessionID: input.sessionID,
+      event: "need_answers",
+      title: "Need your answers",
+      message: questionText || "The agent asked a question and is waiting for your answer.",
+      dedupeKey: `question-${input.callID}`,
+      toolContext: output
+    });
+    return;
+  }
   const state = ctx.manager.getState(input.sessionID);
   if (!state || state.accepted) {
     return;
@@ -20028,9 +20279,31 @@ function createAdvanceWaveTool(ctx) {
         }
         const waveName = WAVE_NAMES[state.wave];
         const nextStep = WAVE_NEXT_STEPS[state.wave];
-        return `Wave ${state.wave} (${waveName}) started for plan '${state.planName}'. You may now proceed with ${nextStep}.`;
+        const advanceWhen = state.wave === 1 ? "Call `advance_wave` only after interview + checklist work is complete." : state.wave === 2 ? "Call `advance_wave` only after Oracle review is complete and gap analysis is done." : state.wave === 3 ? "Call `advance_wave` only after the plan file is written." : "Stay in Wave 4 for plan review/handoff; call `advance_wave` only if explicitly needed (normally you should use `accept_plan`).";
+        if (state.wave === 4) {
+          const planFilePath = resolve2(ctx.worktree, `tasks/plans/${state.planName}.md`);
+          if (existsSync2(planFilePath)) {
+            ctx.notifications.notify({
+              sessionID: args.sessionID,
+              event: "plan_ready",
+              title: "Plan is ready",
+              message: `tasks/plans/${state.planName}.md is ready for handoff review.`,
+              dedupeKey: "wave-4-plan-ready",
+              toolContext: context
+            });
+          }
+        }
+        return `Wave ${state.wave} (${waveName}) started for plan '${state.planName}'. You may now proceed with ${nextStep}. ${advanceWhen}`;
       } catch (error45) {
         const message = error45 instanceof Error ? error45.message : "Unknown error";
+        if (message.includes("Cannot advance to Wave 3 before Oracle gap review is completed")) {
+          return [
+            `Error: ${message}`,
+            "You are still in Wave 2 (Gap Analysis).",
+            'Next action: run Task with subagent_type="oracle" and wait for successful completion.',
+            "Do NOT call advance_wave again until that Oracle task succeeds."
+          ].join(" ");
+        }
         return `Error: ${message}`;
       }
     }
@@ -20137,14 +20410,17 @@ function createAcceptPlanTool(ctx) {
 }
 var DisciplinePlugin = async ({ worktree, directory, client }) => {
   const pluginDir = dirname(fileURLToPath(import.meta.url));
+  const pluginVersion = readPluginVersion(pluginDir);
   const agentConfigs = loadAgentConfigs(resolve2(pluginDir, "../agents"));
   const ctx = {
     manager: new WaveStateManager(worktree),
     todoNudges: new Map,
+    notifications: new NotificationManager,
     worktree,
     directory,
     client
   };
+  await showStartupToast(client, directory, pluginVersion);
   return {
     config: async (input) => {
       const agents = input.agent;
@@ -20158,6 +20434,7 @@ var DisciplinePlugin = async ({ worktree, directory, client }) => {
     "experimental.chat.system.transform": (input, output) => handleSystemTransform(ctx, input, output),
     "tool.execute.before": (input, output) => handleToolExecuteBefore(ctx, input, output),
     "tool.execute.after": (input, output) => handleToolExecuteAfter(ctx, input, output),
+    "session.idle": (input, output) => handleSessionIdle(ctx, input, output),
     tool: {
       advance_wave: createAdvanceWaveTool(ctx),
       accept_plan: createAcceptPlanTool(ctx)

package/dist/wave-state.d.ts

@@ -23,6 +23,7 @@ export declare class WaveStateManager {
     getPlanName(sessionID: string): string | undefined;
     isWaveAtLeast(sessionID: string, minWave: Wave): boolean;
     markAccepted(sessionID: string, buildSessionID: string): WaveState;
+    isAcceptedBuildSession(sessionID: string): boolean;
     private persist;
     private ensureDir;
     private loadStateFromDisk;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-discipline",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",