opencode-goal-plugin 0.5.0 → 0.6.0

package/src/goal-tool-result.js

@@ -0,0 +1,18 @@
+export function goalToolSuccess(message, data) {
+  return { ok: true, message, ...(data === undefined ? {} : { data }) }
+}
+
+export function goalToolFailure(code, message) {
+  return { ok: false, code, message }
+}
+
+export function serializeGoalToolResult(operation, result) {
+  return JSON.stringify({
+    version: 1,
+    operation,
+    ok: result.ok,
+    ...(!result.ok ? { error: result.code } : {}),
+    message: result.message,
+    ...(result.data === undefined ? {} : { data: result.data }),
+  })
+}

package/src/native-agent-config.js

@@ -0,0 +1,69 @@
+const GOAL_AGENT_PROMPT = `Execute explicit goals persistently. Use goal tools to track state and checkpoints. Make concrete progress; claim completion only with verification evidence. Report only genuine blockers.`
+
+const VERIFIER_AGENT_PROMPT = `Independently verify the claim against the goal, constraints, evidence, and workspace. Use read-only checks; never edit or mutate goal state. Approve only when proven; otherwise give one actionable reason.`
+
+export function applyNativeGoalConfig(config, options = {}) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new TypeError("OpenCode config hook requires a mutable config object")
+  }
+  if (options.registerAgents === false) return config
+
+  const goalAgentName = options.goalAgentName ?? "goal"
+  const verifierAgentName = options.verifierAgentName ?? "goal-verify"
+  if (typeof goalAgentName !== "string" || !goalAgentName.trim()) {
+    throw new TypeError("goalAgentName must be a non-empty string")
+  }
+  if (typeof verifierAgentName !== "string" || !verifierAgentName.trim()) {
+    throw new TypeError("verifierAgentName must be a non-empty string")
+  }
+  if (goalAgentName !== goalAgentName.trim() || verifierAgentName !== verifierAgentName.trim()) {
+    throw new TypeError("goal and verifier agent names cannot have surrounding whitespace")
+  }
+  if (goalAgentName === verifierAgentName) {
+    throw new TypeError("goalAgentName and verifierAgentName must be different")
+  }
+
+  config.agent ||= {}
+  if (options.requireVerifierOwnership && config.agent[verifierAgentName]) {
+    throw new Error(
+      `completionAudit cannot safely use existing agent ${JSON.stringify(verifierAgentName)}; choose an unused verifierAgentName`,
+    )
+  }
+  config.agent[goalAgentName] ||= {
+    description: "Execute an explicit user goal with persistent progress and evidence-gated completion.",
+    mode: "primary",
+    prompt: GOAL_AGENT_PROMPT,
+  }
+  config.agent[verifierAgentName] ||= {
+    description: "Independently verify a goal completion claim without modifying the workspace.",
+    mode: "subagent",
+    hidden: true,
+    prompt: VERIFIER_AGENT_PROMPT,
+    permission: {
+      edit: "deny",
+      bash: "deny",
+    },
+    tools: {
+      bash: false,
+      write: false,
+      edit: false,
+      patch: false,
+      goal_set: false,
+      goal_update: false,
+      goal_pause: false,
+      goal_resume: false,
+      goal_block: false,
+      goal_complete: false,
+      goal_cancel: false,
+      set_goal: false,
+      update_goal: false,
+      clear_goal: false,
+    },
+  }
+  return config
+}
+
+export const nativeAgentConfigInternals = Object.freeze({
+  GOAL_AGENT_PROMPT,
+  VERIFIER_AGENT_PROMPT,
+})

package/src/opencode-session-api.js

@@ -0,0 +1,100 @@
+const SHAPE_ERROR_PATTERNS = [
+  /(?:missing|required).*(?:sessionID|path|body|query)/i,
+  /(?:unknown|unrecognized|unexpected|invalid).*(?:sessionID|path|body|query|argument|field|key)/i,
+  /(?:expected|must be).*(?:object|path|body|query|sessionID)/i,
+  /(?:validation|schema|invalid input|invalid argument)/i,
+]
+
+function isArgumentShapeError(error) {
+  if (!(error instanceof TypeError)) return false
+  const message = String(error.message || "")
+  return SHAPE_ERROR_PATTERNS.some((pattern) => pattern.test(message))
+}
+
+function unwrapData(response) {
+  return response && typeof response === "object" && "data" in response
+    ? response.data
+    : response
+}
+
+/**
+ * Present both historical and current OpenCode session SDKs through one API.
+ * A successful shape is remembered independently for every operation.
+ */
+export function createOpenCodeSessionApi(client, options = {}) {
+  if (!client?.session || typeof client.session !== "object") {
+    throw new TypeError("OpenCode client.session is required")
+  }
+
+  const preferredShape = options.preferredShape || "flat"
+  if (preferredShape !== "flat" && preferredShape !== "legacy") {
+    throw new TypeError('preferredShape must be "flat" or "legacy"')
+  }
+  const shapes = new Map()
+
+  async function invoke(operation, flatInput, legacyInput) {
+    const method = client.session[operation]
+    if (typeof method !== "function") {
+      throw new TypeError(`OpenCode client.session.${operation} is not available`)
+    }
+
+    const knownShape = shapes.get(operation)
+    const firstShape = knownShape || preferredShape
+    const firstInput = firstShape === "flat" ? flatInput : legacyInput
+    try {
+      const response = await method.call(client.session, firstInput)
+      shapes.set(operation, firstShape)
+      return unwrapData(response)
+    } catch (error) {
+      if (knownShape || !isArgumentShapeError(error)) throw error
+      const fallbackShape = firstShape === "flat" ? "legacy" : "flat"
+      const fallbackInput = fallbackShape === "flat" ? flatInput : legacyInput
+      const response = await method.call(client.session, fallbackInput)
+      shapes.set(operation, fallbackShape)
+      return unwrapData(response)
+    }
+  }
+
+  return Object.freeze({
+    messages(sessionID, options = {}) {
+      return invoke(
+        "messages",
+        { sessionID, ...options },
+        { path: { id: sessionID }, query: options },
+      )
+    },
+    promptAsync(sessionID, input = {}) {
+      return invoke(
+        "promptAsync",
+        { sessionID, ...input },
+        { path: { id: sessionID }, body: input },
+      )
+    },
+    createChild(parentID, input = {}) {
+      const body = { ...input, parentID }
+      return invoke("create", body, { body })
+    },
+    prompt(sessionID, input = {}) {
+      return invoke(
+        "prompt",
+        { sessionID, ...input },
+        { path: { id: sessionID }, body: input },
+      )
+    },
+    update(sessionID, input = {}) {
+      return invoke(
+        "update",
+        { sessionID, ...input },
+        { path: { id: sessionID }, body: input },
+      )
+    },
+    get(sessionID) {
+      return invoke("get", { sessionID }, { path: { id: sessionID } })
+    },
+    abort(sessionID) {
+      return invoke("abort", { sessionID }, { path: { id: sessionID } })
+    },
+  })
+}
+
+export const sessionApiInternals = Object.freeze({ isArgumentShapeError, unwrapData })

package/src/persistence-lease.js

@@ -0,0 +1,82 @@
+import { randomUUID } from "node:crypto"
+import { promises as fs } from "node:fs"
+import { hostname } from "node:os"
+import { dirname } from "node:path"
+
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    if (error?.code === "ESRCH") return false
+    return true
+  }
+}
+
+async function readOwner(lockPath) {
+  try {
+    return JSON.parse(await fs.readFile(`${lockPath}/owner.json`, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Hold an exclusive workspace lease for the plugin instance lifetime. This
+ * deliberately rejects a second writer instead of allowing stale full-state
+ * snapshots to overwrite each other.
+ */
+export async function acquirePersistenceLease(stateFilePath) {
+  const lockPath = `${stateFilePath}.lock`
+  await fs.mkdir(dirname(stateFilePath), { recursive: true, mode: 0o700 })
+  const owner = {
+    token: randomUUID(),
+    pid: process.pid,
+    hostname: hostname(),
+    createdAt: Date.now(),
+  }
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      await fs.mkdir(lockPath, { mode: 0o700 })
+      await fs.writeFile(`${lockPath}/owner.json`, JSON.stringify(owner), { mode: 0o600 })
+      return {
+        lockPath,
+        owner,
+        async release() {
+          const current = await readOwner(lockPath)
+          if (current?.token !== owner.token) return false
+          await fs.rm(lockPath, { recursive: true, force: true })
+          return true
+        },
+      }
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {})
+        throw error
+      }
+      const existing = await readOwner(lockPath)
+      const sameHost = existing?.hostname === owner.hostname
+      if (sameHost && processIsAlive(existing?.pid) === false) {
+        const stalePath = `${lockPath}.stale.${randomUUID()}`
+        try {
+          await fs.rename(lockPath, stalePath)
+          await fs.rm(stalePath, { recursive: true, force: true })
+          continue
+        } catch (reclaimError) {
+          if (reclaimError?.code === "ENOENT") continue
+        }
+      }
+      const description = existing
+        ? `pid ${existing.pid} on ${existing.hostname}`
+        : "an unknown owner"
+      throw new Error(
+        `goal persistence is already owned by ${description}; close the other OpenCode instance or configure a different stateFilePath`,
+      )
+    }
+  }
+  throw new Error("could not acquire goal persistence lease")
+}
+
+export const persistenceLeaseInternals = Object.freeze({ processIsAlive, readOwner })