opencode-goal-plugin 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,9 +2,14 @@
 
 ## Unreleased
 
+## 0.4.0 — 2026-06-21
+
+- **Expose agent-facing goal tools (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`)** when the host provides `@opencode-ai/plugin` (a new *optional* peer dependency, loaded via a cached dynamic import so the zero-runtime-dependency posture is preserved). `set_goal` is constrained by its description to explicit user requests (so the agent does not set goals on its own); it accepts optional `maxTurns` / `maxTokens` / `maxDurationMs` overrides plus `successCriteria` / `constraints` / `mode`. `update_goal` supports objective edits and `complete` / `blocked` / `paused` / `resumed` transitions (with `evidence` / `blocker`). Tools create, replace, and clear goals through the **multi-goal registry** (the same `buildGoalState` → `registerSessionGoal` → `focusGoal` path the `/goal` command uses), so tool-created goals persist, appear in `/goal list`, and are driven by the idle handler; `complete` archives with evidence and auto-promotes the next goal in an ordered (sisyphus) sequence. Registration is skipped gracefully when the package is absent or with `registerTools: false`. New `buildAgentToolHandlers` / `buildAgentTools` / `agentToolSessionID` helpers. Implements megalist items 7.1 and 7.2. _(This is the work the 0.3.0 changelog mistakenly listed as already shipped; it is now actually implemented and adapted to the current multi-goal architecture.)_
+- **Fix a goal-registry leak when resuming.** `resetGoalBudget` rotates a goal's `goalId`, but the multi-goal registry is keyed by `goalId`, so resuming and then clearing/replacing left a stale entry behind (visible in `/goal list` and persisted). Both the `/goal resume` command path and the agent `update_goal {status:"resumed"}` path now re-key the registry to the new id (the focused pointer holds the same object). Regression test added for the command path.
+
 ## 0.3.0 — 2026-06-14
 
-> A large feature release. Stronger completion integrity (evidence gate, optional auditor, visible audit messages), durable lifecycle ledger with state reconstruction, multiple goals per session with focus and ordered sisyphus sequences, richer goal schema, more auto-continue guardrails, project-local state with migration, agent-facing tools, a deterministic compaction summary, and npm Trusted Publishing CI. All changes are additive and backward-compatible; older state files load unchanged.
+> A large feature release. Stronger completion integrity (evidence gate, optional auditor, visible audit messages), durable lifecycle ledger with state reconstruction, multiple goals per session with focus and ordered sisyphus sequences, richer goal schema, more auto-continue guardrails, project-local state with migration, a deterministic compaction summary, and npm Trusted Publishing CI. All changes are additive and backward-compatible; older state files load unchanged.
 
 ### Completion integrity & audit
 
@@ -36,7 +41,7 @@
 ### Storage, tools & packaging
 
 - **Default goal state to a project-local path, with an env override and migration fallbacks.** State resolves as `stateFilePath` option → `OPENCODE_GOAL_STATE_PATH` env var → project-local `<cwd>/.opencode/goals/state.json` (previously `~/.opencode-goal-plugin/state.json`). When the default path is empty, the plugin migrates forward on first load from the legacy home path and the XDG path, then writes project-local. Explicit option/env paths are literal with no fallback; a present-but-corrupt primary is preserved. New `resolveStateFilePath` / `xdgStateFilePath` / `legacyStateFilePaths` helpers. Home-based fallback paths resolve from an injectable `env.HOME` (falling back to `os.homedir()`), making path resolution deterministic across platforms — `os.homedir()` ignores `$HOME` on macOS. Implements megalist items 6.1 and 6.2.
-- **Expose agent-facing goal tools (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`)** when the host provides `@opencode-ai/plugin` (a new *optional* peer dependency, loaded via a cached dynamic import so the zero-runtime-dependency posture is preserved). `set_goal` is constrained to explicit user requests; `update_goal` supports objective edits and complete/blocked/paused/resumed transitions. Registration is skipped gracefully when the package is absent or with `registerTools: false`. New `buildAgentToolHandlers`. Implements megalist items 7.1 and 7.2.
+- _**Correction (2026-06-21):** an earlier version of this entry claimed agent-facing goal tools shipped in 0.3.0. They did not — the work was on an unmerged branch (`wr/agent-tools`) and was never included in the 0.3.0 release. The feature now actually ships; see the **Unreleased** section above. Megalist items 7.1 and 7.2._
 - **Add a `Publish` GitHub Actions workflow (`.github/workflows/publish.yml`) for npm Trusted Publishing (OIDC).** On a push to `main` it runs the full check matrix on Node 18/20/22, then publishes via OIDC with no stored `NPM_TOKEN`, using a publish-on-version-change model (only publishes when `package.json`'s version is new). The publish job requires `id-token: write` and is gated behind a `release` environment. First run still requires a human to publish an initial version and configure the npm Trusted Publisher. Implements megalist item 9.1.
 
 ## 0.2.0 — 2026-06-14

package/README.md

@@ -256,11 +256,28 @@ Additional plugin-level options:
 - `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.
 - `commandName` — the slash command the plugin owns (default `goal`). Set it to e.g. `objective` to drive the workflow with `/objective` instead of `/goal`; a leading slash is tolerated. Remember to register the matching command name in your OpenCode `command` config. User-facing hints (`/goal status`, `/goal resume`, …) follow the configured name.
 - `registerCommand` — whether the plugin installs its `command.execute.before` hook at all (default `true`). Set it to `false` if you only want the auto-continue/persistence behavior driven programmatically and don't want the plugin to own a slash command.
+- `registerTools` — whether the plugin registers the agent-facing goal tools (default `true`). Requires the optional `@opencode-ai/plugin` peer dependency to be present; when it is absent, tool registration is skipped and the command/event hooks still work. Set to `false` to omit the programmatic tool surface entirely. See [Agent tools](#agent-tools-optional).
 - `persistState` — whether to persist active goals and recent goal results to disk.
 - `stateFilePath` — where the persisted state JSON is written. Overrides the default project-local path and the `OPENCODE_GOAL_STATE_PATH` env var. Useful if you want a fixed or ephemeral location. When unset, the default is `<cwd>/.opencode/goals/state.json` (see the persistence section above), and `OPENCODE_GOAL_STATE_PATH` can override it without editing config.
 - `resultRetentionMs` — how long a completed goal summary remains available through `/goal status` after the goal leaves active memory.
 - `maxStoredResults` — maximum number of completed-goal summaries retained in process memory before the oldest ones are evicted.
 
+## Agent tools (optional)
+
+In addition to the `/goal` command, the plugin can expose the same workflow to the model as callable tools, so the agent can inspect and manage the goal itself. This requires the optional `@opencode-ai/plugin` peer dependency (it provides the `tool` helper and schema). When that package isn't installed the tools are simply not registered and everything else keeps working. Disable them explicitly with `registerTools: false`.
+
+Registered tools:
+
+- `get_goal` — current goal status (objective, budget usage, latest checkpoint).
+- `get_goal_history` — lifecycle history and latest checkpoint.
+- `set_goal` — set/replace the session goal. Its description constrains the agent to call it **only when the user explicitly asks** to set a goal. Accepts `objective` plus optional `maxTurns`, `maxTokens`, `maxDurationMs`, `successCriteria`, `constraints`, and `mode`.
+- `update_goal` — revise the `objective` and/or set `status` to `complete` / `blocked` / `paused` / `resumed` (with `evidence` for complete or `blocker` for blocked).
+- `clear_goal` — clear the current goal and discard its saved status.
+
+These operate on the same per-session multi-goal state as the command path: a tool-set goal persists, shows up in `/goal list`, and is driven by the idle auto-continue; completing a goal in an ordered (sisyphus) sequence auto-promotes the next.
+
+> Integration note: the tool execute-context shape (`ctx.sessionID`) and the `tool.schema` surface follow the OpenCode plugin docs. The tool **logic** is unit-tested independently, but the live registration should be confirmed against a real OpenCode run (see the smoke-test checklist).
+
 ## Audit messages
 
 When the assistant marks a goal complete or blocked, the plugin announces the audit instead of doing it silently: an audit-start message ("Auditing goal completion…") and an audit-result message ("completion accepted — goal archived" / "paused as blocked — …"). By default these are delivered through OpenCode's structured log (`client.app.log`, visible to the user). Provide an `auditMessenger(sessionID, text)` plugin option to route them elsewhere (for example into the live conversation once a suitable message API is available), or set `auditMessages: false` to disable them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Session-scoped /goal workflow for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -32,6 +32,14 @@
     "agent",
     "goal"
   ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
   "license": "MIT",
   "engines": {
     "node": ">=18"

package/src/goal-plugin.js

@@ -1590,6 +1590,240 @@ function buildGoalState(sessionID, condition, options, meta = {}, lastStatus = "
   }
 }
 
+const AGENT_UPDATE_STATUSES = new Set(["complete", "blocked", "paused", "resumed"])
+
+// Programmatic equivalents of the /goal command, exposed to the agent as tools
+// (megalist items 7.1 / 7.2). Each handler operates on a session id and mutates
+// the same in-memory state the command path uses, persisting through the
+// provided `persist` callback, and returns a human-readable string for the tool
+// result. Goal creation/replacement routes through the multi-goal registry
+// (buildGoalState + registerSessionGoal + focusGoal) exactly like the command
+// path, so tool-created goals persist and are driven by the idle handler.
+function buildAgentToolHandlers({ defaultGoalOptions, persist }) {
+  async function getGoal(sessionID) {
+    const goal = goalStates.get(sessionID)
+    if (goal) return formatStatus(goal)
+    const lastResult = lastGoalResults.get(sessionID)
+    if (lastResult) return formatGoalResult(lastResult)
+    return "No active goal."
+  }
+
+  async function getGoalHistory(sessionID) {
+    const goal = goalStates.get(sessionID)
+    if (goal) {
+      return [
+        `Goal history for: ${goal.condition}`,
+        "",
+        `Latest checkpoint: ${goal.lastCheckpoint?.summary || "none yet"}`,
+        "",
+        formatHistory(goal.history),
+      ].join("\n")
+    }
+    const lastResult = lastGoalResults.get(sessionID)
+    if (lastResult) {
+      return [
+        `Last goal history for: ${lastResult.condition}`,
+        "",
+        `Latest checkpoint: ${lastResult.lastCheckpoint?.summary || "none recorded"}`,
+        "",
+        formatHistory(lastResult.history),
+      ].join("\n")
+    }
+    return "No goal history recorded yet."
+  }
+
+  async function setGoal(sessionID, args = {}) {
+    const objective = typeof args.objective === "string" ? args.objective.trim() : ""
+    if (!objective) return "No objective provided. Pass a non-empty `objective`."
+
+    const options = normalizeOptions({
+      ...defaultGoalOptions,
+      ...(Number.isFinite(args.maxTurns) ? { maxTurns: args.maxTurns } : {}),
+      ...(Number.isFinite(args.maxTokens) ? { maxTokens: args.maxTokens } : {}),
+      ...(Number.isFinite(args.maxDurationMs) ? { maxDurationMs: args.maxDurationMs } : {}),
+    })
+    const meta = {
+      successCriteria: typeof args.successCriteria === "string" ? args.successCriteria : "",
+      constraints: typeof args.constraints === "string" ? args.constraints : "",
+      mode: typeof args.mode === "string" ? args.mode : "normal",
+    }
+    const goal = buildGoalState(sessionID, objective, options, meta)
+    pushHistory(
+      goal,
+      "set",
+      `Goal created via agent tool with limits: ${options.maxTurns} auto-continues, ${Math.round(options.maxDurationMs / 1000)}s, ${options.maxTokens.toLocaleString()} context tokens.`,
+    )
+    // Mirror the `/goal <condition>` replace path: discard the focused goal and
+    // its saved result, drop any ordered sequence, then register + focus the new
+    // goal so it persists and the idle handler drives it.
+    sessionOrdered.delete(sessionID)
+    cleanupGoal(sessionID)
+    lastGoalResults.delete(sessionID)
+    registerSessionGoal(goal)
+    focusGoal(sessionID, goal)
+    await persist()
+    return `New active goal: ${goal.condition}`
+  }
+
+  async function updateGoal(sessionID, args = {}) {
+    const goal = goalStates.get(sessionID)
+    if (!goal) return "No active goal to update. Use set_goal first."
+
+    const messages = []
+
+    if (typeof args.objective === "string" && args.objective.trim()) {
+      goal.condition = args.objective.trim()
+      goal.stopped = false
+      goal.stopReason = ""
+      goal.blockedReason = ""
+      goal.budgetWrapupSent = false
+      goal.noProgressTurns = 0
+      goal.lastStatus = "Goal objective updated."
+      pushHistory(goal, "edited", `Objective updated to: ${summarizeText(goal.condition, 400)}`)
+      messages.push(`Objective updated: ${goal.condition}`)
+    }
+
+    if (args.status !== undefined) {
+      const status = String(args.status).trim().toLowerCase()
+      if (!AGENT_UPDATE_STATUSES.has(status)) {
+        return `Invalid status: ${args.status} (expected complete, blocked, paused, or resumed).`
+      }
+      if (status === "complete") {
+        const evidence = typeof args.evidence === "string" ? args.evidence.trim() : ""
+        goal.lastStatus = "Goal completed."
+        pushHistory(
+          goal,
+          "completed",
+          evidence ? `Marked complete via tool: ${summarizeText(evidence, 400)}` : "Marked complete via agent tool.",
+        )
+        rememberGoalResult(sessionID, goal, "achieved", "", evidence)
+        cleanupGoal(sessionID)
+        // Advance an ordered (sisyphus) sequence just like the marker path does.
+        if (sessionOrdered.has(sessionID)) promoteNextOrderedGoal(sessionID)
+        await persist()
+        return "Goal marked complete and archived."
+      }
+      if (status === "blocked") {
+        goal.blockedReason = typeof args.blocker === "string" ? args.blocker.trim() : ""
+        goal.stopped = true
+        goal.stopReason = "blocked"
+        goal.lastStatus = "Assistant reported blocked."
+        pushHistory(goal, "blocked", goal.blockedReason || "Marked blocked via agent tool.")
+        messages.push("Goal marked blocked.")
+      } else if (status === "paused") {
+        goal.stopped = true
+        goal.stopReason = "paused"
+        goal.lastStatus = "Goal paused."
+        pushHistory(goal, "paused", "Paused via agent tool.")
+        messages.push("Goal paused.")
+      } else if (status === "resumed") {
+        const previousGoalId = goal.goalId
+        resetGoalBudget(goal)
+        // resetGoalBudget rotates goalId; re-key the registry so the goal stays
+        // findable by its new id (the focused pointer holds the same object).
+        if (goal.goalId !== previousGoalId) {
+          removeSessionGoal(sessionID, previousGoalId)
+          registerSessionGoal(goal)
+          focusGoal(sessionID, goal)
+        }
+        goal.stopped = false
+        goal.stopReason = ""
+        goal.blockedReason = ""
+        goal.lastStatus = "Goal resumed with a fresh local budget."
+        pushHistory(goal, "resumed", "Resumed via agent tool with a fresh local budget window.")
+        messages.push("Goal resumed with fresh limits.")
+      }
+    }
+
+    if (!messages.length) {
+      return "Nothing to update. Provide `objective` and/or `status`."
+    }
+    await persist()
+    return messages.join(" ")
+  }
+
+  async function clearGoal(sessionID) {
+    // Mirror `/goal clear`: drop the ordered flag and the focused goal + result.
+    sessionOrdered.delete(sessionID)
+    cleanupGoal(sessionID)
+    lastGoalResults.delete(sessionID)
+    await persist()
+    return "Goal cleared."
+  }
+
+  return { getGoal, getGoalHistory, setGoal, updateGoal, clearGoal }
+}
+
+function agentToolSessionID(ctx) {
+  return ctx?.sessionID || ctx?.session_id || ctx?.session?.id || ctx?.sessionId || null
+}
+
+// Cache the optional @opencode-ai/plugin import once. It provides the `tool`
+// helper and `tool.schema` (zod). It is an optional peer dependency: when it is
+// not installed (e.g. unit tests, older OpenCode), tool registration is simply
+// skipped and the command/event hooks still work.
+let opencodePluginModulePromise
+async function loadOpencodePluginModule() {
+  if (opencodePluginModulePromise === undefined) {
+    opencodePluginModulePromise = import("@opencode-ai/plugin")
+      .then((mod) => mod)
+      .catch(() => null)
+  }
+  return opencodePluginModulePromise
+}
+
+function buildAgentTools(toolHelper, handlers) {
+  const schema = toolHelper.schema
+  const run = (handler) => async (args, ctx) => {
+    const sessionID = agentToolSessionID(ctx)
+    if (!sessionID) return "No session id available for the goal tool."
+    return handler(sessionID, args || {})
+  }
+  return {
+    get_goal: toolHelper({
+      description:
+        "Get the status of the current goal for this session (objective, budget usage, last checkpoint).",
+      args: {},
+      execute: run((sessionID) => handlers.getGoal(sessionID)),
+    }),
+    get_goal_history: toolHelper({
+      description: "Get the lifecycle history and latest checkpoint of the current goal for this session.",
+      args: {},
+      execute: run((sessionID) => handlers.getGoalHistory(sessionID)),
+    }),
+    set_goal: toolHelper({
+      description:
+        "Set a new session goal for autonomous auto-continue. ONLY call this when the user explicitly asks you to set, define, or start working toward a goal — never decide to set a goal on your own. Replaces any existing goal.",
+      args: {
+        objective: schema.string(),
+        maxTurns: schema.number().optional(),
+        maxTokens: schema.number().optional(),
+        maxDurationMs: schema.number().optional(),
+        successCriteria: schema.string().optional(),
+        constraints: schema.string().optional(),
+        mode: schema.string().optional(),
+      },
+      execute: run((sessionID, args) => handlers.setGoal(sessionID, args)),
+    }),
+    update_goal: toolHelper({
+      description:
+        "Update the current goal: revise its `objective`, and/or set its `status` to complete, blocked, paused, or resumed. Mark complete only after verifying the objective is truly done; include `evidence` (for complete) or `blocker` (for blocked).",
+      args: {
+        objective: schema.string().optional(),
+        status: schema.string().optional(),
+        evidence: schema.string().optional(),
+        blocker: schema.string().optional(),
+      },
+      execute: run((sessionID, args) => handlers.updateGoal(sessionID, args)),
+    }),
+    clear_goal: toolHelper({
+      description: "Clear the current goal for this session and discard its saved status.",
+      args: {},
+      execute: run((sessionID) => handlers.clearGoal(sessionID)),
+    }),
+  }
+}
+
 function formatGoalList(sessionID) {
   const goals = listSessionGoals(sessionID)
   const focusedId = goalStates.get(sessionID)?.goalId || null
@@ -1787,6 +2021,8 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
     await persist()
   }
 
+  const agentToolHandlers = buildAgentToolHandlers({ defaultGoalOptions, persist })
+
   const hooks = {
     "command.execute.before": async (input, output) => {
       if (input.command !== commandName) return
@@ -1872,7 +2108,16 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
           return
         }
 
+        const previousGoalId = goal.goalId
         resetGoalBudget(goal)
+        // resetGoalBudget rotates goalId; re-key the multi-goal registry to the
+        // new id so a later clear/replace removes the goal instead of leaking a
+        // stale entry (the focused pointer holds the same object reference).
+        if (goal.goalId !== previousGoalId) {
+          removeSessionGoal(sessionID, previousGoalId)
+          registerSessionGoal(goal)
+          focusGoal(sessionID, goal)
+        }
         goal.stopped = false
         goal.stopReason = ""
         goal.blockedReason = ""
@@ -2583,6 +2828,22 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
     delete hooks["command.execute.before"]
   }
 
+  // Register agent-facing tools (megalist 7.1 / 7.2) when @opencode-ai/plugin is
+  // available (it provides the `tool` helper and zod-style schema). Disabled via
+  // `registerTools: false`. When the helper is absent the command/event hooks
+  // still work; only the programmatic tool surface is omitted, preserving the
+  // zero-runtime-dependency posture.
+  if (pluginOptions.registerTools !== false) {
+    const toolModule = await loadOpencodePluginModule()
+    if (toolModule?.tool?.schema) {
+      try {
+        hooks.tool = buildAgentTools(toolModule.tool, agentToolHandlers)
+      } catch (error) {
+        await logPluginError(client, "Failed to register goal agent tools", error)
+      }
+    }
+  }
+
   return hooks
 }
 
@@ -2593,6 +2854,9 @@ export default {
 
 export const testInternals = {
   activeGoal,
+  agentToolSessionID,
+  buildAgentToolHandlers,
+  buildAgentTools,
   listSessionGoals,
   formatGoalList,
   appendLedgerLine,