@orgloop/agentctl 1.1.0 → 1.2.1

package/dist/launch-orchestrator.js

@@ -0,0 +1,198 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { runHook } from "./hooks.js";
+import { createWorktree } from "./worktree.js";
+// --- Group ID generation ---
+/** Generate a short group ID like "g-a1b2c3" */
+export function generateGroupId() {
+    const hex = crypto.randomBytes(3).toString("hex");
+    return `g-${hex}`;
+}
+// --- Slot disambiguation ---
+/**
+ * Generate a short suffix for a slot, used in worktree/branch naming.
+ * When an adapter appears multiple times, disambiguate using the model short name.
+ */
+export function slotSuffix(slot, allSlots) {
+    const sameAdapter = allSlots.filter((s) => s.adapter === slot.adapter);
+    // Short adapter name: claude-code → cc, codex → codex, etc.
+    const adapterShort = shortenAdapter(slot.adapter);
+    if (sameAdapter.length <= 1) {
+        return adapterShort;
+    }
+    // Disambiguate with model short name
+    const modelShort = slot.model ? shortenModel(slot.model) : "default";
+    return `${adapterShort}-${modelShort}`;
+}
+/** Shorten adapter names for path-friendly suffixes */
+function shortenAdapter(adapter) {
+    const map = {
+        "claude-code": "cc",
+        "pi-rust": "pi-rs",
+    };
+    return map[adapter] || adapter;
+}
+/** Extract a short model name from a full model identifier */
+function shortenModel(model) {
+    // claude-opus-4-6 → opus, claude-sonnet-4-5 → sonnet
+    const opusMatch = model.match(/opus/i);
+    if (opusMatch)
+        return "opus";
+    const sonnetMatch = model.match(/sonnet/i);
+    if (sonnetMatch)
+        return "sonnet";
+    const haikuMatch = model.match(/haiku/i);
+    if (haikuMatch)
+        return "haiku";
+    // gpt-5.2-codex → gpt5-codex
+    const gptMatch = model.match(/gpt[- ]?(\d+)/i);
+    if (gptMatch) {
+        const rest = model.replace(/gpt[- ]?\d+\.?\d*/i, "").replace(/^[- .]+/, "");
+        return rest ? `gpt${gptMatch[1]}-${rest}` : `gpt${gptMatch[1]}`;
+    }
+    // Fallback: take last segment, sanitize
+    const parts = model.split(/[/:-]/);
+    return sanitizePath(parts[parts.length - 1] || model);
+}
+/** Sanitize a string for use in file paths and branch names */
+function sanitizePath(s) {
+    return s.replace(/[^a-zA-Z0-9-]/g, "").toLowerCase() || "default";
+}
+// --- Worktree + branch naming ---
+/** Build worktree path: <repo>-<groupId>-<suffix> */
+export function worktreePath(repo, groupId, suffix) {
+    const repoResolved = path.resolve(repo);
+    return `${repoResolved}-${groupId}-${suffix}`;
+}
+/** Build branch name: try/<groupId>/<suffix> */
+export function branchName(groupId, suffix) {
+    return `try/${groupId}/${suffix}`;
+}
+// --- Orchestrator ---
+/**
+ * Orchestrate a parallel multi-adapter launch.
+ *
+ * 1. Generate group ID
+ * 2. For each slot: create worktree, run on_worktree_create hook, launch adapter
+ * 3. Return all results (successes and failures)
+ */
+export async function orchestrateLaunch(opts) {
+    const { slots, prompt, spec, cwd, hooks, adapters } = opts;
+    const groupId = generateGroupId();
+    opts.onGroupCreated?.(groupId);
+    const repo = path.resolve(cwd);
+    // Phase 1: Create all worktrees (sequential to avoid git lock contention)
+    const worktrees = [];
+    for (const slot of slots) {
+        const suffix = slotSuffix(slot, slots);
+        const branch = branchName(groupId, suffix);
+        const worktree = await createWorktree({
+            repo,
+            branch,
+        });
+        // The createWorktree function names the path based on repo+branch slug.
+        // We need to override for our naming convention.
+        // Actually — createWorktree uses `<repo>-<branch-slug>` which for
+        // branch "try/g-a1b2c3/cc" becomes "<repo>-try-g-a1b2c3-cc".
+        // That's acceptable. Let's use the path it returns.
+        worktrees.push({ slot, suffix, branch, worktree });
+        // Run on_worktree_create hook (onCreate) if provided
+        if (hooks?.onCreate) {
+            await runHook(hooks, "onCreate", {
+                sessionId: "", // not yet launched
+                cwd: worktree.path,
+                adapter: slot.adapter,
+                branch,
+                group: groupId,
+                model: slot.model,
+            });
+        }
+    }
+    // Phase 2: Launch all adapters in parallel
+    const launchPromises = worktrees.map(async ({ slot, branch, worktree }) => {
+        const adapter = adapters[slot.adapter];
+        if (!adapter) {
+            return {
+                slot,
+                sessionId: "",
+                cwd: worktree.path,
+                branch,
+                error: `Unknown adapter: ${slot.adapter}`,
+            };
+        }
+        try {
+            const launchOpts = {
+                adapter: slot.adapter,
+                prompt,
+                spec,
+                cwd: worktree.path,
+                model: slot.model,
+                worktree: { repo: worktree.repo, branch },
+                hooks,
+            };
+            const session = await adapter.launch(launchOpts);
+            // Tag the session with the group
+            session.group = groupId;
+            const result = {
+                slot,
+                sessionId: session.id,
+                pid: session.pid,
+                cwd: worktree.path,
+                branch,
+            };
+            opts.onSessionLaunched?.(result);
+            return result;
+        }
+        catch (err) {
+            return {
+                slot,
+                sessionId: "",
+                cwd: worktree.path,
+                branch,
+                error: err.message,
+            };
+        }
+    });
+    const results = await Promise.all(launchPromises);
+    return { groupId, results };
+}
+// --- CLI flag parsing ---
+/**
+ * Parse positional adapter slots from raw argv.
+ *
+ * Multiple --adapter flags, each optionally followed by --model:
+ *   --adapter claude-code --model opus --adapter codex
+ *
+ * Returns AdapterSlot[] representing each launch slot.
+ */
+export function parseAdapterSlots(rawArgs) {
+    const slots = [];
+    let current = null;
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        if (arg === "--adapter" || arg === "-A") {
+            // Flush previous slot
+            if (current)
+                slots.push(current);
+            const value = rawArgs[++i];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`--adapter requires a value`);
+            }
+            current = { adapter: value };
+        }
+        else if (arg === "--model" || arg === "-M") {
+            if (!current) {
+                throw new Error(`--model must follow an --adapter flag`);
+            }
+            const value = rawArgs[++i];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`--model requires a value`);
+            }
+            current.model = value;
+        }
+    }
+    // Flush last slot
+    if (current)
+        slots.push(current);
+    return slots;
+}

package/dist/matrix-parser.d.ts

@@ -0,0 +1,40 @@
+import type { AdapterSlot } from "./launch-orchestrator.js";
+/** A single entry in the matrix array */
+export interface MatrixEntry {
+    adapter: string;
+    model?: string | string[];
+}
+/** Top-level matrix file schema */
+export interface MatrixFile {
+    prompt: string;
+    cwd?: string;
+    spec?: string;
+    hooks?: {
+        on_create?: string;
+        on_complete?: string;
+    };
+    matrix: MatrixEntry[];
+}
+/**
+ * Parse a YAML matrix file and expand into AdapterSlot[].
+ *
+ * Cross-product expansion: when a matrix entry has an array value for `model`,
+ * it expands into one slot per model value.
+ *
+ * Example:
+ *   matrix:
+ *     - adapter: claude-code
+ *       model: [opus, sonnet]
+ *     - adapter: codex
+ *
+ * Expands to 3 slots:
+ *   [{ adapter: "claude-code", model: "opus" },
+ *    { adapter: "claude-code", model: "sonnet" },
+ *    { adapter: "codex" }]
+ */
+export declare function parseMatrixFile(filePath: string): Promise<MatrixFile>;
+/**
+ * Expand a MatrixFile into AdapterSlot[].
+ * Handles cross-product expansion for array-valued fields.
+ */
+export declare function expandMatrix(matrix: MatrixFile): AdapterSlot[];

package/dist/matrix-parser.js

@@ -0,0 +1,69 @@
+import fs from "node:fs/promises";
+import YAML from "yaml";
+// --- Parsing ---
+/**
+ * Parse a YAML matrix file and expand into AdapterSlot[].
+ *
+ * Cross-product expansion: when a matrix entry has an array value for `model`,
+ * it expands into one slot per model value.
+ *
+ * Example:
+ *   matrix:
+ *     - adapter: claude-code
+ *       model: [opus, sonnet]
+ *     - adapter: codex
+ *
+ * Expands to 3 slots:
+ *   [{ adapter: "claude-code", model: "opus" },
+ *    { adapter: "claude-code", model: "sonnet" },
+ *    { adapter: "codex" }]
+ */
+export async function parseMatrixFile(filePath) {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const parsed = YAML.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`Invalid matrix file: ${filePath}`);
+    }
+    if (!parsed.prompt || typeof parsed.prompt !== "string") {
+        throw new Error("Matrix file must have a 'prompt' field (string)");
+    }
+    if (!Array.isArray(parsed.matrix) || parsed.matrix.length === 0) {
+        throw new Error("Matrix file must have a non-empty 'matrix' array");
+    }
+    // Validate entries
+    for (const entry of parsed.matrix) {
+        if (!entry.adapter || typeof entry.adapter !== "string") {
+            throw new Error("Each matrix entry must have an 'adapter' field (string)");
+        }
+    }
+    return parsed;
+}
+/**
+ * Expand a MatrixFile into AdapterSlot[].
+ * Handles cross-product expansion for array-valued fields.
+ */
+export function expandMatrix(matrix) {
+    const slots = [];
+    for (const entry of matrix.matrix) {
+        const models = normalizeToArray(entry.model);
+        if (models.length === 0) {
+            // No model specified — single slot
+            slots.push({ adapter: entry.adapter });
+        }
+        else {
+            // One slot per model
+            for (const model of models) {
+                slots.push({ adapter: entry.adapter, model });
+            }
+        }
+    }
+    return slots;
+}
+/** Normalize a value to an array (handles string | string[] | undefined) */
+function normalizeToArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [value];
+}

package/dist/utils/daemon-env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Save the current process environment to disk.
+ * Called at daemon start time when we still have the user's shell env.
+ */
+export declare function saveEnvironment(configDir: string): Promise<void>;
+/**
+ * Load the saved environment from disk.
+ * Returns undefined if the env file doesn't exist or is corrupt.
+ */
+export declare function loadSavedEnvironment(configDir: string): Promise<Record<string, string> | undefined>;
+/**
+ * Build an augmented environment for spawning subprocesses.
+ * Merges the saved daemon env with common bin paths to ensure
+ * binaries are findable even when the daemon is detached from the shell.
+ */
+export declare function buildSpawnEnv(savedEnv?: Record<string, string>, extraEnv?: Record<string, string>): Record<string, string>;

package/dist/utils/daemon-env.js

@@ -0,0 +1,85 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+const ENV_FILE = "daemon-env.json";
+/**
+ * Common bin directories that should be in PATH when spawning subprocesses.
+ * These cover the usual locations for various package managers and tools.
+ */
+function getCommonBinDirs() {
+    const home = os.homedir();
+    return [
+        path.join(home, ".local", "bin"),
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+        "/usr/sbin",
+        "/sbin",
+        "/opt/homebrew/bin",
+        path.join(home, ".npm-global", "bin"),
+        path.join(home, ".local", "share", "mise", "shims"),
+        path.join(home, ".cargo", "bin"),
+    ];
+}
+/**
+ * Save the current process environment to disk.
+ * Called at daemon start time when we still have the user's shell env.
+ */
+export async function saveEnvironment(configDir) {
+    const envPath = path.join(configDir, ENV_FILE);
+    try {
+        const tmpPath = `${envPath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(process.env));
+        await fs.rename(tmpPath, envPath);
+    }
+    catch (err) {
+        console.error(`Warning: could not save environment: ${err.message}`);
+    }
+}
+/**
+ * Load the saved environment from disk.
+ * Returns undefined if the env file doesn't exist or is corrupt.
+ */
+export async function loadSavedEnvironment(configDir) {
+    const envPath = path.join(configDir, ENV_FILE);
+    try {
+        const raw = await fs.readFile(envPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null) {
+            return parsed;
+        }
+    }
+    catch {
+        // File doesn't exist or is corrupt
+    }
+    return undefined;
+}
+/**
+ * Build an augmented environment for spawning subprocesses.
+ * Merges the saved daemon env with common bin paths to ensure
+ * binaries are findable even when the daemon is detached from the shell.
+ */
+export function buildSpawnEnv(savedEnv, extraEnv) {
+    const base = {};
+    const source = savedEnv || process.env;
+    // Copy source env
+    for (const [k, v] of Object.entries(source)) {
+        if (v !== undefined)
+            base[k] = v;
+    }
+    // Augment PATH with common bin directories
+    const existingPath = base.PATH || "";
+    const existingDirs = new Set(existingPath.split(":").filter(Boolean));
+    const commonDirs = getCommonBinDirs();
+    const newDirs = commonDirs.filter((d) => !existingDirs.has(d));
+    if (newDirs.length > 0) {
+        base.PATH = [...existingPath.split(":").filter(Boolean), ...newDirs].join(":");
+    }
+    // Apply extra env overrides
+    if (extraEnv) {
+        for (const [k, v] of Object.entries(extraEnv)) {
+            base[k] = v;
+        }
+    }
+    return base;
+}

package/dist/utils/partial-read.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Read the first N lines of a file by reading only `maxBytes` from the start.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the start (default 8192)
+ * @returns Array of complete lines (up to maxLines)
+ */
+export declare function readHead(filePath: string, maxLines: number, maxBytes?: number): Promise<string[]>;
+/**
+ * Read the last N lines of a file by reading only `maxBytes` from the end.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the end (default 65536)
+ * @returns Array of complete lines (up to maxLines, in order)
+ */
+export declare function readTail(filePath: string, maxLines: number, maxBytes?: number): Promise<string[]>;

package/dist/utils/partial-read.js

@@ -0,0 +1,66 @@
+import * as fs from "node:fs/promises";
+/**
+ * Read the first N lines of a file by reading only `maxBytes` from the start.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the start (default 8192)
+ * @returns Array of complete lines (up to maxLines)
+ */
+export async function readHead(filePath, maxLines, maxBytes = 8192) {
+    const fh = await fs.open(filePath, "r");
+    try {
+        const stat = await fh.stat();
+        const bytesToRead = Math.min(maxBytes, stat.size);
+        if (bytesToRead === 0)
+            return [];
+        const buf = Buffer.alloc(bytesToRead);
+        const { bytesRead } = await fh.read(buf, 0, bytesToRead, 0);
+        if (bytesRead === 0)
+            return [];
+        const text = buf.subarray(0, bytesRead).toString("utf-8");
+        const lines = text.split("\n");
+        // If we didn't read the whole file, the last chunk may be incomplete — drop it
+        if (bytesRead < stat.size) {
+            lines.pop();
+        }
+        return lines.filter((l) => l.length > 0).slice(0, maxLines);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Read the last N lines of a file by reading only `maxBytes` from the end.
+ * Avoids allocating the entire file into memory for large JSONL files.
+ *
+ * @param filePath - Path to the file
+ * @param maxLines - Maximum number of lines to return
+ * @param maxBytes - Maximum bytes to read from the end (default 65536)
+ * @returns Array of complete lines (up to maxLines, in order)
+ */
+export async function readTail(filePath, maxLines, maxBytes = 65536) {
+    const fh = await fs.open(filePath, "r");
+    try {
+        const stat = await fh.stat();
+        if (stat.size === 0)
+            return [];
+        const bytesToRead = Math.min(maxBytes, stat.size);
+        const offset = Math.max(0, stat.size - bytesToRead);
+        const buf = Buffer.alloc(bytesToRead);
+        const { bytesRead } = await fh.read(buf, 0, bytesToRead, offset);
+        if (bytesRead === 0)
+            return [];
+        const text = buf.subarray(0, bytesRead).toString("utf-8");
+        const lines = text.split("\n");
+        // If we didn't start from the beginning, the first chunk may be a partial line — drop it
+        if (offset > 0) {
+            lines.shift();
+        }
+        return lines.filter((l) => l.length > 0).slice(-maxLines);
+    }
+    finally {
+        await fh.close();
+    }
+}

package/dist/utils/resolve-binary.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resolve the absolute path to a binary, checking known locations first,
+ * then falling back to `which`. Results are cached per binary name.
+ *
+ * @param name - Binary name (e.g., "claude", "codex", "pi")
+ * @param knownLocations - Additional absolute paths to check first
+ * @returns Resolved absolute path, or bare name as last resort
+ */
+export declare function resolveBinaryPath(name: string, knownLocations?: string[]): Promise<string>;
+/**
+ * Clear the resolved path cache. Call this when binaries may have been
+ * updated (e.g., on daemon restart).
+ */
+export declare function clearBinaryCache(): void;

package/dist/utils/resolve-binary.js

@@ -0,0 +1,66 @@
+import { execFile } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** Cache of resolved binary paths: name → absolute path */
+const resolvedCache = new Map();
+/**
+ * Resolve the absolute path to a binary, checking known locations first,
+ * then falling back to `which`. Results are cached per binary name.
+ *
+ * @param name - Binary name (e.g., "claude", "codex", "pi")
+ * @param knownLocations - Additional absolute paths to check first
+ * @returns Resolved absolute path, or bare name as last resort
+ */
+export async function resolveBinaryPath(name, knownLocations = []) {
+    const cached = resolvedCache.get(name);
+    if (cached)
+        return cached;
+    const home = os.homedir();
+    // Default well-known locations for common toolchains
+    const defaultLocations = [
+        path.join(home, ".local", "bin", name),
+        `/usr/local/bin/${name}`,
+        `/opt/homebrew/bin/${name}`, // Homebrew Apple Silicon
+        path.join(home, ".npm-global", "bin", name),
+        path.join(home, ".local", "share", "mise", "shims", name),
+        path.join(home, ".cargo", "bin", name),
+    ];
+    const candidates = [...knownLocations, ...defaultLocations];
+    for (const c of candidates) {
+        try {
+            await fs.access(c, fs.constants.X_OK);
+            // Resolve symlinks to get the actual binary path
+            const resolved = await fs.realpath(c);
+            await fs.access(resolved, fs.constants.X_OK);
+            resolvedCache.set(name, resolved);
+            return resolved;
+        }
+        catch {
+            // Try next
+        }
+    }
+    // Try `which <name>` as fallback
+    try {
+        const { stdout } = await execFileAsync("which", [name]);
+        const p = stdout.trim();
+        if (p) {
+            resolvedCache.set(name, p);
+            return p;
+        }
+    }
+    catch {
+        // Fall through
+    }
+    // Last resort: bare name (let PATH resolve it at spawn time)
+    return name;
+}
+/**
+ * Clear the resolved path cache. Call this when binaries may have been
+ * updated (e.g., on daemon restart).
+ */
+export function clearBinaryCache() {
+    resolvedCache.clear();
+}

package/dist/worktree.d.ts

@@ -22,3 +22,25 @@ export declare function createWorktree(opts: WorktreeCreateOpts): Promise<Worktr
  * Remove a git worktree.
  */
 export declare function removeWorktree(repo: string, worktreePath: string): Promise<void>;
+/** Info about an existing worktree from `git worktree list` */
+export interface WorktreeListEntry {
+    path: string;
+    branch: string;
+    head: string;
+    /** Whether this is the bare/main worktree */
+    bare: boolean;
+}
+/**
+ * List all git worktrees for a repo.
+ * Parses `git worktree list --porcelain` output.
+ */
+export declare function listWorktrees(repo: string): Promise<WorktreeListEntry[]>;
+/**
+ * Remove a worktree and optionally delete its branch.
+ */
+export declare function cleanWorktree(repo: string, worktreePath: string, opts?: {
+    deleteBranch?: boolean;
+}): Promise<{
+    removedPath: string;
+    deletedBranch?: string;
+}>;

package/dist/worktree.js

@@ -63,3 +63,71 @@ export async function removeWorktree(repo, worktreePath) {
         cwd: repoResolved,
     });
 }
+/**
+ * List all git worktrees for a repo.
+ * Parses `git worktree list --porcelain` output.
+ */
+export async function listWorktrees(repo) {
+    const repoResolved = path.resolve(repo);
+    const { stdout } = await execFileAsync("git", ["worktree", "list", "--porcelain"], { cwd: repoResolved });
+    const entries = [];
+    let current = {};
+    for (const line of stdout.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            if (current.path)
+                entries.push(current);
+            current = { path: line.replace("worktree ", ""), bare: false };
+        }
+        else if (line.startsWith("HEAD ")) {
+            current.head = line.replace("HEAD ", "");
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.replace("branch refs/heads/", "");
+        }
+        else if (line === "bare") {
+            current.bare = true;
+        }
+        else if (line === "" && current.path) {
+            // End of entry
+        }
+    }
+    if (current.path)
+        entries.push(current);
+    return entries;
+}
+/**
+ * Remove a worktree and optionally delete its branch.
+ */
+export async function cleanWorktree(repo, worktreePath, opts) {
+    const repoResolved = path.resolve(repo);
+    // Get the branch name before removing
+    let branch;
+    if (opts?.deleteBranch) {
+        try {
+            const { stdout } = await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: worktreePath });
+            branch = stdout.trim();
+        }
+        catch {
+            // Worktree might be broken — still try to remove
+        }
+    }
+    await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
+        cwd: repoResolved,
+    });
+    const result = {
+        removedPath: worktreePath,
+    };
+    // Delete the branch if requested
+    if (branch && opts?.deleteBranch) {
+        try {
+            await execFileAsync("git", ["branch", "-D", branch], {
+                cwd: repoResolved,
+            });
+            result.deletedBranch = branch;
+        }
+        catch {
+            // Branch might already be gone
+        }
+    }
+    return result;
+}