@bojackduy/opencode-loopd 1.0.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@bojackduy/opencode-loopd",
+  "version": "1.0.0",
+  "description": "Codex-inspired background goal engine for OpenCode — autonomous child sessions, engine-driven loop, and modal TUI dashboard",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bojackduy/opencode-loopd.git"
+  },
+  "homepage": "https://github.com/bojackduy/opencode-loopd#readme",
+  "bugs": {
+    "url": "https://github.com/bojackduy/opencode-loopd/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "loop",
+    "goal",
+    "background",
+    "automation",
+    "worker",
+    "subagent",
+    "opencode-loopd"
+  ],
+  "bin": {
+    "opencode-loopd": "./scripts/install-node.mjs"
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "skills",
+    "commands",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "exports": {
+    "./server": {
+      "import": "./dist/server.js"
+    },
+    "./tui": {
+      "import": "./dist/tui.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build:server": "bun build src/server/plugin.ts --outfile dist/server.js --target bun --external @opencode-ai/plugin --external @opencode-ai/plugin/tool",
+    "build:tui": "bun scripts/build-tui.ts",
+    "build": "bun run build:server && bun run build:tui",
+    "clean": "rm -rf dist",
+    "prepack": "bun run typecheck && bun test && bun run build",
+    "test": "bun test",
+    "release:patch": "bun run typecheck && bun test && npm version patch -m \"chore: release %s\" && git push && git push origin $(git describe --tags --abbrev=0)",
+    "release:minor": "bun run typecheck && bun test && npm version minor -m \"chore: release %s\" && git push && git push origin $(git describe --tags --abbrev=0)",
+    "release:major": "bun run typecheck && bun test && npm version major -m \"chore: release %s\" && git push && git push origin $(git describe --tags --abbrev=0)"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.4.0 <2",
+    "@opentui/core": "*",
+    "@opentui/solid": "*",
+    "solid-js": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.15",
+    "@opentui/core": "^0.4.1",
+    "@opentui/solid": "^0.4.1",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0",
+    "solid-js": "^1.9.13",
+    "typescript": "^5.7.0"
+  }
+}

package/scripts/build-tui.ts

@@ -0,0 +1,20 @@
+import solidPlugin from "@opentui/solid/bun-plugin"
+
+const result = await Bun.build({
+  entrypoints: ["src/tui/plugin.tsx"],
+  outdir: "dist",
+  naming: "tui.js",
+  target: "bun",
+  external: [
+    "@opencode-ai/plugin/tui",
+    "@opentui/core",
+    "@opentui/solid",
+    "solid-js",
+  ],
+  plugins: [solidPlugin],
+})
+
+if (!result.success) {
+  for (const log of result.logs) console.error(log)
+  process.exit(1)
+}

package/scripts/install-node.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const config = process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode")
+const pluginDir = join(config, "plugins")
+const commandDir = join(config, "commands")
+const skillDir = join(config, "skills", "loopd")
+const packagePath = join(config, "package.json")
+const packageName = "opencode-loopd"
+const packageVersion = JSON.parse(await readFile(join(root, "package.json"), "utf8")).version
+const packageSpec = `${packageName}@${packageVersion}`
+const configCandidates = ["opencode.json", "opencode.jsonc", "config.json", "config.jsonc"]
+const installerArgs = process.argv.slice(2)
+const uninstallRequested = installerArgs.length === 1 && ["--uninstall", "uninstall", "--remove"].includes(installerArgs[0] || "")
+
+if (installerArgs.includes("--help") || installerArgs.includes("-h")) {
+  console.log(`opencode-loopd installer/updater\n\nUsage:\n  opencode-loopd\n  npx -y opencode-loopd@latest\n  npx -y opencode-loopd@latest --uninstall\n\nInstall/update registers the plugin, installs /goal command and loopd skill.\nUninstall removes the plugin registration, command and skill.\n\nSet OPENCODE_CONFIG_DIR to target a non-default OpenCode config directory.`)
+  process.exit(0)
+}
+
+if (installerArgs.includes("--version") || installerArgs.includes("-v")) {
+  console.log(packageVersion)
+  process.exit(0)
+}
+
+if (installerArgs.length && !uninstallRequested) {
+  console.error(`Unknown installer option: ${installerArgs[0]}`)
+  process.exit(2)
+}
+
+function stripJsonComments(input) {
+  let out = "", quote = "", esc = false, lc = false, bc = false
+  for (let i = 0; i < input.length; i++) {
+    const c = input[i], n = input[i + 1]
+    if (lc) { if (c === "\n" || c === "\r") { lc = false; out += c } continue }
+    if (bc) { if (c === "*" && n === "/") { bc = false; i++ } else if (c === "\n" || c === "\r") out += c; continue }
+    if (quote) { out += c; if (esc) esc = false; else if (c === "\\") esc = true; else if (c === quote) quote = ""; continue }
+    if (c === '"') { quote = c; out += c; continue }
+    if (c === "/" && n === "/") { lc = true; i++; continue }
+    if (c === "/" && n === "*") { bc = true; i++; continue }
+    out += c
+  }
+  return out
+}
+function stripTrailingCommas(input) {
+  let out = "", quote = "", esc = false
+  for (let i = 0; i < input.length; i++) {
+    const c = input[i]
+    if (quote) { out += c; if (esc) esc = false; else if (c === "\\") esc = true; else if (c === quote) quote = ""; continue }
+    if (c === '"') { quote = c; out += c; continue }
+    if (c === ",") { let j = i + 1; while (/\s/.test(input[j] || "")) j++; if (input[j] === "]" || input[j] === "}") continue }
+    out += c
+  }
+  return out
+}
+function parseJsonc(input) {
+  const p = JSON.parse(stripTrailingCommas(stripJsonComments(input)))
+  if (!p || typeof p !== "object" || Array.isArray(p)) throw new Error("OpenCode config root must be an object")
+  return p
+}
+function isPackageSpec(v) { const s = String(v||"").trim(); return s === packageName || s.startsWith(`${packageName}@`) }
+function skipTrivia(s, i) { while (i < s.length) { const c=s[i]||"", n=s[i+1]||""; if (/\s/.test(c)) {i++;continue} if (c==="/"&&n==="/") {i+=2; while(i<s.length&&s[i]!=="\n"&&s[i]!=="\r") i++; continue} if (c==="/"&&n==="*") { const e=s.indexOf("*/",i+2); if(e<0) throw new Error("unterminated block comment"); i=e+2; continue } break } return i }
+function readJsonString(s, i) { if(s[i]!=='"') throw new Error("expected JSON string"); let esc=false; for(let j=i+1;j<s.length;j++){const c=s[j]||""; if(esc){esc=false; continue} if(c==="\\"){esc=true;continue} if(c==='"'){return {value:JSON.parse(s.slice(i,j+1)), end:j+1}}} throw new Error("unterminated JSON string") }
+function skipJsonValue(s,i){ const vs=skipTrivia(s,i), f=s[vs]; if(f==='"') return readJsonString(s,vs).end; if(f==="{"||f==="["){const st=[]; let q=false,esc=false,lc=false,bc=false; for(let j=vs;j<s.length;j++){const c=s[j]||"",n=s[j+1]||""; if(lc){if(c==="\n"||c==="\r") lc=false; continue} if(bc){if(c==="*"&&n==="/"){bc=false;j++} continue} if(q){if(esc) esc=false; else if(c==="\\") esc=true; else if(c==='"') q=false; continue} if(c==='"'){q=true;continue} if(c==="/"&&n==="/"){lc=true;j++;continue} if(c==="/"&&n==="*"){bc=true;j++;continue} if(c==="{"||c==="[") st.push(c); else if(c==="}"||c==="]"){const e=c==="}"?"{":"["; if(st.at(-1)!==e) throw new Error("mismatched delimiters"); st.pop(); if(!st.length) return j+1} } throw new Error("unterminated JSON value") } let j=vs; while(j<s.length&&![",","}","]"].includes(s[j])) j++; return j }
+function findRootProperty(s, name){ let i=skipTrivia(s,0); if(s[i]!=="{") throw new Error("OpenCode config must be root object"); i++; while(true){ i=skipTrivia(s,i); if(s[i]==="}") return null; const k=readJsonString(s,i); i=skipTrivia(s,k.end); if(s[i]!==":") throw new Error(`expected ':' after ${k.value}`); const vs=skipTrivia(s,i+1), ve=skipJsonValue(s,vs); if(k.value===name){ const ls=Math.max(s.lastIndexOf("\n",vs-1),s.lastIndexOf("\r",vs-1))+1; const kls=Math.max(s.lastIndexOf("\n",k.end-1),s.lastIndexOf("\r",k.end-1))+1; const indent=s.slice(kls,k.end-k.value.length-2).match(/^[\t ]*/)?.[0]||"  "; return {valueStart:vs,valueEnd:ve,indent,lineStart:ls} } const av=skipTrivia(s,ve); if(s[av]===",") i=av+1; else if(s[av]==="}") return null; else throw new Error(`expected ',' or '}' after ${k.value}`) } }
+function formatPluginArray(vals, indent, eol){ if(!vals.length) return "[]"; const ci=`${indent}  `; return `[${eol}${vals.map(v=>`${ci}${JSON.stringify(v)}`).join(`,${eol}`)}${eol}${indent}]` }
+function rewriteExistingPluginArray(source, next){ const prop=findRootProperty(source,"plugin"); if(!prop) return source; const eol=source.includes("\r\n")?"\r\n":"\n"; const rep=formatPluginArray(next,prop.indent,eol); return `${source.slice(0,prop.valueStart)}${rep}${source.slice(prop.valueEnd)}` }
+
+async function configurePackagePlugin() {
+  let configured = false; const updatedFiles=[]
+  for (const name of configCandidates) {
+    const target = join(config, name)
+    try {
+      const source = await readFile(target, "utf8")
+      const parsed = parseJsonc(source)
+      if (parsed.plugin !== undefined && !Array.isArray(parsed.plugin)) throw new Error("plugin must be array")
+      const plugins = parsed.plugin || []
+      if (!plugins.some(isPackageSpec)) continue
+      configured = true
+      const next = plugins.filter(v=>!isPackageSpec(v))
+      next.push(packageSpec)
+      const upd = rewriteExistingPluginArray(source, next)
+      if (upd !== source) { await writeFile(target, upd, "utf8"); updatedFiles.push(target) }
+    } catch(e){ if(e?.code!=="ENOENT") throw new Error(`Could not inspect ${target}: ${e.message}`) }
+  }
+  return {configured, updatedFiles}
+}
+async function ensureDependency(){
+  let pkg={}
+  try{ pkg=JSON.parse(await readFile(packagePath,"utf8")) }catch(e){ if(e?.code!=="ENOENT"){ console.warn(`Could not update ${packagePath}: ${e.message}`); return } }
+  if(!pkg||typeof pkg!=="object"||Array.isArray(pkg)) pkg={}
+  pkg.dependencies = pkg.dependencies && typeof pkg.dependencies==="object" && !Array.isArray(pkg.dependencies) ? pkg.dependencies : {}
+  if(!pkg.dependencies["@opencode-ai/plugin"]){ pkg.dependencies["@opencode-ai/plugin"]=">=1.4.0"; await writeFile(packagePath, JSON.stringify(pkg,null,2)+"\n","utf8") }
+}
+async function removePackagedFiles(srcDir, tgtDir){
+  try{ for(const n of await readdir(srcDir)) if(n.endsWith(".md")) await rm(join(tgtDir,n),{force:true}) }catch{}
+}
+async function uninstall(){
+  const plans=[]
+  for(const name of configCandidates){
+    const target=join(config,name)
+    try{
+      const source=await readFile(target,"utf8")
+      const parsed=parseJsonc(source)
+      if(parsed.plugin!==undefined&&!Array.isArray(parsed.plugin)) throw new Error("plugin must be array")
+      const plugins=parsed.plugin||[]
+      const next=plugins.filter(v=>!isPackageSpec(v))
+      const upd= next.length===plugins.length ? source : rewriteExistingPluginArray(source,next)
+      plans.push({target,source,updated:upd})
+    }catch(e){ if(e?.code!=="ENOENT") throw new Error(`Could not inspect ${target}: ${e.message}`) }
+  }
+  for(const p of plans) if(p.updated!==p.source) await writeFile(p.target,p.updated,"utf8")
+  // remove loopd artifacts
+  await rm(join(config,"tui.json"),{force:true}).catch(()=>{}) // legacy if any
+  await removePackagedFiles(join(root,"commands"), join(config,"commands"))
+  await rm(join(config,"skills","loopd","SKILL.md"),{force:true})
+  try{ const d=join(config,"skills","loopd"); const files=await readdir(d); if(!files.length) await rm(d,{force:true}) }catch{}
+  const changed=plans.filter(p=>p.updated!==p.source).length
+  console.log(changed ? `Removed ${packageName} from ${changed} config file(s).` : `${packageName} was not registered.`)
+  console.log("Removed loopd command and skill when present. Project state under .opencode/loopd is preserved.")
+  console.log("Restart OpenCode to finish unloading.")
+}
+async function installOrUpdate(){
+  await mkdir(join(config,"plugins"),{recursive:true})
+  await mkdir(join(config,"commands"),{recursive:true})
+  await mkdir(join(config,"skills","loopd"),{recursive:true})
+  const pc=await configurePackagePlugin()
+  const usePkg=pc.configured
+  if(!usePkg){ await ensureDependency() }
+  // commands
+  for(const n of await readdir(join(root,"commands"))){
+    if(n.endsWith(".md")) await copyFile(join(root,"commands",n), join(config,"commands",n))
+  }
+  // skill
+  await copyFile(join(root,"skills","loopd","SKILL.md"), join(config,"skills","loopd","SKILL.md"))
+  if(usePkg){
+    const pin=pc.updatedFiles.length ? `pinned to ${packageSpec}` : `already pinned to ${packageSpec}`
+    console.log(`OpenCode Loopd is already configured as package in ${config}; ${pin}.`)
+  } else {
+    console.log(`Installed opencode-loopd to ${config}`)
+  }
+  console.log(`Installed ${packageName} command to ${join(config,"commands","goal.md")}`)
+  console.log(`Installed ${packageName} skill to ${join(config,"skills","loopd","SKILL.md")}`)
+  console.log("Restart OpenCode, then run: /goal  or  /loop")
+}
+if(uninstallRequested) await uninstall()
+else await installOrUpdate()

package/skills/loopd/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: loopd
+description: "Agent skill for loopd background goals. Teaches when to create goals, how to inspect/steer/pause them, and how to send instructions to workers."
+metadata:
+  version: "1.0.0"
+  status: active
+  tags: [opencode, loop, goal, background, automation]
+---
+
+# Loopd Background Goals
+
+Loopd runs long-running or autonomous tasks as background goals, each with a dedicated worker session. The parent chat stays interactive while work happens behind the scenes.
+
+## When to Use Loopd
+
+Use loopd when:
+
+- A task takes many turns and would block the main chat
+- You want autonomous work that continues while the user does other things
+- A task needs progress tracking, completion checks, or blocking
+- You want a dashboard to monitor and steer background work
+
+Do not use loopd when:
+
+- The task is trivial (1-3 turns)
+- The user needs to answer questions at every step
+- The task modifies production systems without review gates
+
+## Goal Lifecycle
+
+```
+created → active → complete
+                  → blocked (needs user intervention)
+         paused (user-initiated, can resume)
+```
+
+## Creating a Goal
+
+Use `loopd_create_goal` after clarifying the objective with the user:
+
+```
+loopd_create_goal({
+  name: "short-name",
+  objective: "Detailed description of what the goal should accomplish.",
+  checks: ["npm test"],                    // optional: shell commands for completion verification
+  progressFile: ".opencode/loopd/progress.md", // optional: worker reads/writes this
+  maxTurns: 50,                            // optional: safety budget
+  maxNoProgress: 5,                        // optional: auto-block without progress
+  maxFailures: 3,                          // optional: auto-block on failures
+  compactEvery: 3,                         // optional: compact worker session every N turns
+})
+```
+
+The goal starts immediately. The user can monitor it via `/loop` (Ctrl+L).
+
+## Worker Tools (Running Inside the Goal)
+
+These tools are available to the worker session doing the actual work:
+
+### get_goal
+
+Call at the start of every turn to read the objective, config, and current state. Always call this first.
+
+### report_goal_progress
+
+Call after durable state changes (file writes, verifications). Resets failure and no-progress counters.
+
+```
+report_goal_progress({
+  summary: "What was accomplished this turn.",
+  next: "The next concrete step.",
+  evidence: "Optional proof (file path, test output, etc.)."
+})
+```
+
+### complete_goal
+
+Call only when ALL acceptance criteria pass with concrete evidence. Runs configured completion checks before accepting.
+
+```
+complete_goal({
+  summary: "What was completed.",
+  evidence: "Concrete evidence (test output, file existence, etc.)."
+})
+```
+
+### block_goal
+
+Call only for a real external blocker requiring user intervention (e.g., missing credentials, ambiguous requirements).
+
+```
+block_goal({
+  reason: "Why the goal is blocked.",
+  needed: "What is needed to unblock."
+})
+```
+
+### Worker questions vs send_goal_input
+
+| Tool | Who calls it | Direction | When to use |
+|------|-------------|-----------|-------------|
+| `question` (OpenCode builtin) | Worker (inside goal) | Worker → User | Worker needs info only the user can provide. Question appears in the TUI footer as a blocker tab. |
+| `send_goal_input` | Owner (parent chat) | User → Worker | Owner sends an instruction, answer, or redirect to the worker. |
+
+**question** — The worker uses OpenCode's built-in `question` tool when it's genuinely stuck or ambiguous. The question appears in the TUI footer (blocker tab) and the user answers there. No goal status change needed — the worker stays busy until answered.
+
+**send_goal_input** — The owner calls this to steer the worker. Messages are injected into the worker's next continuation prompt. Use it to:
+- Redirect the worker to a different approach
+- Refine scope or add constraints
+- Provide missing context
+
+## Owner Tools (Parent Chat)
+
+These tools are available in the parent chat that created the goal:
+
+### list_background_goals
+
+Lists all active goals owned by this session. Shows status and progress.
+
+### inspect_background_goal
+
+Shows detailed info: objective, config, progress, blocker, runtime state.
+
+### read_goal_transcript
+
+Reads the last N messages from the worker session. Useful for debugging what the worker is doing.
+
+### send_goal_input
+
+Sends a message to the worker's next turn. See table above.
+
+## Dashboard Commands
+
+Open the dashboard with `/loop` or Ctrl+L.
+
+### Keyboard Shortcuts (Normal Mode)
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Move selection down / up |
+| `g` / `G` | Jump to top / bottom |
+| `o` | Open child (view details) |
+| `L` | Toggle log view |
+| `?` | Toggle help |
+| `Ctrl+N` | Switch to normal mode |
+| `:` | Enter command mode |
+
+### Command Mode (`:` prefix)
+
+| Command | Description |
+|---------|-------------|
+| `:send <message>` | Send instruction to the selected goal's worker |
+| `:open` | Open the selected goal's child session |
+| `:force <summary> --evidence <text>` | Force-complete (bypass verification checks) |
+| `:block <reason> --needed <text>` | Force-block the selected goal |
+| `:pause` | Pause the selected goal |
+| `:resume` | Resume the paused goal |
+| `:retry` | Retry the blocked goal |
+| `:clear` | Clear the selected goal |
+| `:logs` | Toggle log view |
+| `:help` | Show help |
+| `:q` / `:close` | Close dashboard |
+
+> Goal creation (`:goal start`) was removed from the dashboard — create goals via `/goal` in the parent chat so the agent can clarify the objective first.
+
+## Safety Patterns
+
+1. **Always call `get_goal` first** — Read the objective before doing any work.
+2. **Progress after durable changes** — Call `report_goal_progress` after file writes or verifications, not after thinking.
+3. **Complete with evidence** — Never call `complete_goal` without concrete proof (test output, file checks passing).
+4. **Block for real blockers only** — Don't block for things you can figure out. Block when you genuinely need user input.
+5. **Use checks for verification** — Set `checks` on goal creation to auto-verify completion (e.g., `["npm test", "test -f README.md"]`).
+6. **Set safety budgets** — Use `maxTurns`, `maxNoProgress`, and `maxFailures` to prevent runaway goals.
+7. **Compact periodically** — Use `compactEvery` to keep the worker session's context manageable.
+
+## Example: Creating and Monitoring a Goal
+
+**Parent chat:**
+```
+User: Write a README for this project and create a changelog.
+
+Agent: I'll set up a background goal for this.
+
+loopd_create_goal({
+  name: "docs-write",
+  objective: "Write a README.md covering: what it is, install, usage, architecture, and examples. Then create CHANGELOG.md with a v1.0.0 entry.",
+  checks: ["test -f README.md", "test -f CHANGELOG.md"],
+  progressFile: ".opencode/loopd/docs-progress.md",
+  maxTurns: 20
+})
+
+# Goal starts. User can monitor with /loop.
+```
+
+**Worker session (automatic):**
+```
+# Turn 1
+get_goal()  → reads objective
+# ... explores codebase, writes README.md
+report_goal_progress({ summary: "README.md written", next: "Create CHANGELOG.md" })
+
+# Turn 2
+get_goal()  → reads objective
+# ... writes CHANGELOG.md
+complete_goal({ summary: "Docs complete", evidence: "README.md and CHANGELOG.md exist" })
+```