opencodekit 0.15.10 → 0.15.11

package/dist/template/.opencode/tool/swarm-delegate.ts

@@ -0,0 +1,175 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin";
+
+function isSafePathSegment(value: string): boolean {
+	if (!value) return false;
+	if (value.includes("..")) return false;
+	if (value.includes("/")) return false;
+	if (value.includes("\\")) return false;
+	return true;
+}
+
+function sanitizeFilename(value: string): string {
+	const trimmed = value.trim();
+	if (!trimmed) return "delegation.md";
+	if (!isSafePathSegment(trimmed)) return "delegation.md";
+	return trimmed;
+}
+
+function splitList(input?: string): string[] {
+	if (!input) return [];
+	const parts = input
+		.split(/\r?\n|,/g)
+		.map((s) => s.trim())
+		.filter(Boolean);
+	return [...new Set(parts)];
+}
+
+function formatBullets(items: string[]): string {
+	if (items.length === 0) return "- (none)";
+	return items.map((i) => `- ${i}`).join("\n");
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export default tool({
+	description: `Generate a Swarm delegation packet (Beads-as-board).
+
+Purpose:
+- Creates a consistent delegation envelope for a specific Beads task
+- Optionally appends it to .beads/artifacts/<id>/delegation.md
+
+Example:
+swarm-delegate({
+  bead_id: "opencodekit-template-xyz",
+  title: "Add feature X",
+  expected_outcome: "Feature X works and tests pass",
+  required_tools: "read, grep, lsp, bash",
+  must_do: "LSP before edits, run project verification commands",
+  must_not_do: "no new deps, don't edit dist/",
+  acceptance_checks: "typecheck: <command>, lint: <command>, test: <command>",
+  context: "See .beads/artifacts/<id>/spec.md",
+  write: true
+})`,
+	args: {
+		bead_id: tool.schema
+			.string()
+			.describe("Beads issue id (e.g., opencodekit-template-abc)"),
+		title: tool.schema
+			.string()
+			.optional()
+			.describe("Optional title (defaults to Beads id only)"),
+		expected_outcome: tool.schema
+			.string()
+			.describe("Measurable end state for this task"),
+		required_tools: tool.schema
+			.string()
+			.optional()
+			.describe("Comma/newline-separated list of tools"),
+		must_do: tool.schema
+			.string()
+			.optional()
+			.describe("Comma/newline-separated MUST DO list"),
+		must_not_do: tool.schema
+			.string()
+			.optional()
+			.describe("Comma/newline-separated MUST NOT DO list"),
+		acceptance_checks: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Comma/newline-separated checks (prefer 'typecheck: <command>', 'lint: <command>', 'test: <command>')",
+			),
+		context: tool.schema
+			.string()
+			.optional()
+			.describe("Extra context pointers (files/links/notes)"),
+		write: tool.schema
+			.boolean()
+			.optional()
+			.describe("When true, append packet to task artifact file"),
+		output_file: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Artifact filename under .beads/artifacts/<id>/ (default: delegation.md)",
+			),
+	},
+	execute: async (args: {
+		bead_id: string;
+		title?: string;
+		expected_outcome: string;
+		required_tools?: string;
+		must_do?: string;
+		must_not_do?: string;
+		acceptance_checks?: string;
+		context?: string;
+		write?: boolean;
+		output_file?: string;
+	}) => {
+		const beadId = args.bead_id.trim();
+		if (!beadId) return "Error: bead_id is required.";
+		if (!isSafePathSegment(beadId)) {
+			return "Error: bead_id must be a single path segment (no slashes or '..').";
+		}
+
+		const title = args.title?.trim();
+		const taskLine = title ? `${beadId} - ${title}` : beadId;
+
+		const requiredTools = splitList(args.required_tools);
+		const mustDo = splitList(args.must_do);
+		const mustNotDo = splitList(args.must_not_do);
+		const acceptanceChecks = splitList(args.acceptance_checks);
+		const context = args.context?.trim();
+
+		const now = new Date();
+		const stamp = now.toISOString();
+
+		const packet = [
+			"# Delegation Packet",
+			"",
+			`- TASK: ${taskLine}`,
+			`- EXPECTED OUTCOME: ${args.expected_outcome.trim()}`,
+			"- REQUIRED TOOLS:",
+			formatBullets(requiredTools),
+			"- MUST DO:",
+			formatBullets(mustDo),
+			"- MUST NOT DO:",
+			formatBullets(mustNotDo),
+			"- ACCEPTANCE CHECKS:",
+			formatBullets(acceptanceChecks),
+			"- CONTEXT:",
+			context ? context : "(none)",
+		].join("\n");
+
+		if (!args.write) {
+			return `${packet}\n`;
+		}
+
+		const artifactDir = path.join(process.cwd(), ".beads", "artifacts", beadId);
+		const outName = sanitizeFilename(args.output_file || "delegation.md");
+		const outPath = path.join(artifactDir, outName);
+
+		const specPath = path.join(artifactDir, "spec.md");
+		const hasSpec = await fileExists(specPath);
+
+		await fs.mkdir(artifactDir, { recursive: true });
+
+		const header = `\n\n---\nGenerated: ${stamp}\n---\n\n`;
+		await fs.appendFile(outPath, `${header}${packet}\n`, "utf-8");
+
+		const specNote = hasSpec
+			? ""
+			: `\nWarning: spec.md not found at ${specPath}`;
+
+		return `✓ Delegation packet appended to ${outPath}${specNote}\n\n${packet}\n`;
+	},
+});

package/dist/template/.opencode/tool/swarm-helper.ts

@@ -0,0 +1,164 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin";
+
+export const SWARM_MAIL_FILE = ".beads/swarm-mail.jsonl";
+
+type BaseArgs = {
+	team_name: string;
+};
+
+type GetTeamStatusArgs = BaseArgs & {
+	limit?: number;
+};
+
+type SendTeamMessageArgs = BaseArgs & {
+	from_worker?: string;
+	to_worker?: string;
+	message: string;
+};
+
+export default tool({
+	description: `Swarm coordination helper.
+
+Operations:
+  - getTeamStatus: Read swarm mailbox for worker reports and progress
+  - sendTeamMessage: Write to swarm mailbox for coordination
+
+Pattern:
+  - Build agent orchestrates: parses plan → spawns team → monitors → synthesizes
+  - General agent executes: reads delegation packet → makes changes → reports back
+  - Coordination via mailbox: .beads/swarm-mail.jsonl (append-only log)
+
+Example:
+  getTeamStatus({ team_name: "plan-implementation" })
+  → Returns: worker_status for each worker (pending/working/done/error)
+
+  sendTeamMessage({
+    team_name: "plan-implementation",
+    from_worker: "worker-1",
+    to_worker: "worker-2",
+    message: "Need help with file locking",
+  })
+  → Appends JSONL line: { timestamp, from, to, message }
+
+`,
+	args: {
+		team_name: tool.schema
+			.string()
+			.describe("Team identifier (e.g., plan-implementation, auth-feature)"),
+		operation: tool.schema
+			.enum(["getTeamStatus", "sendTeamMessage"])
+			.describe("Which swarm coordination operation to perform"),
+		from_worker: tool.schema
+			.string()
+			.optional()
+			.describe("Sending worker name (sendTeamMessage)"),
+		to_worker: tool.schema
+			.string()
+			.optional()
+			.describe("Target worker name (sendTeamMessage)"),
+		message: tool.schema
+			.string()
+			.optional()
+			.describe("Message content (sendTeamMessage)"),
+		limit: tool.schema
+			.number()
+			.optional()
+			.describe("Limit mailbox entries (getTeamStatus)"),
+	},
+	execute: async (args) => {
+		const operation = args.operation as string;
+
+		if (operation === "getTeamStatus") {
+			const result = await getTeamStatus(args as any);
+			return result;
+		}
+
+		if (operation === "sendTeamMessage") {
+			const result = await sendTeamMessage(args as any);
+			return result;
+		}
+
+		return `Error: Unknown operation: ${operation}. Valid: getTeamStatus, sendTeamMessage`;
+	},
+});
+
+async function getTeamStatus(args: GetTeamStatusArgs) {
+	const { team_name, limit } = args;
+
+	if (!team_name) {
+		return "Error: team_name is required.";
+	}
+
+	const mailPath = path.join(process.cwd(), SWARM_MAIL_FILE);
+	let lines: string[];
+
+	try {
+		const content = await fs.readFile(mailPath, "utf-8");
+		lines = content.trim().split("\n").filter(Boolean);
+	} catch {
+		return `Error: Failed to read ${SWARM_MAIL_FILE}.`;
+	}
+
+	const team_messages = lines
+		.map((line) => {
+			try {
+				return JSON.parse(line) as {
+					timestamp: string;
+					team_name: string;
+					from_worker?: string;
+					to_worker?: string;
+					message?: string;
+					status?: string;
+				};
+			} catch {
+				return null;
+			}
+		})
+		.filter(Boolean);
+
+	const relevant = team_messages.filter((m) => m.team_name === team_name);
+
+	if (limit && limit > 0) {
+		return JSON.stringify(relevant.slice(-limit), null, 2);
+	}
+
+	return JSON.stringify(relevant, null, 2);
+}
+
+async function sendTeamMessage(args: SendTeamMessageArgs) {
+	const { team_name, from_worker, to_worker, message } = args;
+
+	if (!team_name || !message) {
+		return "Error: team_name and message are required.";
+	}
+
+	const mailPath = path.join(process.cwd(), SWARM_MAIL_FILE);
+	const entry = {
+		timestamp: new Date().toISOString(),
+		team_name,
+		from_worker: from_worker || "system",
+		to_worker: to_worker || "all",
+		message,
+		status: "unread",
+	};
+
+	try {
+		await fs.appendFile(mailPath, `${JSON.stringify(entry)}\n`, "utf-8");
+		return JSON.stringify(
+			{
+				success: true,
+				team_name,
+				from_worker,
+				to_worker,
+				message,
+				mail_file: SWARM_MAIL_FILE,
+			},
+			null,
+			2,
+		);
+	} catch (error: any) {
+		return `Error: Failed to write to ${SWARM_MAIL_FILE}: ${error}`;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.15.10",
+	"version": "0.15.11",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",