mini-codex 0.1.0

package/dist/loop.js

@@ -0,0 +1,221 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { createProvider } from "./providers/index.js";
+import { buildPromptInput } from "./prompt.js";
+import { AgentRuntime } from "./runtime.js";
+import { selectSkill } from "./skills.js";
+import { SessionLogger } from "./terminal.js";
+function repeatedSteps(session, window = 3) {
+    if (session.steps.length < window)
+        return false;
+    const tail = session.steps.slice(-window).map((step) => step.action.type === "tool"
+        ? `${step.action.toolCall.tool}:${JSON.stringify(step.action.toolCall.args)}`
+        : `clarify:${step.action.question}:${step.userResponse || ""}`);
+    return new Set(tail).size === 1;
+}
+function finalAnswer(session) {
+    const lastStep = session.steps.at(-1);
+    if (!lastStep)
+        return null;
+    if (lastStep.action.type === "clarify") {
+        return lastStep.userResponse ? null : `Need clarification: ${lastStep.action.question}`;
+    }
+    const answer = lastStep.action.toolCall.args.answer;
+    return typeof answer === "string" && answer.trim() ? answer.trim() : null;
+}
+function stepNameForAction(action) {
+    if (action.type === "clarify")
+        return "Clarify Request";
+    switch (action.toolCall.tool) {
+        case "list_files":
+            return "List Files";
+        case "read_file":
+            return "Read File";
+        case "search_files":
+            return "Search Files";
+        case "write_file":
+            return "Write File";
+        case "edit_file":
+            return "Edit File";
+        case "run_command":
+            return "Run Command";
+        case "write_memory":
+            return "Write Memory";
+        case "spawn_subagents":
+            return "Spawn Sub-Agents";
+        case "wait_subagents":
+            return "Wait For Sub-Agents";
+        case "finish":
+            return "Finish";
+    }
+}
+function timestampFileName(date = new Date()) {
+    const yyyy = String(date.getFullYear());
+    const mm = String(date.getMonth() + 1).padStart(2, "0");
+    const dd = String(date.getDate()).padStart(2, "0");
+    const hh = String(date.getHours()).padStart(2, "0");
+    const min = String(date.getMinutes()).padStart(2, "0");
+    const ss = String(date.getSeconds()).padStart(2, "0");
+    const ms = String(date.getMilliseconds()).padStart(3, "0");
+    return `${yyyy}-${mm}-${dd}_${hh}-${min}-${ss}-${ms}.log`;
+}
+function initialStepName(index) {
+    return index === 1 ? "Start" : "Continue";
+}
+export async function runLoop(task, repoPath, options = {}) {
+    const maxSteps = options.maxSteps ?? 12;
+    const depth = options.depth ?? 0;
+    const interactive = options.interactive ?? false;
+    const renderer = options.renderer ?? null;
+    const provider = options.provider ?? createProvider();
+    const sessionId = crypto.randomUUID();
+    const logger = new SessionLogger(path.join(repoPath, ".codex", "logs", timestampFileName()));
+    const skill = await selectSkill(task, repoPath);
+    const session = {
+        id: sessionId,
+        task: task.trim(),
+        repoPath,
+        maxSteps,
+        depth,
+        interactive,
+        turns: [{ role: "user", kind: "task", content: task.trim() }],
+        steps: [],
+        skillName: skill?.name,
+        skillContent: skill?.content,
+        subagents: [],
+    };
+    await logger.start(sessionId, task.trim(), repoPath);
+    const runtime = new AgentRuntime(session);
+    await runtime.refreshMemory(session.task);
+    try {
+        for (let i = 1; i <= maxSteps; i++) {
+            if (repeatedSteps(session)) {
+                session.steps.push({
+                    index: i,
+                    name: "Finish",
+                    rationale: "Stopping because the same action repeated without progress.",
+                    action: { type: "tool", toolCall: { tool: "finish", args: { answer: "Stopped because the same action repeated without progress." } } },
+                    result: { ok: true, summary: "Finished due to repetition detection." },
+                });
+                break;
+            }
+            renderer?.step(i, initialStepName(i));
+            const prompt = buildPromptInput(session);
+            const model = provider.getModelName();
+            renderer?.llmStart(model, prompt);
+            const decision = await provider.next(session, prompt);
+            const stepName = stepNameForAction(decision.action);
+            await logger.llm(i, stepName, prompt, decision.rawResponse || JSON.stringify(decision), decision.model || model);
+            renderer?.llmAction(decision.action, stepName);
+            if (decision.action.type === "clarify") {
+                session.turns.push({ role: "assistant", kind: "clarification_question", content: decision.action.question });
+                let userResponse;
+                if (interactive && options.askUser) {
+                    renderer?.clarifyPrompt(decision.action.question);
+                    userResponse = await options.askUser(decision.action.question);
+                    renderer?.clarifyAnswer(userResponse);
+                    session.turns.push({ role: "user", kind: "clarification_answer", content: userResponse });
+                }
+                else {
+                    renderer?.warning(`Clarification requested but interactive input is unavailable: ${decision.action.question}`);
+                }
+                session.steps.push({
+                    index: i,
+                    name: stepName,
+                    rationale: decision.rationale,
+                    model: decision.model || model,
+                    action: decision.action,
+                    userResponse,
+                });
+                await logger.clarify(decision.action.question, userResponse);
+                if (!userResponse)
+                    break;
+                continue;
+            }
+            renderer?.toolStart(decision.action.toolCall);
+            const result = await runtime.execute(decision.action.toolCall);
+            renderer?.toolResult(result);
+            await logger.tool(decision.action.toolCall);
+            session.steps.push({
+                index: i,
+                name: stepName,
+                rationale: decision.rationale,
+                model: decision.model || model,
+                action: decision.action,
+                result,
+            });
+            if (decision.action.toolCall.tool === "write_memory") {
+                await runtime.refreshMemory(session.task);
+            }
+            if (decision.action.toolCall.tool === "finish")
+                break;
+        }
+    }
+    finally {
+        await runtime.cleanup();
+    }
+    const answer = finalAnswer(session);
+    if (answer) {
+        await logger.final(answer, session.steps.length);
+    }
+    return session;
+}
+export function renderSession(session, options = {}) {
+    const showToolResults = options.showToolResults ?? true;
+    const lines = [];
+    const touchedFiles = new Set();
+    const commands = [];
+    const answer = finalAnswer(session);
+    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")) {
+            touchedFiles.add(p);
+        }
+        const c = step.action.toolCall.args.command;
+        if (typeof c === "string" && step.action.toolCall.tool === "run_command") {
+            commands.push(c);
+        }
+    }
+    lines.push("# mini-codex report");
+    lines.push(`Task: ${session.task}`);
+    lines.push(`Repo: ${session.repoPath}`);
+    lines.push(`Session: ${session.id}`);
+    lines.push(`Depth: ${session.depth}`);
+    lines.push(`Steps: ${session.steps.length}/${session.maxSteps}`);
+    lines.push(`Skill: ${session.skillName || "none"}`);
+    lines.push(`Touched files: ${touchedFiles.size ? [...touchedFiles].join(", ") : "none"}`);
+    lines.push(`Commands run: ${commands.length ? commands.join(" | ") : "none"}`);
+    lines.push(`Sub-agents: ${session.subagents.length ? session.subagents.map((agent) => `${agent.name}:${agent.status}`).join(", ") : "none"}`);
+    lines.push("");
+    if (answer) {
+        lines.push("## Answer");
+        lines.push(answer);
+        lines.push("");
+    }
+    for (const step of session.steps) {
+        lines.push(`## Step ${step.index}`);
+        if (step.name)
+            lines.push(`Name: ${step.name}`);
+        if (step.model)
+            lines.push(`Model: ${step.model}`);
+        lines.push(`Rationale: ${step.rationale}`);
+        if (step.action.type === "clarify") {
+            lines.push("Action: clarify");
+            lines.push(`Question: ${step.action.question}`);
+            lines.push(`User response: ${step.userResponse || "No response"}`);
+        }
+        else {
+            lines.push(`Tool: ${step.action.toolCall.tool}`);
+            lines.push(`Args: ${JSON.stringify(step.action.toolCall.args)}`);
+            lines.push(`Result: ${step.result?.summary || "No result"}`);
+            if (showToolResults && step.result?.output)
+                lines.push(step.result.output);
+            if (showToolResults && step.result?.error)
+                lines.push(`ERROR: ${step.result.error}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/memory.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryNote, ProjectMemory } from "./types.js";
+export declare function loadProjectMemory(repoPath: string, task: string): Promise<ProjectMemory>;
+export declare function writeProjectMemory(repoPath: string, input: {
+    category: string;
+    title: string;
+    content: string;
+}): Promise<MemoryNote>;

package/dist/memory.js

@@ -0,0 +1,84 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const MEMORY_ROOT = path.join(".codex", "memory");
+const NOTES_DIR = path.join(MEMORY_ROOT, "notes");
+const SUMMARY_FILE = path.join(MEMORY_ROOT, "project.md");
+function tokenize(text) {
+    return [...new Set(text.toLowerCase().split(/[^a-z0-9_]+/).filter((token) => token.length >= 3))];
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+function preview(content) {
+    const text = content.replace(/\s+/g, " ").trim();
+    return text.length > 180 ? `${text.slice(0, 177)}...` : text;
+}
+function noteScore(taskTokens, text) {
+    const haystack = text.toLowerCase();
+    return taskTokens.reduce((score, token) => score + (haystack.includes(token) ? 1 : 0), 0);
+}
+async function ensureMemoryDir(repoPath) {
+    await fs.mkdir(path.join(repoPath, NOTES_DIR), { recursive: true });
+}
+export async function loadProjectMemory(repoPath, task) {
+    const summaryPath = path.join(repoPath, SUMMARY_FILE);
+    const notesRoot = path.join(repoPath, NOTES_DIR);
+    const summary = await fs.readFile(summaryPath, "utf8").catch(() => null);
+    const taskTokens = tokenize(task);
+    const entries = await fs.readdir(notesRoot, { withFileTypes: true }).catch(() => []);
+    const scored = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const fullPath = path.join(notesRoot, entry.name);
+        const raw = await fs.readFile(fullPath, "utf8").catch(() => "");
+        const body = raw.replace(/^---[\s\S]*?---\n?/, "").trim();
+        const titleMatch = raw.match(/^title:\s*(.+)$/m);
+        const categoryMatch = raw.match(/^category:\s*(.+)$/m);
+        const title = titleMatch?.[1]?.trim() || entry.name.replace(/\.md$/, "");
+        const category = categoryMatch?.[1]?.trim() || "finding";
+        const note = {
+            slug: entry.name.replace(/\.md$/, ""),
+            title,
+            category,
+            path: path.relative(repoPath, fullPath),
+            preview: preview(body),
+        };
+        scored.push({ note, score: noteScore(taskTokens, `${title}\n${body}`) });
+    }
+    scored.sort((a, b) => b.score - a.score || a.note.title.localeCompare(b.note.title));
+    const relevantNotes = scored.filter((item) => item.score > 0).slice(0, 3).map((item) => item.note);
+    return { summary, relevantNotes };
+}
+export async function writeProjectMemory(repoPath, input) {
+    await ensureMemoryDir(repoPath);
+    const slugBase = slugify(input.title) || "memory-note";
+    const slug = `${new Date().toISOString().slice(0, 10)}-${slugBase}`;
+    const notePath = path.join(repoPath, NOTES_DIR, `${slug}.md`);
+    const now = new Date().toISOString();
+    const body = `---\ntitle: ${input.title}\ncategory: ${input.category}\ncreatedAt: ${now}\n---\n\n${input.content.trim()}\n`;
+    await fs.writeFile(notePath, body, "utf8");
+    const notes = await fs.readdir(path.join(repoPath, NOTES_DIR)).catch(() => []);
+    const bullets = [];
+    for (const name of notes.filter((name) => name.endsWith(".md")).sort()) {
+        const fullPath = path.join(repoPath, NOTES_DIR, name);
+        const raw = await fs.readFile(fullPath, "utf8").catch(() => "");
+        const title = raw.match(/^title:\s*(.+)$/m)?.[1]?.trim() || name.replace(/\.md$/, "");
+        const category = raw.match(/^category:\s*(.+)$/m)?.[1]?.trim() || "finding";
+        const bodyText = raw.replace(/^---[\s\S]*?---\n?/, "").trim();
+        bullets.push(`- [${category}] ${title}: ${preview(bodyText)}`);
+    }
+    const summary = ["# Project Memory", "", ...bullets].join("\n");
+    await fs.writeFile(path.join(repoPath, SUMMARY_FILE), `${summary}\n`, "utf8");
+    return {
+        slug,
+        title: input.title,
+        category: input.category,
+        path: path.relative(repoPath, notePath),
+        preview: preview(input.content),
+    };
+}

package/dist/model.d.ts

@@ -0,0 +1,5 @@
+import type { ModelDecision, Session } from "./types.js";
+export declare class Model {
+    private client;
+    next(session: Session): Promise<ModelDecision>;
+}

package/dist/model.js

@@ -0,0 +1,69 @@
+import OpenAI from "openai";
+import { z } from "zod";
+const MODEL = process.env.MINI_CODEX_MODEL || "gpt-5";
+const tools = [
+    "list_files",
+    "read_file",
+    "search_files",
+    "write_file",
+    "edit_file",
+    "run_command",
+    "finish",
+];
+const schema = z.object({
+    rationale: z.string(),
+    toolCall: z.object({
+        tool: z.enum(tools),
+        args: z.record(z.unknown()),
+    }),
+});
+const SYSTEM_PROMPT = `You are a useful mini coding agent.
+Work inside one repo only.
+Choose exactly one tool call at a time.
+Prefer list_files/search_files/read_file before write_file/edit_file.
+Prefer edit_file for targeted changes and write_file for full file creation/replacement.
+Use run_command for validation when useful.
+Use finish when done, blocked, or when user input is needed.
+Return only JSON.`;
+export class Model {
+    client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    async next(session) {
+        const history = session.steps
+            .map((step) => `Step ${step.index}\nRationale: ${step.rationale}\nTool: ${step.toolCall.tool}\nArgs: ${JSON.stringify(step.toolCall.args)}\nResult: ${step.result.summary}\nOutput: ${step.result.output || step.result.error || ""}`)
+            .join("\n\n");
+        const response = await this.client.responses.create({
+            model: MODEL,
+            input: [
+                { role: "system", content: SYSTEM_PROMPT },
+                {
+                    role: "user",
+                    content: `Task: ${session.task}\nRepo: ${session.repoPath}\nPast steps:\n${history || "None yet."}`,
+                },
+            ],
+            text: {
+                format: {
+                    type: "json_schema",
+                    name: "decision",
+                    schema: {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            rationale: { type: "string" },
+                            toolCall: {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    tool: { type: "string", enum: [...tools] },
+                                    args: { type: "object", additionalProperties: true },
+                                },
+                                required: ["tool", "args"],
+                            },
+                        },
+                        required: ["rationale", "toolCall"],
+                    },
+                },
+            },
+        });
+        return schema.parse(JSON.parse(response.output_text));
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,3 @@
+import type { Session } from "./types.js";
+export declare function buildPromptInput(session: Session): string;
+export declare function providerInstructions(depth: number): string;

package/dist/prompt.js

@@ -0,0 +1,91 @@
+function formatStep(step) {
+    if (step.action.type === "clarify") {
+        return `Step ${step.index}\nRationale: ${step.rationale}\nClarification question: ${step.action.question}\nUser response: ${step.userResponse || "No response"}`;
+    }
+    const output = step.result?.output || step.result?.error || "";
+    return `Step ${step.index}\nRationale: ${step.rationale}\nTool: ${step.action.toolCall.tool}\nArgs: ${JSON.stringify(step.action.toolCall.args)}\nResult: ${step.result?.summary || "No result"}\nOutput: ${output}`;
+}
+function compactOlderSteps(session, keep = 4) {
+    if (session.steps.length <= keep)
+        return "None.";
+    return session.steps
+        .slice(0, -keep)
+        .map((step) => step.action.type === "clarify"
+        ? `Step ${step.index}: clarify -> ${step.action.question}${step.userResponse ? ` / ${step.userResponse}` : ""}`
+        : `Step ${step.index}: ${step.action.toolCall.tool} -> ${step.result?.summary || "No result"}`)
+        .join("\n");
+}
+function recentSteps(session, keep = 4) {
+    const recent = session.steps.slice(-keep);
+    return recent.length ? recent.map(formatStep).join("\n\n") : "None yet.";
+}
+function memoryBlock(session) {
+    const parts = [];
+    if (session.memorySummary?.trim()) {
+        parts.push(`Project memory summary:\n${session.memorySummary.trim()}`);
+    }
+    if (session.memoryNotes?.length) {
+        parts.push(`Relevant memory notes:\n${session.memoryNotes
+            .map((note) => `- [${note.category}] ${note.title} (${note.path}): ${note.preview}`)
+            .join("\n")}`);
+    }
+    return parts.length ? parts.join("\n\n") : "No relevant project memory.";
+}
+function conversationBlock(session) {
+    if (!session.turns.length)
+        return "No conversation history.";
+    const recent = session.turns.slice(-6);
+    return recent.map((turn) => `${turn.role} [${turn.kind}]: ${turn.content}`).join("\n");
+}
+function subagentBlock(session) {
+    if (!session.subagents.length)
+        return "No child agents.";
+    return session.subagents
+        .map((agent) => {
+        const extra = agent.status === "completed" ? agent.summary || agent.answer || "completed" : agent.error || agent.status;
+        return `- ${agent.name} [${agent.status}] task="${agent.task}" worktree=${agent.worktreePath}${extra ? ` summary=${extra}` : ""}`;
+    })
+        .join("\n");
+}
+export function buildPromptInput(session) {
+    const sections = [
+        `Task: ${session.task}`,
+        `Repo: ${session.repoPath}`,
+        `Agent depth: ${session.depth}`,
+        `Interactive clarifications: ${session.interactive ? "allowed" : "disabled"}`,
+        `Selected skill: ${session.skillName || "none"}`,
+        session.skillContent ? `Skill content:\n${session.skillContent}` : "Skill content: none",
+        `Conversation:\n${conversationBlock(session)}`,
+        memoryBlock(session),
+        `Child agents:\n${subagentBlock(session)}`,
+        `Older step summary:\n${compactOlderSteps(session)}`,
+        `Recent steps:\n${recentSteps(session)}`,
+    ];
+    return sections.join("\n\n");
+}
+export function providerInstructions(depth) {
+    const depthNote = depth > 0
+        ? "You are a child agent. Do not spawn more sub-agents and do not write project memory. Focus on your assigned subtask and finish with a concise answer."
+        : "You may use sub-agents for independent subtasks when parallel work would clearly help. Only write project memory for durable, high-confidence repo knowledge.";
+    return [
+        "You are a useful mini coding agent for one local repository.",
+        "Classify each task before acting: question-answering, investigation/debugging, code-change, or ambiguous.",
+        "If ambiguity materially blocks progress and interactive clarifications are allowed, you should usually ask a short clarification question using the clarify action before guessing.",
+        "For greetings or underspecified requests like hello, hi, help, or fix this, prefer a brief clarification question when interactive clarifications are allowed.",
+        "Do not ask clarification questions for facts that can be discovered from the repository itself.",
+        "For question-answering and investigation tasks, prefer read-only evidence gathering and provide a direct answer in finish.args.answer.",
+        "Prefer list_files and read_file for known files.",
+        "For targeted codebase search, prefer run_command with rg when available.",
+        'Good search patterns include: rg -n "login" src and rg "auth" .',
+        "Use search_files as the cross-platform fallback when rg is unavailable or CLI search is not needed.",
+        "Keep command usage repo-local and purposeful. Good command categories are search (rg), inspection (git status, git diff --stat, ls, pwd), and validation (build/test/typecheck commands).",
+        "Avoid arbitrary shell usage when file reads or search already answer the question.",
+        "Only modify files when the user clearly asks for a concrete repo change.",
+        depthNote,
+        "When using sub-agents, give each one a focused independent task and wait for their summaries before finalizing.",
+        "If interactive clarifications are disabled, do not use clarify; finish with a brief answer or clarification request instead.",
+        "If the request is ambiguous, underspecified, or not clearly a coding task, clarify or finish with a brief answer instead of guessing.",
+        "Use finish when done or blocked.",
+        "Return only JSON.",
+    ].join(" ");
+}

package/dist/providers/base.d.ts

@@ -0,0 +1,5 @@
+import type { Session, ModelDecision } from "../types.js";
+export interface ModelProvider {
+    getModelName(): string;
+    next(session: Session, prompt: string): Promise<ModelDecision>;
+}

package/dist/providers/base.js

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

package/dist/providers/index.d.ts

@@ -0,0 +1,2 @@
+import type { ModelProvider } from "./base.js";
+export declare function createProvider(): ModelProvider;

package/dist/providers/index.js

@@ -0,0 +1,13 @@
+import { OpenAIOAuthProvider } from "./openai.js";
+import { TestFixtureProvider } from "./test-fixture.js";
+export function createProvider() {
+    const provider = process.env.MINI_CODEX_PROVIDER || "openai-oauth";
+    switch (provider) {
+        case "openai-oauth":
+            return new OpenAIOAuthProvider();
+        case "test-fixture":
+            return new TestFixtureProvider();
+        default:
+            throw new Error(`Unsupported provider: ${provider}`);
+    }
+}

package/dist/providers/openai.d.ts

@@ -0,0 +1,9 @@
+import type { ModelDecision, Session } from "../types.js";
+import type { ModelProvider } from "./base.js";
+export declare function extractJsonObjects(text: string): string[];
+export declare function parseDecision(raw: string): ModelDecision;
+export declare class OpenAIOAuthProvider implements ModelProvider {
+    private auth;
+    getModelName(): string;
+    next(session: Session, prompt: string): Promise<ModelDecision>;
+}