@prevalentware/opencode-goal-plugin 0.1.15 → 0.1.17

package/README.md

@@ -1,8 +1,20 @@
 # OpenCode Goal Plugin
 
-Codex-style long-running goal mode for OpenCode.
+[![npm version](https://img.shields.io/npm/v/@prevalentware/opencode-goal-plugin.svg)](https://www.npmjs.com/package/@prevalentware/opencode-goal-plugin)
+[![GitHub repository](https://img.shields.io/badge/GitHub-prevalentWare%2Fopencode--goal--plugin-blue?logo=github)](https://github.com/prevalentWare/opencode-goal-plugin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-This plugin adds:
+OpenCode Goal Plugin adds Codex-style long-running goal mode to OpenCode. It gives AI coding agents a `/goal` slash command, persistent goal state, completion evidence, idle continuation, and a terminal UI goal indicator so an OpenCode session can keep working toward one explicit objective until it is complete, blocked, or cleared.
+
+If you are searching for an OpenCode goal plugin, goal mode for OpenCode, or a way to keep an OpenCode AI coding agent focused on a long-running task, this package is the npm plugin for that workflow.
+
+Links:
+
+- npm package: [`@prevalentware/opencode-goal-plugin`](https://www.npmjs.com/package/@prevalentware/opencode-goal-plugin)
+- GitHub repository: [`prevalentWare/opencode-goal-plugin`](https://github.com/prevalentWare/opencode-goal-plugin)
+- OpenCode plugin command: `opencode plugin @prevalentware/opencode-goal-plugin`
+
+The OpenCode Goal Plugin adds:
 
 - `/goal <objective>` as an OpenCode command for TUI, desktop, and web.
 - A sidebar goal indicator with status, elapsed time, and objective.
@@ -12,6 +24,17 @@ This plugin adds:
 - Optional automatic continuation on `session.idle`.
 - Compaction context so active goals are preserved when OpenCode summarizes a long session.
 
+## Why Use This OpenCode Goal Plugin?
+
+Use this plugin when you want OpenCode to behave more like a goal-driven coding agent instead of a one-prompt assistant. A goal stays visible, survives session compaction, can continue automatically when the session becomes idle, and can only be closed with explicit evidence or a concrete blocker.
+
+Common use cases:
+
+- Keep an OpenCode agent focused during long refactors, migrations, reviews, or test-fixing sessions.
+- Track one explicit objective across TUI, desktop, and web OpenCode surfaces.
+- Require completion evidence before a goal is marked done.
+- Preserve the current goal when OpenCode summarizes or compacts a long conversation.
+
 ## Install
 
 Install locally for the current OpenCode project:
@@ -60,7 +83,8 @@ Server options can be configured in `opencode.json`:
       {
         "auto_continue": true,
         "max_auto_turns": 25,
-        "min_continue_interval_seconds": 3
+        "min_continue_interval_seconds": 3,
+        "max_prompt_failures": 3
       }
     ]
   ]
@@ -72,6 +96,7 @@ Defaults:
 - `auto_continue`: `true`
 - `max_auto_turns`: `25`
 - `min_continue_interval_seconds`: `3`
+- `max_prompt_failures`: `3`
 - `register_command`: `true`
 - `command_name`: `"goal"`
 
@@ -83,7 +108,7 @@ Use `/goal <objective>` in a fresh OpenCode chat to create a long-running goal:
 /goal review the frontend and translate visible English UI text to Spanish
 ```
 
-Bare `/goal` reports the current goal state. `/goal clear` clears the goal. The TUI also includes a `Goal` command-palette entry for viewing, refreshing, or clearing the current goal state without creating a new goal.
+Bare `/goal` reports the current goal state. `/goal pause` pauses the goal without clearing it, and `/goal resume` resumes it. `/goal clear` clears the goal; `/goal stop`, `/goal off`, `/goal reset`, `/goal none`, and `/goal cancel` are clear aliases. The TUI also includes a `Goal` command-palette entry for viewing, refreshing, or clearing the current goal state without creating a new goal.
 
 You can also ask the agent to formulate the objective and call `set_goal` itself, for example: "set your own goal to finish this refactor safely." The tool uses the agent-written objective but still only creates a goal when explicitly requested.
 
@@ -147,4 +172,6 @@ OpenCode plugin modules are target-specific. This package exports separate modul
 }
 ```
 
-Codex goal mode has deeper runtime integration for thread lifecycle control. This plugin implements the same workflow using OpenCode plugin hooks. Token usage is read from OpenCode step-finish usage when available and falls back to message token metadata or text estimation when exact usage is unavailable. Continuation is driven by OpenCode's `session.idle` event.
+Codex goal mode has deeper runtime integration for thread lifecycle control. This plugin implements the same workflow using OpenCode plugin hooks. Token usage is read from OpenCode step-finish usage when available and falls back to message token metadata or text estimation when exact usage is unavailable. Continuation is driven by OpenCode idle events, including `session.idle` and `session.status` idle notifications.
+
+The goal sidebar shows the current status, elapsed time, auto-continue count, latest status message, and objective when a goal is active or paused. Closed goals remain visible briefly through the latest tool state as achieved or unmet.

package/dist/server.js

@@ -32,7 +32,9 @@ var GoalSchema = Schema.Struct({
   closedAt: Schema.optionalWith(NullableNumber, { default: () => null }),
   lastAccountedAt: NullableNumber,
   autoTurns: Schema.Number,
-  lastContinuationAt: NullableNumber
+  lastContinuationAt: NullableNumber,
+  continuationFailures: Schema.optionalWith(Schema.Number, { default: () => 0 }),
+  lastStatus: Schema.optionalWith(NullableString, { default: () => null })
 });
 var StateSchema = Schema.Struct({
   version: Schema.Literal(1),
@@ -145,6 +147,10 @@ function snapshot(goal) {
     completionEvidence: goal.completionEvidence ?? null,
     blocker: goal.blocker ?? null,
     closedAt: goal.closedAt ?? null,
+    continuationFailures: goal.continuationFailures,
+    lastStatus: goal.lastStatus,
+    autoTurns: goal.autoTurns,
+    lastContinuationAt: goal.lastContinuationAt,
     remainingTokens: null,
     sampledAt
   };
@@ -176,12 +182,28 @@ async function createGoal(sessionID, objective, _tokenBudget) {
       closedAt: null,
       lastAccountedAt: now,
       autoTurns: 0,
-      lastContinuationAt: null
+      lastContinuationAt: null,
+      continuationFailures: 0,
+      lastStatus: "Goal set."
     };
     state.goals[sessionID] = goal;
     return snapshot(goal);
   });
 }
+async function setGoalStatus(sessionID, status) {
+  return mutate((state) => {
+    const goal = state.goals[sessionID];
+    if (!goal)
+      throw new Error("cannot update goal because this session has no goal");
+    accountWallClock(goal);
+    goal.status = status;
+    goal.updatedAt = nowSeconds();
+    goal.lastAccountedAt = status === "active" ? goal.updatedAt : null;
+    goal.continuationFailures = status === "active" ? 0 : goal.continuationFailures;
+    goal.lastStatus = status === "active" ? "Goal resumed." : "Goal paused.";
+    return snapshot(goal);
+  });
+}
 async function closeGoal(sessionID, input) {
   return mutate((state) => {
     const goal = state.goals[sessionID];
@@ -252,10 +274,35 @@ async function reserveContinuation(sessionID, maxAutoTurns, minIntervalSeconds)
     accountWallClock(goal, now);
     goal.autoTurns += 1;
     goal.lastContinuationAt = now;
+    goal.lastStatus = `Auto-continue ${goal.autoTurns} reserved.`;
     goal.updatedAt = now;
     return snapshot(goal);
   });
 }
+async function recordContinuationResult(sessionID, result, maxFailures) {
+  return mutate((state) => {
+    const goal = state.goals[sessionID];
+    if (!goal || goal.status !== "active")
+      return goal ? snapshot(goal) : null;
+    const now = nowSeconds();
+    goal.updatedAt = now;
+    if (result === "success") {
+      goal.continuationFailures = 0;
+      goal.lastStatus = "Auto-continue prompt sent.";
+      return snapshot(goal);
+    }
+    goal.continuationFailures += 1;
+    goal.lastStatus = `Auto-continue failed ${goal.continuationFailures} time(s).`;
+    if (goal.continuationFailures >= maxFailures) {
+      accountWallClock(goal, now);
+      goal.status = "paused";
+      goal.lastAccountedAt = null;
+      goal.lastStatus = `Paused after ${goal.continuationFailures} auto-continue failure(s).`;
+      goal.blocker = "Auto-continue prompt failed repeatedly. Resume the goal to retry.";
+    }
+    return snapshot(goal);
+  });
+}
 function accountWallClock(goal, now = nowSeconds()) {
   if (goal.status !== "active")
     return;
@@ -275,8 +322,11 @@ function formatGoal(goal) {
   const lines = [
     `Objective: ${goal.objective}`,
     `Status: ${goal.status}`,
-    `Time used: ${goal.timeUsedSeconds}s`
+    `Time used: ${goal.timeUsedSeconds}s`,
+    `Auto-continues: ${goal.autoTurns}`
   ];
+  if (goal.lastStatus)
+    lines.push(`Last status: ${goal.lastStatus}`);
   if (goal.completionEvidence)
     lines.push(`Completion evidence: ${goal.completionEvidence}`);
   if (goal.blocker)
@@ -335,7 +385,9 @@ Preserve the goal objective, status, elapsed time, and any completion evidence o
 // src/server.ts
 var DEFAULT_MAX_AUTO_TURNS = 25;
 var DEFAULT_CONTINUE_INTERVAL_SECONDS = 3;
+var DEFAULT_MAX_PROMPT_FAILURES = 3;
 var DEFAULT_COMMAND_NAME = "goal";
+var activeContinuations = new Set;
 function goalCommandTemplate(commandName) {
   return `OpenCode goal mode command "/${commandName}" was invoked.
 
@@ -348,7 +400,9 @@ Use the goal tools to handle this command:
 
 - If the arguments are empty, call get_goal and briefly report the current goal state.
 - If the arguments are "status", "show", or "current", call get_goal and briefly report the current goal state.
-- If the arguments are "clear", call clear_goal and report whether a goal was cleared.
+- If the arguments are "clear", "stop", "off", "reset", "none", or "cancel", call clear_goal and report whether a goal was cleared.
+- If the arguments are "pause", pause the current goal by calling update_goal_status with status "paused" and report the result.
+- If the arguments are "resume", resume the current goal by calling update_goal_status with status "active" and continue working toward it.
 - If the arguments start with "complete " or "done ", perform a completion audit against real artifacts and command output. Call update_goal with status "complete" only if the goal is achieved, using concise evidence from the audit.
 - If the arguments start with "unmet ", "blocked ", or "blocker ", call update_goal with status "unmet" only when the goal cannot be achieved or needs external input, using the remaining arguments as the blocker.
 - Otherwise, create a new goal with create_goal. Use the full arguments as the objective.
@@ -426,10 +480,27 @@ async function sendContinuation(client, sessionID, prompt) {
     }
   });
 }
+function isIdleEvent(event) {
+  if (event.type === "session.idle")
+    return true;
+  const status = event.properties?.status;
+  return event.type === "session.status" && typeof status === "object" && status !== null && status.type === "idle";
+}
+function sessionIDFromEvent(event) {
+  const direct = event.properties?.sessionID;
+  if (typeof direct === "string")
+    return direct;
+  const info = event.properties?.info;
+  if (typeof info === "object" && info !== null && typeof info.sessionID === "string") {
+    return info.sessionID;
+  }
+  return;
+}
 var server = async ({ client }, options) => {
   const autoContinue = options?.auto_continue ?? true;
   const maxAutoTurns = options?.max_auto_turns ?? DEFAULT_MAX_AUTO_TURNS;
   const minInterval = options?.min_continue_interval_seconds ?? DEFAULT_CONTINUE_INTERVAL_SECONDS;
+  const maxPromptFailures = options?.max_prompt_failures ?? DEFAULT_MAX_PROMPT_FAILURES;
   const registerCommand = options?.register_command ?? true;
   const commandName = commandNameFromOptions(options);
   return {
@@ -487,6 +558,17 @@ var server = async ({ client }, options) => {
           return JSON.stringify({ goal, unmet_report: report }, null, 2);
         }
       },
+      update_goal_status: {
+        description: "Pause or resume the current OpenCode goal when the user explicitly asks to pause or resume it.",
+        args: {
+          status: z.enum(["active", "paused"]).describe("active resumes a goal; paused pauses it without clearing it.")
+        },
+        async execute(args, context) {
+          const input = args;
+          const goal = await setGoalStatus(context.sessionID, input.status);
+          return JSON.stringify({ goal }, null, 2);
+        }
+      },
       clear_goal: {
         description: "Clear the current OpenCode goal for this session when the user explicitly asks to clear it.",
         args: {},
@@ -513,13 +595,33 @@ var server = async ({ client }, options) => {
       output.context.push(compactionContext(goal));
     },
     async event({ event }) {
-      if (!autoContinue || event.type !== "session.idle")
+      if (!autoContinue || !isIdleEvent(event))
         return;
-      const sessionID = event.properties.sessionID;
-      const goal = await reserveContinuation(sessionID, maxAutoTurns, minInterval);
-      if (!goal)
+      const sessionID = sessionIDFromEvent(event);
+      if (!sessionID)
+        return;
+      if (activeContinuations.has(sessionID))
         return;
-      await sendContinuation(client, sessionID, continuationPrompt(goal));
+      activeContinuations.add(sessionID);
+      try {
+        const goal = await reserveContinuation(sessionID, maxAutoTurns, minInterval);
+        if (!goal)
+          return;
+        await sendContinuation(client, sessionID, continuationPrompt(goal));
+        await recordContinuationResult(sessionID, "success", maxPromptFailures);
+      } catch (error) {
+        await recordContinuationResult(sessionID, "failure", maxPromptFailures);
+        await client.app?.log?.({
+          body: {
+            service: "opencode-goal-plugin",
+            level: "error",
+            message: "Auto-continue failed",
+            extra: { error: error instanceof Error ? error.message : String(error) }
+          }
+        });
+      } finally {
+        activeContinuations.delete(sessionID);
+      }
     }
   };
 };

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@prevalentware/opencode-goal-plugin",
-  "version": "0.1.15",
-  "description": "Codex-style long-running goal mode for OpenCode.",
+  "version": "0.1.17",
+  "description": "OpenCode goal plugin that adds Codex-style long-running goal mode, /goal commands, persistence, and TUI status for AI coding agents.",
   "keywords": [
     "opencode",
     "opencode-plugin",
+    "opencode goal plugin",
+    "opencode goal mode",
+    "opencode ai",
     "goal",
+    "goal-mode",
+    "slash-command",
+    "coding-agent",
+    "ai-agent",
+    "developer-tools",
     "agent",
     "tui"
   ],

package/src/tui.tsx

@@ -14,6 +14,10 @@ type GoalSnapshot = {
   completionEvidence?: string | null
   blocker?: string | null
   closedAt?: number | null
+  continuationFailures: number
+  lastStatus: string | null
+  autoTurns: number
+  lastContinuationAt: number | null
   remainingTokens: number | null
   sampledAt?: number
 }
@@ -155,6 +159,10 @@ function isGoalSnapshot(value: unknown): value is GoalSnapshot {
   if (value.completionEvidence != null && typeof value.completionEvidence !== "string") return false
   if (value.blocker != null && typeof value.blocker !== "string") return false
   if (value.closedAt != null && typeof value.closedAt !== "number") return false
+  if (typeof value.continuationFailures !== "number") return false
+  if (value.lastStatus != null && typeof value.lastStatus !== "string") return false
+  if (typeof value.autoTurns !== "number") return false
+  if (value.lastContinuationAt != null && typeof value.lastContinuationAt !== "number") return false
   if (value.remainingTokens !== null && typeof value.remainingTokens !== "number") return false
   if (value.sampledAt != null && typeof value.sampledAt !== "number") return false
   return true
@@ -162,7 +170,7 @@ function isGoalSnapshot(value: unknown): value is GoalSnapshot {
 
 function parseGoalToolOutput(part: GoalToolPart): GoalSnapshot | null | undefined {
   if (part.type !== "tool") return undefined
-  if (!["get_goal", "create_goal", "update_goal", "clear_goal"].includes(part.tool ?? "")) return undefined
+  if (!["get_goal", "create_goal", "update_goal", "update_goal_status", "clear_goal"].includes(part.tool ?? "")) return undefined
   if (part.state?.status !== "completed") return undefined
   if (part.tool === "clear_goal") return null
   if (typeof part.state.output !== "string") return undefined
@@ -209,7 +217,9 @@ function formatGoal(goal: GoalSnapshot | null) {
     `Objective: ${goal.objective}`,
     `Status: ${visibleStatus(goal.status)}`,
     `Time used: ${formatDuration(goal.timeUsedSeconds)}`,
+    `Auto-continues: ${goal.autoTurns}`,
   ]
+  if (goal.lastStatus) lines.push(`Last status: ${goal.lastStatus}`)
   if (goal.completionEvidence) lines.push(`Completion evidence: ${goal.completionEvidence}`)
   if (goal.blocker) lines.push(`Blocker: ${goal.blocker}`)
   return lines.join("\n")
@@ -243,6 +253,10 @@ function GoalSidebar(props: { api: TuiPluginApi; sessionID: string }) {
               </text>
               <text fg={theme().textMuted}>Status: {visibleStatus(value().status)}</text>
               <text fg={theme().textMuted}>Time: {formatDuration(elapsed())}</text>
+              <text fg={theme().textMuted}>Auto-continues: {value().autoTurns}</text>
+              <Show when={value().lastStatus}>
+                {(status: () => string) => <text fg={theme().textMuted}>{status()}</text>}
+              </Show>
               <text fg={theme().textMuted}>{objective()}</text>
             </box>
           }