opencode-goal-plugin 0.4.7 → 0.6.0

package/index.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Type declarations for opencode-goal-plugin.
+ *
+ * These describe the plugin-level configuration object accepted in
+ * `opencode.json` under `plugin: [["opencode-goal-plugin", { ... }]]`,
+ * and the shape of the module's exports.
+ */
+
+/**
+ * Verdict returned by a completion auditor (built-in or custom). See
+ * {@link GoalPluginOptions.auditor} and {@link GoalPluginOptions.completionAudit}.
+ */
+export interface CompletionAuditVerdict {
+  /** `true` to archive the goal as achieved; `false` to reject the completion. */
+  approved: boolean
+  /** Human-readable reason, surfaced in the goal's status when rejected. */
+  reason?: string
+}
+
+/** Arguments passed to a custom {@link GoalPluginOptions.auditor} function. */
+export interface CompletionAuditContext {
+  /** The goal being audited (objective, budget usage, checkpoints, etc.). */
+  goal: unknown
+  /** The OpenCode session ID the goal belongs to. */
+  sessionID: string
+  /** The assistant's latest response text, containing the `[goal:evidence]`/`[goal:complete]` claim. */
+  latestText: string
+}
+
+/** Options for the built-in child-session completion auditor (`completionAudit: true`). */
+export interface CompletionAuditorOptions {
+  /**
+   * How long, in milliseconds, the built-in auditor waits for a verdict from
+   * its child OpenCode session. A timeout rejects the audit and pauses the
+   * goal. Operational failures follow {@link failurePolicy}.
+   * @default 120000
+   */
+  timeoutMs?: number
+
+  /**
+   * Result used when the child-session API is unavailable, malformed, throws,
+   * or times out. Semantic rejection or an invalid verdict always rejects.
+   * `"approve"` is an explicit compatibility escape hatch.
+   * @default "reject"
+   */
+  failurePolicy?: "reject" | "approve"
+}
+
+/**
+ * Configuration options for opencode-goal-plugin. All fields are optional;
+ * unset fields fall back to the plugin's built-in defaults. These act as
+ * the default limits for every goal set in a session, and most of the
+ * budget/behavior fields can be overridden per-goal via `/goal` command
+ * flags (e.g. `--max-turns`, `--success`, `--mode`).
+ */
+export interface GoalPluginOptions {
+  /**
+   * OpenCode session SDK argument shape. PluginInput currently supplies the
+   * legacy generated client; set `"flat"` when embedding with the v2 SDK.
+   * The compatibility adapter remembers the successful shape per operation.
+   * @default "legacy"
+   */
+  sdkShape?: "legacy" | "flat"
+
+  /**
+   * Maximum number of auto-continue turns sent toward a goal before it is
+   * stopped for exceeding limits. Overridable per-goal with `--max-turns`.
+   * @default 10
+   */
+  maxTurns?: number
+
+  /**
+   * Maximum wall-clock duration, in milliseconds, a goal may run before it
+   * is stopped for exceeding limits. Overridable per-goal with
+   * `--max-duration-ms` or `--max-minutes`.
+   * @default 900000
+   */
+  maxDurationMs?: number
+
+  /**
+   * Maximum context token budget a goal may consume before it is stopped
+   * for exceeding limits. Overridable per-goal with `--max-tokens` or the
+   * `--budget` shorthand (accepts a `k`/`m` suffix, e.g. `100k`, `1.5m`).
+   * @default 200000
+   */
+  maxTokens?: number
+
+  /**
+   * Minimum delay, in milliseconds, enforced between consecutive
+   * auto-continue prompts. Overridable per-goal with `--cooldown-ms`.
+   * @default 1500
+   */
+  minDelayMs?: number
+
+  /**
+   * 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.
+   * @default 50
+   */
+  maxRecentMessages?: number
+
+  /**
+   * Output token floor below which a turn is considered "low-output" for
+   * no-progress detection. Overridable per-goal with
+   * `--no-progress-threshold`.
+   * @default 50
+   */
+  noProgressTokenThreshold?: number
+
+  /**
+   * Grace window for low-output stalls: the goal is paused only after this
+   * many consecutive stalled low-output turns, rather than on the first
+   * one. Overridable per-goal with `--no-progress-turns`.
+   * @default 2
+   */
+  noProgressTurnsBeforePause?: number
+
+  /**
+   * Grace window for tool-free continuation turns (a "talk only" turn that
+   * calls no tool). Complements the no-progress check by catching
+   * self-chat loops that still produce output. Overridable per-goal with
+   * `--no-tool-turns`.
+   * @default 2
+   */
+  noToolCallTurnsBeforePause?: number
+
+  /**
+   * Fraction (between 0 and 1, exclusive) of any budget (turns, duration,
+   * or tokens) at which the plugin sends a one-time "wrap up" prompt
+   * nudging the model to finish before the hard limit is hit.
+   * @default 0.8
+   */
+  budgetWrapupRatio?: number
+
+  /**
+   * Number of remaining auto-continue turns at which a limit-approaching
+   * warning is included in status output.
+   * @default 3
+   */
+  warnTurnsRemaining?: number
+
+  /**
+   * Remaining duration, in milliseconds, at which a limit-approaching
+   * warning is included in status output.
+   * @default 60000
+   */
+  warnDurationMsRemaining?: number
+
+  /**
+   * Remaining context tokens at which a limit-approaching warning is
+   * included in status output.
+   * @default 25000
+   */
+  warnTokensRemaining?: number
+
+  /**
+   * Maximum number of consecutive prompt failures (e.g. transport errors
+   * sending the auto-continue prompt, or repeated missing-evidence /
+   * missing-blocker format violations) tolerated before the goal is
+   * stopped.
+   * @default 3
+   */
+  maxPromptFailures?: number
+
+  /**
+   * Whether to persist active/backgrounded goals and recent goal results
+   * to disk so they survive a restart. Recovered active goals are loaded
+   * in a paused state. Set to `false` for purely in-memory behavior (this
+   * also disables the lifecycle ledger).
+   * @default true
+   */
+  persistState?: boolean
+
+  /**
+   * Filesystem path where persisted goal state is written when
+   * `persistState` is enabled. Overrides both the project-local default
+   * and the `OPENCODE_GOAL_STATE_PATH` environment variable.
+   * @default "<cwd>/.opencode/goals/state.json"
+   */
+  stateFilePath?: string
+
+  /**
+   * Filesystem path for the append-only lifecycle ledger
+   * (`<event> per line`, used to reconstruct active goals if the main
+   * state file is missing or corrupted).
+   * @default "<stateFilePath>.ledger.jsonl"
+   */
+  ledgerFilePath?: string
+
+  /** Maximum bytes in one lifecycle-ledger generation. @default 2097152 */
+  ledgerMaxBytes?: number
+
+  /** Number of rotated lifecycle-ledger generations to retain (0-10). @default 3 */
+  ledgerRetentionFiles?: number
+
+  /**
+   * How long, in milliseconds, a completed goal's summary remains
+   * available through `/goal status` after the goal leaves active memory.
+   * @default 604800000
+   */
+  resultRetentionMs?: number
+
+  /**
+   * Maximum number of completed-goal summaries retained in process memory
+   * before the oldest ones are evicted.
+   * @default 200
+   */
+  maxStoredResults?: number
+
+  /**
+   * The slash command the plugin owns. Set to e.g. `"objective"` to drive
+   * the workflow with `/objective` instead of `/goal`; a leading slash is
+   * tolerated and stripped. Remember to register the matching command
+   * name in your OpenCode `command` config.
+   * @default "goal"
+   */
+  commandName?: string
+
+  /**
+   * Whether the plugin installs its `command.execute.before` hook at all.
+   * Set to `false` if you only want the auto-continue/persistence
+   * behavior driven programmatically (e.g. via {@link registerTools})
+   * and don't want the plugin to own a slash command.
+   * @default true
+   */
+  registerCommand?: boolean
+
+  /**
+   * Whether the plugin registers the agent-facing goal tools
+   * (canonical `goal_status`, `goal_set`, `goal_pause`, `goal_resume`,
+   * `goal_block`, `goal_complete`, plus legacy `get_goal`,
+   * `get_goal_history`, `set_goal`, `update_goal`, `clear_goal`).
+   * Canonical tools return versioned JSON envelopes. Requires the optional `@opencode-ai/plugin` peer
+   * dependency; when it is absent, tool registration is silently skipped
+   * and the command/event hooks still work.
+   * @default true
+   */
+  registerTools?: boolean
+
+  /** Register collision-safe native `goal` and `goal-verify` agents through OpenCode's config hook. */
+  registerAgents?: boolean
+
+  /** Name of the native primary goal agent. @default "goal" */
+  goalAgentName?: string
+
+  /** Name of the native read-only verifier subagent. @default "goal-verify" */
+  verifierAgentName?: string
+
+  /**
+   * Enables the built-in child-session completion auditor: before a
+   * `[goal:complete]` is archived, the plugin spawns an independent
+   * OpenCode session to verify the completion against the goal and
+   * workspace. Ignored if {@link auditor} is also set (the custom
+   * auditor takes precedence). Tune the built-in auditor with
+   * {@link auditorOptions}.
+   * @default false
+   */
+  completionAudit?: boolean
+
+  /**
+   * Supply a custom completion auditor instead of the built-in
+   * child-session one. Takes precedence over `completionAudit: true`.
+   * A verdict of `{ approved: false }` pauses the goal (stop reason
+   * `"audit rejected"`) instead of archiving it. A thrown error is
+   * treated as a rejection (fail closed).
+   */
+  auditor?: (context: CompletionAuditContext) => Promise<CompletionAuditVerdict>
+
+  /**
+   * Tuning options for the built-in child-session auditor. Ignored when
+   * a custom {@link auditor} is supplied.
+   */
+  auditorOptions?: CompletionAuditorOptions
+
+  /**
+   * Whether the plugin announces completion/blocked audits (an
+   * audit-start and an audit-result message) instead of running silently.
+   * @default true
+   */
+  auditMessages?: boolean
+
+  /**
+   * Custom sink for audit announcements. Defaults to routing through
+   * OpenCode's structured log (`client.app.log`). Provide this to route
+   * audit messages elsewhere, e.g. into the live conversation.
+   */
+  auditMessenger?: (sessionID: string, text: string) => Promise<void>
+}
+
+/**
+ * OpenCode plugin hook map returned by the plugin's `server` factory.
+ * Matches OpenCode's plugin hook contract; kept loose (`unknown`
+ * input/output) since hook payload shapes are defined by OpenCode itself,
+ * not by this package.
+ */
+export interface GoalPluginHooks {
+  /** Registers collision-safe native goal and verifier agents. */
+  config: (config: unknown) => Promise<void>
+  /** Omitted entirely when {@link GoalPluginOptions.registerCommand} is `false`. */
+  "command.execute.before"?: (input: unknown, output: unknown) => Promise<void>
+  event: (input: unknown) => Promise<void>
+  "experimental.chat.system.transform": (input: unknown, output: unknown) => Promise<void>
+  "experimental.compaction.autocontinue": (input: unknown, output: unknown) => Promise<void>
+  "experimental.session.compacting": (input: unknown, output: unknown) => Promise<void>
+  /**
+   * Agent-facing tool definitions, present only when
+   * {@link GoalPluginOptions.registerTools} is enabled (default) and the
+   * optional `@opencode-ai/plugin` peer dependency is installed.
+   */
+  tool?: Record<string, unknown>
+  /** Cancels pending continuation work and releases this plugin instance. */
+  dispose: () => Promise<void>
+  [hook: string]: unknown
+}
+
+/**
+ * The plugin's `server` factory. OpenCode calls this with a client bound
+ * to the running session and the resolved plugin options from
+ * `opencode.json`.
+ */
+export function GoalPlugin(
+  context: {
+    client: unknown
+    /** OpenCode's resolved project directory for this plugin instance. */
+    directory?: string
+    /** OpenCode's resolved worktree directory for this plugin instance. */
+    worktree?: string
+  },
+  options?: GoalPluginOptions,
+): Promise<GoalPluginHooks>
+
+/**
+ * Default export consumed by OpenCode's plugin loader:
+ * `{ "opencode-goal-plugin": { ... } }` in `opencode.json` resolves `id`
+ * and calls `server` to obtain the plugin's hooks.
+ */
+declare const goalPlugin: {
+  id: "opencode-goal-plugin"
+  server: typeof GoalPlugin
+}
+
+export default goalPlugin

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.4.7",
-  "description": "Session-scoped /goal workflow for OpenCode.",
+  "version": "0.6.0",
+  "description": "Durable, guarded goal workflows for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
+  "types": "./index.d.ts",
   "exports": {
     ".": "./src/goal-plugin.js",
     "./server": "./src/goal-plugin.js"
   },
+  "bin": {
+    "opencode-goal-plugin": "./scripts/verify.mjs"
+  },
   "files": [
     "src",
     "scripts",
     "examples",
+    "demo",
+    "docs",
+    "index.d.ts",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
@@ -20,9 +27,12 @@
     ".nvmrc"
   ],
   "scripts": {
-    "test": "node --test",
-    "test:coverage": "node --test --experimental-test-coverage",
+    "test": "node --test test/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage test/*.test.js",
     "smoke": "node scripts/smoke-command-hook.mjs",
+    "smoke:packed-host": "node scripts/packed-host-contract.mjs",
+    "benchmark:behavior": "node scripts/behavior-benchmark.mjs",
+    "verify": "node scripts/verify.mjs",
     "check": "node -c src/goal-plugin.js && npm test",
     "pack:check": "npm pack --dry-run"
   },
@@ -33,7 +43,7 @@
     "goal"
   ],
   "peerDependencies": {
-    "@opencode-ai/plugin": ">=1"
+    "@opencode-ai/plugin": ">=1.17.15 <2"
   },
   "peerDependenciesMeta": {
     "@opencode-ai/plugin": {

package/scripts/behavior-benchmark.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict"
+import { promises as fs } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { GoalPlugin } from "../src/goal-plugin.js"
+
+const startedAt = performance.now()
+const temporaryDirectories = []
+
+function assistantMessage(sessionID, text, id = `assistant-${sessionID}`) {
+  return {
+    info: {
+      id,
+      role: "assistant",
+      sessionID,
+      tokens: { input: 20, output: 120, reasoning: 0 },
+    },
+    parts: [{ type: "text", text }],
+  }
+}
+
+function createHost(messageForSession = () => "Working with tools.") {
+  const prompts = []
+  const notices = []
+  return {
+    prompts,
+    notices,
+    client: {
+      app: { log: async () => {} },
+      session: {
+        messages: async ({ path }) => ({
+          data: [assistantMessage(path.id, messageForSession(path.id))],
+        }),
+        promptAsync: async (input) => {
+          prompts.push(input)
+          return {}
+        },
+      },
+    },
+  }
+}
+
+function promptCharacters(prompts) {
+  return prompts.reduce(
+    (total, prompt) => total + (prompt?.body?.parts || []).reduce(
+      (partTotal, part) => partTotal + (typeof part?.text === "string" ? part.text.length : 0),
+      0,
+    ),
+    0,
+  )
+}
+
+async function makeDirectory(label) {
+  const directory = await fs.mkdtemp(join(tmpdir(), `goal-benchmark-${label}-`))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+async function createHooks(host, options = {}) {
+  return GoalPlugin(
+    { client: host.client, directory: await makeDirectory("workspace") },
+    {
+      persistState: false,
+      registerTools: false,
+      registerAgents: false,
+      minDelayMs: 1,
+      noProgressTokenThreshold: 1,
+      noProgressTurnsBeforePause: 10,
+      noToolCallTurnsBeforePause: 2,
+      ...options,
+    },
+  )
+}
+
+async function goalCommand(hooks, sessionID, argumentsText) {
+  const output = { parts: [] }
+  await hooks["command.execute.before"](
+    { command: "goal", sessionID, arguments: argumentsText },
+    output,
+  )
+  return output.parts.map((part) => part.text || "").join("\n")
+}
+
+async function idle(hooks, sessionID, id) {
+  await hooks.event({
+    event: {
+      id,
+      type: "session.status",
+      properties: { sessionID, status: { type: "idle" } },
+    },
+  })
+}
+
+async function scenario(name, points, run) {
+  const scenarioStartedAt = performance.now()
+  try {
+    const telemetry = await run()
+    return {
+      name,
+      passed: true,
+      points,
+      durationMs: Number((performance.now() - scenarioStartedAt).toFixed(2)),
+      ...telemetry,
+    }
+  } catch (error) {
+    return {
+      name,
+      passed: false,
+      points: 0,
+      possiblePoints: points,
+      durationMs: Number((performance.now() - scenarioStartedAt).toFixed(2)),
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+const results = []
+
+results.push(await scenario("verified-success", 20, async () => {
+  const sessionID = "benchmark-success"
+  const host = createHost(() => "Tests pass.\n[goal:evidence] npm test: 210/210\n[goal:complete]")
+  const hooks = await createHooks(host, {
+    auditor: async () => ({ approved: true, reason: "evidence independently accepted" }),
+  })
+  await goalCommand(hooks, sessionID, "ship a verified release")
+  await idle(hooks, sessionID, "success-idle")
+  const status = await goalCommand(hooks, sessionID, "status")
+  assert.match(status, /State: achieved/)
+  await hooks.dispose()
+  return {
+    continuationPrompts: host.prompts.length,
+    continuationCharacters: promptCharacters(host.prompts),
+    status: "archived",
+  }
+}))
+
+results.push(await scenario("false-completion", 20, async () => {
+  const sessionID = "benchmark-false-completion"
+  const host = createHost(() => "Looks done.\n[goal:evidence] guessed from source\n[goal:complete]")
+  const hooks = await createHooks(host, {
+    auditor: async () => ({ approved: false, reason: "no executed verification" }),
+  })
+  await goalCommand(hooks, sessionID, "do not accept an unverified claim")
+  await idle(hooks, sessionID, "false-idle")
+  const status = await goalCommand(hooks, sessionID, "status")
+  assert.match(status, /audit rejected/i)
+  assert.doesNotMatch(status, /No active goal/)
+  await hooks.dispose()
+  return {
+    continuationPrompts: host.prompts.length,
+    continuationCharacters: promptCharacters(host.prompts),
+    status: "rejected",
+  }
+}))
+
+results.push(await scenario("loop-circuit-breaker", 15, async () => {
+  const sessionID = "benchmark-loop"
+  let turn = 0
+  const host = createHost(() => `Still discussing the work, turn ${turn++}.`)
+  const hooks = await createHooks(host)
+  await goalCommand(hooks, sessionID, "stop self-chat loops")
+  await idle(hooks, sessionID, "loop-1")
+  await idle(hooks, sessionID, "loop-2")
+  await idle(hooks, sessionID, "loop-3")
+  const status = await goalCommand(hooks, sessionID, "status")
+  assert.match(status, /no tool calls|self-chat loop/i)
+  assert.equal(host.prompts.length, 2)
+  await hooks.dispose()
+  return {
+    continuationPrompts: host.prompts.length,
+    continuationCharacters: promptCharacters(host.prompts),
+    status: "paused",
+  }
+}))
+
+results.push(await scenario("human-interruption", 15, async () => {
+  const sessionID = "benchmark-interruption"
+  const host = createHost()
+  const hooks = await createHooks(host)
+  await goalCommand(hooks, sessionID, "respect explicit interruption")
+  await hooks.event({
+    event: {
+      type: "session.error",
+      properties: {
+        sessionID,
+        error: { name: "MessageAbortedError", message: "aborted by user" },
+      },
+    },
+  })
+  await idle(hooks, sessionID, "interruption-idle")
+  assert.equal(host.prompts.length, 0)
+  assert.match(await goalCommand(hooks, sessionID, "status"), /abort|paused|stopped/i)
+  await hooks.dispose()
+  return { continuationPrompts: 0, status: "paused" }
+}))
+
+results.push(await scenario("compaction-continuity", 15, async () => {
+  const sessionID = "benchmark-compaction"
+  const host = createHost()
+  const hooks = await createHooks(host)
+  await goalCommand(hooks, sessionID, "preserve the objective across compaction")
+  const output = { context: [] }
+  await hooks["experimental.session.compacting"]({ sessionID }, output)
+  assert.equal(output.context.length, 1)
+  assert.match(output.context[0], /preserve the objective across compaction/)
+  assert.ok(output.context[0].length < 2_000, "compaction context exceeded token-efficient size cap")
+  await hooks.dispose()
+  return {
+    contextCharacters: output.context[0].length,
+    estimatedContextTokens: Math.ceil(output.context[0].length / 4),
+    status: "preserved",
+  }
+}))
+
+results.push(await scenario("restart-recovery", 15, async () => {
+  const sessionID = "benchmark-restart"
+  const directory = await makeDirectory("restart")
+  const stateFilePath = join(directory, "state.json")
+  const host = createHost()
+  const first = await GoalPlugin(
+    { client: host.client, directory },
+    { persistState: true, stateFilePath, registerTools: false, registerAgents: false, minDelayMs: 1 },
+  )
+  await goalCommand(first, sessionID, "recover safely after restart")
+  await first.dispose()
+  const second = await GoalPlugin(
+    { client: host.client, directory },
+    { persistState: true, stateFilePath, registerTools: false, registerAgents: false, minDelayMs: 1 },
+  )
+  const status = await goalCommand(second, sessionID, "status")
+  assert.match(status, /Recovered persisted goal state|recovered after restart/i)
+  await idle(second, sessionID, "restart-idle")
+  assert.equal(host.prompts.length, 0, "recovered goals must not resume without user consent")
+  const stateBytes = (await fs.stat(stateFilePath)).size
+  await second.dispose()
+  return { continuationPrompts: 0, persistedStateBytes: stateBytes, status: "recovered-paused" }
+}))
+
+const score = results.reduce((total, result) => total + result.points, 0)
+const possibleScore = 100
+const continuationCharacters = results.reduce(
+  (total, result) => total + (result.continuationCharacters || 0),
+  0,
+)
+const report = {
+  schemaVersion: 1,
+  benchmark: "opencode-goal-plugin-behavior",
+  score,
+  possibleScore,
+  passed: score === possibleScore,
+  durationMs: Number((performance.now() - startedAt).toFixed(2)),
+  efficiency: {
+    totalContinuationPrompts: results.reduce(
+      (total, result) => total + (result.continuationPrompts || 0),
+      0,
+    ),
+    continuationCharacters,
+    estimatedContinuationTokens: Math.ceil(continuationCharacters / 4),
+    modelCalls: 0,
+    externalRequests: 0,
+  },
+  scenarios: results,
+}
+
+for (const directory of temporaryDirectories) {
+  await fs.rm(directory, { recursive: true, force: true })
+}
+
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+if (!report.passed) process.exitCode = 1