opencode-goal-plugin 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -2,9 +2,27 @@
 
 ## Unreleased
 
+## 0.1.14 — 2026-06-12
+
+- **Count cached context tokens in the budget.** `totalTokensForMessage` now includes `tokens.cache.read` / `cache.write` alongside `input + output + reasoning`. On providers with prompt caching (e.g. Anthropic) most of the conversation context arrives as cache reads with a tiny `input`, so the prior estimate undercounted the context window and the token budget / wrap-up could effectively never trigger.
+- **Honor `/goal pause` issued mid-handler.** The post-await re-checks in the idle handler now use a new `activeGoal` helper that treats a `stopped` goal as inactive, so a pause sent while messages are being fetched or during the cooldown no longer lets one more auto-continue slip through. Adds a regression test.
+- **Harden `escapeGoalText` against forged opening tags.** In addition to escaping closing tags, the plugin now neutralizes opening forms of its own structural tags (`<budget_wrapup>`, `<next_step>`, `<completion_audit>`, `<goal_objective>`, `<goal_continuation>`, `<progress_budget>`), closing a prompt-injection path where goal text could mimic elevated-instruction blocks. Non-structural tag-like text (e.g. `<div>`) is left untouched.
+- **Stop the smoke test from touching real state.** `scripts/smoke-command-hook.mjs` now runs with `persistState: false`, so `npm run smoke` can no longer read or overwrite `~/.opencode-goal-plugin/state.json`.
+- Document the `warnTurnsRemaining` / `warnDurationMsRemaining` / `warnTokensRemaining` options in the README.
+
+## 0.1.13 — 2026-06-11
+
+> Fixes a significant token-tracking bug where the reported token count could be 5–10× higher than what OpenCode displays, making budgets appear exhausted far sooner than expected.
+
+- **Fix token tracking to use context window size instead of cumulative API consumption.** Each `message.updated` event carries `input + output + reasoning` tokens where `input` already includes the full conversation context. Accumulating deltas across messages re-counted prior turns every time, inflating the total. The plugin now uses `Math.max` across all message updates so `totalTokens` reflects the peak context window size — matching what OpenCode reports.
+- Rename `tracked_tokens_used` / `tracked_tokens_remaining` → `context_tokens_used` / `context_tokens_remaining` in continuation prompts.
+- Rename `Tokens:` → `Context tokens:` in status and result displays.
+- Rename `tracked token limit` / `tracked token budget` → `context token limit` / `context token budget` in all user-facing messages.
+- Add regression test verifying that multi-message token tracking no longer accumulates across turns.
+
 ## 0.1.12 — 2026-06-08
 
-- Harden `escapeGoalText` to escape all XML closing tags (`</` → `<\/`) instead of only `</goal_objective>`, closing a prompt-injection path where user-supplied goal text could break structural framing in the continuation message.
+- Harden `escapeGoalText` to escape all XML closing tags (`</` → `<\\/`) instead of only `</goal_objective>`, closing a prompt-injection path where user-supplied goal text could break structural framing in the continuation message.
 - Add unit tests for `outputTokensForMessage`, `budgetWrapupNeeded`, `getSessionID`, `stopReason`, `normalizeOptions` boundary inputs (zero, negative, NaN, null, `budgetWrapupRatio` at 0 and 1), and `escapeGoalText` covering all structural tags.
 
 ## 0.1.11 — 2026-06-04
@@ -91,4 +109,4 @@
 
 ## 0.1.0
 
-- Initial experimental marker-based `/goal` plugin.
+- Initial experimental marker-based `/goal` plugin.

package/README.md

@@ -110,15 +110,15 @@ Markers must appear on their own final line. The bracketed form is canonical, bu
 |---|---|
 | Auto-continue turns | 10 |
 | Max duration | 15 minutes |
-| Tracked tokens | 200,000 |
+| Context tokens | 200,000 |
 | Min delay between continues | 1.5 seconds |
 | No-progress pause | < 50 output tokens on a stalled turn (after a 2-turn grace window) |
-| Budget wrap-up threshold | 80% of tracked token budget |
+| Budget wrap-up threshold | 80% of context token budget |
 | Auto-continue failure pause | 3 consecutive prompt failures |
 
 **Effective turn count.** Each LLM turn on a real task typically takes 30–90 seconds. At that latency, raising `--max-minutes` is usually more useful than raising `--max-turns`. At 45 s/turn, the default 15-minute window gives roughly 15–20 turns of headroom before the turn limit becomes the binding brake.
 
-**Token budget.** The plugin tracks `input + output + reasoning` tokens across all session messages. In high-context sessions (large codebases, long conversation history), input overhead per turn can be substantial and the budget may be exhausted before the turn limit is reached. Treat it as a safety brake, not precise billing accounting.
+**Token budget.** The plugin tracks the session's context window size (`input + output + reasoning` tokens on the latest message). This matches the token count that OpenCode displays, so the numbers should be consistent. When the context window reaches the `--max-tokens` limit, the plugin sends a wrap-up prompt and stops. In high-context sessions (large codebases, long conversation history), the context can grow quickly — treat the budget as a safety brake.
 
 **No-progress heuristic.** A low-output turn does not pause immediately anymore. The plugin pauses only after `noProgressTurnsBeforePause` consecutive *stalled* low-output turns — repeated turns with very little output and no meaningful change in the latest assistant checkpoint.
 
@@ -141,7 +141,7 @@ Override any limit for a single goal:
 | `--max-turns <n>` | Auto-continue turn limit |
 | `--max-minutes <n>` | Duration limit in minutes |
 | `--max-duration-ms <n>` | Duration limit in milliseconds |
-| `--max-tokens <n>` | Tracked token limit |
+| `--max-tokens <n>` | Context token limit |
 | `--cooldown-ms <n>` | Minimum delay between continues |
 | `--no-progress-threshold <n>` | Output token floor before pausing |
 | `--no-progress-turns <n>` | Consecutive stalled low-output turns before pausing |
@@ -187,6 +187,7 @@ Additional plugin-level options:
 
 - `maxRecentMessages` — how many recent session messages to scan when looking for the latest assistant turn before auto-continuing. Higher values make long, tool-heavy sessions less likely to lose the most recent assistant response.
 - `noProgressTurnsBeforePause` — grace window for low-output stalls. The plugin pauses only after this many consecutive stalled low-output turns rather than on the first one.
+- `warnTurnsRemaining` / `warnDurationMsRemaining` / `warnTokensRemaining` — thresholds at which the auto-continue prompt appends a "limits are near" warning (default `3` turns, `60000` ms, `25000` context tokens). Lower them to warn closer to the limit, or raise them to warn earlier.
 - `persistState` — whether to persist active goals and recent goal results to disk.
 - `stateFilePath` — where the persisted state JSON is written. Useful if you want per-project or ephemeral storage.
 - `resultRetentionMs` — how long a completed goal summary remains available through `/goal status` after the goal leaves active memory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Session-scoped /goal workflow for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -47,4 +47,4 @@
   "author": {
     "name": "willytop8"
   }
-}
+}

package/scripts/smoke-command-hook.mjs

@@ -23,7 +23,9 @@ const client = {
 assert.equal(pluginModule.id, "opencode-goal-plugin")
 assert.equal(pluginModule.server, GoalPlugin)
 
-const hooks = await GoalPlugin({ client }, { minDelayMs: 1 })
+// persistState:false keeps the smoke test from reading or overwriting the
+// user's real ~/.opencode-goal-plugin/state.json.
+const hooks = await GoalPlugin({ client }, { minDelayMs: 1, persistState: false })
 assert.equal(typeof hooks["command.execute.before"], "function")
 assert.equal(typeof hooks.event, "function")
 assert.equal(typeof hooks["experimental.chat.system.transform"], "function")

package/src/goal-plugin.js

@@ -142,7 +142,7 @@ function formatStatus(goal) {
   const lines = [
     `Active goal: ${goal.condition}`,
     `Auto-continues sent: ${goal.turnCount}/${goal.options.maxTurns}`,
-    `Tokens: ${goal.totalTokens.toLocaleString()}/${goal.options.maxTokens.toLocaleString()}`,
+    `Context tokens: ${goal.totalTokens.toLocaleString()}/${goal.options.maxTokens.toLocaleString()}`,
     `Elapsed: ${elapsed}s/${Math.round(goal.options.maxDurationMs / 1000)}s`,
     `Last progress: ${lastProgress}`,
     `No-progress turns: ${goal.noProgressTurns}`,
@@ -168,7 +168,7 @@ function formatGoalResult(result) {
     `Last goal: ${result.condition}`,
     `State: ${result.state}`,
     `Auto-continues sent: ${result.turnCount}`,
-    `Tokens: ${result.totalTokens.toLocaleString()}`,
+    `Context tokens: ${result.totalTokens.toLocaleString()}`,
     `Elapsed: ${elapsed}s`,
     `Last checkpoint: ${lastCheckpoint}`,
     `Last status: ${result.lastStatus || "No status recorded."}`,
@@ -198,7 +198,7 @@ function stopReason(goal) {
   if (Date.now() - goal.startedAt >= goal.options.maxDurationMs) {
     return `max duration reached (${Math.round(goal.options.maxDurationMs / 1000)}s)`
   }
-  if (goal.totalTokens >= goal.options.maxTokens) return `max tokens reached (${goal.options.maxTokens})`
+  if (goal.totalTokens >= goal.options.maxTokens) return `max context tokens reached (${goal.options.maxTokens.toLocaleString()})`
   return null
 }
 
@@ -285,6 +285,16 @@ function currentGoal(sessionID, goalID) {
   return goal
 }
 
+// Like currentGoal, but also returns null if the goal was stopped (paused,
+// cleared-and-replaced, blocked) while an async step was in flight. Used at the
+// post-await re-checks so a `/goal pause` issued during messages-fetch or the
+// cooldown sleep actually prevents the next auto-continue from firing.
+function activeGoal(sessionID, goalID) {
+  const goal = currentGoal(sessionID, goalID)
+  if (!goal || goal.stopped) return null
+  return goal
+}
+
 function toPositiveInteger(value, fallback) {
   const parsed = Number(value)
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
@@ -679,16 +689,34 @@ function buildLimitWarning(goal) {
     warnings.push(`${Math.max(0, Math.round(remainingMs / 1000))}s remaining`)
   }
   if (remainingTokens <= goal.options.warnTokensRemaining) {
-    warnings.push(`${Math.max(0, remainingTokens).toLocaleString()} tracked token(s) remaining`)
+    warnings.push(`${Math.max(0, remainingTokens).toLocaleString()} context token(s) remaining`)
   }
 
   return warnings.length ? ` Limits are near: ${warnings.join(", ")}.` : ""
 }
 
+// Tag names the plugin uses to frame its own instructions. Goal text must not
+// be able to forge either an opening or a closing form of any of these.
+const STRUCTURAL_TAGS = [
+  "goal_continuation",
+  "goal_objective",
+  "progress_budget",
+  "budget_wrapup",
+  "next_step",
+  "completion_audit",
+]
+const STRUCTURAL_OPEN_TAG_RE = new RegExp(`<(${STRUCTURAL_TAGS.join("|")})\\b`, "gi")
+
 function escapeGoalText(text) {
   // Escape every XML closing tag so user-supplied goal text cannot break the
-  // structural framing used in buildGoalBlock and buildContinueMessage.
-  return String(text).replaceAll("</", "<\\/")
+  // structural framing used in buildGoalBlock and buildContinueMessage...
+  let escaped = String(text).replaceAll("</", "<\\/")
+  // ...and neutralize opening forms of the plugin's own structural tags so goal
+  // text cannot inject a forged block (e.g. <budget_wrapup>, <next_step>) that
+  // mimics elevated instructions. Closing forms are already broken above, so
+  // this regex only matches genuine `<tag` openings.
+  escaped = escaped.replace(STRUCTURAL_OPEN_TAG_RE, "<\\$1")
+  return escaped
 }
 
 function buildGoalBlock(goal) {
@@ -711,8 +739,8 @@ function buildContinueMessage(goal, { budgetWrapup = false } = {}) {
     "<progress_budget>",
     `auto_continues_used: ${goal.turnCount}`,
     `auto_continues_remaining: ${remainingTurns}`,
-    `tracked_tokens_used: ${goal.totalTokens}`,
-    `tracked_tokens_remaining: ${remainingTokens}`,
+    `context_tokens_used: ${goal.totalTokens}`,
+    `context_tokens_remaining: ${remainingTokens}`,
     `elapsed_seconds: ${elapsedSeconds}`,
     "</progress_budget>",
     "",
@@ -721,7 +749,7 @@ function buildContinueMessage(goal, { budgetWrapup = false } = {}) {
   if (budgetWrapup) {
     lines.push(
       "<budget_wrapup>",
-      "This goal is near its tracked token limit. Finish the current step if it is small and safe.",
+      "This goal is near its context token limit. Finish the current step if it is small and safe.",
       "Then write a concise handoff summary covering what is done, what remains, and the next concrete command or file to inspect.",
       "Do not output [goal:complete] unless the goal is actually finished and verified.",
       "After the handoff, stop.",
@@ -798,12 +826,23 @@ function messageTokens(message) {
       : {}
 }
 
+function cacheTokensForMessage(tokens) {
+  // OpenCode reports cached context separately as `cache: { read, write }`.
+  // On cache-heavy providers (e.g. Anthropic prompt caching) most of the
+  // conversation context arrives as `cache.read` with a small `input`, so the
+  // cache fields must be counted toward the context-window estimate or the
+  // token budget is undercounted by an order of magnitude.
+  const cache = isPlainObject(tokens.cache) ? tokens.cache : {}
+  return toNonNegativeInteger(cache.read) + toNonNegativeInteger(cache.write)
+}
+
 function totalTokensForMessage(message) {
   const tokens = messageTokens(message)
   return (
     toNonNegativeInteger(tokens.input) +
     toNonNegativeInteger(tokens.output) +
-    toNonNegativeInteger(tokens.reasoning)
+    toNonNegativeInteger(tokens.reasoning) +
+    cacheTokensForMessage(tokens)
   )
 }
 
@@ -1030,7 +1069,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
       pushHistory(
         goal,
         "set",
-        `Goal created with limits: ${goal.options.maxTurns} auto-continues, ${Math.round(goal.options.maxDurationMs / 1000)}s, ${goal.options.maxTokens.toLocaleString()} tracked tokens.`,
+        `Goal created with limits: ${goal.options.maxTurns} auto-continues, ${Math.round(goal.options.maxDurationMs / 1000)}s, ${goal.options.maxTokens.toLocaleString()} context tokens.`,
       )
 
       cleanupGoal(sessionID)
@@ -1049,7 +1088,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
             "",
             `Limits: ${goal.options.maxTurns} auto-continues, ${Math.round(
               goal.options.maxDurationMs / 1000,
-            )}s, ${goal.options.maxTokens.toLocaleString()} tracked tokens.`,
+            )}s, ${goal.options.maxTokens.toLocaleString()} context tokens.`,
           ].join("\n"),
         ),
       ]
@@ -1072,7 +1111,13 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
         const currentTokens = totalTokensForMessage(message)
         const previousTokens = seenTokens.get(currentMessageID) || 0
         if (currentTokens > previousTokens) {
-          goal.totalTokens += currentTokens - previousTokens
+          // Track the context window size (peak input+output+reasoning),
+          // not cumulative API token consumption. Each message's tokens
+          // include the full conversation context, so accumulating deltas
+          // across messages inflates the count by re-counting prior turns.
+          // Using Math.max gives the current context size, matching what
+          // OpenCode displays and making the budget check intuitive.
+          goal.totalTokens = Math.max(goal.totalTokens, currentTokens)
           seenTokens.set(currentMessageID, currentTokens)
           goal.messageIDs.add(currentMessageID)
           changed = true
@@ -1106,7 +1151,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           path: { id: sessionID },
           query: { limit: goal.options.maxRecentMessages },
         })
-        const activeGoalAfterMessages = currentGoal(sessionID, goalID)
+        const activeGoalAfterMessages = activeGoal(sessionID, goalID)
         if (!activeGoalAfterMessages) return
 
         const latestAssistant = findLatestAssistantMessage(messages.data)
@@ -1211,7 +1256,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           await sleep(activeGoalAfterMessages.options.minDelayMs - elapsedSinceLastContinue)
         }
 
-        const activeGoalBeforePrompt = currentGoal(sessionID, goalID)
+        const activeGoalBeforePrompt = activeGoal(sessionID, goalID)
         if (!activeGoalBeforePrompt) return
 
         const budgetWrapup = budgetWrapupNeeded(activeGoalBeforePrompt)
@@ -1261,7 +1306,7 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
               activeGoalAfterPrompt,
               budgetWrapup ? "budget-wrapup" : "auto-continue",
               budgetWrapup
-                ? "Sent a final handoff request near the tracked token budget."
+                ? "Sent a final handoff request near the context token budget."
                 : `Sent auto-continue prompt ${activeGoalAfterPrompt.turnCount}/${activeGoalAfterPrompt.options.maxTurns}.`,
             )
           }
@@ -1326,6 +1371,7 @@ export default {
 }
 
 export const testInternals = {
+  activeGoal,
   buildLimitWarning,
   buildContinueMessage,
   buildGoalBlock,
@@ -1333,6 +1379,7 @@ export const testInternals = {
   cleanupGoal,
   currentGoal,
   escapeGoalText,
+  totalTokensForMessage,
   extractBlockedReason,
   findLatestAssistantMessage,
   formatArgumentErrors,