opencode-goal-plugin 0.5.0 → 0.6.1

package/index.d.ts

@@ -31,10 +31,19 @@ export interface CompletionAuditContext {
 export interface CompletionAuditorOptions {
   /**
    * How long, in milliseconds, the built-in auditor waits for a verdict from
-   * its child OpenCode session before failing open (auto-approving).
+   * 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"
 }
 
 /**
@@ -45,6 +54,14 @@ export interface CompletionAuditorOptions {
  * 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`.
@@ -104,7 +121,7 @@ export interface GoalPluginOptions {
    * 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`.
+   * `--no-tool-turns`. Set the plugin option to `0` to disable this heuristic.
    * @default 2
    */
   noToolCallTurnsBeforePause?: number
@@ -172,6 +189,12 @@ export interface GoalPluginOptions {
    */
   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.
@@ -206,14 +229,25 @@ export interface GoalPluginOptions {
 
   /**
    * Whether the plugin registers the agent-facing goal tools
-   * (`get_goal`, `get_goal_history`, `set_goal`, `update_goal`,
-   * `clear_goal`). Requires the optional `@opencode-ai/plugin` peer
+   * (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
@@ -262,17 +296,22 @@ export interface GoalPluginOptions {
  * 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
 }
 
@@ -282,10 +321,19 @@ export interface GoalPluginHooks {
  * `opencode.json`.
  */
 export function GoalPlugin(
-  context: { client: unknown },
+  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>
 
+/** Internal diagnostic/test helpers. Not covered by semantic-version compatibility guarantees. */
+export const testInternals: Readonly<Record<string, unknown>>
+
 /**
  * Default export consumed by OpenCode's plugin loader:
  * `{ "opencode-goal-plugin": { ... } }` in `opencode.json` resolves `id`

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.5.0",
-  "description": "Session-scoped /goal workflow for OpenCode.",
+  "version": "0.6.1",
+  "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"
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/goal-plugin.js",
+      "default": "./src/goal-plugin.js"
+    },
+    "./server": {
+      "types": "./index.d.ts",
+      "import": "./src/goal-plugin.js",
+      "default": "./src/goal-plugin.js"
+    }
   },
   "bin": {
     "opencode-goal-plugin": "./scripts/verify.mjs"
@@ -16,6 +24,8 @@
     "src",
     "scripts",
     "examples",
+    "demo",
+    "docs",
     "index.d.ts",
     "README.md",
     "CHANGELOG.md",
@@ -28,6 +38,8 @@
     "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"
@@ -39,7 +51,7 @@
     "goal"
   ],
   "peerDependencies": {
-    "@opencode-ai/plugin": ">=1"
+    "@opencode-ai/plugin": ">=1.17.15 <2"
   },
   "peerDependenciesMeta": {
     "@opencode-ai/plugin": {
@@ -48,7 +60,8 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=18",
+    "opencode": ">=1.17.15 <2"
   },
   "repository": {
     "type": "git",

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

package/scripts/packed-host-contract.mjs

@@ -0,0 +1,160 @@
+import assert from "node:assert/strict"
+import { execFileSync } from "node:child_process"
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+const repository = new URL("..", import.meta.url)
+const root = await mkdtemp(join(tmpdir(), "opencode-goal-plugin-packed-host-"))
+const packDirectory = join(root, "pack")
+const projectDirectory = join(root, "host-project")
+const cacheDirectory = join(root, "npm-cache")
+const npmEnvironment = { ...process.env, npm_config_cache: cacheDirectory }
+
+try {
+  await Promise.all([
+    mkdir(packDirectory, { recursive: true }),
+    mkdir(projectDirectory, { recursive: true }),
+    mkdir(cacheDirectory, { recursive: true }),
+  ])
+  await writeFile(
+    join(projectDirectory, "package.json"),
+    JSON.stringify({ private: true, type: "module" }),
+  )
+
+  const packResult = JSON.parse(
+    execFileSync(
+      "npm",
+      ["pack", "--json", "--pack-destination", packDirectory],
+      { cwd: repository, encoding: "utf8", env: npmEnvironment },
+    ),
+  )
+  assert.equal(packResult.length, 1)
+  const tarball = join(packDirectory, packResult[0].filename)
+
+  // Install only the artifact npm produced. The optional peer is omitted so this
+  // contract test is offline-safe and cannot mutate the user's OpenCode install.
+  execFileSync(
+    "npm",
+    [
+      "install",
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      "--no-package-lock",
+      "--omit=peer",
+      "--offline",
+      "--cache",
+      cacheDirectory,
+      tarball,
+    ],
+    { cwd: projectDirectory, encoding: "utf8", env: npmEnvironment },
+  )
+
+  const installedManifestPath = join(
+    projectDirectory,
+    "node_modules",
+    "opencode-goal-plugin",
+    "package.json",
+  )
+  const installedManifest = JSON.parse(await readFile(installedManifestPath, "utf8"))
+  const installedEntry = join(
+    projectDirectory,
+    "node_modules",
+    "opencode-goal-plugin",
+    installedManifest.main,
+  )
+  const installed = await import(pathToFileURL(installedEntry).href)
+
+  assert.equal(installed.default.id, "opencode-goal-plugin")
+  assert.equal(installed.default.server, installed.GoalPlugin)
+
+  const sessionID = "packed-host-contract"
+  const promptCalls = []
+  const client = {
+    app: { log: async () => {} },
+    session: {
+      messages: async ({ path }) => ({
+        data: [
+          {
+            info: {
+              id: "assistant-packed-contract",
+              role: "assistant",
+              sessionID: path.id,
+              tokens: { input: 1, output: 1, reasoning: 0 },
+            },
+            parts: [{ type: "text", text: "Work remains." }],
+          },
+        ],
+      }),
+      promptAsync: async (input) => {
+        promptCalls.push(input)
+        return {}
+      },
+    },
+  }
+  const hooks = await installed.GoalPlugin(
+    { client, directory: projectDirectory },
+    {
+      persistState: false,
+      registerTools: false,
+      minDelayMs: 1,
+      noToolCallTurnsBeforePause: 10,
+    },
+  )
+
+  for (const hook of [
+    "config",
+    "command.execute.before",
+    "event",
+    "experimental.chat.system.transform",
+    "experimental.session.compacting",
+    "experimental.compaction.autocontinue",
+    "dispose",
+  ]) {
+    assert.equal(typeof hooks[hook], "function", `${hook} must be callable`)
+  }
+  const config = {}
+  await hooks.config(config)
+  assert.equal(config.agent.goal.mode, "primary")
+  assert.equal(config.agent["goal-verify"].tools.edit, false)
+
+  const output = { parts: [] }
+  await hooks["command.execute.before"](
+    { command: "goal", sessionID, arguments: "verify the installed artifact --max-turns 1" },
+    output,
+  )
+  assert.match(output.parts[0]?.text, /New active goal/)
+
+  // Let the configured throttle window elapse before idle. This avoids leaving
+  // the contract dependent on the host's event-loop/timer shutdown behavior.
+  await new Promise((resolve) => setTimeout(resolve, 5))
+
+  await hooks.event({
+    event: {
+      type: "session.status",
+      properties: { sessionID, status: { type: "idle" } },
+    },
+  })
+
+  assert.equal(promptCalls.length, 1)
+  // PluginInput currently supplies OpenCode's generated legacy client shape:
+  // session.promptAsync({ path, body }). The standalone adapter suite covers
+  // flattened v2 clients separately.
+  assert.deepEqual(promptCalls[0].path, { id: sessionID })
+  assert.equal(promptCalls[0].body.parts.length, 1)
+  assert.deepEqual(promptCalls[0].body.parts[0].metadata, {
+    "opencode-goal-plugin": { kind: "continuation" },
+  })
+  assert.equal(promptCalls[0].body.parts[0].synthetic, true)
+
+  await hooks.dispose()
+  await hooks.dispose()
+
+  console.log(
+    `packed host contract passed (${installedManifest.name}@${installedManifest.version}; ${packResult[0].size} byte tarball)`,
+  )
+} finally {
+  await rm(root, { recursive: true, force: true })
+}

package/scripts/verify.mjs

@@ -7,10 +7,12 @@
 import assert from "node:assert/strict"
 
 const REQUIRED_HOOKS = [
+  "config",
   "command.execute.before",
   "event",
   "experimental.chat.system.transform",
   "experimental.compaction.autocontinue",
+  "experimental.session.compacting",
 ]
 
 const results = []
@@ -68,10 +70,10 @@ const client = {
 
 let hooks
 
-await check("plugin initializes and registers all 4 required hooks", async () => {
+await check(`plugin initializes and registers all ${REQUIRED_HOOKS.length} required hooks`, async () => {
   // registerTools defaults to true but silently no-ops without the optional
   // @opencode-ai/plugin peer dependency, so it is not asserted here — the
-  // 4 hooks below are always present regardless of that peer dependency.
+  // These hooks are always present regardless of that peer dependency.
   hooks = await GoalPlugin({ client }, { minDelayMs: 1, persistState: false })
   for (const hookName of REQUIRED_HOOKS) {
     assert.equal(