opencodekit 0.14.1 → 0.14.2

package/dist/template/.opencode/plugin/ralph-wiggum.ts

@@ -0,0 +1,182 @@
+/**
+ * Ralph Wiggum Plugin for OpenCode
+ *
+ * Handles the session.idle event to continue the Ralph loop.
+ * Tools are defined separately in .opencode/tool/ralph.ts
+ *
+ * Based on: https://ghuntley.com/ralph/
+ */
+
+import fs from "node:fs/promises";
+import type { Plugin } from "@opencode-ai/plugin";
+
+const STATE_FILE = ".opencode/.ralph-state.json";
+const IDLE_DEBOUNCE_MS = 2000;
+let lastIdleTime = 0;
+
+interface RalphState {
+	active: boolean;
+	sessionID: string | null;
+	iteration: number;
+	maxIterations: number;
+	completionPromise: string;
+	task: string;
+	prdFile: string | null;
+	progressFile: string;
+	startedAt: number | null;
+	mode: "hitl" | "afk";
+}
+
+async function loadState(): Promise<RalphState | null> {
+	try {
+		const content = await fs.readFile(STATE_FILE, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return null;
+	}
+}
+
+async function saveState(state: RalphState): Promise<void> {
+	await fs.writeFile(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+async function resetState(): Promise<void> {
+	try {
+		await fs.unlink(STATE_FILE);
+	} catch {
+		// File doesn't exist, that's fine
+	}
+}
+
+export const RalphWiggum: Plugin = async ({ client }) => {
+	const log = async (
+		message: string,
+		level: "info" | "warn" | "error" = "info",
+	) => {
+		await client.app
+			.log({
+				body: { service: "ralph-wiggum", level, message },
+			})
+			.catch(() => {});
+	};
+
+	const showToast = async (
+		title: string,
+		message: string,
+		variant: "info" | "success" | "warning" | "error" = "info",
+	) => {
+		await client.tui
+			.showToast({
+				body: {
+					title: `Ralph: ${title}`,
+					message,
+					variant,
+					duration: variant === "error" ? 8000 : 5000,
+				},
+			})
+			.catch(() => {});
+	};
+
+	const buildContinuationPrompt = (state: RalphState): string => {
+		const prdRef = state.prdFile ? `@${state.prdFile} ` : "";
+		const progressRef = `@${state.progressFile}`;
+
+		return `
+${prdRef}${progressRef}
+
+## Ralph Wiggum Loop - Iteration ${state.iteration}/${state.maxIterations}
+
+You are in an autonomous loop. Continue working on the task.
+
+**Task:** ${state.task}
+
+**Instructions:**
+1. Review the PRD/task list and progress file
+2. Choose the highest-priority INCOMPLETE task
+3. Implement ONE feature/change only
+4. Run feedback loops: typecheck, test, lint
+5. Commit if all pass
+6. Update ${state.progressFile}
+7. If ALL tasks complete, output: ${state.completionPromise}
+
+**Constraints:** ONE feature per iteration. Quality over speed.
+`.trim();
+	};
+
+	const handleSessionIdle = async (sessionID: string): Promise<void> => {
+		const now = Date.now();
+		if (now - lastIdleTime < IDLE_DEBOUNCE_MS) return;
+		lastIdleTime = now;
+
+		const state = await loadState();
+		if (!state?.active || state.sessionID !== sessionID) return;
+
+		try {
+			const messagesResponse = await client.session.messages({
+				path: { id: sessionID },
+			});
+			const messages = messagesResponse.data || [];
+			const lastMessage = messages[messages.length - 1];
+
+			const lastText =
+				lastMessage?.parts
+					?.filter((p) => p.type === "text")
+					.map((p) => ("text" in p ? (p.text as string) : ""))
+					.join("") || "";
+
+			if (lastText.includes(state.completionPromise)) {
+				const duration = state.startedAt
+					? Math.round((Date.now() - state.startedAt) / 1000 / 60)
+					: 0;
+				await showToast(
+					"Complete!",
+					`Finished in ${state.iteration} iterations (${duration} min)`,
+					"success",
+				);
+				await log(`Loop completed in ${state.iteration} iterations`);
+				await resetState();
+				return;
+			}
+
+			state.iteration++;
+			if (state.iteration >= state.maxIterations) {
+				await showToast(
+					"Stopped",
+					`Max iterations (${state.maxIterations}) reached`,
+					"warning",
+				);
+				await log(`Max iterations reached: ${state.maxIterations}`, "warn");
+				await resetState();
+				return;
+			}
+
+			await saveState(state);
+
+			await client.session.prompt({
+				path: { id: sessionID },
+				body: {
+					parts: [{ type: "text", text: buildContinuationPrompt(state) }],
+				},
+			});
+
+			await log(`Iteration ${state.iteration}/${state.maxIterations}`);
+		} catch (error) {
+			await log(`Error in Ralph loop: ${error}`, "error");
+			await resetState();
+		}
+	};
+
+	return {
+		event: async ({ event }) => {
+			if (event.type === "session.idle") {
+				const sessionID = (event as { properties?: { sessionID?: string } })
+					.properties?.sessionID;
+				if (sessionID) {
+					await handleSessionIdle(sessionID);
+				}
+			}
+		},
+	};
+};
+
+export default RalphWiggum;

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

@@ -0,0 +1,461 @@
+import { execSync } 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";
+
+interface BackgroundTask {
+	taskId: string;
+	sessionId: string;
+	parentSessionId: string; // Track parent for debugging
+	agent: string;
+	prompt: string;
+	started: number;
+	status: "running" | "completed" | "cancelled";
+	// Beads integration
+	beadId?: string;
+	autoCloseBead?: boolean; // Only allowed for safe agents (explore, scout)
+}
+
+interface TasksStore {
+	tasks: Record<string, BackgroundTask>;
+}
+
+async function loadTasks(): Promise<TasksStore> {
+	try {
+		const content = await fs.readFile(TASKS_FILE, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return { tasks: {} };
+	}
+}
+
+async function saveTasks(store: TasksStore): Promise<void> {
+	await fs.mkdir(path.dirname(TASKS_FILE), { recursive: true });
+	await fs.writeFile(TASKS_FILE, JSON.stringify(store, null, 2));
+}
+
+function createClient() {
+	return createOpencodeClient({ baseUrl: "http://localhost:4096" });
+}
+
+/**
+ * Find the bd binary path dynamically
+ */
+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,
+			shell: "/bin/sh",
+		}).trim();
+		if (result) return result;
+	} catch {
+		// Fallback to common locations
+		const commonPaths = [
+			`${process.env.HOME}/.local/bin/bd`,
+			`${process.env.HOME}/.bun/bin/bd`,
+			"/usr/local/bin/bd",
+			"/opt/homebrew/bin/bd",
+		];
+		for (const p of commonPaths) {
+			try {
+				execSync(`test -x "${p}"`, { timeout: 1000 });
+				return p;
+			} catch {
+				continue;
+			}
+		}
+	}
+	// Last resort - assume it's in PATH
+	return "bd";
+}
+
+// Cache the bd path
+let bdPath: string | null = null;
+function getBdPath(): string {
+	if (!bdPath) {
+		bdPath = findBdPath();
+	}
+	return bdPath;
+}
+
+/**
+ * Helper to run beads CLI commands
+ */
+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,
+			shell: "/bin/sh",
+			env: { ...process.env },
+		});
+		return { success: true, output };
+	} catch (e) {
+		const error = e as { stderr?: string; message?: string };
+		return {
+			success: false,
+			output: error.stderr || error.message || String(e),
+		};
+	}
+}
+
+// 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",
+	"review",
+	"planner",
+	"vision",
+	"looker",
+	"rush",
+] as const;
+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",
+	"looker",
+] as const;
+
+/**
+ * Start a background subagent task.
+ * Creates a child session that runs independently.
+ */
+export const start = tool({
+	description:
+		"Start a background subagent task. Returns a task_id to collect results later. Use for parallel research/exploration or executing beads subtasks. NOTE: Cannot delegate to 'build' agent (build is the orchestrator).",
+	args: {
+		agent: tool.schema
+			.string()
+			.describe(
+				"Agent type: explore, scout, review, planner, vision, looker, rush (NOT build - build is the orchestrator)",
+			),
+		prompt: tool.schema.string().describe("Task prompt for the agent"),
+		title: tool.schema
+			.string()
+			.optional()
+			.describe("Optional task title for identification"),
+		beadId: tool.schema
+			.string()
+			.optional()
+			.describe("Bead ID to associate with this task (e.g., bd-abc123)"),
+		autoCloseBead: tool.schema
+			.boolean()
+			.optional()
+			.describe(
+				"Auto-close bead on completion. Only allowed for safe agents (explore, scout). Blocked for rush/review/planner/vision/looker.",
+			),
+	},
+	execute: async (args, context) => {
+		// Validate agent type - build cannot delegate to itself
+		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.",
+			});
+		}
+
+		if (!ALLOWED_AGENTS.includes(args.agent as AllowedAgent)) {
+			return JSON.stringify({
+				error: `Invalid agent type: ${args.agent}. Allowed: ${ALLOWED_AGENTS.join(", ")}`,
+			});
+		}
+
+		// Validate autoCloseBead - only allowed for safe agents
+		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.`,
+			});
+		}
+
+		const client = createClient();
+		const taskId = `bg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+		const title = args.title || `bg-${args.agent}-${Date.now()}`;
+
+		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: {
+					title,
+					parentID: context.sessionID, // Link to parent session for context inheritance
+				},
+			});
+
+			if (!session.data?.id) {
+				return JSON.stringify({ error: "Failed to create session" });
+			}
+
+			// 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,
+						},
+					],
+				},
+			});
+
+			// Persist task info
+			const store = await loadTasks();
+			store.tasks[taskId] = {
+				taskId,
+				sessionId: session.data.id,
+				parentSessionId: context.sessionID,
+				agent: args.agent,
+				prompt: args.prompt,
+				started: Date.now(),
+				status: "running",
+				beadId: args.beadId,
+				autoCloseBead: args.autoCloseBead,
+			};
+			await saveTasks(store);
+
+			// If beadId provided, mark it as in_progress
+			if (args.beadId) {
+				await runBeadsCommand([
+					"update",
+					args.beadId,
+					"--status",
+					"in_progress",
+				]);
+			}
+
+			return JSON.stringify({
+				taskId,
+				sessionId: session.data.id,
+				agent: args.agent,
+				beadId: args.beadId,
+				status: "started",
+				message: `Background task started. Use background_output(taskId="${taskId}") to get results.`,
+			});
+		} catch (e) {
+			const error = e instanceof Error ? e.message : String(e);
+			return JSON.stringify({
+				error: `Failed to start background task: ${error}`,
+			});
+		}
+	},
+});
+
+/**
+ * Get output from a background task.
+ * Retrieves the last assistant message from the child session.
+ */
+export const output = tool({
+	description:
+		"Get output from a background task. Returns the agent's response or 'still running' if not complete.",
+	args: {
+		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];
+
+		if (!task) {
+			return JSON.stringify({
+				error: `Task not found: ${args.taskId}`,
+				availableTasks: Object.keys(store.tasks),
+			});
+		}
+
+		try {
+			const messages = await client.session.messages({
+				path: { id: task.sessionId },
+			});
+
+			if (!messages.data?.length) {
+				return JSON.stringify({
+					taskId: args.taskId,
+					status: "running",
+					message: "No messages yet - task still initializing",
+				});
+			}
+
+			// Find last assistant message
+			const assistantMessages = messages.data.filter(
+				(m) => m.info?.role === "assistant",
+			);
+
+			if (!assistantMessages.length) {
+				return JSON.stringify({
+					taskId: args.taskId,
+					status: "running",
+					message: "Task running - no response yet",
+				});
+			}
+
+			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);
+
+			// Build result object
+			const result: Record<string, unknown> = {
+				taskId: args.taskId,
+				agent: task.agent,
+				status: "completed",
+				output: textParts || "(empty response)",
+			};
+
+			// Handle bead closing
+			if (task.beadId) {
+				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",
+						task.beadId,
+						"--reason",
+						`Auto-closed: ${task.agent} task completed (${task.taskId})`,
+					]);
+					result.beadClosed = closeResult.success;
+					if (!closeResult.success) {
+						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 "..." `;
+				}
+			}
+
+			return JSON.stringify(result);
+		} catch (e) {
+			const error = e instanceof Error ? e.message : String(e);
+			return JSON.stringify({
+				taskId: args.taskId,
+				error: `Failed to get output: ${error}`,
+			});
+		}
+	},
+});
+
+/**
+ * Cancel background tasks.
+ * Aborts running sessions and cleans up task records.
+ */
+export const cancel = tool({
+	description:
+		"Cancel background tasks. Use all=true to cancel all, or specify taskId.",
+	args: {
+		all: tool.schema
+			.boolean()
+			.optional()
+			.describe("Cancel all background tasks"),
+		taskId: tool.schema
+			.string()
+			.optional()
+			.describe("Specific task ID to cancel"),
+	},
+	execute: async (args) => {
+		const client = createClient();
+		const store = await loadTasks();
+		const cancelled: string[] = [];
+		const errors: string[] = [];
+
+		const tasksToCancel = args.all
+			? Object.values(store.tasks).filter((t) => t.status === "running")
+			: args.taskId && store.tasks[args.taskId]
+				? [store.tasks[args.taskId]]
+				: [];
+
+		if (!tasksToCancel.length) {
+			return JSON.stringify({
+				message: args.all
+					? "No running tasks to cancel"
+					: `Task not found: ${args.taskId}`,
+				activeTasks: Object.values(store.tasks)
+					.filter((t) => t.status === "running")
+					.map((t) => t.taskId),
+			});
+		}
+
+		for (const task of tasksToCancel) {
+			try {
+				await client.session.abort({ path: { id: task.sessionId } });
+				task.status = "cancelled";
+				cancelled.push(task.taskId);
+			} catch (e) {
+				const error = e instanceof Error ? e.message : String(e);
+				errors.push(`${task.taskId}: ${error}`);
+			}
+		}
+
+		await saveTasks(store);
+
+		return JSON.stringify({
+			cancelled,
+			errors: errors.length ? errors : undefined,
+			remaining: Object.values(store.tasks)
+				.filter((t) => t.status === "running")
+				.map((t) => t.taskId),
+		});
+	},
+});
+
+/**
+ * List all background tasks with their status.
+ */
+export const list = tool({
+	description: "List all background tasks with their status.",
+	args: {
+		status: tool.schema
+			.enum(["running", "completed", "cancelled", "all"])
+			.optional()
+			.default("all")
+			.describe("Filter by status"),
+	},
+	execute: async (args) => {
+		const store = await loadTasks();
+		const tasks = Object.values(store.tasks);
+
+		const filtered =
+			args.status === "all"
+				? tasks
+				: tasks.filter((t) => t.status === args.status);
+
+		return JSON.stringify({
+			total: filtered.length,
+			tasks: filtered.map((t) => ({
+				taskId: t.taskId,
+				agent: t.agent,
+				status: t.status,
+				started: new Date(t.started).toISOString(),
+				prompt: t.prompt.slice(0, 100) + (t.prompt.length > 100 ? "..." : ""),
+			})),
+		});
+	},
+});