orcastrator 0.2.5 → 0.2.7

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

@@ -80,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"
@@ -155,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/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)}`);
@@ -52,7 +62,7 @@ export async function loadConfig(configPath) {
     const configCandidate = "default" in importedModule ? importedModule.default : importedModule;
     return coerceConfig(configCandidate);
 }
-const TOP_LEVEL_SCALARS = ["runsDir", "sessionLogs", "maxRetries", "anthropicApiKey", "openaiApiKey"];
+const TOP_LEVEL_SCALARS = ["runsDir", "sessionLogs", "maxRetries", "anthropicApiKey", "openaiApiKey", "executor"];
 export function mergeConfigs(...configs) {
     const presentConfigs = configs.filter((config) => config !== undefined);
     if (presentConfigs.length === 0) {
@@ -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,11 +1,14 @@
 import path from "node:path";
 import { promises as fs } from "node:fs";
-import { executeTask } from "../agents/claude/session.js";
+import * as claudeAgent from "../agents/claude/session.js";
+import { createCodexSession } from "../agents/codex/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;
+// Non-null only when set by tests — null means "use real executor logic"
+let testExecuteTaskOverride = null;
 export function setExecuteTaskForTests(fn) {
-    executeTaskImpl = fn ?? executeTask;
+    testExecuteTaskOverride = fn;
 }
 function toErrorMessage(error) {
     if (error instanceof Error) {
@@ -40,6 +43,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"
@@ -83,8 +96,34 @@ async function writeSessionSummary(store, runId, sessionLogsDir) {
 }
 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);
+    // Test mocks bypass all executor logic entirely — no real sessions created.
+    const mockFn = options.executeTask ?? testExecuteTaskOverride;
+    // Build real executor (Codex persistent session or Claude stateless fallback).
+    // Only runs in production — skipped completely when a mock is active.
+    let codexSession;
+    let executeTaskFn;
+    if (mockFn) {
+        executeTaskFn = mockFn;
+    }
+    else {
+        const executor = config?.executor ?? "codex";
+        if (executor === "codex") {
+            try {
+                codexSession = await createCodexSession(process.cwd(), config);
+                executeTaskFn = (task, taskRunId, _cfg, systemContext) => codexSession.executeTask(task, taskRunId, systemContext);
+            }
+            catch (sessionError) {
+                console.warn(`[orca] Codex session init failed, falling back to Claude: ${toErrorMessage(sessionError)}`);
+                executeTaskFn = claudeAgent.executeTask;
+            }
+        }
+        else {
+            executeTaskFn = claudeAgent.executeTask;
+        }
+    }
     let run = await store.getRun(runId);
     if (!run) {
         throw new Error(`Run not found: ${runId}`);
@@ -199,7 +238,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) {
@@ -307,4 +346,14 @@ export async function runTaskRunner(options) {
         await writeSessionSummary(store, runId, config?.sessionLogs);
         throw error;
     }
+    finally {
+        if (codexSession) {
+            try {
+                await codexSession.disconnect();
+            }
+            catch {
+                // Best-effort cleanup — don't mask the real error.
+            }
+        }
+    }
 }

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.5",
+  "version": "0.2.7",
   "type": "module",
   "bin": {
     "orca": "dist/cli/index.js"