orcastrator 0.2.4 → 0.2.6

package/README.md

@@ -82,10 +82,30 @@ export default {
     onTaskComplete: "echo task done: $ORCA_TASK_NAME",
     onComplete: "echo run complete",
     onError: "echo run failed"
+  },
+  codex: {
+    model: "gpt-5.3-codex",       // override the codex model
+    multiAgent: true,              // enable codex multi-agent (see below)
   }
 };
 ```
 
+### Multi-agent mode
+
+Codex supports experimental [multi-agent workflows](https://developers.openai.com/codex/multi-agent) where it can spawn parallel sub-agents for complex tasks.
+
+To enable it in orca, set `codex.multiAgent: true` in your config:
+
+```js
+export default {
+  codex: { multiAgent: true }
+};
+```
+
+When enabled, orca adds `multi_agent = true` to your global `~/.codex/config.toml`. If you already have multi-agent enabled in your Codex config, it will work automatically without setting anything in orca.
+
+> **Note:** Multi-agent is off by default because enabling it modifies your global Codex configuration. It is currently an experimental Codex feature.
+
 ## Reference
 
 ### Flags

package/dist/agents/claude/session.js

@@ -13,8 +13,9 @@ function buildPlanningPrompt(spec, systemContext) {
         spec
     ].join("\n\n");
 }
-function buildTaskExecutionPrompt(task, runId, cwd) {
+function buildTaskExecutionPrompt(task, runId, cwd, systemContext) {
     return [
+        ...(systemContext ? [systemContext] : []),
         "You are Orca's task execution assistant.",
         `Run ID: ${runId}`,
         `Repository CWD: ${cwd}`,
@@ -54,7 +55,15 @@ function parseTaskArray(raw) {
     if (!Array.isArray(parsed)) {
         throw new Error("Claude plan response was not a JSON array");
     }
-    return parsed;
+    // Coerce numeric task IDs and dependency refs to strings.
+    // LLMs sometimes emit numeric IDs (1, 2, 3) even when we ask for strings.
+    return parsed.map((task) => ({
+        ...task,
+        id: String(task.id),
+        dependencies: Array.isArray(task.dependencies)
+            ? task.dependencies.map(String)
+            : [],
+    }));
 }
 function parseTaskExecution(raw) {
     const parsed = JSON.parse(raw);
@@ -120,14 +129,14 @@ export async function planSpec(spec, systemContext) {
         session.close();
     }
 }
-export async function executeTask(task, runId, config) {
+export async function executeTask(task, runId, config, systemContext) {
     const session = unstable_v2_createSession({
         model: getModel(config),
         permissionMode: "bypassPermissions",
     });
     try {
         const streamPromise = collectSessionResult(session);
-        await session.send(buildTaskExecutionPrompt(task, runId, process.cwd()));
+        await session.send(buildTaskExecutionPrompt(task, runId, process.cwd(), systemContext));
         const rawResponse = await streamPromise;
         return parseTaskExecution(rawResponse);
     }

package/dist/agents/codex/session.js

@@ -13,8 +13,9 @@ function buildPlanningPrompt(spec, systemContext) {
         spec,
     ].join("\n\n");
 }
-function buildTaskExecutionPrompt(task, runId, cwd) {
+function buildTaskExecutionPrompt(task, runId, cwd, systemContext) {
     return [
+        ...(systemContext ? [systemContext] : []),
         "You are Orca's task execution assistant.",
         `Run ID: ${runId}`,
         `Repository CWD: ${cwd}`,
@@ -164,13 +165,13 @@ export async function createCodexSession(cwd, config) {
                 rawResponse,
             };
         },
-        async executeTask(task, runId) {
+        async executeTask(task, runId, systemContext) {
             const result = await client.runTurn({
                 threadId,
                 input: [
                     {
                         type: "text",
-                        text: buildTaskExecutionPrompt(task, runId, cwd),
+                        text: buildTaskExecutionPrompt(task, runId, cwd, systemContext),
                     },
                 ],
             });
@@ -236,10 +237,10 @@ export async function planSpec(spec, systemContext, config) {
         await session.disconnect();
     }
 }
-export async function executeTask(task, runId, config) {
+export async function executeTask(task, runId, config, systemContext) {
     const session = await createCodexSession(process.cwd(), config);
     try {
-        return await session.executeTask(task, runId);
+        return await session.executeTask(task, runId, systemContext);
     }
     finally {
         await session.disconnect();

package/dist/cli/commands/plan.js

@@ -1,17 +1,19 @@
 import { access } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import path from "node:path";
+import { resolveConfig } from "../../core/config-loader.js";
 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 orcaConfig = await resolveConfig(options.config);
     const runId = generateRunId(specPath);
     console.log(`Run ID: ${runId}`);
     const store = new RunStore();
     await store.createRun(runId, specPath);
-    await runPlanner(specPath, store, runId);
+    await runPlanner(specPath, store, runId, orcaConfig);
     const run = await store.getRun(runId);
     if (!run) {
         throw new Error(`Run not found after planning: ${runId}`);

package/dist/cli/commands/run.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { createCodexSession } from "../../agents/codex/session.js";
+import { ensureCodexMultiAgent } from "../../core/codex-config.js";
 import { resolveConfig } from "../../core/config-loader.js";
 import { runPlanner } from "../../core/planner.js";
 import { runTaskRunner } from "../../core/task-runner.js";
@@ -79,7 +80,7 @@ export async function runCommandHandler(options) {
         console.log(`Run ID: ${runId}`);
         const store = createStore();
         await store.createRun(runId, specPath);
-        await runPlanner(specPath, store, runId);
+        await runPlanner(specPath, store, runId, orcaConfig);
         await store.updateRun(runId, {
             mode: "run",
             overallStatus: "running"
@@ -124,6 +125,10 @@ export async function runCommandHandler(options) {
             await dispatcher.dispatch(event);
         };
         const cwd = process.cwd();
+        const multiAgentResult = await ensureCodexMultiAgent(orcaConfig ?? undefined);
+        if (multiAgentResult.action === "created" || multiAgentResult.action === "appended") {
+            console.log(`Multi-agent: enabled (updated ${multiAgentResult.path})`);
+        }
         const codexSession = await createCodexSession(cwd, orcaConfig ?? undefined);
         try {
             // Phase 4: Codex consults the task graph before execution begins.
@@ -150,7 +155,7 @@ export async function runCommandHandler(options) {
                 store,
                 ...(orcaConfig ? { config: orcaConfig } : {}),
                 emitHook,
-                executeTask: (task, runId, _config) => codexSession.executeTask(task, runId),
+                executeTask: (task, runId, _config, systemContext) => codexSession.executeTask(task, runId, systemContext),
             });
             const reviewText = await codexSession.reviewChanges();
             console.log("Codex post-execution review:");

package/dist/core/codex-config.js

@@ -0,0 +1,58 @@
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const CODEX_HOME = path.join(os.homedir(), ".codex");
+const GLOBAL_CONFIG_FILE = path.join(CODEX_HOME, "config.toml");
+const ORCA_MULTI_AGENT_BLOCK = `# Added by orca — remove or set multi_agent = false to disable
+[features]
+multi_agent = true
+`;
+function isMultiAgentEnabled(config) {
+    // Default: off. Only enable if explicitly set to true.
+    return config?.codex?.multiAgent === true;
+}
+function containsMultiAgentSetting(content) {
+    return /multi_agent\s*=/.test(content);
+}
+/**
+ * Ensures `~/.codex/config.toml` has `multi_agent = true` set.
+ *
+ * Uses the global config (not project-scoped) to avoid the "trusted projects"
+ * restriction that prevents project-level config from being loaded headlessly.
+ *
+ * - If the file doesn't exist: creates it with the multi_agent block.
+ * - If the file exists and already has `multi_agent`: leaves it alone.
+ * - If the file exists but has no `multi_agent`: appends the feature block.
+ * - If `multiAgent` is false in orca config: skips entirely.
+ *
+ * @param config - Orca config (checks codex.multiAgent flag)
+ * @param _configFile - Override config file path (for testing only)
+ */
+export async function ensureCodexMultiAgent(config, _configFile) {
+    const configFile = _configFile ?? GLOBAL_CONFIG_FILE;
+    if (!isMultiAgentEnabled(config)) {
+        return { action: "skipped", path: configFile };
+    }
+    let existingContent = null;
+    try {
+        await access(configFile, fsConstants.R_OK);
+        existingContent = await readFile(configFile, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    if (existingContent === null) {
+        await mkdir(path.dirname(configFile), { recursive: true });
+        await writeFile(configFile, ORCA_MULTI_AGENT_BLOCK, "utf8");
+        return { action: "created", path: configFile };
+    }
+    if (containsMultiAgentSetting(existingContent)) {
+        return { action: "already-set", path: configFile };
+    }
+    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+    await writeFile(configFile, `${existingContent}${separator}${ORCA_MULTI_AGENT_BLOCK}`, "utf8");
+    return { action: "appended", path: configFile };
+}

package/dist/core/config-loader.js

@@ -19,6 +19,16 @@ function coerceConfig(candidate) {
     if (!isObject(candidate)) {
         throw new Error("Config module must export an object");
     }
+    if ("skills" in candidate && candidate.skills !== undefined) {
+        if (!Array.isArray(candidate.skills)) {
+            throw new Error(`Config.skills must be an array, got ${describeType(candidate.skills)}`);
+        }
+        for (const skillPath of candidate.skills) {
+            if (typeof skillPath !== "string") {
+                throw new Error(`Config.skills entries must be strings, got ${describeType(skillPath)}`);
+            }
+        }
+    }
     if ("hooks" in candidate && candidate.hooks !== undefined) {
         if (!isObject(candidate.hooks)) {
             throw new Error(`Config.hooks must be an object, got ${describeType(candidate.hooks)}`);
@@ -80,6 +90,9 @@ export function mergeConfigs(...configs) {
         if (merged.hookCommands !== undefined || config.hookCommands !== undefined) {
             merged.hookCommands = { ...merged.hookCommands, ...config.hookCommands };
         }
+        if (config.skills !== undefined) {
+            merged.skills = [...new Set([...(merged.skills ?? []), ...config.skills])];
+        }
     }
     return merged;
 }

package/dist/core/planner.js

@@ -1,15 +1,30 @@
 import { promises as fs } from "node:fs";
 import { planSpec } from "../agents/claude/session.js";
 import { logger } from "../utils/logger.js";
+import { loadSkills } from "../utils/skill-loader.js";
 import { validateDAG } from "./dependency-graph.js";
 const DEFAULT_SYSTEM_CONTEXT = "You are Orca planner.";
 let planSpecImpl = planSpec;
 export function setPlanSpecForTests(fn) {
     planSpecImpl = fn ?? planSpec;
 }
-export async function runPlanner(specPath, store, runId) {
+function formatSkillsSection(skills) {
+    const formattedSkills = skills.map((skill) => [
+        `### ${skill.name}`,
+        "",
+        `Description: ${skill.description}`,
+        "",
+        skill.body
+    ].join("\n"));
+    return ["## Available Skills", "", ...formattedSkills].join("\n");
+}
+export async function runPlanner(specPath, store, runId, config) {
     const spec = await fs.readFile(specPath, "utf8");
-    const result = await planSpecImpl(spec, DEFAULT_SYSTEM_CONTEXT);
+    const skills = await loadSkills(config);
+    const systemContext = skills.length === 0
+        ? DEFAULT_SYSTEM_CONTEXT
+        : `${DEFAULT_SYSTEM_CONTEXT}\n\n${formatSkillsSection(skills)}`;
+    const result = await planSpecImpl(spec, systemContext);
     validateDAG(result.tasks);
     await store.writeTasks(runId, result.tasks);
     await store.updateRun(runId, {

package/dist/core/task-runner.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { promises as fs } from "node:fs";
 import { executeTask } from "../agents/claude/session.js";
+import { loadSkills } from "../utils/skill-loader.js";
 import { getRunnable, validateDAG } from "./dependency-graph.js";
 import { shouldRetry } from "./retry-policy.js";
 let executeTaskImpl = executeTask;
@@ -40,6 +41,16 @@ function stripOptionalFields(task, fields) {
 function hasPendingTasks(tasks) {
     return tasks.some((task) => task.status === "pending" || task.status === "in_progress");
 }
+function formatSkillsSection(skills) {
+    const formattedSkills = skills.map((skill) => [
+        `### ${skill.name}`,
+        "",
+        `Description: ${skill.description}`,
+        "",
+        skill.body
+    ].join("\n"));
+    return ["## Available Skills", "", ...formattedSkills].join("\n");
+}
 function buildSessionSummary(run) {
     const taskRows = run.tasks.length === 0
         ? "| (none) | - | - | - | - |\n"
@@ -85,6 +96,8 @@ export async function runTaskRunner(options) {
     const emitHook = options.emitHook ?? defaultEmitHook;
     const executeTaskFn = options.executeTask ?? executeTaskImpl;
     const { runId, store, config } = options;
+    const skills = await loadSkills(config);
+    const taskSystemContext = skills.length === 0 ? undefined : formatSkillsSection(skills);
     let run = await store.getRun(runId);
     if (!run) {
         throw new Error(`Run not found: ${runId}`);
@@ -199,7 +212,7 @@ export async function runTaskRunner(options) {
                 tasks: inProgressTasks
             });
             try {
-                const result = await executeTaskFn(task, runId, config);
+                const result = await executeTaskFn(task, runId, config, taskSystemContext);
                 if (result.outcome === "done") {
                     const doneTasks = inProgressTasks.map((candidate) => {
                         if (candidate.id !== task.id) {

package/dist/utils/skill-loader.js

@@ -0,0 +1,115 @@
+import { readdir, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+function expandHome(inputPath) {
+    if (inputPath === "~") {
+        return os.homedir();
+    }
+    if (inputPath.startsWith("~/") || inputPath.startsWith("~\\")) {
+        return path.join(os.homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+function parseFrontmatter(frontmatter) {
+    const parsed = {};
+    for (const rawLine of frontmatter.split(/\r?\n/u)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#")) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        if (key === "") {
+            continue;
+        }
+        let value = line.slice(separatorIndex + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        parsed[key] = value;
+    }
+    return parsed;
+}
+export function parseSkillFile(fileContent) {
+    const frontmatterMatch = fileContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/u);
+    if (!frontmatterMatch) {
+        return {
+            name: "",
+            description: "",
+            body: fileContent
+        };
+    }
+    const frontmatter = parseFrontmatter(frontmatterMatch[1] ?? "");
+    const body = fileContent.slice(frontmatterMatch[0].length);
+    return {
+        name: frontmatter.name ?? "",
+        description: frontmatter.description ?? "",
+        body
+    };
+}
+export async function loadSkill(skillDirPath) {
+    const expandedDirPath = path.resolve(expandHome(skillDirPath));
+    const skillFilePath = path.join(expandedDirPath, "SKILL.md");
+    let skillFileContent;
+    try {
+        skillFileContent = await readFile(skillFilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+    const parsed = parseSkillFile(skillFileContent);
+    const inferredName = path.basename(expandedDirPath);
+    return {
+        name: parsed.name || inferredName,
+        description: parsed.description,
+        body: parsed.body,
+        dirPath: expandedDirPath,
+        filePath: skillFilePath
+    };
+}
+export async function loadSkillsFromDir(skillsDirPath) {
+    const expandedDirPath = path.resolve(expandHome(skillsDirPath));
+    let entries;
+    try {
+        entries = await readdir(expandedDirPath, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const subdirectories = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+    const loaded = await Promise.all(subdirectories.map((subdirName) => loadSkill(path.join(expandedDirPath, subdirName))));
+    return loaded.filter((skill) => skill !== null);
+}
+export async function loadSkills(config) {
+    const fromConfig = await Promise.all((config?.skills ?? []).map((skillPath) => loadSkill(skillPath)));
+    const projectSkills = await loadSkillsFromDir(path.join(process.cwd(), ".orca", "skills"));
+    const globalSkills = await loadSkillsFromDir(path.join(os.homedir(), ".orca", "skills"));
+    const allSkills = [
+        ...fromConfig.filter((skill) => skill !== null),
+        ...projectSkills,
+        ...globalSkills
+    ];
+    const seenNames = new Set();
+    const deduped = [];
+    for (const skill of allSkills) {
+        if (seenNames.has(skill.name)) {
+            continue;
+        }
+        seenNames.add(skill.name);
+        deduped.push(skill);
+    }
+    return deduped;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcastrator",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "bin": {
     "orca": "dist/cli/index.js"