@bybrawe/opencode-loop 0.5.12 → 0.5.14

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.5.14
+
+- Guarded active-run finalization so heartbeat and retry checks do not treat a still-running assistant turn as finished.
+- Made loop state writes atomic and backed up corrupt state files before falling back to an empty state.
+- Changed `opencode-loopd` to pass prompts as process arguments instead of shell strings, preserving quotes in inline prompts.
+- Stripped UTF-8 BOMs from daemon prompt files before sending them to OpenCode.
+- Removed the package plugin entry from the example config to avoid duplicate loading after the recommended local installer path.
+
+## 0.5.13
+
+- Wrapped experimental goal tools with `tool()` and Zod schemas for current OpenCode tool validation.
+- Added `@opencode-ai/plugin` as a dev dependency so fresh clones can resolve the tool helper during local development.
+
 ## 0.5.12
 
 - Fixed local plugin installs to write `opencode-loop.ts`, matching OpenCode local plugin discovery.

package/README.md

@@ -151,32 +151,12 @@ OpenCode Loop is designed for developers searching for:
 
 ### Recommended: install from npm
 
-For a clean reinstall or upgrade, use the latest published package:
+Use the npm installer from any shell: Windows PowerShell, Windows CMD, macOS, or Linux.
 
 ```bash
 npx -y @bybrawe/opencode-loop@latest
 ```
 
-Then fully restart OpenCode.
-
-Install from npm with `npx`:
-
-```bash
-npx -y @bybrawe/opencode-loop
-```
-
-On Windows CMD:
-
-```bat
-npx -y @bybrawe/opencode-loop
-```
-
-On Windows PowerShell:
-
-```powershell
-npx -y @bybrawe/opencode-loop
-```
-
 The installer copies the plugin and slash command files into your OpenCode config directory.
 It also removes the old local `opencode-loop.js` copy from earlier releases so only the current local `opencode-loop.ts` plugin remains.
 
@@ -217,6 +197,7 @@ The `npx` installer installs both parts:
 - the `/loop-*` command markdown files
 
 Use the OpenCode config-only method only if you already installed the command files separately or you are only testing plugin loading.
+Do not use the config package entry and the local `npx`-installed plugin at the same time unless you intentionally want to test duplicate plugin loading.
 
 ### Optional: OpenCode config package entry
 
@@ -239,6 +220,8 @@ If `/loop` does not appear after using only the config method, run the installer
 npx -y @bybrawe/opencode-loop
 ```
 
+If you later switch back to the recommended `npx` local install, remove `@bybrawe/opencode-loop` from the `plugin` array to avoid loading the package plugin and local plugin together.
+
 ### Install from GitHub
 
 Use this if you want to install from source instead of npm.
@@ -1113,6 +1096,16 @@ Improve the application in small safe steps.
 
 ## Changelog highlights
 
+### v0.5.13
+
+- Wrapped experimental goal tools with OpenCode's `tool()` helper and Zod schemas for current OpenCode tool validation.
+- Added `@opencode-ai/plugin` as a development dependency so fresh clones can resolve the tool helper.
+
+### v0.5.12
+
+- Changed local installs to write `opencode-loop.ts` and remove stale `opencode-loop.js` copies.
+- Fixed OpenCode CLI command argument parsing, current SDK call shapes, and `opencode-loopd` prompt passing.
+
 ### v0.5.7
 
 - Added experimental Goal Mode with `/loop-goal <objective>`.
@@ -1127,11 +1120,11 @@ Improve the application in small safe steps.
 - Stabilized `/loop-command 200m /compact` by routing compact/summarize through OpenCode TUI compact handling instead of treating it as a custom prompt command.
 - Clarified that command loops wait for idle and should be used for slash commands such as `/compact`.
 
-## v0.5.5
+### v0.5.5
 
 - Added explicit loop action types: prompt, scheduled question, OpenCode slash command, and shell command.
 - Added `/loop-command` / `/loop-cmd` for commands such as `/compact`; these wait for the first interval by default.
-- Added `/loop-ask` for recurring checks such as “did you run tests, tsc --noEmit, and build?”; it waits for the first interval by default.
+- Added `/loop-ask` for recurring checks such as "did you run tests, tsc --noEmit, and build?"; it waits for the first interval by default.
 - Added `/loop-shell` for recurring shell commands.
 - Added `--prompt`, `--ask`, `--command`, `--cmd`, `--slash`, `--shell`, and `--compact` type flags for `/loop`.
 - Clarified idle behavior: if a job becomes due while OpenCode is busy, it waits and runs on the next idle event.

package/examples/opencode.json

@@ -1,7 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "@bybrawe/opencode-loop",
     "@tarquinen/opencode-dcp@latest"
   ],
   "permission": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: heartbeat scheduler, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
   "type": "module",
   "main": "src/index.js",
@@ -54,6 +54,9 @@
   "peerDependencies": {
     "@opencode-ai/plugin": ">=1.4.0"
   },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.4.0"
+  },
   "bin": {
     "opencode-loop": "scripts/install-node.mjs",
     "opencode-loopd": "scripts/loopd.mjs"

package/scripts/loopd.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url"
 
 const args = process.argv.slice(2)
 const FAILED_RUN_RETRY_MS = 5_000
+const OPENCODE_BIN = process.env.OPENCODE_BIN || "opencode"
 
 function arg(name, fallback = null) {
   const i = args.indexOf(name)
@@ -39,25 +40,60 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
-function run(command, cwd) {
+function spawnOnce(command, commandArgs, cwd) {
   return new Promise((resolve) => {
-    const child = spawn(command, {
-      cwd,
-      shell: true,
-      stdio: "inherit",
-      env: process.env,
-    })
-
-    child.on("exit", (code) => resolve(code ?? 0))
+    let settled = false
+    const done = (result) => {
+      if (settled) return
+      settled = true
+      resolve(result)
+    }
+
+    let child
+    try {
+      child = spawn(command, commandArgs, {
+        cwd,
+        shell: false,
+        stdio: "inherit",
+        env: process.env,
+        windowsHide: true,
+      })
+    } catch (error) {
+      done({ code: -1, error })
+      return
+    }
+
+    child.on("error", (error) => done({ code: -1, error }))
+    child.on("exit", (code) => done({ code: code ?? 0 }))
   })
 }
 
+function quoteWindowsArg(value) {
+  const text = String(value ?? "")
+  return `"${text.replace(/(\\*)"/g, '$1$1\\"').replace(/\\+$/g, "$&$&")}"`
+}
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+}
+
+async function run(command, commandArgs, cwd) {
+  const direct = await spawnOnce(command, commandArgs, cwd)
+  if (direct.code !== -1 || process.platform !== "win32" || !["ENOENT", "EINVAL"].includes(direct.error?.code)) return direct.code
+
+  const fallback = await spawnOnce("cmd.exe", ["/d", "/s", "/c", command, ...commandArgs], cwd)
+  if (fallback.code === -1) {
+    console.error(`[opencode-loopd] failed to start ${command}: ${fallback.error?.message || direct.error?.message || "unknown error"}`)
+  }
+  return fallback.code
+}
+
 function readPrompt(project) {
   const promptFile = arg("--prompt-file")
   const promptArg = arg("--prompt")
 
   if (promptFile) {
-    return fs.readFileSync(path.resolve(project, promptFile), "utf8")
+    return stripBom(fs.readFileSync(path.resolve(project, promptFile), "utf8"))
   }
 
   if (promptArg) return promptArg
@@ -99,8 +135,7 @@ async function daemon() {
     console.log("")
     console.log(`[opencode-loopd] run #${count} ${new Date().toISOString()}`)
 
-    const command = `opencode run --continue ${JSON.stringify(prompt)}`
-    const code = await run(command, project)
+    const code = await run(OPENCODE_BIN, ["run", "--continue", prompt], project)
 
     if (code !== 0) {
       console.log(`[opencode-loopd] opencode exited with code ${code}`)
@@ -135,25 +170,25 @@ function installTask() {
   const script = fileURLToPath(import.meta.url)
 
   const commandParts = [
-    `"${node}"`,
-    `"${script}"`,
+    quoteWindowsArg(node),
+    quoteWindowsArg(script),
     "daemon",
     "--project",
-    `"${project}"`,
+    quoteWindowsArg(project),
     "--every",
     "0s",
     "--max-runs",
     "1",
   ]
 
-  if (promptFile) commandParts.push("--prompt-file", `"${promptFile}"`)
-  if (promptArg) commandParts.push("--prompt", `"${promptArg.replaceAll('"', '\\"')}"`)
+  if (promptFile) commandParts.push("--prompt-file", quoteWindowsArg(promptFile))
+  if (promptArg) commandParts.push("--prompt", quoteWindowsArg(promptArg))
 
   const taskCommand = commandParts.join(" ")
-  const schtasks = `schtasks /Create /F /SC MINUTE /MO ${minutes} /TN "${name}" /TR ${JSON.stringify(taskCommand)}`
+  const taskArgs = ["/Create", "/F", "/SC", "MINUTE", "/MO", String(minutes), "/TN", name, "/TR", taskCommand]
 
-  console.log(schtasks)
-  const result = spawnSync(schtasks, { shell: true, stdio: "inherit" })
+  console.log(["schtasks", ...taskArgs.map((part) => JSON.stringify(part))].join(" "))
+  const result = spawnSync("schtasks", taskArgs, { shell: false, stdio: "inherit" })
   process.exit(result.status ?? 0)
 }
 
@@ -163,7 +198,7 @@ function uninstallTask() {
   }
 
   const name = arg("--name", "OpenCodeLoop")
-  const result = spawnSync(`schtasks /Delete /F /TN "${name}"`, { shell: true, stdio: "inherit" })
+  const result = spawnSync("schtasks", ["/Delete", "/F", "/TN", name], { shell: false, stdio: "inherit" })
   process.exit(result.status ?? 0)
 }
 

package/src/index.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs"
 import path from "node:path"
 import { spawn } from "node:child_process"
+import { tool } from "@opencode-ai/plugin/tool"
 
 const SERVICE = "opencode-loop"
 const STATE_DIR = ".opencode/opencode-loop"
@@ -24,6 +25,7 @@ const dueTimers = new Map()
 const watchdogTimers = new Map()
 const runLocks = new Map()
 const knownSessions = new Map()
+const stateWriteLocks = new Map()
 let heartbeatTimer
 const sessionStatuses = new Map()
 const sessionStatusSeenAt = new Map()
@@ -319,21 +321,61 @@ function statePath(directory, sessionID) { return path.join(stateDir(directory),
 async function ensureDir(directory) { await fs.mkdir(directory, { recursive: true }) }
 async function pathExists(filePath) { try { await fs.access(filePath); return true } catch { return false } }
 
+function stateLockKey(directory, sessionID) {
+  return `${path.resolve(directory)}:${safeID(sessionID)}`
+}
+
+async function withStateWriteLock(directory, sessionID, fn) {
+  const key = stateLockKey(directory, sessionID)
+  const previous = stateWriteLocks.get(key) || Promise.resolve()
+  let release
+  const current = new Promise((resolve) => { release = resolve })
+  const next = previous.catch(() => {}).then(() => current)
+  stateWriteLocks.set(key, next)
+  await previous.catch(() => {})
+  try {
+    return await fn()
+  } finally {
+    release()
+    if (stateWriteLocks.get(key) === next) stateWriteLocks.delete(key)
+  }
+}
+
 async function readState(directory, sessionID) {
+  const target = statePath(directory, sessionID)
   try {
-    const parsed = JSON.parse(await fs.readFile(statePath(directory, sessionID), "utf8"))
+    const parsed = JSON.parse(await fs.readFile(target, "utf8"))
     return { version: 4, jobs: Array.isArray(parsed.jobs) ? parsed.jobs : [] }
-  } catch {
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      try {
+        await ensureDir(stateDir(directory))
+        await fs.copyFile(target, `${target}.corrupt-${Date.now()}`)
+      } catch {}
+    }
     return { version: 4, jobs: [] }
   }
 }
 
 async function writeState(directory, sessionID, state) {
-  await ensureDir(stateDir(directory))
-  await fs.writeFile(statePath(directory, sessionID), JSON.stringify({ version: 4, jobs: state.jobs || [] }, null, 2))
+  await withStateWriteLock(directory, sessionID, async () => {
+    await ensureDir(stateDir(directory))
+    const target = statePath(directory, sessionID)
+    const temp = `${target}.${process.pid}.${Date.now()}.tmp`
+    try {
+      await fs.writeFile(temp, JSON.stringify({ version: 4, jobs: state.jobs || [] }, null, 2))
+      await fs.rename(temp, target)
+    } finally {
+      try { await fs.rm(temp, { force: true }) } catch {}
+    }
+  })
 }
 
-async function removeState(directory, sessionID) { try { await fs.unlink(statePath(directory, sessionID)) } catch {} }
+async function removeState(directory, sessionID) {
+  await withStateWriteLock(directory, sessionID, async () => {
+    try { await fs.unlink(statePath(directory, sessionID)) } catch {}
+  })
+}
 
 function sdkError(result) {
   if (!result || typeof result !== "object") return undefined
@@ -496,7 +538,7 @@ function startHeartbeat() {
       }
       Promise.resolve()
         .then(async () => {
-          await finalizeActiveRun(info.directory, info.client, sessionID, { forceStale: true })
+          await finalizeActiveRun(info.directory, info.client, sessionID, { requireIdle: true, forceStale: true })
           await maybeRunDueJobs(info.directory, info.client, sessionID, { heartbeat: true })
         })
         .catch((error) => appendLoopLog(info.directory, "heartbeat-error", { sessionID, error: sdkErrorMessage(error) }).catch(() => {}))
@@ -819,6 +861,19 @@ function staleActiveRun(sessionID) {
   return age >= threshold
 }
 
+async function canFinalizeActiveRun(directory, client, sessionID, active, options = {}) {
+  if (!options.requireIdle && !options.forceStale) return true
+  if (options.forceStale && staleActiveRun(sessionID)) return true
+  if (!options.requireIdle) return false
+
+  const live = await readLiveSessionStatus(client, sessionID, directory)
+  if (live?.type) return live.type === "idle"
+
+  const cached = sessionStatuses.get(sessionID)
+  const seenAt = sessionStatusSeenAt.get(sessionID) || 0
+  return cached === "idle" && seenAt > (active.startedAt || 0)
+}
+
 async function readLiveSessionStatus(client, sessionID, directory) {
   const argsList = []
   if (directory) argsList.push({ query: { directory } }, { workspace: directory }, { directory })
@@ -1147,14 +1202,17 @@ async function runGoalChecks(directory, sessionID, job, client) {
   return job
 }
 
-async function finalizeActiveRun(directory, client, sessionID) {
+async function finalizeActiveRun(directory, client, sessionID, options = {}) {
   const active = activeRuns.get(sessionID)
   if (!active) return
+  if (!await canFinalizeActiveRun(directory, client, sessionID, active, options)) return false
+  const recoveredStale = staleActiveRun(sessionID)
   clearActiveRun(sessionID)
   const state = await readState(directory, sessionID)
   let job = (state.jobs || []).find((candidate) => candidate.id === active.jobId)
   if (!job) return
   job.lastFinishedAt = now()
+  if (recoveredStale) await appendLoopLog(directory, "active-stale-recovery", { sessionID, job: job.name || job.id, startedAt: active.startedAt })
 
   if (job.verifyCommand) {
     const verify = await runShellCommand(job.verifyCommand, directory, job.timeoutMs || 300_000)
@@ -1200,6 +1258,7 @@ async function finalizeActiveRun(directory, client, sessionID) {
   if (isGoalJob(job)) await writeGoalReport(directory, sessionID, job)
   await createCheckpoint(directory, sessionID, job, client)
   await scheduleDueWork(directory, client, sessionID)
+  return true
 }
 
 async function fireAction(directory, client, sessionID, job) {
@@ -1257,7 +1316,7 @@ async function maybeRunDueJobs(directory, client, sessionID, options = {}) {
   runLocks.set(sessionID, now())
   let job
   try {
-    await finalizeActiveRun(directory, client, sessionID, { forceStale: true })
+    await finalizeActiveRun(directory, client, sessionID, { requireIdle: true, forceStale: true })
     if (!await sessionIsIdle(client, sessionID, directory)) {
       if (options.force) await toast(client, "Loop queued: session is busy; it will run on the next idle check.", "info")
       await reschedule(BUSY_RETRY_MS)
@@ -1360,6 +1419,8 @@ async function maybeRunDueJobs(directory, client, sessionID, options = {}) {
       let timer
       if (job.timeoutMs > 0) timer = setTimeout(() => { fireSdk(client, "session.abort", client.session.abort.bind(client.session), { path: { id: sessionID }, body: {} }, { sessionID }); toast(client, `Loop timeout fired: ${job.name || job.id}`, "warning").catch(() => {}) }, job.timeoutMs)
       activeRuns.set(sessionID, { jobId: job.id, job, startedAt: now(), timer })
+      sessionStatuses.set(sessionID, "busy")
+      sessionStatusSeenAt.set(sessionID, now())
       await reschedule(BUSY_RETRY_MS)
     } catch (error) {
       clearActiveRun(sessionID)
@@ -1640,39 +1701,39 @@ async function handleCommand(directory, client, input, fallbackName, fallbackArg
 
 function goalTools(defaultDirectory) {
   return {
-    opencode_loop_goal_complete: {
+    opencode_loop_goal_complete: tool({
       description: "Mark the current OpenCode Loop experimental goal as completed. Use only after acceptance criteria are satisfied and you have evidence from tests, typecheck, build, or code inspection.",
       args: {
-        summary: { type: "string", description: "Short human-readable summary of what was completed." },
-        evidence: { type: "string", description: "Concrete evidence that the goal is complete, such as commands run, passing checks, files changed, and important results." },
+        summary: tool.schema.string().describe("Short human-readable summary of what was completed."),
+        evidence: tool.schema.string().describe("Concrete evidence that the goal is complete, such as commands run, passing checks, files changed, and important results."),
       },
       execute: async (args, context) => {
         const result = await setGoalComplete(context.directory || defaultDirectory, context.sessionID, args)
         return { title: result.ok ? "Goal completed" : "Goal not found", output: result.message }
       },
-    },
-    opencode_loop_goal_blocked: {
+    }),
+    opencode_loop_goal_blocked: tool({
       description: "Mark the current OpenCode Loop experimental goal as blocked when user input or manual intervention is required.",
       args: {
-        reason: { type: "string", description: "Why the goal is blocked." },
-        needed: { type: "string", description: "What user input, credential, decision, or manual action is needed to continue." },
+        reason: tool.schema.string().describe("Why the goal is blocked."),
+        needed: tool.schema.string().describe("What user input, credential, decision, or manual action is needed to continue."),
       },
       execute: async (args, context) => {
         const result = await setGoalBlocked(context.directory || defaultDirectory, context.sessionID, args)
         return { title: result.ok ? "Goal blocked" : "Goal not found", output: result.message }
       },
-    },
-    opencode_loop_goal_progress: {
+    }),
+    opencode_loop_goal_progress: tool({
       description: "Record meaningful progress on the current OpenCode Loop experimental goal without completing it.",
       args: {
-        summary: { type: "string", description: "What useful progress was made." },
-        next: { type: "string", description: "The next step toward completing the goal." },
+        summary: tool.schema.string().describe("What useful progress was made."),
+        next: tool.schema.string().describe("The next step toward completing the goal."),
       },
       execute: async (args, context) => {
         const result = await setGoalProgress(context.directory || defaultDirectory, context.sessionID, args)
         return { title: result.ok ? "Goal progress" : "Goal not found", output: result.message }
       },
-    },
+    }),
   }
 }