opencode-goal-plugin 0.4.7 → 0.6.0

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

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Installation verification for opencode-goal-plugin.
+// Checks the plugin can be loaded and wired up correctly without ever
+// invoking a model — every check below uses the same mock-client approach
+// as scripts/smoke-command-hook.mjs.
+
+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 = []
+
+function check(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => {
+      results.push({ name, ok: true })
+      console.log(`  ✅ ${name}`)
+    })
+    .catch((error) => {
+      results.push({ name, ok: false, error })
+      console.log(`  ❌ ${name}`)
+      console.log(`     ${error.message}`)
+    })
+}
+
+console.log("opencode-goal-plugin installation verification\n")
+
+await check("Node.js >= 18", () => {
+  const major = Number(process.versions.node.split(".")[0])
+  assert.ok(major >= 18, `Node ${process.versions.node} is below the required >=18`)
+})
+
+let pluginModule
+let GoalPlugin
+
+await check("plugin module resolves and exposes expected shape", async () => {
+  pluginModule = await import("opencode-goal-plugin")
+  GoalPlugin = pluginModule.GoalPlugin
+  assert.equal(pluginModule.default.id, "opencode-goal-plugin")
+  assert.equal(typeof pluginModule.default.server, "function")
+  assert.equal(typeof GoalPlugin, "function")
+})
+
+const sessionID = `verify-${process.pid}`
+const promptCalls = []
+const logCalls = []
+
+const client = {
+  app: {
+    log: async (input) => {
+      logCalls.push(input)
+    },
+  },
+  session: {
+    messages: async () => ({ data: [] }),
+    promptAsync: async (input) => {
+      promptCalls.push(input)
+      return {}
+    },
+  },
+}
+
+let hooks
+
+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
+  // 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(
+      typeof hooks[hookName],
+      "function",
+      `missing or non-function hook: ${hookName}`,
+    )
+  }
+})
+
+async function runGoalCommand(args) {
+  const output = { parts: [] }
+  await hooks["command.execute.before"](
+    { command: "goal", sessionID, arguments: args },
+    output,
+  )
+  assert.equal(output.parts.length, 1)
+  assert.equal(output.parts[0].type, "text")
+  return output.parts[0].text
+}
+
+await check("/goal status works", async () => {
+  const text = await runGoalCommand("status")
+  assert.match(text, /No active goal/)
+})
+
+await check("/goal set works", async () => {
+  const text = await runGoalCommand("verify the installation --max-turns 1")
+  assert.match(text, /New active goal: verify the installation/)
+  const statusText = await runGoalCommand("status")
+  assert.match(statusText, /Active goal: verify the installation/)
+})
+
+await check("no model calls were made during verification", () => {
+  assert.equal(promptCalls.length, 0, "expected zero promptAsync calls")
+})
+
+// Clean up the goal created above so this script has no side effects.
+await runGoalCommand("clear")
+
+console.log()
+
+const failed = results.filter((r) => !r.ok)
+if (failed.length > 0) {
+  console.log(`${failed.length}/${results.length} checks failed.`)
+  process.exit(1)
+}
+
+console.log(`All ${results.length} checks passed. opencode-goal-plugin is installed correctly.`)

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") }
+}