mini-codex 0.1.0

package/dist/subagents.js

@@ -0,0 +1,196 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+const execFileAsync = promisify(execFile);
+const MAX_PARALLEL_SUBAGENTS = 2;
+const MAX_SUBAGENT_DEPTH = 1;
+const CHILD_MAX_STEPS = 8;
+const WAIT_TIMEOUT_MS = 30_000;
+const CLI_ENTRY = fileURLToPath(new URL("./cli.ts", import.meta.url));
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40) || "subagent";
+}
+function touchedFiles(session) {
+    const files = new Set();
+    for (const step of session.steps) {
+        if (step.action.type !== "tool")
+            continue;
+        const p = step.action.toolCall.args.path;
+        if (typeof p === "string" && (step.action.toolCall.tool === "write_file" || step.action.toolCall.tool === "edit_file")) {
+            files.add(p);
+        }
+    }
+    return [...files];
+}
+function finalAnswer(session) {
+    const lastStep = session.steps.at(-1);
+    if (!lastStep)
+        return undefined;
+    if (lastStep.action.type === "clarify") {
+        return lastStep.userResponse ? undefined : lastStep.action.question;
+    }
+    const answer = lastStep.action.toolCall.args.answer;
+    return typeof answer === "string" && answer.trim() ? answer.trim() : undefined;
+}
+async function maybeCopyMemory(sourceRepoPath, worktreePath) {
+    const source = path.join(sourceRepoPath, ".codex", "memory");
+    const target = path.join(worktreePath, ".codex", "memory");
+    try {
+        await fs.access(source);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.cp(source, target, { recursive: true, force: true });
+    }
+    catch {
+        // no memory to copy
+    }
+}
+async function gitRoot(repoPath) {
+    const { stdout } = await execFileAsync("git", ["-C", repoPath, "rev-parse", "--show-toplevel"]);
+    return stdout.trim();
+}
+export class SubagentManager {
+    repoPath;
+    sessionId;
+    depth;
+    active = new Map();
+    rootPathPromise = null;
+    constructor(repoPath, sessionId, depth) {
+        this.repoPath = repoPath;
+        this.sessionId = sessionId;
+        this.depth = depth;
+    }
+    async rootPath() {
+        if (!this.rootPathPromise)
+            this.rootPathPromise = gitRoot(this.repoPath);
+        return this.rootPathPromise;
+    }
+    async spawn(specs) {
+        if (this.depth >= MAX_SUBAGENT_DEPTH) {
+            throw new Error(`Sub-agent depth limit reached (${MAX_SUBAGENT_DEPTH})`);
+        }
+        const availableSlots = Math.max(0, MAX_PARALLEL_SUBAGENTS - this.active.size);
+        if (specs.length > availableSlots) {
+            throw new Error(`Cannot spawn ${specs.length} sub-agents with ${availableSlots} slot${availableSlots === 1 ? "" : "s"} available (limit ${MAX_PARALLEL_SUBAGENTS}, active ${this.active.size})`);
+        }
+        const root = await this.rootPath();
+        const spawned = [];
+        for (const spec of specs) {
+            const id = `${slugify(spec.name)}-${Date.now().toString(36)}`;
+            const worktreePath = path.join(root, ".codex", "subagents", this.sessionId, id);
+            await fs.mkdir(path.dirname(worktreePath), { recursive: true });
+            await execFileAsync("git", ["-C", root, "worktree", "add", "--detach", worktreePath, "HEAD"]);
+            await maybeCopyMemory(this.repoPath, worktreePath);
+            const record = {
+                id,
+                name: spec.name.trim() || id,
+                task: spec.task.trim(),
+                status: "running",
+                worktreePath,
+            };
+            const promise = new Promise((resolve) => {
+                const child = spawn("bun", [
+                    "run",
+                    CLI_ENTRY,
+                    "run",
+                    spec.task,
+                    "--repo",
+                    worktreePath,
+                    "--max-steps",
+                    String(CHILD_MAX_STEPS),
+                    "--json",
+                    "--depth",
+                    String(this.depth + 1),
+                ], {
+                    cwd: root,
+                    env: process.env,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                let stdout = "";
+                let stderr = "";
+                child.stdout.on("data", (chunk) => {
+                    stdout += String(chunk);
+                });
+                child.stderr.on("data", (chunk) => {
+                    stderr += String(chunk);
+                });
+                const timer = setTimeout(() => {
+                    child.kill("SIGTERM");
+                }, WAIT_TIMEOUT_MS);
+                child.on("close", async (code) => {
+                    clearTimeout(timer);
+                    let result = { ...record };
+                    try {
+                        if (code === 0) {
+                            const session = JSON.parse(stdout);
+                            const changedFiles = touchedFiles(session);
+                            result = {
+                                ...result,
+                                status: "completed",
+                                summary: session.steps.at(-1)?.result?.summary || "Completed",
+                                answer: finalAnswer(session),
+                                changedFiles,
+                            };
+                        }
+                        else {
+                            result = {
+                                ...result,
+                                status: "failed",
+                                error: stderr.trim() || stdout.trim() || `Sub-agent exited with code ${code}`,
+                            };
+                        }
+                    }
+                    catch (error) {
+                        result = {
+                            ...result,
+                            status: "failed",
+                            error: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                    try {
+                        if (!result.changedFiles?.length) {
+                            await execFileAsync("git", ["-C", root, "worktree", "remove", "--force", worktreePath]);
+                        }
+                    }
+                    catch {
+                        // keep worktree if cleanup fails
+                    }
+                    resolve(result);
+                });
+            });
+            this.active.set(id, { record, promise });
+            spawned.push(record);
+        }
+        return spawned;
+    }
+    async wait() {
+        const entries = [...this.active.values()];
+        if (!entries.length)
+            return [];
+        const settled = await Promise.all(entries.map((entry) => entry.promise));
+        for (const agent of settled) {
+            this.active.delete(agent.id);
+        }
+        return settled;
+    }
+    async cleanupAll() {
+        const root = await this.rootPath().catch(() => null);
+        if (!root)
+            return;
+        const entries = [...this.active.values()];
+        this.active.clear();
+        for (const entry of entries) {
+            try {
+                await execFileAsync("git", ["-C", root, "worktree", "remove", "--force", entry.record.worktreePath]);
+            }
+            catch {
+                // ignore cleanup failure
+            }
+        }
+    }
+}

package/dist/terminal.d.ts

@@ -0,0 +1,29 @@
+import type { ModelAction, ToolCall, ToolResult } from "./types.js";
+export declare class TerminalRenderer {
+    private readonly enabled;
+    private readonly showLlmDetails;
+    private readonly showToolResults;
+    constructor(enabled: boolean, showLlmDetails?: boolean, showToolResults?: boolean);
+    private line;
+    step(index: number, name: string): void;
+    llmStart(model: string, prompt?: string): void;
+    llmAction(action: ModelAction, stepName?: string): void;
+    toolStart(call: ToolCall): void;
+    toolResult(result: ToolResult): void;
+    clarifyPrompt(question: string): void;
+    clarifyAnswer(answer: string): void;
+    finalAnswer(answer: string): void;
+    warning(message: string): void;
+}
+export declare class SessionLogger {
+    private readonly filePath;
+    private llmExchanges;
+    private toolCalls;
+    private clarifyCount;
+    constructor(filePath: string);
+    start(sessionId: string, task: string, repoPath: string): Promise<void>;
+    llm(stepIndex: number, stepName: string, prompt: string, rawResponse: string, model: string): Promise<void>;
+    tool(call: ToolCall): Promise<void>;
+    clarify(question: string, answer?: string): Promise<void>;
+    final(answer: string, totalSteps: number): Promise<void>;
+}

package/dist/terminal.js

@@ -0,0 +1,242 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const BLUE = "\x1b[34m";
+const MAGENTA = "\x1b[35m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+async function appendLogLine(filePath, text) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${text}\n`, "utf8");
+}
+function stats(label, text) {
+    const chars = text.length;
+    const lines = text ? text.split("\n").length : 0;
+    const bytes = Buffer.byteLength(text, "utf8");
+    return [`${label}_chars: ${chars}`, `${label}_lines: ${lines}`, `${label}_bytes: ${bytes}`];
+}
+function formatJsonIfPossible(text) {
+    try {
+        return JSON.stringify(JSON.parse(text), null, 2);
+    }
+    catch {
+        const objects = extractJsonObjects(text);
+        if (!objects.length)
+            return text;
+        return objects
+            .map((value, index) => [`JSON_OBJECT_${index + 1}`, JSON.stringify(value, null, 2)].join("\n"))
+            .join(`\n${"-".repeat(40)}\n`);
+    }
+}
+function extractJsonObjects(text) {
+    const values = [];
+    let cursor = 0;
+    while (cursor < text.length) {
+        const start = text.indexOf("{", cursor);
+        if (start < 0)
+            break;
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        let end = -1;
+        for (let i = start; i < text.length; i++) {
+            const char = text[i];
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (char === "\\") {
+                    escaped = true;
+                }
+                else if (char === "\"") {
+                    inString = false;
+                }
+                continue;
+            }
+            if (char === "\"") {
+                inString = true;
+                continue;
+            }
+            if (char === "{")
+                depth++;
+            if (char === "}")
+                depth--;
+            if (depth === 0) {
+                end = i + 1;
+                break;
+            }
+        }
+        if (end < 0)
+            break;
+        const candidate = text.slice(start, end);
+        try {
+            values.push(JSON.parse(candidate));
+        }
+        catch {
+            // ignore invalid object candidate and continue scanning
+        }
+        cursor = end;
+    }
+    return values;
+}
+function color(enabled, code, text) {
+    return enabled ? `${code}${text}${RESET}` : text;
+}
+export class TerminalRenderer {
+    enabled;
+    showLlmDetails;
+    showToolResults;
+    constructor(enabled, showLlmDetails = false, showToolResults = false) {
+        this.enabled = enabled;
+        this.showLlmDetails = showLlmDetails;
+        this.showToolResults = showToolResults;
+    }
+    line(text = "") {
+        process.stdout.write(`${text}\n`);
+    }
+    step(index, name) {
+        this.line(color(this.enabled, `${BOLD}${CYAN}`, `\n🧭 Step ${index} · ${name}`));
+    }
+    llmStart(model, prompt) {
+        this.line(color(this.enabled, `${BOLD}${BLUE}`, `🤖 [LLM:${model}] Calling remote model...`));
+        if (!prompt?.trim())
+            return;
+        const lines = prompt.split("\n").length;
+        const chars = prompt.length;
+        if (this.showLlmDetails) {
+            this.line(color(this.enabled, `${BOLD}${BLUE}`, `[LLM] Prompt (${lines} lines, ${chars} chars)`));
+            this.line(color(this.enabled, DIM, prompt));
+            return;
+        }
+        this.line(color(this.enabled, DIM, `🤖 Prompt collapsed by default (${lines} lines, ${chars} chars). Full prompt/response logging is still enabled. Use --show-llm-details to expand.`));
+    }
+    llmAction(action, stepName) {
+        if (stepName) {
+            this.line(color(this.enabled, `${BOLD}${CYAN}`, `🧭 Resolved Step · ${stepName}`));
+        }
+        if (action.type === "clarify") {
+            this.line(color(this.enabled, `${BOLD}${MAGENTA}`, `🤖 [LLM] Clarification requested: ${action.question}`));
+            return;
+        }
+        this.line(color(this.enabled, `${BOLD}${BLUE}`, `🤖 [LLM] Next action: ${action.toolCall.tool}`));
+        this.line(color(this.enabled, DIM, `      args: ${JSON.stringify(action.toolCall.args)}`));
+    }
+    toolStart(call) {
+        this.line(color(this.enabled, `${BOLD}${YELLOW}`, `🛠️ [TOOL] ${call.tool}`));
+        this.line(color(this.enabled, DIM, `      args: ${JSON.stringify(call.args)}`));
+    }
+    toolResult(result) {
+        const tone = result.ok ? `${BOLD}${GREEN}` : `${BOLD}${RED}`;
+        this.line(color(this.enabled, tone, `📦 [RESULT] ${result.summary}`));
+        if (this.showToolResults && result.output)
+            this.line(color(this.enabled, DIM, result.output));
+        if (this.showToolResults && result.error)
+            this.line(color(this.enabled, `${BOLD}${RED}`, result.error));
+    }
+    clarifyPrompt(question) {
+        this.line(color(this.enabled, `${BOLD}${MAGENTA}`, `💬 [CLARIFY] ${question}`));
+    }
+    clarifyAnswer(answer) {
+        this.line(color(this.enabled, `${BOLD}${MAGENTA}`, `🧑 [YOU] ${answer}`));
+    }
+    finalAnswer(answer) {
+        this.line(color(this.enabled, `${BOLD}${GREEN}`, `\n✅ Answer\n${answer}`));
+    }
+    warning(message) {
+        this.line(color(this.enabled, `${BOLD}${YELLOW}`, `⚠️ [WARN] ${message}`));
+    }
+}
+export class SessionLogger {
+    filePath;
+    llmExchanges = 0;
+    toolCalls = 0;
+    clarifyCount = 0;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async start(sessionId, task, repoPath) {
+        await appendLogLine(this.filePath, [
+            "=".repeat(88),
+            "SESSION START",
+            "-".repeat(88),
+            `session_id: ${sessionId}`,
+            `task: ${task}`,
+            `repo: ${repoPath}`,
+            "=".repeat(88),
+            "",
+        ].join("\n"));
+    }
+    async llm(stepIndex, stepName, prompt, rawResponse, model) {
+        this.llmExchanges += 1;
+        const formattedResponse = formatJsonIfPossible(rawResponse);
+        await appendLogLine(this.filePath, [
+            "=".repeat(88),
+            `🧭 STEP ${stepIndex} · ${stepName}`,
+            "🤖 LLM EXCHANGE",
+            "-".repeat(88),
+            `step: ${stepIndex}`,
+            `step_name: ${stepName}`,
+            `model: ${model}`,
+            ...stats("prompt", prompt),
+            "-".repeat(88),
+            "PROMPT",
+            "-".repeat(88),
+            prompt,
+            "-".repeat(88),
+            ...stats("response", formattedResponse),
+            "-".repeat(88),
+            "RESPONSE",
+            "-".repeat(88),
+            formattedResponse,
+            "=".repeat(88),
+            "",
+        ].join("\n"));
+    }
+    async tool(call) {
+        this.toolCalls += 1;
+        await appendLogLine(this.filePath, [
+            "=".repeat(88),
+            "🛠️ TOOL CALL",
+            "-".repeat(88),
+            `tool: ${call.tool}`,
+            `args: ${JSON.stringify(call.args)}`,
+            "=".repeat(88),
+            "",
+        ].join("\n"));
+    }
+    async clarify(question, answer) {
+        this.clarifyCount += 1;
+        await appendLogLine(this.filePath, [
+            "=".repeat(88),
+            "💬 CLARIFICATION",
+            "-".repeat(88),
+            `question: ${question}`,
+            `answer: ${answer || ""}`,
+            "=".repeat(88),
+            "",
+        ].join("\n"));
+    }
+    async final(answer, totalSteps) {
+        await appendLogLine(this.filePath, [
+            "=".repeat(88),
+            "📘 SESSION SUMMARY",
+            "-".repeat(88),
+            `total_steps: ${totalSteps}`,
+            `llm_exchanges: ${this.llmExchanges}`,
+            `tool_calls: ${this.toolCalls}`,
+            `clarifications: ${this.clarifyCount}`,
+            "=".repeat(88),
+            "",
+            "=".repeat(88),
+            "✅ FINAL ANSWER",
+            "-".repeat(88),
+            answer,
+            "=".repeat(88),
+            "",
+        ].join("\n"));
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolCall, ToolResult } from "./types.js";
+export declare function runTool(repoPath: string, call: ToolCall): Promise<ToolResult>;

package/dist/tools.js

@@ -0,0 +1,136 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+const MAX_OUTPUT = 12000;
+const MAX_MATCHES = 50;
+const SKIPPED_DIRECTORIES = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    path.join(".codex", "logs"),
+    path.join(".codex", "subagents"),
+]);
+const DANGEROUS_COMMAND = /\b(rm\s+-rf|sudo|shutdown|reboot|mkfs|dd\s+if=|curl\b|wget\b|ssh\b|scp\b|sftp\b|nc\b|ncat\b|telnet\b|git\s+push\b|git\s+reset\s+--hard\b)\b/;
+function defaultShell() {
+    if (process.platform === "win32") {
+        return process.env.ComSpec || "cmd.exe";
+    }
+    return process.env.SHELL || "/bin/sh";
+}
+function insideRepo(repoPath, targetPath) {
+    const repo = path.resolve(repoPath);
+    const full = path.resolve(repo, targetPath);
+    if (full !== repo && !full.startsWith(repo + path.sep)) {
+        throw new Error(`Path escapes repo: ${targetPath}`);
+    }
+    return full;
+}
+function trim(text) {
+    return text.length > MAX_OUTPUT ? text.slice(0, MAX_OUTPUT) + "\n...[truncated]" : text;
+}
+async function walk(dir, base = "") {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        const rel = path.join(base, entry.name);
+        if (SKIPPED_DIRECTORIES.has(rel) || (base === "" && SKIPPED_DIRECTORIES.has(entry.name)))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await walk(full, rel)));
+        else
+            out.push(rel);
+    }
+    return out;
+}
+export async function runTool(repoPath, call) {
+    try {
+        switch (call.tool) {
+            case "list_files": {
+                const files = await walk(repoPath);
+                return { ok: true, summary: `Found ${files.length} files`, output: files.slice(0, 300).join("\n") };
+            }
+            case "read_file": {
+                const file = String(call.args.path || "");
+                const content = await fs.readFile(insideRepo(repoPath, file), "utf8");
+                return { ok: true, summary: `Read ${file}`, output: trim(content) };
+            }
+            case "search_files": {
+                const query = String(call.args.query || "").toLowerCase();
+                if (!query)
+                    return { ok: false, summary: "Missing query", error: "query is required" };
+                const files = await walk(repoPath);
+                const matches = [];
+                for (const rel of files) {
+                    const content = await fs.readFile(insideRepo(repoPath, rel), "utf8").catch(() => "");
+                    const lines = content.split(/\r?\n/);
+                    for (let i = 0; i < lines.length; i++) {
+                        if (lines[i].toLowerCase().includes(query)) {
+                            matches.push(`${rel}:${i + 1}: ${lines[i]}`);
+                        }
+                        if (matches.length >= MAX_MATCHES)
+                            break;
+                    }
+                    if (matches.length >= MAX_MATCHES)
+                        break;
+                }
+                return { ok: true, summary: `Found ${matches.length} matches`, output: matches.join("\n") || "No matches" };
+            }
+            case "write_file": {
+                const file = String(call.args.path || "");
+                const content = String(call.args.content || "");
+                const full = insideRepo(repoPath, file);
+                await fs.mkdir(path.dirname(full), { recursive: true });
+                await fs.writeFile(full, content, "utf8");
+                return { ok: true, summary: `Wrote ${file}` };
+            }
+            case "edit_file": {
+                const file = String(call.args.path || "");
+                const oldText = String(call.args.oldText || "");
+                const newText = String(call.args.newText || "");
+                if (!file || !oldText) {
+                    return { ok: false, summary: "Missing edit args", error: "path and oldText are required" };
+                }
+                const full = insideRepo(repoPath, file);
+                const current = await fs.readFile(full, "utf8");
+                if (!current.includes(oldText)) {
+                    return { ok: false, summary: `Target text not found in ${file}`, error: "oldText not found" };
+                }
+                const updated = current.replace(oldText, newText);
+                await fs.writeFile(full, updated, "utf8");
+                return { ok: true, summary: `Edited ${file}` };
+            }
+            case "run_command": {
+                const command = String(call.args.command || "");
+                if (!command)
+                    return { ok: false, summary: "Missing command", error: "command is required" };
+                if (DANGEROUS_COMMAND.test(command)) {
+                    return { ok: false, summary: "Blocked dangerous command", error: command };
+                }
+                const { stdout, stderr } = await execAsync(command, {
+                    cwd: repoPath,
+                    shell: defaultShell(),
+                    timeout: 20000,
+                    maxBuffer: 1024 * 1024,
+                    env: process.env,
+                });
+                return { ok: true, summary: `Ran ${command}`, output: trim(`${stdout}${stderr}`.trim()) };
+            }
+            case "write_memory":
+            case "spawn_subagents":
+            case "wait_subagents":
+                return { ok: false, summary: `Tool ${call.tool} must be handled by the agent runtime`, error: call.tool };
+            case "finish":
+                return { ok: true, summary: "Finished" };
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: `Tool ${call.tool} failed`,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+export type ToolName = "list_files" | "read_file" | "search_files" | "write_file" | "edit_file" | "run_command" | "write_memory" | "spawn_subagents" | "wait_subagents" | "finish";
+export interface ToolCall {
+    tool: ToolName;
+    args: Record<string, unknown>;
+}
+export interface ClarifyAction {
+    type: "clarify";
+    question: string;
+}
+export interface ToolAction {
+    type: "tool";
+    toolCall: ToolCall;
+}
+export type ModelAction = ClarifyAction | ToolAction;
+export interface ToolResult {
+    ok: boolean;
+    summary: string;
+    output?: string;
+    error?: string;
+}
+export interface ConversationTurn {
+    role: "user" | "assistant";
+    kind: "task" | "clarification_question" | "clarification_answer";
+    content: string;
+}
+export interface Step {
+    index: number;
+    name?: string;
+    rationale: string;
+    model?: string;
+    action: ModelAction;
+    result?: ToolResult;
+    userResponse?: string;
+}
+export interface MemoryNote {
+    slug: string;
+    title: string;
+    category: string;
+    path: string;
+    preview: string;
+}
+export interface ProjectMemory {
+    summary: string | null;
+    relevantNotes: MemoryNote[];
+}
+export type SubagentStatus = "running" | "completed" | "failed";
+export interface SubagentRecord {
+    id: string;
+    name: string;
+    task: string;
+    status: SubagentStatus;
+    worktreePath: string;
+    summary?: string;
+    answer?: string;
+    changedFiles?: string[];
+    error?: string;
+}
+export interface Session {
+    id: string;
+    task: string;
+    repoPath: string;
+    maxSteps: number;
+    depth: number;
+    interactive: boolean;
+    turns: ConversationTurn[];
+    steps: Step[];
+    skillName?: string;
+    skillContent?: string;
+    memorySummary?: string | null;
+    memoryNotes?: MemoryNote[];
+    subagents: SubagentRecord[];
+}
+export interface ModelDecision {
+    rationale: string;
+    action: ModelAction;
+    model?: string;
+    rawResponse?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};