@teammates/cli 0.1.0

package/dist/adapters/cli-proxy.js

@@ -0,0 +1,463 @@
+/**
+ * Generic CLI proxy adapter — spawns any coding agent as a subprocess
+ * and streams its output live to the user's terminal.
+ *
+ * Supports any CLI agent that accepts a prompt and runs to completion:
+ *   claude -p "prompt"
+ *   codex exec "prompt" --full-auto
+ *   aider --message "prompt"
+ *   etc.
+ *
+ * The adapter:
+ *   1. Writes the full prompt (identity + memory + task) to a temp file
+ *   2. Spawns the agent with the prompt file
+ *   3. Tees stdout/stderr to the user's terminal in real time
+ *   4. Captures output for result parsing (changed files, handoff envelopes)
+ */
+import { spawn } from "node:child_process";
+import { writeFile, unlink, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { buildTeammatePrompt } from "../adapter.js";
+export const PRESETS = {
+    claude: {
+        name: "claude",
+        command: "claude",
+        buildArgs({ prompt }, teammate, options) {
+            const args = ["-p", "--verbose", "--dangerously-skip-permissions"];
+            if (options.model)
+                args.push("--model", options.model);
+            args.push("--", prompt);
+            return args;
+        },
+        env: { FORCE_COLOR: "1", CLAUDECODE: "" },
+    },
+    codex: {
+        name: "codex",
+        command: "codex",
+        buildArgs({ prompt }, teammate, options) {
+            const args = ["exec", prompt];
+            if (teammate.cwd)
+                args.push("-C", teammate.cwd);
+            const sandbox = teammate.sandbox ?? options.defaultSandbox ?? "workspace-write";
+            args.push("-s", sandbox);
+            args.push("--full-auto");
+            if (options.model)
+                args.push("-m", options.model);
+            return args;
+        },
+        env: { FORCE_COLOR: "1" },
+    },
+    aider: {
+        name: "aider",
+        command: "aider",
+        buildArgs({ promptFile }, teammate, options) {
+            const args = ["--message-file", promptFile, "--yes", "--no-git"];
+            if (options.model)
+                args.push("--model", options.model);
+            return args;
+        },
+        env: { FORCE_COLOR: "1" },
+    },
+};
+let nextId = 1;
+export class CliProxyAdapter {
+    name;
+    /** Team roster — set by the orchestrator so prompts include teammate info. */
+    roster = [];
+    /** Installed services — set by the CLI so prompts include service info. */
+    services = [];
+    preset;
+    options;
+    /** Session files per teammate — persists state across task invocations. */
+    sessionFiles = new Map();
+    /** Base directory for session files. */
+    sessionsDir = "";
+    /** Temp prompt files that need cleanup — guards against crashes before finally. */
+    pendingTempFiles = new Set();
+    constructor(options) {
+        this.options = options;
+        this.preset =
+            typeof options.preset === "string"
+                ? PRESETS[options.preset]
+                : options.preset;
+        if (!this.preset) {
+            throw new Error(`Unknown agent preset: ${options.preset}. Available: ${Object.keys(PRESETS).join(", ")}`);
+        }
+        this.name = this.preset.name;
+    }
+    async startSession(teammate) {
+        const id = `${this.name}-${teammate.name}-${nextId++}`;
+        // Create session file for this teammate
+        if (!this.sessionsDir) {
+            this.sessionsDir = join(tmpdir(), `teammates-sessions-${randomUUID()}`);
+            await mkdir(this.sessionsDir, { recursive: true });
+        }
+        const sessionFile = join(this.sessionsDir, `${teammate.name}.md`);
+        await writeFile(sessionFile, `# Session — ${teammate.name}\n\n`, "utf-8");
+        this.sessionFiles.set(teammate.name, sessionFile);
+        return id;
+    }
+    async executeTask(sessionId, teammate, prompt) {
+        // If the teammate has no soul (e.g. the raw agent), skip identity/memory
+        // wrapping but include handoff instructions so it can delegate to teammates
+        const sessionFile = this.sessionFiles.get(teammate.name);
+        let fullPrompt;
+        if (teammate.soul) {
+            fullPrompt = buildTeammatePrompt(teammate, prompt, {
+                roster: this.roster,
+                services: this.services,
+                sessionFile,
+            });
+        }
+        else {
+            const parts = [prompt];
+            const others = this.roster.filter((r) => r.name !== teammate.name);
+            if (others.length > 0) {
+                parts.push("\n\n---\n");
+                parts.push("If part of this task belongs to a specialist, you can hand it off.");
+                parts.push("Your teammates:");
+                for (const t of others) {
+                    const owns = t.ownership.primary.length > 0
+                        ? ` — owns: ${t.ownership.primary.join(", ")}`
+                        : "";
+                    parts.push(`- @${t.name}: ${t.role}${owns}`);
+                }
+                parts.push("\nTo hand off, end your response with:");
+                parts.push("```json");
+                parts.push('{ "handoff": { "to": "<teammate>", "task": "<what you need them to do>", "context": "<any context>" } }');
+                parts.push("```");
+            }
+            fullPrompt = parts.join("\n");
+        }
+        // Write prompt to temp file to avoid shell escaping issues
+        const promptFile = join(tmpdir(), `teammates-${this.name}-${randomUUID()}.md`);
+        await writeFile(promptFile, fullPrompt, "utf-8");
+        this.pendingTempFiles.add(promptFile);
+        try {
+            const output = await this.spawnAndProxy(teammate, promptFile, fullPrompt);
+            const teammateNames = this.roster.map((r) => r.name);
+            return parseResult(teammate.name, output, teammateNames, prompt);
+        }
+        finally {
+            this.pendingTempFiles.delete(promptFile);
+            await unlink(promptFile).catch(() => { });
+        }
+    }
+    async routeTask(task, roster) {
+        const lines = [
+            "You are a task router. Given a task and a list of teammates, reply with ONLY the name of the teammate who should handle it. No explanation, no punctuation — just the name.",
+            "",
+            "Teammates:",
+        ];
+        for (const t of roster) {
+            const owns = t.ownership.primary.length > 0
+                ? ` — owns: ${t.ownership.primary.join(", ")}`
+                : "";
+            lines.push(`- ${t.name}: ${t.role}${owns}`);
+        }
+        lines.push("", `Task: ${task}`);
+        const prompt = lines.join("\n");
+        const promptFile = join(tmpdir(), `teammates-route-${randomUUID()}.md`);
+        await writeFile(promptFile, prompt, "utf-8");
+        try {
+            const command = this.options.commandPath ?? this.preset.command;
+            const args = this.preset.buildArgs({ promptFile, prompt }, { name: "_router", role: "", soul: "", memories: "", dailyLogs: [], ownership: { primary: [], secondary: [] } }, { ...this.options, model: this.options.model ?? "haiku" });
+            const env = { ...process.env, ...this.preset.env };
+            const output = await new Promise((resolve, reject) => {
+                const child = spawn(command, args, {
+                    cwd: process.cwd(),
+                    env,
+                    stdio: ["ignore", "pipe", "pipe"],
+                    shell: this.preset.shell ?? false,
+                });
+                const captured = [];
+                child.stdout?.on("data", (chunk) => captured.push(chunk));
+                child.stderr?.on("data", (chunk) => captured.push(chunk));
+                const timer = setTimeout(() => {
+                    if (!child.killed)
+                        child.kill("SIGTERM");
+                }, 30_000);
+                child.on("close", () => {
+                    clearTimeout(timer);
+                    resolve(Buffer.concat(captured).toString("utf-8"));
+                });
+                child.on("error", (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+            });
+            // Extract the teammate name from the output
+            const rosterNames = roster.map((r) => r.name);
+            const trimmed = output.trim().toLowerCase();
+            // Check each name — the agent should have returned just one
+            for (const name of rosterNames) {
+                if (trimmed === name.toLowerCase() || trimmed.endsWith(name.toLowerCase())) {
+                    return name;
+                }
+            }
+            // Fuzzy: check if any name appears in the output
+            for (const name of rosterNames) {
+                if (trimmed.includes(name.toLowerCase())) {
+                    return name;
+                }
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            await unlink(promptFile).catch(() => { });
+        }
+    }
+    async destroySession(sessionId) {
+        // Clean up any leaked temp prompt files
+        for (const file of this.pendingTempFiles) {
+            await unlink(file).catch(() => { });
+        }
+        this.pendingTempFiles.clear();
+        // Clean up session files
+        for (const [, file] of this.sessionFiles) {
+            await unlink(file).catch(() => { });
+        }
+        this.sessionFiles.clear();
+    }
+    /**
+     * Spawn the agent, stream its output live, and capture it.
+     */
+    spawnAndProxy(teammate, promptFile, fullPrompt) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                ...this.preset.buildArgs({ promptFile, prompt: fullPrompt }, teammate, this.options),
+                ...(this.options.extraFlags ?? []),
+            ];
+            const command = this.options.commandPath ?? this.preset.command;
+            const env = { ...process.env, ...this.preset.env };
+            const timeout = this.options.timeout ?? 600_000;
+            const interactive = this.preset.interactive ?? false;
+            const child = spawn(command, args, {
+                cwd: teammate.cwd ?? process.cwd(),
+                env,
+                stdio: [interactive ? "pipe" : "ignore", "pipe", "pipe"],
+                shell: this.preset.shell ?? false,
+            });
+            // ── Timeout with SIGTERM → SIGKILL escalation ──────────────
+            let killed = false;
+            let killTimer = null;
+            const timeoutTimer = setTimeout(() => {
+                if (!child.killed) {
+                    killed = true;
+                    child.kill("SIGTERM");
+                    // If SIGTERM doesn't work after 5s, force-kill
+                    killTimer = setTimeout(() => {
+                        if (!child.killed) {
+                            child.kill("SIGKILL");
+                        }
+                    }, 5_000);
+                }
+            }, timeout);
+            // Connect user's stdin → child only if agent may ask questions
+            let onUserInput = null;
+            if (interactive && child.stdin) {
+                onUserInput = (chunk) => {
+                    child.stdin?.write(chunk);
+                };
+                if (process.stdin.isTTY) {
+                    process.stdin.setRawMode(false);
+                }
+                process.stdin.resume();
+                process.stdin.on("data", onUserInput);
+            }
+            const captured = [];
+            child.stdout?.on("data", (chunk) => {
+                captured.push(chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                captured.push(chunk);
+            });
+            const cleanup = () => {
+                clearTimeout(timeoutTimer);
+                if (killTimer)
+                    clearTimeout(killTimer);
+                if (onUserInput) {
+                    process.stdin.removeListener("data", onUserInput);
+                }
+            };
+            child.on("close", (code) => {
+                cleanup();
+                const output = Buffer.concat(captured).toString("utf-8");
+                if (killed) {
+                    resolve(output + `\n\n[TIMEOUT] Agent process killed after ${timeout}ms`);
+                }
+                else {
+                    resolve(output);
+                }
+            });
+            child.on("error", (err) => {
+                cleanup();
+                reject(new Error(`Failed to spawn ${command}: ${err.message}`));
+            });
+        });
+    }
+}
+// ─── Output parsing (shared across all agents) ─────────────────────
+function parseResult(teammateName, output, teammateNames = [], originalTask) {
+    // Try to parse the structured JSON block the agent was asked to produce
+    const structured = parseStructuredOutput(output);
+    if (structured) {
+        return { ...structured, teammate: teammateName, rawOutput: output };
+    }
+    // Fallback: scrape what we can from freeform output
+    return {
+        teammate: teammateName,
+        success: true,
+        summary: extractSummary(output),
+        changedFiles: parseChangedFiles(output),
+        handoff: parseHandoffEnvelope(output) ?? parseHandoffFromMention(teammateName, output, teammateNames, originalTask) ?? undefined,
+        rawOutput: output,
+    };
+}
+/**
+ * Parse the structured JSON block from the output protocol.
+ * Looks for either { "result": ... } or { "handoff": ... }.
+ */
+function parseStructuredOutput(output) {
+    const jsonBlocks = [...output.matchAll(/```json\s*\n([\s\S]*?)```/g)];
+    // Take the last JSON block — that's the protocol output
+    for (let i = jsonBlocks.length - 1; i >= 0; i--) {
+        const block = jsonBlocks[i][1].trim();
+        try {
+            const parsed = JSON.parse(block);
+            if (parsed.result) {
+                return {
+                    success: true,
+                    summary: parsed.result.summary ?? "",
+                    changedFiles: parsed.result.changedFiles ?? parsed.result.changed_files ?? [],
+                };
+            }
+            if (parsed.handoff && parsed.handoff.to && parsed.handoff.task) {
+                const h = parsed.handoff;
+                return {
+                    success: true,
+                    summary: h.context ?? h.task,
+                    changedFiles: h.changedFiles ?? h.changed_files ?? [],
+                    handoff: {
+                        from: h.from ?? "",
+                        to: h.to,
+                        task: h.task,
+                        changedFiles: h.changedFiles ?? h.changed_files,
+                        acceptanceCriteria: h.acceptanceCriteria ?? h.acceptance_criteria,
+                        openQuestions: h.openQuestions ?? h.open_questions,
+                        context: h.context,
+                    },
+                };
+            }
+        }
+        catch {
+            // Not valid JSON
+        }
+    }
+    return null;
+}
+/** Extract file paths from agent output. */
+function parseChangedFiles(output) {
+    const files = new Set();
+    // diff --git a/path b/path
+    for (const match of output.matchAll(/diff --git a\/(.+?) b\//g)) {
+        files.add(match[1]);
+    }
+    // "Created/Modified/Updated/Wrote/Edited <path>" patterns
+    for (const match of output.matchAll(/(?:Created|Modified|Updated|Wrote|Edited)\s+(?:file:\s*)?[`"]?([^\s`"]+\.\w+)[`"]?/gi)) {
+        files.add(match[1]);
+    }
+    return Array.from(files);
+}
+/**
+ * Look for a JSON handoff envelope in the output.
+ * Agents request handoffs by including a fenced JSON block:
+ *
+ * ```json
+ * { "handoff": { "to": "tester", "task": "...", ... } }
+ * ```
+ */
+function parseHandoffEnvelope(output) {
+    const jsonBlocks = output.matchAll(/```json\s*\n([\s\S]*?)```/g);
+    for (const match of jsonBlocks) {
+        const block = match[1].trim();
+        if (!block.includes('"handoff"') && !block.includes('"to"'))
+            continue;
+        try {
+            const parsed = JSON.parse(block);
+            const envelope = parsed.handoff ?? parsed;
+            if (envelope.to && envelope.task) {
+                return {
+                    from: envelope.from ?? "",
+                    to: envelope.to,
+                    task: envelope.task,
+                    changedFiles: envelope.changedFiles ?? envelope.changed_files,
+                    acceptanceCriteria: envelope.acceptanceCriteria ?? envelope.acceptance_criteria,
+                    openQuestions: envelope.openQuestions ?? envelope.open_questions,
+                    context: envelope.context,
+                };
+            }
+        }
+        catch {
+            // Not valid JSON, skip
+        }
+    }
+    return null;
+}
+/**
+ * Detect handoff intent from plain-text @mentions in the agent's response.
+ * Catches cases like "This is in @beacon's domain. Let me hand it off."
+ * where the agent didn't produce the structured JSON block.
+ */
+/**
+ * Detect handoff intent from plain-text @mentions in the agent's response.
+ * Catches cases like "This is in @beacon's domain. Let me hand it off."
+ * where the agent didn't produce the structured JSON block.
+ */
+function parseHandoffFromMention(fromTeammate, output, teammateNames, originalTask) {
+    if (teammateNames.length === 0)
+        return null;
+    // Look for @teammate mentions (excluding the agent's own name)
+    const others = teammateNames.filter((n) => n !== fromTeammate);
+    if (others.length === 0)
+        return null;
+    // Match @name patterns — require handoff-like language nearby
+    const handoffPatterns = /\bhand(?:ing)?\s*(?:it\s+)?off\b|\bdelegate\b|\broute\b|\bpass(?:ing)?\s+(?:it\s+)?(?:to|along)\b|\bbelong(?:s)?\s+to\b|\b(?:is\s+in)\s+@\w+'?s?\s+domain\b/i;
+    for (const name of others) {
+        const mentionPattern = new RegExp(`@${name}\\b`, "i");
+        if (mentionPattern.test(output) && handoffPatterns.test(output)) {
+            return {
+                from: fromTeammate,
+                to: name,
+                task: originalTask || output.slice(0, 200).trim(),
+                context: output.replace(/```json[\s\S]*?```/g, "").trim().slice(0, 500),
+            };
+        }
+    }
+    return null;
+}
+/** Extract a summary from agent output. */
+function extractSummary(output) {
+    // Look for a "## Summary" or "Summary:" section
+    const summaryMatch = output.match(/(?:##?\s*Summary|Summary:)\s*\n([\s\S]*?)(?:\n##|\n---|\n```|$)/i);
+    if (summaryMatch) {
+        const summary = summaryMatch[1].trim();
+        if (summary.length > 0)
+            return summary.slice(0, 500);
+    }
+    // Fall back to last non-empty paragraph
+    const paragraphs = output
+        .split(/\n\s*\n/)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0 && !p.startsWith("```"));
+    if (paragraphs.length > 0) {
+        const last = paragraphs[paragraphs.length - 1];
+        return last.length > 500 ? last.slice(0, 497) + "..." : last;
+    }
+    return output.slice(0, 200).trim();
+}

package/dist/adapters/codex.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Codex adapter — runs each teammate as a `codex exec` subprocess.
+ *
+ * Uses the OpenAI Codex CLI in non-interactive mode:
+ *   codex exec "<prompt>" --full-auto -C <cwd> -s <sandbox> -m <model>
+ *
+ * Each execution is stateless (no thread continuity). The teammate's full
+ * identity, memory, and handoff context are injected into the prompt every time.
+ *
+ * Requirements:
+ *   - `codex` CLI installed and on PATH
+ *   - OPENAI_API_KEY or CODEX_API_KEY set in environment
+ */
+import type { AgentAdapter } from "../adapter.js";
+import type { TeammateConfig, TaskResult, SandboxLevel } from "../types.js";
+export interface CodexAdapterOptions {
+    /** Codex model override (e.g. "o4-mini", "o3") */
+    model?: string;
+    /** Default sandbox level if teammate doesn't specify one */
+    defaultSandbox?: SandboxLevel;
+    /** Use --full-auto mode (default: true) */
+    fullAuto?: boolean;
+    /** Use --ephemeral to skip persisting session files (default: true) */
+    ephemeral?: boolean;
+    /** Additional CLI flags to pass to codex exec */
+    extraFlags?: string[];
+    /** Timeout in ms for codex exec (default: 300000 = 5 min) */
+    timeout?: number;
+    /** Path to codex binary (default: "codex") */
+    codexPath?: string;
+}
+export declare class CodexAdapter implements AgentAdapter {
+    readonly name = "codex";
+    private options;
+    constructor(options?: CodexAdapterOptions);
+    startSession(teammate: TeammateConfig): Promise<string>;
+    executeTask(sessionId: string, teammate: TeammateConfig, prompt: string): Promise<TaskResult>;
+    /**
+     * Spawn `codex exec` and capture its output.
+     * Prompt is passed via a temp file read with shell substitution.
+     */
+    private runCodex;
+    /** Build the argument list for codex exec */
+    private buildArgs;
+    /**
+     * Parse codex output into a TaskResult.
+     * Looks for changed files and handoff envelopes in the output.
+     */
+    private parseResult;
+}