@kortix/sandbox 0.4.1

package/opencode/patches/opencode-pty-spawn.txt

@@ -0,0 +1,49 @@
+Spawns a new interactive PTY (pseudo-terminal) session that runs in the background.
+
+Unlike the built-in bash tool which runs commands synchronously and waits for completion, PTY sessions persist and allow you to:
+- Run long-running processes (dev servers, watch modes, etc.)
+- Send interactive input (including Ctrl+C, arrow keys, etc.)
+- Read output at any time
+- Manage multiple concurrent terminal sessions
+
+Usage:
+- The `command` parameter is required (e.g., "npm", "python", "bash")
+- Use `args` to pass arguments to the command (e.g., ["run", "dev"])
+- Use `workdir` to set the working directory (defaults to project root)
+- Use `env` to set additional environment variables
+- Use `title` to give the session a human-readable name
+- The `description` parameter is required: a clear, concise 5-10 word description
+- Use `notifyOnExit` to receive a notification when the process exits (default: false)
+
+Returns the session info including:
+- `id`: Unique identifier (pty_XXXXXXXX) for use with other pty_* tools
+- `pid`: Process ID
+- `status`: Current status ("running")
+
+After spawning, use:
+- `pty_write` to send input to the PTY
+- `pty_read` to read output from the PTY
+- `pty_list` to see all active PTY sessions
+- `pty_kill` to terminate the PTY
+
+Exit Notifications:
+When `notifyOnExit` is true, you will receive a message when the process exits containing:
+- Session ID and title
+- Exit code
+- Total output lines
+- Last line of output (truncated to 250 chars)
+
+This is useful for long-running processes where you want to be notified when they complete
+instead of polling with `pty_read`. If the process fails (non-zero exit code), the notification
+will suggest using `pty_read` with the `pattern` parameter to search for errors.
+
+Examples:
+- Start a dev server: command="npm", args=["run", "dev"], title="Dev Server"
+- Start a Python REPL: command="python3", title="Python REPL"
+- Run tests in watch mode: command="npm", args=["test", "--", "--watch"]
+- Run build with notification: command="npm", args=["run", "build"], notifyOnExit=true
+
+IMPORTANT — Anti-patterns to avoid:
+- NEVER prepend `sleep N &&` to commands in PTY. PTY sessions are already async — sleep just adds dead time before the command even starts. Run the command directly.
+- NEVER use `sleep` for synchronization. Use notifyOnExit=true and wait for the <pty_exited> notification, or chain commands with && in the synchronous bash tool.
+- NEVER wrap simple one-shot commands in PTY. Use the bash tool for commands that complete quickly (<2 min). PTY is for long-running/interactive processes only.

package/opencode/plugin/background-agents.ts.disabled

@@ -0,0 +1,483 @@
+/**
+ * background-agents — Async delegation plugin for OpenCode
+ *
+ * Provides fire-and-forget background delegation to any agent.
+ * Results persist in memory, survive context compaction, and
+ * automatically notify the parent session on completion.
+ *
+ * Tools:
+ *   delegate(prompt, agent, title?)    — Launch a background task
+ *   delegation_read(id)                — Retrieve full result
+ *   delegation_list()                  — List all delegations
+ *
+ * Hooks:
+ *   event(session.idle)                — Detect child completion, notify parent
+ *   experimental.session.compacting    — Inject delegation state for compaction survival
+ */
+
+import { type Plugin, tool } from "@opencode-ai/plugin";
+import type { Event } from "@opencode-ai/sdk";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+interface Delegation {
+  id: string;
+  sessionID: string;
+  parentSessionID: string;
+  parentAgent: string;
+  prompt: string;
+  agent: string;
+  title: string;
+  status: "running" | "complete" | "error" | "timeout";
+  startedAt: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+}
+
+interface SessionMessageItem {
+  info: { id: string; role: string; sessionID: string };
+  parts: Array<{ type: string; text?: string; tool?: string }>;
+}
+
+// ── State ────────────────────────────────────────────────────────────────────
+
+const delegations = new Map<string, Delegation>();
+let counter = 0;
+
+function nextId(): string {
+  return `d-${++counter}`;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remaining = seconds % 60;
+  return `${minutes}m ${remaining}s`;
+}
+
+/**
+ * Extract the last assistant text from a session's messages.
+ */
+function extractLastAssistantText(
+  messages: SessionMessageItem[],
+): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]!;
+    if (msg.info.role !== "assistant") continue;
+
+    const textParts = msg.parts
+      .filter((p) => p.type === "text" && p.text)
+      .map((p) => p.text!)
+      .join("\n");
+
+    if (textParts.length > 0) return textParts;
+  }
+  return "";
+}
+
+/**
+ * Find a delegation by its child session ID.
+ */
+function findBySessionID(sessionID: string): Delegation | undefined {
+  for (const d of delegations.values()) {
+    if (d.sessionID === sessionID) return d;
+  }
+  return undefined;
+}
+
+/**
+ * Find all delegations belonging to a parent session (or its root).
+ */
+function findByParent(parentSessionID: string): Delegation[] {
+  return Array.from(delegations.values()).filter(
+    (d) => d.parentSessionID === parentSessionID,
+  );
+}
+
+// ── Plugin ───────────────────────────────────────────────────────────────────
+
+const MAX_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
+
+export const BackgroundAgentsPlugin: Plugin = async ({ client }) => {
+  // Track sessions we've already notified about to avoid duplicates
+  const notified = new Set<string>();
+
+  // ── Completion handler ─────────────────────────────────────────────────
+
+  async function handleCompletion(delegation: Delegation): Promise<void> {
+    if (notified.has(delegation.id)) return;
+    notified.add(delegation.id);
+
+    try {
+      // Read messages from child session
+      const messagesResult = await client.session.messages({
+        path: { id: delegation.sessionID },
+      });
+
+      const messages = (messagesResult.data ?? []) as SessionMessageItem[];
+      const lastText = extractLastAssistantText(messages);
+
+      delegation.status = "complete";
+      delegation.completedAt = Date.now();
+      delegation.result = lastText || "(No output produced)";
+
+      // Build notification for parent
+      const duration = formatDuration(
+        delegation.completedAt - delegation.startedAt,
+      );
+      const resultPreview =
+        delegation.result.length > 1000
+          ? delegation.result.slice(0, 1000) + "\n\n[...truncated — use delegation_read for full output]"
+          : delegation.result;
+
+      const notification = [
+        "<delegation_completed>",
+        `Delegation: ${delegation.id}`,
+        `Title: ${delegation.title}`,
+        `Agent: ${delegation.agent}`,
+        `Duration: ${duration}`,
+        "",
+        `Result:`,
+        resultPreview,
+        "</delegation_completed>",
+        "",
+        `A background delegation just completed. Review the result above and inform the user. Use delegation_read("${delegation.id}") if you need the full untruncated output.`,
+      ].join("\n");
+
+      // Send notification into the parent session
+      await client.session.promptAsync({
+        path: { id: delegation.parentSessionID },
+        body: {
+          agent: delegation.parentAgent,
+          parts: [{ type: "text", text: notification }],
+        },
+      });
+    } catch (e) {
+      delegation.status = "error";
+      delegation.completedAt = Date.now();
+      delegation.error = e instanceof Error ? e.message : String(e);
+    }
+  }
+
+  // ── Tools ──────────────────────────────────────────────────────────────
+
+  const delegateTool = tool({
+    description:
+      "Delegate a task to a background agent. Returns immediately — the agent " +
+      "runs asynchronously. You will be automatically notified via a " +
+      "<delegation_completed> message when it finishes. Use delegation_read(id) " +
+      "to retrieve the full result if it was truncated or lost during compaction.\n\n" +
+      "Available agents: kortix-main, kortix-research, kortix-web-dev, " +
+      "kortix-browser, kortix-slides, kortix-image-gen, kortix-sheets.\n\n" +
+      "Write a clear, self-contained prompt — the agent starts with zero context.",
+    args: {
+      prompt: tool.schema
+        .string()
+        .describe(
+          "The full prompt for the background agent. Must be self-contained — " +
+            "include all context, constraints, and desired output location.",
+        ),
+      agent: tool.schema
+        .string()
+        .describe(
+          "Agent to delegate to. Options: 'kortix-main' (general), " +
+            "'kortix-research' (deep research), 'kortix-web-dev' (web apps), " +
+            "'kortix-browser' (browser automation), 'kortix-slides' (presentations), " +
+            "'kortix-image-gen' (images), 'kortix-sheets' (spreadsheets).",
+        ),
+      title: tool.schema
+        .string()
+        .optional()
+        .describe(
+          "Short title for the delegation (e.g. 'OAuth2 research', 'Landing page build'). " +
+            "Defaults to the agent name.",
+        ),
+    },
+    async execute(args, context) {
+      const id = nextId();
+      const title = args.title || `${args.agent} task`;
+
+      try {
+        // Create child session linked to parent via parentID
+        const sessionResult = await client.session.create({
+          body: {
+            parentID: context.sessionID,
+            title: `[${id}] ${title}`,
+          },
+        });
+
+        const childSessionID = (sessionResult.data as { id: string })?.id;
+        if (!childSessionID) {
+          return JSON.stringify({
+            error: "Failed to create child session",
+          });
+        }
+
+        // Store delegation
+        const delegation: Delegation = {
+          id,
+          sessionID: childSessionID,
+          parentSessionID: context.sessionID,
+          parentAgent: context.agent,
+          prompt: args.prompt,
+          agent: args.agent,
+          title,
+          status: "running",
+          startedAt: Date.now(),
+        };
+        delegations.set(id, delegation);
+
+        // Fire the prompt asynchronously
+        await client.session.promptAsync({
+          path: { id: childSessionID },
+          body: {
+            agent: args.agent,
+            parts: [{ type: "text", text: args.prompt }],
+          },
+        });
+
+        // Set timeout safety net
+        setTimeout(async () => {
+          if (delegation.status === "running") {
+            delegation.status = "timeout";
+            delegation.completedAt = Date.now();
+            delegation.error = `Timed out after ${MAX_TIMEOUT_MS / 1000}s`;
+
+            // Try to abort
+            try {
+              await client.session.abort({
+                path: { id: childSessionID },
+              });
+            } catch {}
+
+            // Notify parent about timeout
+            await client.session.promptAsync({
+              path: { id: delegation.parentSessionID },
+              body: {
+                agent: delegation.parentAgent,
+                parts: [
+                  {
+                    type: "text",
+                    text: `<delegation_timeout>\nDelegation ${id} ("${title}") timed out after ${MAX_TIMEOUT_MS / 1000}s.\nAgent: ${args.agent}\n</delegation_timeout>`,
+                  },
+                ],
+              },
+            });
+          }
+        }, MAX_TIMEOUT_MS);
+
+        context.metadata({ title: `Delegated: ${title}` });
+
+        return [
+          `Delegation ${id} started.`,
+          `Title: ${title}`,
+          `Agent: ${args.agent}`,
+          `Session: ${childSessionID}`,
+          ``,
+          `You will be automatically notified when it completes.`,
+          `Do not poll — continue with other work.`,
+        ].join("\n");
+      } catch (e) {
+        return JSON.stringify({
+          error: `Failed to delegate: ${e instanceof Error ? e.message : String(e)}`,
+        });
+      }
+    },
+  });
+
+  const delegationReadTool = tool({
+    description:
+      "Read the full output of a completed delegation. Use this when " +
+      "the <delegation_completed> notification was truncated or lost " +
+      "during context compaction.",
+    args: {
+      id: tool.schema
+        .string()
+        .describe('The delegation ID (e.g. "d-1", "d-2")'),
+    },
+    async execute(args) {
+      const delegation = delegations.get(args.id);
+
+      if (!delegation) {
+        const available = Array.from(delegations.keys()).join(", ");
+        return `Delegation "${args.id}" not found. Available: ${available || "(none)"}`;
+      }
+
+      if (delegation.status === "running") {
+        // Try to get current progress from the session
+        try {
+          const messagesResult = await client.session.messages({
+            path: { id: delegation.sessionID },
+          });
+          const messages =
+            (messagesResult.data ?? []) as SessionMessageItem[];
+          const lastText = extractLastAssistantText(messages);
+
+          const elapsed = formatDuration(Date.now() - delegation.startedAt);
+          return [
+            `Delegation ${args.id} is still running (${elapsed} elapsed).`,
+            `Title: ${delegation.title}`,
+            `Agent: ${delegation.agent}`,
+            "",
+            lastText
+              ? `Latest progress:\n${lastText}`
+              : "No output yet.",
+          ].join("\n");
+        } catch {
+          return `Delegation ${args.id} is still running. No progress available yet.`;
+        }
+      }
+
+      // Completed/error/timeout — return stored result
+      const header = [
+        `# ${delegation.title}`,
+        ``,
+        `**ID:** ${delegation.id}`,
+        `**Agent:** ${delegation.agent}`,
+        `**Status:** ${delegation.status}`,
+        `**Duration:** ${delegation.completedAt ? formatDuration(delegation.completedAt - delegation.startedAt) : "N/A"}`,
+        delegation.error ? `**Error:** ${delegation.error}` : "",
+        ``,
+        `---`,
+        ``,
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      // If we have the result in memory, return it
+      if (delegation.result) {
+        return header + delegation.result;
+      }
+
+      // Otherwise try to read from the session
+      try {
+        const messagesResult = await client.session.messages({
+          path: { id: delegation.sessionID },
+        });
+        const messages =
+          (messagesResult.data ?? []) as SessionMessageItem[];
+        const lastText = extractLastAssistantText(messages);
+        return header + (lastText || "(No output found)");
+      } catch {
+        return header + "(Session no longer available)";
+      }
+    },
+  });
+
+  const delegationListTool = tool({
+    description:
+      "List all background delegations for the current session. " +
+      "Shows running and completed delegations with their IDs, titles, " +
+      "agents, and statuses.",
+    args: {},
+    async execute(_args, context) {
+      const all = findByParent(context.sessionID);
+
+      if (all.length === 0) {
+        return "No delegations found for this session.";
+      }
+
+      const lines = all.map((d) => {
+        const status =
+          d.status === "running"
+            ? `RUNNING (${formatDuration(Date.now() - d.startedAt)})`
+            : d.status === "complete"
+              ? `COMPLETE`
+              : d.status === "timeout"
+                ? `TIMEOUT`
+                : `ERROR`;
+        return `- ${d.id} | ${d.title} | ${d.agent} | ${status}`;
+      });
+
+      return ["## Delegations", "", ...lines].join("\n");
+    },
+  });
+
+  // ── Return hooks ───────────────────────────────────────────────────────
+
+  return {
+    tool: {
+      delegate: delegateTool,
+      delegation_read: delegationReadTool,
+      delegation_list: delegationListTool,
+    },
+
+    // Watch for child session completion
+    event: async ({ event }: { event: Event }) => {
+      if (event.type === "session.idle") {
+        const sessionID = event.properties.sessionID;
+        const delegation = findBySessionID(sessionID);
+        if (delegation && delegation.status === "running") {
+          await handleCompletion(delegation);
+        }
+      }
+    },
+
+    // Inject delegation state during context compaction
+    "experimental.session.compacting": async (
+      input: { sessionID: string },
+      output: { context: string[]; prompt?: string },
+    ) => {
+      const all = findByParent(input.sessionID);
+      if (all.length === 0) return;
+
+      const running = all.filter((d) => d.status === "running");
+      const completed = all.filter((d) => d.status !== "running");
+
+      const sections: string[] = ["<delegation-context>"];
+
+      if (running.length > 0) {
+        sections.push("## Running Delegations");
+        for (const d of running) {
+          const elapsed = formatDuration(Date.now() - d.startedAt);
+          sections.push(
+            `- **${d.id}** | ${d.title} | ${d.agent} | running for ${elapsed}`,
+          );
+          sections.push(
+            `  Prompt: ${d.prompt.length > 150 ? d.prompt.slice(0, 150) + "..." : d.prompt}`,
+          );
+        }
+        sections.push("");
+        sections.push(
+          "> You will be notified via <delegation_completed> when these finish. Do not poll.",
+        );
+      }
+
+      if (completed.length > 0) {
+        sections.push("");
+        sections.push("## Completed Delegations");
+        for (const d of completed) {
+          const statusLabel =
+            d.status === "complete"
+              ? "DONE"
+              : d.status === "error"
+                ? "ERROR"
+                : "TIMEOUT";
+          sections.push(
+            `- **${d.id}** | ${d.title} | ${d.agent} | ${statusLabel}`,
+          );
+          if (d.result) {
+            const preview =
+              d.result.length > 200
+                ? d.result.slice(0, 200) + "..."
+                : d.result;
+            sections.push(`  Result preview: ${preview}`);
+          }
+        }
+        sections.push("");
+        sections.push(
+          '> Use delegation_read("id") to retrieve full results.',
+        );
+      }
+
+      sections.push("</delegation-context>");
+      output.context.push(sections.join("\n"));
+    },
+  };
+};
+
+export default BackgroundAgentsPlugin;

package/opencode/plugin/kdco-primitives/get-project-id.ts

@@ -0,0 +1,172 @@
+/**
+ * Project ID generation for kdco registry plugins.
+ *
+ * Generates a stable, unique identifier for a project based on its git history.
+ * Used for cross-worktree consistency in delegation storage, state databases,
+ * and other plugin data that should be shared across worktrees.
+ *
+ * @module kdco-primitives/get-project-id
+ */
+
+import * as crypto from "node:crypto"
+import { stat } from "node:fs/promises"
+import * as path from "node:path"
+import { logWarn } from "./log-warn"
+import type { OpencodeClient } from "./types"
+import { TimeoutError, withTimeout } from "./with-timeout"
+
+/**
+ * Generate a short hash from a path for project ID fallback.
+ *
+ * Used when git root commit is unavailable (non-git repos, empty repos).
+ * Produces a 16-character hex string for reasonable uniqueness.
+ *
+ * @param projectRoot - Absolute path to hash
+ * @returns 16-char hex hash
+ */
+function hashPath(projectRoot: string): string {
+	const hash = crypto.createHash("sha256").update(projectRoot).digest("hex")
+	return hash.slice(0, 16)
+}
+
+/**
+ * Generate a unique project ID from the project root path.
+ *
+ * **Strategy:**
+ * 1. Uses the first root commit SHA for stability across renames/moves
+ * 2. Falls back to path hash for non-git repos or empty repos
+ * 3. Caches result in .git/opencode for performance
+ *
+ * **Git Worktree Support:**
+ * When .git is a file (worktree), resolves the actual .git directory
+ * and uses the shared cache. This ensures all worktrees share the same
+ * project ID and associated data.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param client - Optional OpenCode client for logging warnings
+ * @returns 40-char hex SHA (git root) or 16-char hash (fallback)
+ * @throws {Error} When projectRoot is invalid or .git file has invalid format
+ *
+ * @example
+ * ```ts
+ * const projectId = await getProjectId("/home/user/my-repo")
+ * // Returns: "abc123..." (40-char git hash)
+ *
+ * const projectId = await getProjectId("/home/user/non-git-folder")
+ * // Returns: "def456..." (16-char path hash)
+ * ```
+ */
+export async function getProjectId(projectRoot: string, client?: OpencodeClient): Promise<string> {
+	// Guard: Validate projectRoot (Law 1: Early Exit, Law 4: Fail Fast)
+	if (!projectRoot || typeof projectRoot !== "string") {
+		throw new Error("getProjectId: projectRoot is required and must be a string")
+	}
+
+	const gitPath = path.join(projectRoot, ".git")
+
+	// Check if .git exists and what type it is
+	const gitStat = await stat(gitPath).catch(() => null)
+
+	// Guard: No .git directory - not a git repo (Law 1: Early Exit)
+	if (!gitStat) {
+		logWarn(client, "project-id", `No .git found at ${projectRoot}, using path hash`)
+		return hashPath(projectRoot)
+	}
+
+	let gitDir = gitPath
+
+	// Handle worktree case: .git is a file containing gitdir reference
+	if (gitStat.isFile()) {
+		const content = await Bun.file(gitPath).text()
+		const match = content.match(/^gitdir:\s*(.+)$/m)
+
+		// Guard: Invalid .git file format (Law 4: Fail Fast)
+		if (!match) {
+			throw new Error(`getProjectId: .git file exists but has invalid format at ${gitPath}`)
+		}
+
+		// Resolve path (handles both relative and absolute)
+		const gitdirPath = match[1].trim()
+		const resolvedGitdir = path.resolve(projectRoot, gitdirPath)
+
+		// The gitdir contains a 'commondir' file pointing to shared .git
+		const commondirPath = path.join(resolvedGitdir, "commondir")
+		const commondirFile = Bun.file(commondirPath)
+
+		if (await commondirFile.exists()) {
+			const commondirContent = (await commondirFile.text()).trim()
+			gitDir = path.resolve(resolvedGitdir, commondirContent)
+		} else {
+			// Fallback to ../.. assumption for older git or unusual setups
+			gitDir = path.resolve(resolvedGitdir, "../..")
+		}
+
+		// Guard: Resolved gitdir must be a directory (Law 4: Fail Fast)
+		const gitDirStat = await stat(gitDir).catch(() => null)
+		if (!gitDirStat?.isDirectory()) {
+			throw new Error(`getProjectId: Resolved gitdir ${gitDir} is not a directory`)
+		}
+	}
+
+	// Check cache in .git/opencode
+	const cacheFile = path.join(gitDir, "opencode")
+	const cache = Bun.file(cacheFile)
+
+	if (await cache.exists()) {
+		const cached = (await cache.text()).trim()
+		// Validate cache content (40-char hex for git hash, or 16-char for path hash)
+		if (/^[a-f0-9]{40}$/i.test(cached) || /^[a-f0-9]{16}$/i.test(cached)) {
+			return cached
+		}
+		logWarn(client, "project-id", `Invalid cache content at ${cacheFile}, regenerating`)
+	}
+
+	// Generate project ID from git root commit
+	try {
+		const proc = Bun.spawn(["git", "rev-list", "--max-parents=0", "--all"], {
+			cwd: projectRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, GIT_DIR: undefined, GIT_WORK_TREE: undefined },
+		})
+
+		// 5 second timeout to prevent hangs on network filesystems
+		const timeoutMs = 5000
+		const exitCode = await withTimeout(proc.exited, timeoutMs, `git rev-list timed out`).catch(
+			(e) => {
+				if (e instanceof TimeoutError) {
+					proc.kill()
+				}
+				return 1 // Treat timeout/errors as failure, fall back to path hash
+			},
+		)
+
+		if (exitCode === 0) {
+			const output = await new Response(proc.stdout).text()
+			const roots = output
+				.split("\n")
+				.filter(Boolean)
+				.map((x) => x.trim())
+				.sort()
+
+			if (roots.length > 0 && /^[a-f0-9]{40}$/i.test(roots[0])) {
+				const projectId = roots[0]
+				// Cache the result
+				try {
+					await Bun.write(cacheFile, projectId)
+				} catch (e) {
+					logWarn(client, "project-id", `Failed to cache project ID: ${e}`)
+				}
+				return projectId
+			}
+		} else {
+			const stderr = await new Response(proc.stderr).text()
+			logWarn(client, "project-id", `git rev-list failed (${exitCode}): ${stderr.trim()}`)
+		}
+	} catch (error) {
+		logWarn(client, "project-id", `git command failed: ${error}`)
+	}
+
+	// Fallback to path hash
+	return hashPath(projectRoot)
+}