opencodekit 0.14.1 → 0.14.3

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 {
+				// Try next path
+			}
+		}
+	}
+	// 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 ? "..." : ""),
+			})),
+		});
+	},
+});

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

@@ -0,0 +1,203 @@
+/**
+ * Ralph Wiggum Tools
+ *
+ * Standalone tools for the Ralph Wiggum autonomous loop pattern.
+ * The plugin (ralph-wiggum.ts) handles event listening, these handle user interaction.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin";
+
+const STATE_FILE = ".opencode/.ralph-state.json";
+
+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";
+}
+
+const DEFAULT_STATE: RalphState = {
+	active: false,
+	sessionID: null,
+	iteration: 0,
+	maxIterations: 50,
+	completionPromise: "<promise>COMPLETE</promise>",
+	task: "",
+	prdFile: null,
+	progressFile: "progress.txt",
+	startedAt: null,
+	mode: "hitl",
+};
+
+async function loadState(): Promise<RalphState> {
+	try {
+		const content = await fs.readFile(STATE_FILE, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return { ...DEFAULT_STATE };
+	}
+}
+
+async function saveState(state: RalphState): Promise<void> {
+	await fs.mkdir(path.dirname(STATE_FILE), { recursive: true });
+	await fs.writeFile(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Start Ralph Wiggum autonomous loop
+ */
+export const ralph_start = tool({
+	description:
+		"Start Ralph Wiggum autonomous loop. Agent will work on tasks until completion or max iterations.",
+	args: {
+		task: tool.schema
+			.string()
+			.describe(
+				"Task description or goal (e.g., 'Migrate all Jest tests to Vitest')",
+			),
+		prdFile: tool.schema
+			.string()
+			.optional()
+			.describe("Path to PRD/task list file (e.g., 'PRD.md')"),
+		progressFile: tool.schema
+			.string()
+			.optional()
+			.describe("Path to progress tracking file (default: progress.txt)"),
+		completionPromise: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Text to output when done (default: <promise>COMPLETE</promise>)",
+			),
+		maxIterations: tool.schema
+			.number()
+			.optional()
+			.describe("Maximum iterations before stopping (default: 50)"),
+		mode: tool.schema
+			.enum(["hitl", "afk"])
+			.optional()
+			.describe("Mode: hitl (human-in-the-loop) or afk (away-from-keyboard)"),
+	},
+	execute: async (args, context) => {
+		const state: RalphState = {
+			active: true,
+			sessionID: context.sessionID,
+			iteration: 0,
+			maxIterations: args.maxIterations || 50,
+			completionPromise:
+				args.completionPromise || "<promise>COMPLETE</promise>",
+			task: args.task,
+			prdFile: args.prdFile || null,
+			progressFile: args.progressFile || "progress.txt",
+			startedAt: Date.now(),
+			mode: args.mode || "hitl",
+		};
+
+		await saveState(state);
+
+		const modeDesc =
+			state.mode === "hitl"
+				? "Human-in-the-loop (watch and intervene)"
+				: "Away-from-keyboard (autonomous)";
+
+		return `
+## Ralph Loop Active
+
+**Task:** ${state.task}
+**Mode:** ${modeDesc}
+**Max Iterations:** ${state.maxIterations}
+**Completion Signal:** ${state.completionPromise}
+**PRD File:** ${state.prdFile || "(none - using task description)"}
+**Progress File:** ${state.progressFile}
+
+### Next Steps
+
+1. Work on the task described above
+2. After each feature, update ${state.progressFile}
+3. Run feedback loops (typecheck, test, lint)
+4. Commit changes
+5. When ALL tasks complete, output: ${state.completionPromise}
+
+The loop will continue automatically after each completion until:
+- You output the completion promise, OR
+- Max iterations (${state.maxIterations}) reached
+
+**Remember:** ONE feature per iteration. Small steps. Quality over speed.
+`.trim();
+	},
+});
+
+/**
+ * Stop Ralph Wiggum loop
+ */
+export const ralph_stop = tool({
+	description: "Stop the Ralph Wiggum loop gracefully",
+	args: {
+		reason: tool.schema.string().optional().describe("Reason for stopping"),
+	},
+	execute: async (args) => {
+		const state = await loadState();
+
+		if (!state.active) {
+			return "No Ralph loop is currently running.";
+		}
+
+		const duration = state.startedAt
+			? Math.round((Date.now() - state.startedAt) / 1000 / 60)
+			: 0;
+
+		const summary = `
+## Ralph Loop Stopped
+
+**Iterations Completed:** ${state.iteration}
+**Duration:** ${duration} minutes
+**Reason:** ${args.reason || "Manual stop requested"}
+**Task:** ${state.task}
+
+Progress has been saved to ${state.progressFile}.
+`.trim();
+
+		// Reset state
+		await saveState(DEFAULT_STATE);
+
+		return summary;
+	},
+});
+
+/**
+ * Get Ralph Wiggum status
+ */
+export const ralph_status = tool({
+	description: "Get current Ralph Wiggum loop status",
+	args: {},
+	execute: async () => {
+		const state = await loadState();
+
+		if (!state.active) {
+			return "No Ralph loop is currently active.";
+		}
+
+		const duration = state.startedAt
+			? Math.round((Date.now() - state.startedAt) / 1000 / 60)
+			: 0;
+
+		return `
+## Ralph Loop Active
+
+**Task:** ${state.task}
+**Iteration:** ${state.iteration}/${state.maxIterations}
+**Duration:** ${duration} minutes
+**Mode:** ${state.mode}
+**Completion Signal:** ${state.completionPromise}
+**Progress File:** ${state.progressFile}
+`.trim();
+	},
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.14.1",
+	"version": "0.14.3",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"type": "module",
 	"repository": {