@prevalentware/opencode-goal-plugin 0.1.3 → 0.1.4

package/README.md

@@ -7,8 +7,10 @@ This plugin adds:
 - `/goal` in the OpenCode TUI.
 - A sidebar goal indicator with status, elapsed time, token usage, remaining budget, and objective.
 - Agent tools: `get_goal`, `create_goal`, `update_goal`, and `clear_goal`.
+- Goal close evidence: `complete` requires verified evidence, and `unmet` requires a concrete blocker.
 - Persistent per-session goal state.
 - Optional automatic continuation on `session.idle`.
+- Compaction context so active goals are preserved when OpenCode summarizes a long session.
 
 ## Install
 
@@ -71,6 +73,25 @@ Defaults:
 - `max_auto_turns`: `25`
 - `min_continue_interval_seconds`: `3`
 
+## Goal Workflow
+
+Use `/goal` from an OpenCode TUI session to set, refresh, or clear the goal. New goals support budget presets:
+
+- No budget
+- `250K`
+- `1M`
+- `2M`
+- Custom positive integer
+
+When setting the objective, include the scope, non-goals, and verification path when they matter. The agent is reminded to audit real files, command output, tests, or PR state before closing the goal.
+
+The `update_goal` tool can close a goal in two ways:
+
+- `status: "complete"` with `evidence` when every requirement is actually achieved.
+- `status: "unmet"` with `blocker` when the objective cannot be achieved or is blocked by missing external input.
+
+Budget exhaustion does not close a goal by itself. It only marks the goal `budgetLimited` and asks the agent to wrap up with remaining work or blockers.
+
 ## State
 
 Goal state is stored at:
@@ -124,4 +145,4 @@ OpenCode plugin modules are target-specific. This package exports separate modul
 }
 ```
 
-Codex goal mode has deeper runtime integration for exact token accounting and thread lifecycle control. This plugin implements the same workflow using OpenCode plugin hooks, so token usage is estimated from message text and 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's `session.idle` event.

package/dist/server.js

@@ -60,6 +60,17 @@ function validateBudget(tokenBudget) {
   }
   return tokenBudget;
 }
+function validateEvidence(evidence, label) {
+  const value = evidence?.trim();
+  if (!value)
+    throw new Error(`${label} must not be empty`);
+  if ([...value].length > 4000)
+    throw new Error(`${label} must be at most 4000 characters`);
+  return value;
+}
+function isClosed(status) {
+  return status === "complete" || status === "unmet";
+}
 function snapshot(goal) {
   const activeSeconds = goal.status === "active" && goal.lastAccountedAt != null ? Math.max(0, nowSeconds() - goal.lastAccountedAt) : 0;
   const timeUsedSeconds = goal.timeUsedSeconds + activeSeconds;
@@ -72,6 +83,9 @@ function snapshot(goal) {
     timeUsedSeconds,
     createdAt: goal.createdAt,
     updatedAt: goal.updatedAt,
+    completionEvidence: goal.completionEvidence ?? null,
+    blocker: goal.blocker ?? null,
+    closedAt: goal.closedAt ?? null,
     remainingTokens: goal.tokenBudget == null ? null : Math.max(0, goal.tokenBudget - goal.tokensUsed)
   };
 }
@@ -85,8 +99,8 @@ async function createGoal(sessionID, objective, tokenBudget) {
   const budget = validateBudget(tokenBudget);
   return mutate((state) => {
     const existing = state.goals[sessionID];
-    if (existing && existing.status !== "complete") {
-      throw new Error("cannot create a new goal because this session already has a non-complete goal");
+    if (existing && !isClosed(existing.status)) {
+      throw new Error("cannot create a new goal because this session already has a non-closed goal");
     }
     const now = nowSeconds();
     const goal = {
@@ -98,6 +112,9 @@ async function createGoal(sessionID, objective, tokenBudget) {
       timeUsedSeconds: 0,
       createdAt: now,
       updatedAt: now,
+      completionEvidence: null,
+      blocker: null,
+      closedAt: null,
       lastAccountedAt: now,
       autoTurns: 0,
       lastContinuationAt: null
@@ -106,20 +123,32 @@ async function createGoal(sessionID, objective, tokenBudget) {
     return snapshot(goal);
   });
 }
-async function setGoalStatus(sessionID, status) {
+async function closeGoal(sessionID, input) {
   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;
+    const now = nowSeconds();
+    goal.status = input.status;
+    goal.updatedAt = now;
+    goal.closedAt = now;
+    goal.lastAccountedAt = null;
+    if (input.status === "complete") {
+      goal.completionEvidence = validateEvidence(input.evidence, "completion evidence");
+      goal.blocker = null;
+    } else {
+      goal.blocker = validateEvidence(input.blocker, "blocker");
+      goal.completionEvidence = null;
+    }
     return snapshot(goal);
   });
 }
-async function completeGoal(sessionID) {
-  return setGoalStatus(sessionID, "complete");
+async function completeGoal(sessionID, evidence) {
+  return closeGoal(sessionID, { status: "complete", evidence });
+}
+async function markGoalUnmet(sessionID, blocker) {
+  return closeGoal(sessionID, { status: "unmet", blocker });
 }
 async function clearGoal(sessionID) {
   return mutate((state) => {
@@ -182,13 +211,18 @@ function formatGoal(goal) {
   if (!goal)
     return "No goal is set for this session.";
   const budget = goal.tokenBudget == null ? "none" : `${goal.tokensUsed} / ${goal.tokenBudget}`;
-  return [
+  const lines = [
     `Objective: ${goal.objective}`,
     `Status: ${goal.status}`,
     `Tokens: ${budget}`,
     `Remaining tokens: ${goal.remainingTokens ?? "n/a"}`,
     `Time used: ${goal.timeUsedSeconds}s`
-  ].join(`
+  ];
+  if (goal.completionEvidence)
+    lines.push(`Completion evidence: ${goal.completionEvidence}`);
+  if (goal.blocker)
+    lines.push(`Blocker: ${goal.blocker}`);
+  return lines.join(`
 `);
 }
 
@@ -218,7 +252,7 @@ Before deciding that the goal is achieved, perform a completion audit against th
 - Identify any missing, incomplete, weakly verified, or uncovered requirement.
 - Treat uncertainty as not achieved; do more verification or continue the work.
 
-Do not rely on intent, partial progress, elapsed effort, memory of earlier work, or a plausible final answer as proof of completion. Only call update_goal with status "complete" when the objective has actually been achieved and no required work remains.`;
+Do not rely on intent, partial progress, elapsed effort, memory of earlier work, or a plausible final answer as proof of completion. Only call update_goal with status "complete" when the objective has actually been achieved and no required work remains, and include concise evidence. If the objective is impossible or blocked by missing external input, call update_goal with status "unmet" and include the blocker.`;
 }
 function budgetLimitedPrompt(goal) {
   return `The active session goal has reached its token budget.
@@ -234,13 +268,13 @@ Budget:
 - Tokens used: ${goal.tokensUsed}
 - Token budget: ${goal.tokenBudget ?? "none"}
 
-Goal mode has marked the goal as budgetLimited, so do not start new substantive work for this goal. Wrap up soon with useful progress, remaining work or blockers, and a clear next step. Do not call update_goal unless the goal is actually complete.`;
+Goal mode has marked the goal as budgetLimited, so do not start new substantive work for this goal. Wrap up soon with useful progress, remaining work or blockers, and a clear next step. Do not call update_goal unless the goal is actually complete or objectively unmet.`;
 }
 function systemReminder(goal) {
   if (!goal) {
     return `OpenCode goal mode is available through get_goal, create_goal, and update_goal tools.
 
-Create a goal only when explicitly requested by the user or system/developer instructions. Do not infer goals from ordinary tasks.`;
+Create a goal only when explicitly requested by the user or system/developer instructions. Do not infer goals from ordinary tasks. When closing a goal, update_goal requires evidence for status "complete" or a blocker for status "unmet".`;
   }
   if (goal.status === "active")
     return continuationPrompt(goal);
@@ -252,6 +286,13 @@ ${formatGoal(goal)}
 
 If the user resumes the goal, continue from the objective and current evidence.`;
 }
+function compactionContext(goal) {
+  return `OpenCode goal mode is tracking this session goal across compaction.
+
+${formatGoal(goal)}
+
+Preserve the goal objective, status, budget, elapsed time, token count, and any completion evidence or blocker in the compacted context. After compaction, continue from the next concrete unfinished step. Before closing the goal, audit real artifacts and command outputs; close with update_goal status "complete" only with evidence, or status "unmet" only with a concrete blocker.`;
+}
 
 // src/server.ts
 var DEFAULT_MAX_AUTO_TURNS = 25;
@@ -271,6 +312,39 @@ function estimateMessages(messages) {
     return sum + (message.parts ?? []).reduce((partSum, part) => partSum + estimateTokensFromText(textFromPart(part)), 0);
   }, 0);
 }
+function tokensFromRecord(value) {
+  if (!value || typeof value !== "object")
+    return;
+  const tokens = value;
+  if (typeof tokens.total === "number")
+    return tokens.total;
+  const cache = tokens.cache && typeof tokens.cache === "object" ? tokens.cache : {};
+  const fields = [tokens.input, tokens.output, tokens.reasoning, cache.read, cache.write];
+  if (!fields.some((field) => typeof field === "number"))
+    return;
+  return fields.reduce((sum, field) => sum + (typeof field === "number" && Number.isFinite(field) ? field : 0), 0);
+}
+function exactTokensFromPart(part) {
+  if (!part || typeof part !== "object")
+    return;
+  const value = part;
+  if (value.type !== "step-finish")
+    return;
+  return tokensFromRecord(value.tokens);
+}
+function exactTokensFromMessage(message) {
+  const partTotal = (message.parts ?? []).reduce((sum, part) => sum + (exactTokensFromPart(part) ?? 0), 0);
+  if (partTotal > 0)
+    return partTotal;
+  if (message.info && typeof message.info === "object") {
+    return tokensFromRecord(message.info.tokens);
+  }
+  return;
+}
+function tokensFromMessages(messages) {
+  const exactTotal = messages.reduce((sum, message) => sum + (exactTokensFromMessage(message) ?? 0), 0);
+  return exactTotal > 0 ? exactTotal : estimateMessages(messages);
+}
 async function sendContinuation(client, sessionID, prompt) {
   await client.session.promptAsync({
     path: { id: sessionID },
@@ -305,14 +379,22 @@ var server = async ({ client }, options) => {
         }
       },
       update_goal: {
-        description: "Use this tool only to mark the existing goal achieved. Set status to complete only when the objective is achieved and no required work remains. Do not mark complete merely because the budget is exhausted or because work is stopping.",
+        description: "Close the existing goal only after an audit against real evidence. Use status complete only when the objective is achieved and no required work remains, and include evidence. Use status unmet only when the objective cannot be achieved or is blocked, and include the blocker. Do not close a goal merely because the budget is exhausted or because work is stopping.",
         args: {
-          status: z.enum(["complete"]).describe("Required. The only model-controlled status is complete.")
+          status: z.enum(["complete", "unmet"]).describe("Required. complete means achieved; unmet means blocked or impossible."),
+          evidence: z.string().min(1).max(4000).optional().describe("Required when status is complete. Summarize the concrete evidence verified."),
+          blocker: z.string().min(1).max(4000).optional().describe("Required when status is unmet. Explain the concrete blocker or impossibility.")
         },
-        async execute(_args, context) {
-          const goal = await completeGoal(context.sessionID);
-          const report = goal.tokenBudget == null ? `Goal achieved. Time used: ${goal.timeUsedSeconds} seconds.` : `Goal achieved. Tokens used: ${goal.tokensUsed} of ${goal.tokenBudget}; time used: ${goal.timeUsedSeconds} seconds.`;
-          return JSON.stringify({ goal, remaining_tokens: goal.remainingTokens, completion_budget_report: report }, null, 2);
+        async execute(args, context) {
+          const input = args;
+          if (input.status === "complete") {
+            const goal2 = await completeGoal(context.sessionID, input.evidence ?? "");
+            const report2 = goal2.tokenBudget == null ? `Goal achieved. Time used: ${goal2.timeUsedSeconds} seconds. Evidence: ${goal2.completionEvidence}.` : `Goal achieved. Tokens used: ${goal2.tokensUsed} of ${goal2.tokenBudget}; time used: ${goal2.timeUsedSeconds} seconds. Evidence: ${goal2.completionEvidence}.`;
+            return JSON.stringify({ goal: goal2, remaining_tokens: goal2.remainingTokens, completion_budget_report: report2 }, null, 2);
+          }
+          const goal = await markGoalUnmet(context.sessionID, input.blocker ?? "");
+          const report = goal.tokenBudget == null ? `Goal unmet. Time used: ${goal.timeUsedSeconds} seconds. Blocker: ${goal.blocker}.` : `Goal unmet. Tokens used: ${goal.tokensUsed} of ${goal.tokenBudget}; time used: ${goal.timeUsedSeconds} seconds. Blocker: ${goal.blocker}.`;
+          return JSON.stringify({ goal, remaining_tokens: goal.remainingTokens, unmet_report: report }, null, 2);
         }
       },
       clear_goal: {
@@ -327,13 +409,19 @@ var server = async ({ client }, options) => {
       const sessionID = "sessionID" in input && typeof input.sessionID === "string" ? input.sessionID : output.messages.find((message) => typeof message.info.sessionID === "string")?.info.sessionID;
       if (!sessionID)
         return;
-      await accountUsage(sessionID, estimateMessages(output.messages));
+      await accountUsage(sessionID, tokensFromMessages(output.messages));
     },
     async "experimental.chat.system.transform"(input, output) {
       if (typeof input.sessionID !== "string")
         return;
       output.system.push(systemReminder(await getGoal(input.sessionID)));
     },
+    async "experimental.session.compacting"(input, output) {
+      const goal = await getGoal(input.sessionID);
+      if (!goal)
+        return;
+      output.context.push(compactionContext(goal));
+    },
     async event({ event }) {
       if (!autoContinue || event.type !== "session.idle")
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prevalentware/opencode-goal-plugin",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Codex-style long-running goal mode for OpenCode.",
   "keywords": [
     "opencode",

package/src/tui.tsx

@@ -5,12 +5,15 @@ import { createMemo, Show } from "solid-js"
 type GoalSnapshot = {
   sessionID: string
   objective: string
-  status: "active" | "paused" | "budgetLimited" | "complete"
+  status: "active" | "paused" | "budgetLimited" | "complete" | "unmet"
   tokenBudget: number | null
   tokensUsed: number
   timeUsedSeconds: number
   createdAt: number
   updatedAt: number
+  completionEvidence?: string | null
+  blocker?: string | null
+  closedAt?: number | null
   remainingTokens: number | null
 }
 
@@ -58,42 +61,84 @@ function clearGoalPrompt() {
   return "Clear the current session goal by calling clear_goal. Report whether a goal was cleared."
 }
 
+function showCustomBudget(api: TuiPluginApi, sessionID: string, objective: string) {
+  const DialogPrompt = api.ui.DialogPrompt
+  api.ui.dialog.replace(() =>
+    DialogPrompt({
+      title: "Custom budget",
+      placeholder: "Positive integer",
+      onConfirm(rawBudget) {
+        const value = rawBudget.trim()
+        const budget = Number(value)
+        if (!Number.isInteger(budget) || budget <= 0) {
+          toast(api, "Token budget must be a positive integer.", "warning")
+          return
+        }
+        void sendGoalPrompt(api, sessionID, createGoalPrompt(objective, budget))
+          .then(() => {
+            api.ui.dialog.clear()
+            toast(api, "Goal request sent.", "success")
+          })
+          .catch((error) => toast(api, error instanceof Error ? error.message : String(error), "error"))
+      },
+      onCancel() {
+        api.ui.dialog.clear()
+      },
+    }),
+  )
+}
+
+function showBudgetSelect(api: TuiPluginApi, sessionID: string, objective: string) {
+  const DialogSelect = api.ui.DialogSelect
+  const budgets = [
+    { title: "No budget", value: "none", budget: null, description: "Track progress without a token limit" },
+    { title: "250K", value: "250k", budget: 250_000, description: "Short focused goal" },
+    { title: "1M", value: "1m", budget: 1_000_000, description: "Default long-running goal" },
+    { title: "2M", value: "2m", budget: 2_000_000, description: "Large investigation or migration" },
+    { title: "Custom", value: "custom", budget: undefined, description: "Enter an exact token budget" },
+  ]
+  api.ui.dialog.replace(() =>
+    DialogSelect({
+      title: "Token budget",
+      placeholder: "Choose a budget",
+      options: budgets.map((item) => ({
+        title: item.title,
+        value: item.value,
+        description: item.description,
+        onSelect: () => {
+          if (item.budget === undefined) {
+            showCustomBudget(api, sessionID, objective)
+            return
+          }
+          void sendGoalPrompt(api, sessionID, createGoalPrompt(objective, item.budget))
+            .then(() => {
+              api.ui.dialog.clear()
+              toast(api, "Goal request sent.", "success")
+            })
+            .catch((error) => toast(api, error instanceof Error ? error.message : String(error), "error"))
+        },
+      })),
+      onSelect(option) {
+        option.onSelect?.()
+      },
+    }),
+  )
+}
+
 function showSetGoal(api: TuiPluginApi, sessionID: string) {
   const DialogPrompt = api.ui.DialogPrompt
   api.ui.dialog.setSize("medium")
   api.ui.dialog.replace(() =>
     DialogPrompt({
       title: "Set goal",
-      placeholder: "Concrete objective",
+      placeholder: "Objective, scope, non-goals, verification path",
       onConfirm(objective) {
         const trimmed = objective.trim()
         if (!trimmed) {
           toast(api, "Goal objective is required.", "warning")
           return
         }
-        api.ui.dialog.replace(() =>
-          DialogPrompt({
-            title: "Token budget",
-            placeholder: "Optional positive integer",
-            onConfirm(rawBudget) {
-              const value = rawBudget.trim()
-              const budget = value ? Number(value) : null
-              if (budget != null && (!Number.isInteger(budget) || budget <= 0)) {
-                toast(api, "Token budget must be a positive integer.", "warning")
-                return
-              }
-              void sendGoalPrompt(api, sessionID, createGoalPrompt(trimmed, budget))
-                .then(() => {
-                  api.ui.dialog.clear()
-                  toast(api, "Goal request sent.", "success")
-                })
-                .catch((error) => toast(api, error instanceof Error ? error.message : String(error), "error"))
-            },
-            onCancel() {
-              api.ui.dialog.clear()
-            },
-          }),
-        )
+        showBudgetSelect(api, sessionID, trimmed)
       },
       onCancel() {
         api.ui.dialog.clear()
@@ -189,12 +234,15 @@ function isGoalSnapshot(value: unknown): value is GoalSnapshot {
   if (!isRecord(value)) return false
   if (typeof value.sessionID !== "string") return false
   if (typeof value.objective !== "string") return false
-  if (!["active", "paused", "budgetLimited", "complete"].includes(String(value.status))) return false
+  if (!["active", "paused", "budgetLimited", "complete", "unmet"].includes(String(value.status))) return false
   if (value.tokenBudget !== null && typeof value.tokenBudget !== "number") return false
   if (typeof value.tokensUsed !== "number") return false
   if (typeof value.timeUsedSeconds !== "number") return false
   if (typeof value.createdAt !== "number") return false
   if (typeof value.updatedAt !== "number") return false
+  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 (value.remainingTokens !== null && typeof value.remainingTokens !== "number") return false
   return true
 }
@@ -231,13 +279,16 @@ function goalFromSession(api: TuiPluginApi, sessionID: string) {
 function formatGoal(goal: GoalSnapshot | null) {
   if (!goal) return "No recent goal state found in this session."
   const budget = goal.tokenBudget == null ? "none" : `${goal.tokensUsed} / ${goal.tokenBudget}`
-  return [
+  const lines = [
     `Objective: ${goal.objective}`,
     `Status: ${goal.status}`,
     `Tokens: ${budget}`,
     `Remaining tokens: ${goal.remainingTokens ?? "n/a"}`,
     `Time used: ${goal.timeUsedSeconds}s`,
-  ].join("\n")
+  ]
+  if (goal.completionEvidence) lines.push(`Completion evidence: ${goal.completionEvidence}`)
+  if (goal.blocker) lines.push(`Blocker: ${goal.blocker}`)
+  return lines.join("\n")
 }
 
 function GoalSidebar(props: { api: TuiPluginApi; sessionID: string }) {
@@ -266,7 +317,7 @@ function GoalSidebar(props: { api: TuiPluginApi; sessionID: string }) {
     <Show when={goal()}>
       {(value: () => GoalSnapshot) => (
         <Show
-          when={value().status === "complete"}
+          when={value().status === "complete" || value().status === "unmet"}
           fallback={
             <box>
               <text fg={theme().text}>
@@ -280,8 +331,9 @@ function GoalSidebar(props: { api: TuiPluginApi; sessionID: string }) {
             </box>
           }
         >
-          <text fg={theme().primary}>
-            <b>Goal achieved</b> ({formatDurationBadge(value().timeUsedSeconds)})
+          <text fg={value().status === "complete" ? theme().primary : theme().textMuted}>
+            <b>{value().status === "complete" ? "Goal achieved" : "Goal unmet"}</b> (
+            {formatDurationBadge(value().timeUsedSeconds)})
           </text>
         </Show>
       )}