opencode-goal-plugin 0.5.0 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.5.0",
-  "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",
@@ -16,6 +16,8 @@
     "src",
     "scripts",
     "examples",
+    "demo",
+    "docs",
     "index.d.ts",
     "README.md",
     "CHANGELOG.md",
@@ -28,6 +30,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 +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

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(

package/src/completion-claim.js

@@ -0,0 +1,127 @@
+const MAX_SUMMARY_LENGTH = 500
+const MAX_CRITERIA = 20
+const MAX_CHECKS = 20
+const MAX_CHANGED_FILES = 100
+const MAX_LIMITATIONS = 20
+const MAX_CRITERION_LENGTH = 300
+const MAX_ITEM_LENGTH = 500
+const CHECK_RESULTS = new Set(["passed", "failed", "not-run"])
+
+function cleanStringList(values, field) {
+  const cleaned = values.map((value) => (typeof value === "string" ? value.trim() : ""))
+  return cleaned.every((value) => value && value.length <= MAX_ITEM_LENGTH)
+    ? { ok: true, values: cleaned }
+    : {
+        ok: false,
+        error: `${field} entries must be non-empty strings of ${MAX_ITEM_LENGTH} characters or fewer`,
+      }
+}
+
+/**
+ * Validate an untrusted completion claim and render the concise evidence text
+ * consumed by completion auditors. Validation belongs at this tool boundary so
+ * malformed claims never enter goal state or verifier prompts.
+ */
+export function serializeCompletionClaim(raw = {}) {
+  const claim = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {}
+  const summary = typeof claim.summary === "string" ? claim.summary.trim() : ""
+  if (!summary) return { ok: false, error: "summary must be a non-empty string" }
+  if (summary.length > MAX_SUMMARY_LENGTH) {
+    return { ok: false, error: `summary must be ${MAX_SUMMARY_LENGTH} characters or fewer` }
+  }
+
+  const criteria = claim.criteria === undefined ? [] : claim.criteria
+  const checks = claim.checks === undefined ? [] : claim.checks
+  const changedFiles = claim.changedFiles === undefined ? [] : claim.changedFiles
+  const knownLimitations = claim.knownLimitations === undefined ? [] : claim.knownLimitations
+  if (
+    !Array.isArray(criteria) ||
+    !Array.isArray(checks) ||
+    !Array.isArray(changedFiles) ||
+    !Array.isArray(knownLimitations)
+  ) {
+    return {
+      ok: false,
+      error: "criteria, checks, changedFiles, and knownLimitations must be arrays when provided",
+    }
+  }
+  if (
+    criteria.length > MAX_CRITERIA ||
+    checks.length > MAX_CHECKS ||
+    changedFiles.length > MAX_CHANGED_FILES ||
+    knownLimitations.length > MAX_LIMITATIONS
+  ) {
+    return { ok: false, error: "completion claim exceeds item limits" }
+  }
+
+  const cleanCriteria = []
+  for (const item of criteria) {
+    const criterion = typeof item?.criterion === "string" ? item.criterion.trim() : ""
+    const evidence = Array.isArray(item?.evidence)
+      ? item.evidence.map((value) => (typeof value === "string" ? value.trim() : "")).filter(Boolean)
+      : []
+    if (!criterion || evidence.length === 0) {
+      return {
+        ok: false,
+        error: "each criterion requires a non-empty criterion and at least one evidence item",
+      }
+    }
+    if (
+      criterion.length > MAX_CRITERION_LENGTH ||
+      evidence.some((value) => value.length > MAX_ITEM_LENGTH)
+    ) {
+      return {
+        ok: false,
+        error: `criterion must be ${MAX_CRITERION_LENGTH} characters or fewer and evidence items ${MAX_ITEM_LENGTH} or fewer`,
+      }
+    }
+    cleanCriteria.push({ criterion, evidence })
+  }
+
+  const cleanChecks = []
+  for (const item of checks) {
+    const result = typeof item?.result === "string" ? item.result.trim() : ""
+    if (!CHECK_RESULTS.has(result)) {
+      return { ok: false, error: "each check result must be passed, failed, or not-run" }
+    }
+    if (result === "failed") return { ok: false, error: "completion cannot include a failed check" }
+    const command = typeof item?.command === "string" ? item.command.trim() : ""
+    const explanation = typeof item?.explanation === "string" ? item.explanation.trim() : ""
+    const exitCode = item?.exitCode
+    if (exitCode !== undefined && (!Number.isInteger(exitCode) || exitCode < 0)) {
+      return { ok: false, error: "check exitCode must be a non-negative integer" }
+    }
+    if (!command && !explanation) {
+      return { ok: false, error: "each check requires a command or explanation" }
+    }
+    if (command.length > MAX_ITEM_LENGTH || explanation.length > MAX_ITEM_LENGTH) {
+      return {
+        ok: false,
+        error: `check command and explanation must be ${MAX_ITEM_LENGTH} characters or fewer`,
+      }
+    }
+    cleanChecks.push({ command, result, exitCode, explanation })
+  }
+
+  const files = cleanStringList(changedFiles, "changedFiles")
+  if (!files.ok) return files
+  const limitations = cleanStringList(knownLimitations, "knownLimitations")
+  if (!limitations.ok) return limitations
+
+  const lines = [`Summary: ${summary}`]
+  cleanCriteria.forEach(({ criterion, evidence }) => {
+    lines.push(`Criterion: ${criterion} | Evidence: ${evidence.join("; ")}`)
+  })
+  cleanChecks.forEach(({ command, result, exitCode, explanation }) => {
+    const subject = command || "manual check"
+    const details = [exitCode === undefined ? "" : `exit ${exitCode}`, explanation]
+      .filter(Boolean)
+      .join("; ")
+    lines.push(`Check: ${subject} | ${result}${details ? ` | ${details}` : ""}`)
+  })
+  if (files.values.length) lines.push(`Changed files: ${files.values.join(", ")}`)
+  if (limitations.values.length) {
+    lines.push(`Known limitations: ${limitations.values.join("; ")}`)
+  }
+  return { ok: true, evidence: lines.join("\n") }
+}