orcastrator 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# orca
+
+Orca is a TypeScript CLI harness for coordinated agent planning and execution. It takes a goal or spec file, uses Claude to decompose it into a task graph, runs a pre-execution review pass with Codex, then executes each task via a persistent Codex thread — keeping full context across the entire run.
+
+**Pipeline:** Claude plans → Codex reviews task graph → Codex executes (persistent thread) → Codex post-run review
+
+## Install
+
+```bash
+bun install
+```
+
+## Usage
+
+### Inline goal (no file needed)
+
+```bash
+orca -p "add a settings screen to the iOS app"
+orca --prompt "refactor the auth module to use JWTs"
+orca --task "write unit tests for the payments service"
+```
+
+### Spec file
+
+```bash
+orca run --spec ./specs/myfeature.md
+```
+
+`run` is optional — the above is equivalent to:
+
+```bash
+orca --spec ./specs/myfeature.md
+```
+
+### Other commands
+
+```bash
+orca plan --spec ./specs/myfeature.md   # plan only, no execution
+orca status --run <run-id>              # show status for a specific run
+orca status                             # list all runs with status
+orca list                               # list all runs
+orca resume --run <run-id>             # resume an incomplete run
+orca cancel --run <run-id>             # cancel an active run
+orca pr-finalize --run <run-id>        # finalize a prepared pull request
+```
+
+### Hooks
+
+```bash
+orca -p "build X" \
+  --on-task-complete "echo task done: $ORCA_TASK_NAME" \
+  --on-complete "open -a Terminal" \
+  --on-error "say orca failed"
+```
+
+Available hooks: `--on-milestone`, `--on-task-complete`, `--on-task-fail`, `--on-complete`, `--on-error`
+
+## Run output
+
+Run state is written to:
+
+```text
+~/.orca/runs/<run-id>/status.json
+```
+
+Run IDs follow the format:
+
+```text
+<spec-slug>-<timestamp-ms>-<4char-hex>
+```
+
+## Dev
+
+```bash
+bun test              # run tests
+bun run src/cli/index.ts -p "your goal here"   # run without building
+```
+
+## Architecture
+
+| Step | Model | What |
+|------|-------|------|
+| Planning | Claude | Spec → task graph (dependency-aware DAG) |
+| Phase 4 review | Codex | Reviews task graph before execution; aborts on hard blockers |
+| Execution | Codex | Persistent thread runs each task (full context across tasks) |
+| Post-run review | Codex | Reviews all changes after execution completes |

package/dist/agents/claude/session.js

@@ -0,0 +1,137 @@
+import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
+function buildPlanningPrompt(spec, systemContext) {
+    return [
+        systemContext,
+        "You are decomposing a spec into an ordered task graph.",
+        "Return a JSON array of tasks.",
+        "Each task must include fields: id, name, description, dependencies, acceptance_criteria, status, retries, maxRetries.",
+        "Set status to \"pending\", retries to 0, and maxRetries to 3 for every task.",
+        "dependencies must be an array of task IDs.",
+        "acceptance_criteria must be an array of strings.",
+        "Return ONLY valid JSON. No markdown fences. No explanation.",
+        "Spec:",
+        spec
+    ].join("\n\n");
+}
+function buildTaskExecutionPrompt(task, runId, cwd) {
+    return [
+        "You are Orca's task execution assistant.",
+        `Run ID: ${runId}`,
+        `Repository CWD: ${cwd}`,
+        `Task ID: ${task.id}`,
+        `Task Name: ${task.name}`,
+        "Task Description:",
+        task.description,
+        "Acceptance Criteria:",
+        ...task.acceptance_criteria.map((criterion, index) => `${index + 1}. ${criterion}`),
+        "Execute this task and return ONLY JSON.",
+        "JSON schema:",
+        "{\"outcome\":\"done\"|\"failed\",\"error\"?:\"string\"}",
+        "If you cannot complete the task, return outcome=failed with a short error reason."
+    ].join("\n\n");
+}
+function extractAssistantText(message) {
+    if (!message || typeof message !== "object") {
+        return null;
+    }
+    const obj = message;
+    if (obj.type !== "assistant") {
+        return null;
+    }
+    const blocks = obj.message?.content;
+    if (!Array.isArray(blocks)) {
+        return null;
+    }
+    const text = blocks
+        .filter((block) => block.type === "text" && typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n")
+        .trim();
+    return text.length > 0 ? text : null;
+}
+function parseTaskArray(raw) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        throw new Error("Claude plan response was not a JSON array");
+    }
+    return parsed;
+}
+function parseTaskExecution(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("Claude task response was not a JSON object");
+    }
+    const candidate = parsed;
+    if (candidate.outcome !== "done" && candidate.outcome !== "failed") {
+        throw new Error("Claude task response missing valid outcome");
+    }
+    if (candidate.error !== undefined && typeof candidate.error !== "string") {
+        throw new Error("Claude task response error must be a string");
+    }
+    return {
+        outcome: candidate.outcome,
+        rawResponse: raw,
+        ...(typeof candidate.error === "string" ? { error: candidate.error } : {})
+    };
+}
+async function collectSessionResult(session) {
+    const assistantMessages = [];
+    let resultText = null;
+    for await (const message of session.stream()) {
+        const assistantText = extractAssistantText(message);
+        if (assistantText) {
+            assistantMessages.push(assistantText);
+        }
+        if (message.type === "result" &&
+            message.subtype === "success" &&
+            typeof message.result === "string") {
+            resultText = message.result;
+        }
+        if (message.type === "result" && message.subtype !== "success") {
+            const details = "errors" in message ? message.errors.join("; ") : "unknown error";
+            throw new Error(`Claude session failed (${message.subtype}): ${details}`);
+        }
+    }
+    const rawResponse = assistantMessages.length > 0
+        ? assistantMessages[assistantMessages.length - 1]
+        : resultText;
+    if (!rawResponse) {
+        throw new Error("Claude response was empty");
+    }
+    return rawResponse;
+}
+function getModel(config) {
+    return config?.claude?.model ?? process.env.ORCA_CLAUDE_MODEL ?? "claude-sonnet-4-5";
+}
+export async function planSpec(spec, systemContext) {
+    const session = unstable_v2_createSession({
+        model: getModel()
+    });
+    try {
+        const streamPromise = collectSessionResult(session);
+        await session.send(buildPlanningPrompt(spec, systemContext));
+        const rawResponse = await streamPromise;
+        return {
+            tasks: parseTaskArray(rawResponse),
+            rawResponse
+        };
+    }
+    finally {
+        session.close();
+    }
+}
+export async function executeTask(task, runId, config) {
+    const session = unstable_v2_createSession({
+        model: getModel(config),
+        permissionMode: "bypassPermissions",
+    });
+    try {
+        const streamPromise = collectSessionResult(session);
+        await session.send(buildTaskExecutionPrompt(task, runId, process.cwd()));
+        const rawResponse = await streamPromise;
+        return parseTaskExecution(rawResponse);
+    }
+    finally {
+        session.close();
+    }
+}

package/dist/agents/codex/index.js

@@ -0,0 +1 @@
+export { createCodexSession, planSpec, executeTask, } from "./session.js";

package/dist/agents/codex/session.js

@@ -0,0 +1,247 @@
+import { CodexClient } from "orca-codex-client";
+function buildPlanningPrompt(spec, systemContext) {
+    return [
+        systemContext,
+        "You are decomposing a spec into an ordered task graph.",
+        "Return a JSON array of tasks.",
+        "Each task must include fields: id, name, description, dependencies, acceptance_criteria, status, retries, maxRetries.",
+        'Set status to "pending", retries to 0, and maxRetries to 3 for every task.',
+        "dependencies must be an array of task IDs.",
+        "acceptance_criteria must be an array of strings.",
+        "Return ONLY valid JSON. No markdown fences. No explanation.",
+        "Spec:",
+        spec,
+    ].join("\n\n");
+}
+function buildTaskExecutionPrompt(task, runId, cwd) {
+    return [
+        "You are Orca's task execution assistant.",
+        `Run ID: ${runId}`,
+        `Repository CWD: ${cwd}`,
+        `Task ID: ${task.id}`,
+        `Task Name: ${task.name}`,
+        "Task Description:",
+        task.description,
+        "Acceptance Criteria:",
+        ...task.acceptance_criteria.map((criterion, index) => `${index + 1}. ${criterion}`),
+        "Execute this task. You have full shell access — run commands, read/write files, and do whatever is needed.",
+        "When done, output ONLY JSON on the last line:",
+        '{"outcome":"done"|"failed","error"?:"string"}',
+        "If you cannot complete the task, return outcome=failed with a short error reason.",
+    ].join("\n\n");
+}
+function extractAgentText(result) {
+    if (result.agentMessage.length > 0) {
+        return result.agentMessage;
+    }
+    const agentItems = result.items.filter((item) => item.type === "agentMessage");
+    if (agentItems.length > 0) {
+        const last = agentItems[agentItems.length - 1];
+        if (last !== undefined && "text" in last && typeof last.text === "string") {
+            return last.text;
+        }
+    }
+    throw new Error("Codex response was empty");
+}
+function extractJson(text) {
+    // Try to find JSON in the response — could be wrapped in markdown fences
+    const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    if (fenceMatch?.[1]) {
+        return fenceMatch[1].trim();
+    }
+    // Try the last line (common pattern: explanation then JSON)
+    const lines = text.trim().split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim() ?? "";
+        if (line.startsWith("{") || line.startsWith("[")) {
+            try {
+                JSON.parse(line);
+                return line;
+            }
+            catch {
+                // not valid JSON, keep looking
+            }
+        }
+    }
+    // Fall back to entire text
+    return text.trim();
+}
+function parseTaskArray(raw) {
+    const json = extractJson(raw);
+    const parsed = JSON.parse(json);
+    if (!Array.isArray(parsed)) {
+        throw new Error("Codex plan response was not a JSON array");
+    }
+    return parsed;
+}
+const POSITIVE_COMPLETION_PATTERNS = [
+    /\bdone\b/i,
+    /\bcomplet/i,
+    /\bsuccess/i,
+    /\bwrote\b/i,
+    /\bwritten\b/i,
+    /\bcreated\b/i,
+    /\bfinished\b/i,
+];
+const FAILURE_PATTERNS = [
+    /\berror\b/i,
+    /\bfailed?\b/i,
+    /\bcannot\b/i,
+    /\bunable\b/i,
+    /\bpermission denied\b/i,
+];
+function inferOutcomeFromText(raw) {
+    const hasFailure = FAILURE_PATTERNS.some((p) => p.test(raw));
+    if (hasFailure) {
+        return {
+            outcome: "failed",
+            rawResponse: raw,
+            error: "Codex did not emit a JSON completion marker; inferred failure from response text.",
+        };
+    }
+    // No failure indicators — assume done. Codex often narrates rather than emitting JSON,
+    // so false negatives here are more harmful than false positives.
+    if (!POSITIVE_COMPLETION_PATTERNS.some((p) => p.test(raw))) {
+        console.warn("[orca] Warning: Codex response had no clear completion marker; assuming done.");
+    }
+    return { outcome: "done", rawResponse: raw };
+}
+function parseTaskExecution(raw) {
+    let json;
+    let parsed;
+    try {
+        json = extractJson(raw);
+        parsed = JSON.parse(json);
+    }
+    catch {
+        // Codex did not emit a JSON completion marker — fall back to text inference.
+        return inferOutcomeFromText(raw);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return inferOutcomeFromText(raw);
+    }
+    const candidate = parsed;
+    if (candidate.outcome !== "done" && candidate.outcome !== "failed") {
+        return inferOutcomeFromText(raw);
+    }
+    if (candidate.error !== undefined && typeof candidate.error !== "string") {
+        throw new Error("Codex task response error must be a string");
+    }
+    return {
+        outcome: candidate.outcome,
+        rawResponse: raw,
+        ...(typeof candidate.error === "string" ? { error: candidate.error } : {}),
+    };
+}
+function getModel(config) {
+    return config?.codex?.model ?? process.env.ORCA_CODEX_MODEL ?? "gpt-5.3-codex";
+}
+function getCodexPath() {
+    return (process.env.ORCA_CODEX_PATH ??
+        `${process.env.HOME}/.nvm/versions/node/v22.22.0/bin/codex`);
+}
+export async function createCodexSession(cwd, config) {
+    const client = new CodexClient({
+        codexPath: getCodexPath(),
+        model: getModel(config),
+        cwd,
+        approvalPolicy: "never",
+        sandbox: "workspace-write",
+    });
+    await client.connect();
+    const thread = await client.startThread({});
+    const threadId = thread.id;
+    return {
+        threadId,
+        async planSpec(spec, systemContext) {
+            const result = await client.runTurn({
+                threadId,
+                input: [{ type: "text", text: buildPlanningPrompt(spec, systemContext) }],
+            });
+            const rawResponse = extractAgentText(result);
+            return {
+                tasks: parseTaskArray(rawResponse),
+                rawResponse,
+            };
+        },
+        async executeTask(task, runId) {
+            const result = await client.runTurn({
+                threadId,
+                input: [
+                    {
+                        type: "text",
+                        text: buildTaskExecutionPrompt(task, runId, cwd),
+                    },
+                ],
+            });
+            const rawResponse = extractAgentText(result);
+            return parseTaskExecution(rawResponse);
+        },
+        async consultTaskGraph(tasks) {
+            const taskGraphJson = JSON.stringify(tasks, null, 2);
+            const prompt = [
+                "Review this Orca task graph before execution.",
+                "Flag any: missing steps, wrong dependency order, tasks that are underdefined, or potential blockers.",
+                "",
+                "Set ok: false ONLY if there is a hard blocking issue — dependency cycle, circular reference, a task that cannot possibly run as defined, or a critical missing step that would cause the run to fail.",
+                "For minor issues (ambiguous wording, style preferences, nice-to-haves): list them in issues but set ok: true.",
+                "If the graph looks generally reasonable and executable, set ok: true even if you have minor suggestions.",
+                "",
+                "Be brief. Output JSON on the last line: { \"issues\": [...], \"ok\": boolean }",
+                "",
+                "Task graph:",
+                taskGraphJson,
+            ].join("\n");
+            const result = await client.runTurn({
+                threadId,
+                input: [{ type: "text", text: prompt }],
+            });
+            const rawResponse = extractAgentText(result);
+            const json = extractJson(rawResponse);
+            const parsed = JSON.parse(json);
+            if (!parsed || typeof parsed !== "object") {
+                throw new Error("Codex consultation response was not a JSON object");
+            }
+            const candidate = parsed;
+            return {
+                issues: Array.isArray(candidate.issues)
+                    ? candidate.issues.filter((i) => typeof i === "string")
+                    : [],
+                ok: typeof candidate.ok === "boolean" ? candidate.ok : false,
+            };
+        },
+        async reviewChanges() {
+            const result = await client.runReview({
+                threadId,
+                target: { type: "uncommittedChanges" },
+            });
+            return result.reviewText;
+        },
+        async disconnect() {
+            await client.disconnect();
+        },
+    };
+}
+/**
+ * Stateless wrappers that match the Claude adapter interface.
+ * Each call creates a new client + thread (no persistence).
+ * Use createCodexSession() for persistent threads.
+ */
+export async function planSpec(spec, systemContext, config) {
+    const session = await createCodexSession(process.cwd(), config);
+    try {
+        return await session.planSpec(spec, systemContext);
+    }
+    finally {
+        await session.disconnect();
+    }
+}
+export async function executeTask(task, runId, config) {
+    const session = await createCodexSession(process.cwd(), config);
+    try {
+        return await session.executeTask(task, runId);
+    }
+    finally {
+        await session.disconnect();
+    }
+}

package/dist/cli/commands/cancel.js

@@ -0,0 +1,60 @@
+import { RunStore } from "../../state/store.js";
+function createStore() {
+    const runsDir = process.env.ORCA_RUNS_DIR;
+    return runsDir ? new RunStore(runsDir) : new RunStore();
+}
+function formatRunIds(runs) {
+    if (runs.length === 0) {
+        return "(none)";
+    }
+    return runs.map((run) => run.runId).join(", ");
+}
+function getActiveRuns(runs) {
+    return runs.filter((run) => run.overallStatus === "planning" || run.overallStatus === "running");
+}
+export async function cancelCommandHandler(options) {
+    const store = createStore();
+    const knownRuns = await store.listRuns();
+    if (!options.run) {
+        console.error(`Missing required --run <run-id>\nActive runs: ${formatRunIds(getActiveRuns(knownRuns))}`);
+        process.exitCode = 1;
+        return;
+    }
+    const run = await store.getRun(options.run);
+    if (!run) {
+        console.error(`Run not found: ${options.run}\nKnown run IDs: ${formatRunIds(knownRuns)}`);
+        process.exitCode = 1;
+        return;
+    }
+    const cancelledAt = new Date().toISOString();
+    let cancelledTaskId = null;
+    const tasks = run.tasks.map((task) => {
+        if (task.status === "in_progress") {
+            cancelledTaskId = task.id;
+            return {
+                ...task,
+                status: "cancelled",
+                finishedAt: cancelledAt,
+                lastError: "Run cancelled"
+            };
+        }
+        return task;
+    });
+    await store.updateRun(run.runId, {
+        overallStatus: "cancelled",
+        tasks
+    });
+    if (cancelledTaskId) {
+        console.log(`Cancelled run ${run.runId}; task ${cancelledTaskId} marked cancelled.`);
+        return;
+    }
+    console.log(`Cancelled run ${run.runId}.`);
+}
+export function registerCancelCommand(program) {
+    program
+        .command("cancel")
+        .description("Cancel an active run")
+        .option("--run <run-id>", "Run ID to cancel")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => cancelCommandHandler(options));
+}

package/dist/cli/commands/list.js

@@ -0,0 +1,50 @@
+import { RunStore } from "../../state/store.js";
+function createStore() {
+    const runsDir = process.env.ORCA_RUNS_DIR;
+    return runsDir ? new RunStore(runsDir) : new RunStore();
+}
+function pad(value, width) {
+    return value.padEnd(width, " ");
+}
+function formatTable(headers, rows) {
+    const widths = headers.map((header, index) => {
+        const rowWidths = rows.map((row) => row[index]?.length ?? 0);
+        return Math.max(header.length, ...rowWidths);
+    });
+    const headerLine = headers.map((header, index) => pad(header, widths[index] ?? header.length)).join("  ");
+    const separator = widths.map((width) => "-".repeat(width)).join("  ");
+    const body = rows.map((row) => row.map((cell, index) => pad(cell, widths[index] ?? cell.length)).join("  "));
+    return [headerLine, separator, ...body].join("\n");
+}
+function toSummaryRow(run) {
+    return [
+        run.runId,
+        run.specPath,
+        run.overallStatus,
+        run.createdAt
+    ];
+}
+export function formatRunSummaryTable(runs) {
+    const headers = ["Run ID", "Spec", "Status", "Started"];
+    const rows = runs.map(toSummaryRow);
+    return formatTable(headers, rows);
+}
+export async function listRuns() {
+    const store = createStore();
+    return await store.listRuns();
+}
+export async function listCommandHandler(_options) {
+    const runs = await listRuns();
+    if (runs.length === 0) {
+        console.log("No runs found.");
+        return;
+    }
+    console.log(formatRunSummaryTable(runs));
+}
+export function registerListCommand(program) {
+    program
+        .command("list")
+        .description("List all runs in run store")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => listCommandHandler(options));
+}

package/dist/cli/commands/plan.js

@@ -0,0 +1,40 @@
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { runPlanner } from "../../core/planner.js";
+import { RunStore } from "../../state/store.js";
+import { generateRunId } from "../../utils/ids.js";
+export async function planCommand(options) {
+    const specPath = path.resolve(options.spec);
+    await access(specPath, fsConstants.R_OK);
+    const runId = generateRunId(specPath);
+    console.log(`Run ID: ${runId}`);
+    const store = new RunStore();
+    await store.createRun(runId, specPath);
+    await runPlanner(specPath, store, runId);
+    const run = await store.getRun(runId);
+    if (!run) {
+        throw new Error(`Run not found after planning: ${runId}`);
+    }
+    console.log("Tasks:");
+    for (const task of run.tasks) {
+        console.log(`- ${task.name}`);
+    }
+    console.log(`Run dir: ${store.getRunDir(runId)}`);
+}
+export async function planCommandHandler(options) {
+    const commandOptions = options.config
+        ? { spec: options.spec, config: options.config }
+        : { spec: options.spec };
+    await planCommand(commandOptions);
+}
+export function registerPlanCommand(program) {
+    program
+        .command("plan")
+        .description("Run pre-planning and output validated task graph")
+        .requiredOption("--spec <path>", "Path to spec markdown file")
+        .option("--config <path>", "Path to orca config file")
+        .option("--on-milestone <cmd>", "Shell hook command for onMilestone")
+        .option("--on-error <cmd>", "Shell hook command for onError")
+        .action(async (options) => planCommandHandler(options));
+}

package/dist/cli/commands/pr-finalize.js

@@ -0,0 +1,11 @@
+export async function prFinalizeCommandHandler(_options) {
+    console.log("not yet implemented");
+}
+export function registerPrFinalizeCommand(program) {
+    program
+        .command("pr-finalize")
+        .description("Finalize a prepared pull request")
+        .requiredOption("--run <run-id>", "Run ID to finalize PR for")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => prFinalizeCommandHandler(options));
+}