opencodekit 0.14.3 → 0.14.5

package/dist/template/.opencode/tool/background.ts

@@ -1,22 +1,45 @@
-import { execSync } from "node:child_process";
+/**
+ * @experimental Background Task Tool
+ *
+ * LIMITATION: Creates SEPARATE sessions, NOT child sessions of the parent.
+ * This means background tasks don't inherit context from the build agent's session.
+ *
+ * USE CASES:
+ * - True fire-and-forget async execution
+ * - When you need to continue working before results are ready
+ *
+ * FOR MOST CASES: Use the Task tool instead. Multiple Task calls in one message
+ * run in parallel AND create proper child sessions.
+ *
+ * Example with Task (recommended):
+ *   Task({ subagent_type: "scout", prompt: "..." })  // ┐
+ *   Task({ subagent_type: "explore", prompt: "..." }) // ┘ Parallel, proper sessions
+ *
+ * Example with Background (fire-and-forget):
+ *   background_start({ agent: "scout", prompt: "..." }) // → taskId
+ *   // ... continue other work ...
+ *   background_output({ taskId }) // collect later
+ */
+
+import { type ChildProcess, execSync, spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import { createOpencodeClient } from "@opencode-ai/sdk";
 
 const TASKS_FILE = ".opencode/.background-tasks.json";
+const OUTPUT_DIR = ".opencode/.background-output";
 
 interface BackgroundTask {
 	taskId: string;
-	sessionId: string;
-	parentSessionId: string; // Track parent for debugging
+	pid: number;
+	outputFile: string;
 	agent: string;
 	prompt: string;
 	started: number;
-	status: "running" | "completed" | "cancelled";
+	status: "running" | "completed" | "cancelled" | "failed";
 	// Beads integration
 	beadId?: string;
-	autoCloseBead?: boolean; // Only allowed for safe agents (explore, scout)
+	autoCloseBead?: boolean;
 }
 
 interface TasksStore {
@@ -37,8 +60,8 @@ async function saveTasks(store: TasksStore): Promise<void> {
 	await fs.writeFile(TASKS_FILE, JSON.stringify(store, null, 2));
 }
 
-function createClient() {
-	return createOpencodeClient({ baseUrl: "http://localhost:4096" });
+async function ensureOutputDir(): Promise<void> {
+	await fs.mkdir(OUTPUT_DIR, { recursive: true });
 }
 
 /**
@@ -46,7 +69,6 @@ function createClient() {
  */
 function findBdPath(): string {
 	try {
-		// Try to find bd in PATH using shell
 		const result = execSync("which bd || command -v bd", {
 			encoding: "utf-8",
 			timeout: 5000,
@@ -54,7 +76,6 @@ function findBdPath(): string {
 		}).trim();
 		if (result) return result;
 	} catch {
-		// Fallback to common locations
 		const commonPaths = [
 			`${process.env.HOME}/.local/bin/bd`,
 			`${process.env.HOME}/.bun/bin/bd`,
@@ -70,11 +91,9 @@ function findBdPath(): string {
 			}
 		}
 	}
-	// Last resort - assume it's in PATH
 	return "bd";
 }
 
-// Cache the bd path
 let bdPath: string | null = null;
 function getBdPath(): string {
 	if (!bdPath) {
@@ -90,11 +109,9 @@ async function runBeadsCommand(
 	args: string[],
 ): Promise<{ success: boolean; output: string }> {
 	try {
-		// Quote arguments that contain spaces
 		const quotedArgs = args.map((arg) =>
 			arg.includes(" ") ? `"${arg}"` : arg,
 		);
-		// Use dynamically detected bd path with shell for proper PATH resolution
 		const output = execSync(`${getBdPath()} ${quotedArgs.join(" ")}`, {
 			encoding: "utf-8",
 			timeout: 30000,
@@ -111,10 +128,19 @@ async function runBeadsCommand(
 	}
 }
 
+/**
+ * Check if a process is still running by PID
+ */
+function isProcessRunning(pid: number): boolean {
+	try {
+		process.kill(pid, 0); // Signal 0 = check if process exists
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 // Allowed agents for background delegation
-// - Subagents: explore, scout, review, planner, vision, looker (stateless workers)
-// - Primary: rush (autonomous execution)
-// - NOT allowed: build (build is the orchestrator that uses this tool)
 const ALLOWED_AGENTS = [
 	"explore",
 	"scout",
@@ -127,7 +153,6 @@ const ALLOWED_AGENTS = [
 type AllowedAgent = (typeof ALLOWED_AGENTS)[number];
 
 // Agents safe for autoCloseBead (pure research, no side effects)
-// These only return information, don't make changes that need verification
 const SAFE_AUTOCLOSE_AGENTS: readonly string[] = [
 	"explore",
 	"scout",
@@ -135,8 +160,8 @@ const SAFE_AUTOCLOSE_AGENTS: readonly string[] = [
 ] as const;
 
 /**
- * Start a background subagent task.
- * Creates a child session that runs independently.
+ * Start a background subagent task using `opencode run`.
+ * Spawns a separate process that runs independently.
  */
 export const start = tool({
 	description:
@@ -145,7 +170,7 @@ export const start = tool({
 		agent: tool.schema
 			.string()
 			.describe(
-				"Agent type: explore, scout, review, planner, vision, looker, rush (NOT build - build is the orchestrator)",
+				"Agent type: explore, scout, review, planner, vision, looker, rush (NOT build)",
 			),
 		prompt: tool.schema.string().describe("Task prompt for the agent"),
 		title: tool.schema
@@ -160,15 +185,15 @@ export const start = tool({
 			.boolean()
 			.optional()
 			.describe(
-				"Auto-close bead on completion. Only allowed for safe agents (explore, scout). Blocked for rush/review/planner/vision/looker.",
+				"Auto-close bead on completion. Only allowed for safe agents (explore, scout, looker).",
 			),
 	},
-	execute: async (args, context) => {
-		// Validate agent type - build cannot delegate to itself
+	execute: async (args) => {
+		// Validate agent type
 		if (args.agent === "build") {
 			return JSON.stringify({
 				error:
-					"Cannot delegate to 'build' agent. Build is the orchestrator that uses this tool. Use subagents (explore, scout, review, planner, vision, looker) or rush instead.",
+					"Cannot delegate to 'build' agent. Build is the orchestrator. Use subagents instead.",
 			});
 		}
 
@@ -178,56 +203,61 @@ export const start = tool({
 			});
 		}
 
-		// Validate autoCloseBead - only allowed for safe agents
+		// Validate autoCloseBead
 		if (args.autoCloseBead && !SAFE_AUTOCLOSE_AGENTS.includes(args.agent)) {
 			return JSON.stringify({
-				error: `autoCloseBead not allowed for '${args.agent}' agent. Only safe for: ${SAFE_AUTOCLOSE_AGENTS.join(", ")}. Build agent must verify output from ${args.agent} before closing beads.`,
+				error: `autoCloseBead not allowed for '${args.agent}' agent. Only safe for: ${SAFE_AUTOCLOSE_AGENTS.join(", ")}`,
 			});
 		}
 
-		const client = createClient();
+		await ensureOutputDir();
+
 		const taskId = `bg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-		const title = args.title || `bg-${args.agent}-${Date.now()}`;
+		const title = args.title || `bg-${args.agent}-${taskId}`;
+		const outputFile = path.join(OUTPUT_DIR, `${taskId}.txt`);
 
 		try {
-			// Create child session linked to parent (build agent's session)
-			// This enables context inheritance from the main session
-			const session = await client.session.create({
-				body: {
+			// Create output file to capture stdout
+			const outFd = await fs.open(outputFile, "w");
+
+			// Spawn opencode run with the agent and prompt
+			// Using --format default for readable output (json is too verbose for collection)
+			const proc = spawn(
+				"opencode",
+				[
+					"run",
+					"--agent",
+					args.agent,
+					"--title",
 					title,
-					parentID: context.sessionID, // Link to parent session for context inheritance
+					"--format",
+					"default",
+					args.prompt,
+				],
+				{
+					detached: true, // Run independently of parent
+					stdio: ["ignore", outFd.fd, outFd.fd], // Redirect stdout/stderr to file
+					cwd: process.cwd(),
+					env: { ...process.env },
 				},
-			});
+			);
 
-			if (!session.data?.id) {
-				return JSON.stringify({ error: "Failed to create session" });
-			}
+			// Don't wait for completion - let it run in background
+			proc.unref();
 
-			// Fire the prompt (this returns immediately, session runs async)
-			// Use the agent field and AgentPartInput to properly route to the specified agent
-			await client.session.prompt({
-				path: { id: session.data.id },
-				body: {
-					agent: args.agent, // Specify agent type directly in body
-					parts: [
-						{
-							type: "agent" as const,
-							name: args.agent, // AgentPartInput triggers agent routing
-						},
-						{
-							type: "text" as const,
-							text: args.prompt,
-						},
-					],
-				},
-			});
+			// Close our handle to the output file (process keeps its own)
+			await outFd.close();
+
+			if (!proc.pid) {
+				return JSON.stringify({ error: "Failed to spawn opencode process" });
+			}
 
 			// Persist task info
 			const store = await loadTasks();
 			store.tasks[taskId] = {
 				taskId,
-				sessionId: session.data.id,
-				parentSessionId: context.sessionID,
+				pid: proc.pid,
+				outputFile,
 				agent: args.agent,
 				prompt: args.prompt,
 				started: Date.now(),
@@ -249,7 +279,7 @@ export const start = tool({
 
 			return JSON.stringify({
 				taskId,
-				sessionId: session.data.id,
+				pid: proc.pid,
 				agent: args.agent,
 				beadId: args.beadId,
 				status: "started",
@@ -266,7 +296,7 @@ export const start = tool({
 
 /**
  * Get output from a background task.
- * Retrieves the last assistant message from the child session.
+ * Reads the output file and checks if the process has completed.
  */
 export const output = tool({
 	description:
@@ -275,7 +305,6 @@ export const output = tool({
 		taskId: tool.schema.string().describe("Task ID from background_start"),
 	},
 	execute: async (args) => {
-		const client = createClient();
 		const store = await loadTasks();
 		const task = store.tasks[args.taskId];
 
@@ -287,54 +316,47 @@ export const output = tool({
 		}
 
 		try {
-			const messages = await client.session.messages({
-				path: { id: task.sessionId },
-			});
+			// Check if process is still running
+			const running = isProcessRunning(task.pid);
 
-			if (!messages.data?.length) {
-				return JSON.stringify({
-					taskId: args.taskId,
-					status: "running",
-					message: "No messages yet - task still initializing",
-				});
+			// Read output file
+			let output = "";
+			try {
+				output = await fs.readFile(task.outputFile, "utf-8");
+			} catch {
+				output = "(no output yet)";
 			}
 
-			// Find last assistant message
-			const assistantMessages = messages.data.filter(
-				(m) => m.info?.role === "assistant",
-			);
-
-			if (!assistantMessages.length) {
+			// If still running and no substantial output
+			if (running && output.length < 100) {
 				return JSON.stringify({
 					taskId: args.taskId,
+					agent: task.agent,
 					status: "running",
-					message: "Task running - no response yet",
+					message: "Task still running - no complete response yet",
+					partialOutput: output.slice(0, 500),
 				});
 			}
 
-			const lastMessage = assistantMessages[assistantMessages.length - 1];
-			const textParts = lastMessage.parts
-				?.filter((p) => p.type === "text")
-				.map((p) => p.text)
-				.join("\n");
-
-			// Update status
-			task.status = "completed";
-			await saveTasks(store);
+			// Process completed or has substantial output
+			if (!running) {
+				// Update status
+				task.status = output.length > 0 ? "completed" : "failed";
+				await saveTasks(store);
+			}
 
 			// Build result object
 			const result: Record<string, unknown> = {
 				taskId: args.taskId,
 				agent: task.agent,
-				status: "completed",
-				output: textParts || "(empty response)",
+				status: running ? "running" : task.status,
+				output: output || "(empty response)",
 			};
 
-			// Handle bead closing
-			if (task.beadId) {
+			// Handle bead closing (only if completed)
+			if (task.beadId && !running && task.status === "completed") {
 				result.beadId = task.beadId;
 
-				// Auto-close for safe agents (explore, scout)
 				if (task.autoCloseBead && SAFE_AUTOCLOSE_AGENTS.includes(task.agent)) {
 					const closeResult = await runBeadsCommand([
 						"close",
@@ -347,8 +369,7 @@ export const output = tool({
 						result.beadCloseError = closeResult.output;
 					}
 				} else {
-					// For unsafe agents or when autoClose not requested, remind to verify
-					result.beadAction = `VERIFY output, then run: bd close ${task.beadId} --reason "..." `;
+					result.beadAction = `VERIFY output, then run: bd close ${task.beadId} --reason "..."`;
 				}
 			}
 
@@ -364,8 +385,7 @@ export const output = tool({
 });
 
 /**
- * Cancel background tasks.
- * Aborts running sessions and cleans up task records.
+ * Cancel background tasks by killing the process.
  */
 export const cancel = tool({
 	description:
@@ -381,7 +401,6 @@ export const cancel = tool({
 			.describe("Specific task ID to cancel"),
 	},
 	execute: async (args) => {
-		const client = createClient();
 		const store = await loadTasks();
 		const cancelled: string[] = [];
 		const errors: string[] = [];
@@ -405,12 +424,24 @@ export const cancel = tool({
 
 		for (const task of tasksToCancel) {
 			try {
-				await client.session.abort({ path: { id: task.sessionId } });
+				// Kill the process and its children (negative PID kills process group)
+				try {
+					process.kill(-task.pid, "SIGTERM");
+				} catch {
+					// Try without process group
+					process.kill(task.pid, "SIGTERM");
+				}
 				task.status = "cancelled";
 				cancelled.push(task.taskId);
 			} catch (e) {
 				const error = e instanceof Error ? e.message : String(e);
-				errors.push(`${task.taskId}: ${error}`);
+				// Process might already be dead
+				if (error.includes("ESRCH")) {
+					task.status = "cancelled";
+					cancelled.push(task.taskId);
+				} else {
+					errors.push(`${task.taskId}: ${error}`);
+				}
 			}
 		}
 
@@ -433,7 +464,7 @@ export const list = tool({
 	description: "List all background tasks with their status.",
 	args: {
 		status: tool.schema
-			.enum(["running", "completed", "cancelled", "all"])
+			.enum(["running", "completed", "cancelled", "failed", "all"])
 			.optional()
 			.default("all")
 			.describe("Filter by status"),
@@ -442,6 +473,20 @@ export const list = tool({
 		const store = await loadTasks();
 		const tasks = Object.values(store.tasks);
 
+		// Update status of running tasks
+		for (const task of tasks) {
+			if (task.status === "running" && !isProcessRunning(task.pid)) {
+				// Process finished, check if it has output
+				try {
+					const output = await fs.readFile(task.outputFile, "utf-8");
+					task.status = output.length > 0 ? "completed" : "failed";
+				} catch {
+					task.status = "failed";
+				}
+			}
+		}
+		await saveTasks(store);
+
 		const filtered =
 			args.status === "all"
 				? tasks
@@ -453,8 +498,11 @@ export const list = tool({
 				taskId: t.taskId,
 				agent: t.agent,
 				status: t.status,
+				pid: t.pid,
 				started: new Date(t.started).toISOString(),
+				running: t.status === "running" ? isProcessRunning(t.pid) : false,
 				prompt: t.prompt.slice(0, 100) + (t.prompt.length > 100 ? "..." : ""),
+				beadId: t.beadId,
 			})),
 		});
 	},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.14.3",
+	"version": "0.14.5",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"type": "module",
 	"repository": {
@@ -34,23 +34,23 @@
 	},
 	"dependencies": {
 		"@clack/prompts": "^0.7.0",
-		"@opencode-ai/plugin": "^1.1.2",
-		"@opentui/core": "^0.1.69",
-		"@opentui/solid": "^0.1.69",
+		"@opencode-ai/plugin": "^1.1.12",
+		"@opentui/core": "^0.1.72",
+		"@opentui/solid": "^0.1.72",
 		"beads-village": "^1.3.3",
 		"cac": "^6.7.14",
 		"cli-table3": "^0.6.5",
 		"ora": "^9.0.0",
 		"picocolors": "^1.1.1",
 		"solid-js": "^1.9.10",
-		"zod": "^3.23.8"
+		"zod": "^3.25.76"
 	},
 	"devDependencies": {
 		"@beads/bd": "^0.29.0",
 		"@biomejs/biome": "^1.9.4",
 		"@types/bun": "latest",
-		"@types/node": "^22.10.1",
-		"typescript": "^5.7.2"
+		"@types/node": "^22.19.5",
+		"typescript": "^5.9.3"
 	},
 	"trustedDependencies": ["@beads/bd"]
 }

package/dist/template/.opencode/command/ralph-loop.md

@@ -1,97 +0,0 @@
----
-description: Start Ralph Wiggum autonomous loop for task completion
-argument-hint: "<task> [--prd <file>] [--max <iterations>] [--afk]"
-agent: build
----
-
-# Ralph Wiggum Loop
-
-You are starting a Ralph Wiggum autonomous loop. This pattern enables you to work autonomously on a task list until completion.
-
-## Task
-
-$ARGUMENTS
-
-## Setup
-
-1. **Start the loop** by calling the `ralph-start` tool:
-
-```typescript
-ralph -
-  start({
-    task: "$1",
-    prdFile: "$2" || null, // Optional: PRD.md, tasks.md, etc.
-    progressFile: "progress.txt",
-    maxIterations: 50,
-    mode: "hitl", // or "afk" for autonomous
-  });
-```
-
-2. **Create progress.txt** if it doesn't exist:
-
-```markdown
-# Progress Log
-
-## Session Started: [date]
-
-### Completed Tasks
-
-(none yet)
-
-### Notes for Next Iteration
-
-- Starting fresh
-```
-
-## Loop Behavior
-
-After each iteration, the loop will automatically:
-
-1. Check if you output `<promise>COMPLETE</promise>`
-2. If yes → Loop ends, success!
-3. If no → Send continuation prompt for next iteration
-4. Repeat until completion or max iterations
-
-## Your Instructions
-
-For each iteration:
-
-1. **Review** the PRD/task list and progress file
-2. **Choose** the highest-priority incomplete task (YOU decide, not first in list)
-3. **Implement** ONE feature only (small steps prevent context rot)
-4. **Validate** with feedback loops:
-   - `npm run typecheck` (must pass)
-   - `npm run test` (must pass)
-   - `npm run lint` (must pass)
-5. **Commit** if all pass
-6. **Update** progress.txt with:
-   - Task completed
-   - Key decisions made
-   - Files changed
-   - Notes for next iteration
-
-## Exit Conditions
-
-Output `<promise>COMPLETE</promise>` when:
-
-- ALL tasks in the PRD are complete
-- ALL feedback loops pass
-- Code is committed
-
-The loop will also stop if:
-
-- Max iterations reached
-- You call `ralph-stop` tool
-- An error occurs
-
-## Best Practices
-
-- **Small steps**: One feature per iteration
-- **Quality over speed**: Never skip tests
-- **Explicit scope**: Vague tasks loop forever
-- **Track progress**: Update progress.txt every iteration
-- **Prioritize risk**: Hard tasks first, easy wins last
-
-## Start Now
-
-Call `ralph-start` with the task description to begin the loop.

package/dist/template/.opencode/plugin/handoff.ts

@@ -1,37 +0,0 @@
-/**
- * OpenCode Handoff Plugin
- * Injects the most recent handoff file into session compaction
- *
- * Workflow:
- * 1. User creates handoff markdown file in .opencode/memory/handoffs/
- * 2. Session compaction (Ctrl+K) includes handoff context
- * 3. New session resumes from previous state
- */
-
-import type { Plugin } from "@opencode-ai/plugin";
-
-export const HandoffPlugin: Plugin = async ({ $, directory }) => {
-	const HANDOFF_DIR = `${directory}/.opencode/memory/handoffs`;
-
-	return {
-		"experimental.session.compacting": async (_input, output) => {
-			// Find most recent handoff file
-			const result =
-				await $`ls -t ${HANDOFF_DIR}/*.md 2>/dev/null | head -1`.quiet();
-
-			if (!result.stdout) return;
-
-			const handoffPath = result.stdout.toString().trim();
-			const handoffContent = await $`cat ${handoffPath}`.text();
-
-			// Inject into compaction context
-			output.context.push(`
-## Previous Session Handoff
-
-${handoffContent}
-
-**IMPORTANT**: Resume work from where previous session left off.
-`);
-		},
-	};
-};