@femtomc/mu-orchestrator 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @femtomc/mu-orchestrator
+
+Node DAG runner that drives `@femtomc/mu-issue` and `@femtomc/mu-forum` to execute ready leaf issues and log outcomes.
+
+## Install
+
+After publishing:
+
+```bash
+npm install @femtomc/mu-orchestrator
+# or: bun add @femtomc/mu-orchestrator
+```
+
+From this repo:
+
+```bash
+cd mu
+bun install
+bun run build
+```
+
+## Usage
+
+```ts
+import { FsJsonlStore, fsEventLog, getStorePaths } from "@femtomc/mu-core/node";
+import { ForumStore } from "@femtomc/mu-forum";
+import { IssueStore } from "@femtomc/mu-issue";
+import { DagRunner } from "@femtomc/mu-orchestrator";
+
+const repoRoot = process.cwd();
+const paths = getStorePaths(repoRoot);
+const events = fsEventLog(paths.eventsPath);
+
+const issues = new IssueStore(new FsJsonlStore(paths.issuesPath), { events });
+const forum = new ForumStore(new FsJsonlStore(paths.forumPath), { events });
+
+const runner = new DagRunner(issues, forum, repoRoot);
+const result = await runner.run("mu-<root-id>");
+console.log(result);
+```
+
+## Tests / Typecheck
+
+From the `mu/` repo root:
+
+```bash
+bun test packages/orchestrator
+bun run typecheck
+```
+
+## Runtime
+
+- **Node-only** (uses `node:child_process` + filesystem).
+- Default backend is the `pi` CLI (`pi --mode json ...`). If you don't have `pi`, pass a custom `BackendRunner`.

package/dist/dag_runner.d.ts

@@ -0,0 +1,20 @@
+import { type EventLog } from "@femtomc/mu-core/node";
+import type { ForumStore } from "@femtomc/mu-forum";
+import type { IssueStore } from "@femtomc/mu-issue";
+import type { BackendRunner } from "./pi_backend.js";
+export type DagResult = {
+    status: "root_final" | "no_executable_leaf" | "max_steps_exhausted" | "error";
+    steps: number;
+    error: string;
+};
+export declare class DagRunner {
+    #private;
+    constructor(store: IssueStore, forum: ForumStore, repoRoot: string, opts?: {
+        backend?: BackendRunner;
+        events?: EventLog;
+    });
+    run(rootId: string, maxSteps?: number, opts?: {
+        review?: boolean;
+    }): Promise<DagResult>;
+}
+//# sourceMappingURL=dag_runner.d.ts.map

package/dist/dag_runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag_runner.d.ts","sourceRoot":"","sources":["../src/dag_runner.ts"],"names":[],"mappings":"AAIA,OAAO,EAEN,KAAK,QAAQ,EAMb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,MAAM,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,YAAY,GAAG,oBAAoB,GAAG,qBAAqB,GAAG,OAAO,CAAC;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAuBF,qBAAa,SAAS;;gBAepB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,aAAa,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;KAAO;IAiVpD,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,SAAS,CAAC;CAkLrG"}

package/dist/dag_runner.js

@@ -0,0 +1,465 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { currentRunId, executionSpecFromDict, fsEventLogFromRepoRoot, getStorePaths, newRunId, runContext, } from "@femtomc/mu-core/node";
+import { PiCliBackend } from "./pi_backend.js";
+import { readPromptMeta, renderPromptTemplate } from "./prompt.js";
+function roundTo(n, digits) {
+    const f = 10 ** digits;
+    return Math.round(n * f) / f;
+}
+function relPath(repoRoot, path) {
+    try {
+        const rel = relative(repoRoot, path);
+        return rel || path;
+    }
+    catch {
+        return path;
+    }
+}
+export class DagRunner {
+    // Hardcoded fallbacks if neither execution_spec nor orchestrator.md provide config.
+    #fallbackCli = "pi";
+    #fallbackModel = "gpt-5.3-codex";
+    #fallbackReasoning = "xhigh";
+    #store;
+    #forum;
+    #repoRoot;
+    #events;
+    #backend;
+    #reorchestrateOutcomes = new Set(["failure", "needs_work"]);
+    constructor(store, forum, repoRoot, opts = {}) {
+        this.#store = store;
+        this.#forum = forum;
+        this.#repoRoot = repoRoot;
+        this.#events = opts.events ?? fsEventLogFromRepoRoot(repoRoot);
+        this.#backend = opts.backend ?? new PiCliBackend();
+    }
+    async #resolveConfig(issue) {
+        let cli = this.#fallbackCli;
+        let model = this.#fallbackModel;
+        let reasoning = this.#fallbackReasoning;
+        let promptPath = null;
+        // Tier 1: orchestrator.md frontmatter (global defaults).
+        const { orchestratorPath } = getStorePaths(this.#repoRoot);
+        if (existsSync(orchestratorPath)) {
+            const meta = await readPromptMeta(orchestratorPath);
+            if (typeof meta.cli === "string")
+                cli = meta.cli;
+            if (typeof meta.model === "string")
+                model = meta.model;
+            if (typeof meta.reasoning === "string")
+                reasoning = meta.reasoning;
+            promptPath = orchestratorPath;
+        }
+        // Parse execution spec (may set role + explicit fields).
+        const specDict = issue.execution_spec ?? null;
+        const spec = specDict ? executionSpecFromDict(specDict, this.#repoRoot) : null;
+        // Tier 2: role file frontmatter (role-specific defaults).
+        if (spec?.role) {
+            const rolePath = join(this.#repoRoot, ".mu", "roles", `${spec.role}.md`);
+            if (existsSync(rolePath)) {
+                const roleMeta = await readPromptMeta(rolePath);
+                if (typeof roleMeta.cli === "string")
+                    cli = roleMeta.cli;
+                if (typeof roleMeta.model === "string")
+                    model = roleMeta.model;
+                if (typeof roleMeta.reasoning === "string")
+                    reasoning = roleMeta.reasoning;
+            }
+        }
+        // Tier 3: execution_spec explicit fields (highest priority).
+        if (spec) {
+            if (spec.cli != null)
+                cli = spec.cli;
+            if (spec.model != null)
+                model = spec.model;
+            if (spec.reasoning != null)
+                reasoning = spec.reasoning;
+            if (spec.prompt_path != null)
+                promptPath = spec.prompt_path;
+        }
+        return { cli, model, reasoning, promptPath };
+    }
+    async #renderPrompt(issue, promptPath, rootId) {
+        let rendered;
+        if (promptPath && existsSync(promptPath)) {
+            rendered = await renderPromptTemplate(promptPath, issue, { repoRoot: this.#repoRoot });
+        }
+        else {
+            rendered = issue.title;
+            if (issue.body) {
+                rendered += `\n\n${issue.body}`;
+            }
+        }
+        rendered += `\n\n## Inshallah Context\nRoot: ${rootId}\nAssigned issue: ${issue.id}\n`;
+        return rendered;
+    }
+    async #executeBackend(issue, cfg, rootId, opts = {}) {
+        const logSuffix = opts.logSuffix ?? "";
+        const rendered = await this.#renderPrompt(issue, cfg.promptPath, rootId);
+        const { logsDir } = getStorePaths(this.#repoRoot);
+        await mkdir(logsDir, { recursive: true });
+        const suffix = logSuffix ? `.${logSuffix}` : "";
+        const teePath = join(logsDir, `${issue.id}${suffix}.jsonl`);
+        await this.#events.emit("backend.run.start", {
+            source: "backend",
+            issueId: issue.id,
+            payload: {
+                cli: cfg.cli,
+                model: cfg.model,
+                reasoning: cfg.reasoning,
+                prompt_path: cfg.promptPath,
+                tee_path: relPath(this.#repoRoot, teePath),
+                log_suffix: logSuffix,
+            },
+        });
+        const t0 = Date.now();
+        const exitCode = await this.#backend.run({
+            issueId: issue.id,
+            prompt: rendered,
+            model: cfg.model,
+            thinking: cfg.reasoning,
+            cwd: this.#repoRoot,
+            cli: cfg.cli,
+            promptPath: cfg.promptPath,
+            logSuffix,
+            teePath,
+        });
+        const elapsedS = (Date.now() - t0) / 1000;
+        await this.#events.emit("backend.run.end", {
+            source: "backend",
+            issueId: issue.id,
+            payload: {
+                cli: cfg.cli,
+                exit_code: exitCode,
+                elapsed_s: roundTo(elapsedS, 3),
+                tee_path: relPath(this.#repoRoot, teePath),
+                log_suffix: logSuffix,
+            },
+        });
+        return { exitCode, elapsedS };
+    }
+    #hasReviewer() {
+        return existsSync(join(this.#repoRoot, ".mu", "roles", "reviewer.md"));
+    }
+    async #maybeReview(issue, rootId, step) {
+        const issueId = issue.id;
+        // Guards.
+        if (issue.outcome !== "success") {
+            return issue;
+        }
+        if (!this.#hasReviewer()) {
+            return issue;
+        }
+        await this.#events.emit("dag.review.start", {
+            source: "dag_runner",
+            issueId,
+            payload: { root_id: rootId, step },
+        });
+        const reviewIssue = { ...issue, execution_spec: { role: "reviewer" } };
+        const cfg = await this.#resolveConfig(reviewIssue);
+        const { exitCode, elapsedS } = await this.#executeBackend(reviewIssue, cfg, rootId, { logSuffix: "review" });
+        await this.#forum.post(`issue:${issueId}`, JSON.stringify({
+            step,
+            issue_id: issueId,
+            title: issue.title,
+            exit_code: exitCode,
+            elapsed_s: roundTo(elapsedS, 1),
+            type: "review",
+        }), "reviewer");
+        const updated = (await this.#store.get(issueId)) ?? issue;
+        await this.#events.emit("dag.review.end", {
+            source: "dag_runner",
+            issueId,
+            payload: { root_id: rootId, step, outcome: updated.outcome },
+        });
+        return updated;
+    }
+    async #reopenForOrchestration(issueId, opts) {
+        const reopened = await this.#store.update(issueId, { status: "open", outcome: null, execution_spec: null });
+        await this.#events.emit("dag.unstick.reopen", {
+            source: "dag_runner",
+            issueId,
+            payload: { reason: opts.reason, step: opts.step },
+        });
+        await this.#forum.post(`issue:${issueId}`, JSON.stringify({
+            step: opts.step,
+            issue_id: issueId,
+            title: reopened.title ?? "",
+            type: "reorchestrate",
+            reason: opts.reason,
+        }), "orchestrator");
+    }
+    async #maybeUnstick(rootId, step) {
+        const idsInScope = new Set(await this.#store.subtree_ids(rootId));
+        const rows = await this.#store.list();
+        // Build children mapping once.
+        const childrenOf = new Map();
+        for (const row of rows) {
+            for (const dep of row.deps ?? []) {
+                if (dep.type !== "parent")
+                    continue;
+                const list = childrenOf.get(dep.target) ?? [];
+                list.push(row);
+                childrenOf.set(dep.target, list);
+            }
+        }
+        const hasOpenChildren = (issueId) => (childrenOf.get(issueId) ?? []).some((child) => child.status !== "closed");
+        const candidates = [];
+        for (const row of rows) {
+            if (!idsInScope.has(row.id))
+                continue;
+            if (row.status !== "closed")
+                continue;
+            const outcome = row.outcome;
+            if (outcome && this.#reorchestrateOutcomes.has(outcome)) {
+                if (hasOpenChildren(row.id))
+                    continue;
+                candidates.push(row);
+                continue;
+            }
+            if (outcome === "expanded" && (childrenOf.get(row.id)?.length ?? 0) === 0) {
+                candidates.push(row);
+            }
+        }
+        if (candidates.length === 0) {
+            return false;
+        }
+        candidates.sort((a, b) => (a.priority ?? 3) - (b.priority ?? 3));
+        const target = candidates[0];
+        await this.#reopenForOrchestration(target.id, { reason: `was outcome=${target.outcome}`, step });
+        return true;
+    }
+    async #collapseReview(issue, rootId, step) {
+        const issueId = issue.id;
+        await this.#events.emit("dag.collapse_review.start", {
+            source: "dag_runner",
+            issueId,
+            payload: { root_id: rootId, step },
+        });
+        const kids = await this.#store.children(issueId);
+        const lines = [];
+        for (const kid of kids) {
+            lines.push(`- [${kid.outcome ?? "?"}] ${kid.id}: ${kid.title}`);
+        }
+        const childrenSummary = lines.join("\n");
+        const originalBody = issue.body || "";
+        const collapsePrompt = `# Collapse Review\n\n` +
+            `## Original Specification\n\n` +
+            `**${issue.title}**\n\n` +
+            `${originalBody}\n\n` +
+            `## Children Outcomes\n\n` +
+            `${childrenSummary}\n\n` +
+            `## Instructions\n\n` +
+            `All children of this issue have completed. Review whether their aggregate work satisfies the original specification above.\n\n` +
+            `If satisfied: no action needed (the issue will be marked successful).\n\n` +
+            `If NOT satisfied: mark the parent as needing work by running:\n\n` +
+            `  \`mu issues update ${issueId} --outcome needs_work\`\n\n` +
+            `Then explain the gaps in the forum topic (issue:${issueId}).\n\n` +
+            `Do NOT create child issues yourself; the orchestrator will re-expand the issue into remediation children.\n`;
+        const reviewIssue = {
+            ...issue,
+            title: `Collapse review: ${issue.title}`,
+            body: collapsePrompt,
+            execution_spec: { role: "reviewer" },
+        };
+        const cfg = await this.#resolveConfig(reviewIssue);
+        const { exitCode, elapsedS } = await this.#executeBackend(reviewIssue, { ...cfg, promptPath: null }, rootId, {
+            logSuffix: "collapse-review",
+        });
+        await this.#forum.post(`issue:${issueId}`, JSON.stringify({
+            step,
+            issue_id: issueId,
+            title: issue.title,
+            exit_code: exitCode,
+            elapsed_s: roundTo(elapsedS, 1),
+            type: "collapse-review",
+        }), "reviewer");
+        const newKids = await this.#store.children(issueId);
+        const openKids = newKids.filter((k) => k.status !== "closed");
+        const updated = (await this.#store.get(issueId)) ?? issue;
+        if (updated.status !== "closed") {
+            await this.#events.emit("dag.collapse_review.end", {
+                source: "dag_runner",
+                issueId,
+                payload: { root_id: rootId, step, status: updated.status, outcome: updated.outcome },
+            });
+            return;
+        }
+        if (updated.outcome && this.#reorchestrateOutcomes.has(updated.outcome)) {
+            await this.#events.emit("dag.collapse_review.end", {
+                source: "dag_runner",
+                issueId,
+                payload: { root_id: rootId, step, status: updated.status, outcome: updated.outcome },
+            });
+            return;
+        }
+        if (openKids.length > 0) {
+            await this.#events.emit("dag.collapse_review.end", {
+                source: "dag_runner",
+                issueId,
+                payload: {
+                    root_id: rootId,
+                    step,
+                    status: updated.status,
+                    outcome: updated.outcome,
+                    open_kids: openKids.length,
+                },
+            });
+            return;
+        }
+        await this.#store.update(issueId, { outcome: "success" });
+        await this.#events.emit("dag.collapse_review.end", {
+            source: "dag_runner",
+            issueId,
+            payload: { root_id: rootId, step, outcome: "success" },
+        });
+    }
+    async run(rootId, maxSteps = 20, opts = {}) {
+        const review = opts.review ?? true;
+        const runId = currentRunId() ?? newRunId();
+        return await runContext({ runId }, async () => {
+            await this.#events.emit("dag.run.start", {
+                source: "dag_runner",
+                issueId: rootId,
+                payload: { root_id: rootId, max_steps: maxSteps, review },
+            });
+            let final = null;
+            try {
+                for (let i = 0; i < maxSteps; i++) {
+                    const step = i + 1;
+                    // 0. Unstick: failures / needs_work trigger re-orchestration.
+                    await this.#maybeUnstick(rootId, step);
+                    // 1. Collapse review (before termination check).
+                    if (review && this.#hasReviewer()) {
+                        const collapsible = await this.#store.collapsible(rootId);
+                        if (collapsible.length > 0) {
+                            await this.#collapseReview(collapsible[0], rootId, step);
+                            continue;
+                        }
+                    }
+                    // 2. Check termination.
+                    const v = await this.#store.validate(rootId);
+                    if (v.is_final) {
+                        final = { status: "root_final", steps: i, error: "" };
+                        return final;
+                    }
+                    // 3. Select next ready leaf.
+                    const candidates = await this.#store.ready(rootId, { tags: ["node:agent"] });
+                    if (candidates.length === 0) {
+                        // Repair pass on the root to resolve deadlocks / bad expansions.
+                        await this.#events.emit("dag.unstick.start", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: { root_id: rootId, step },
+                        });
+                        const rootIssue = await this.#store.get(rootId);
+                        if (!rootIssue) {
+                            final = { status: "error", steps: i, error: "root vanished" };
+                            return final;
+                        }
+                        const idsInScope = new Set(await this.#store.subtree_ids(rootId));
+                        const openIssues = (await this.#store.list({ status: "open" })).filter((r) => idsInScope.has(r.id));
+                        const diag = `- open_issues: ${openIssues.length}\n` +
+                            `- action: diagnose deadlocks or missing expansions and create executable leaf work\n` +
+                            `- hint: run \`mu issues ready --root ${rootId}\` and \`mu issues list --root ${rootId}\`\n`;
+                        const repairIssue = {
+                            ...rootIssue,
+                            title: `Repair stuck DAG: ${rootIssue.title}`,
+                            body: `${(rootIssue.body || "").trim()}\n\n## Runner Diagnostics\n\n${diag}`.trim(),
+                            execution_spec: null,
+                        };
+                        const cfg = await this.#resolveConfig(repairIssue);
+                        const { exitCode, elapsedS } = await this.#executeBackend(repairIssue, cfg, rootId, {
+                            logSuffix: "unstick",
+                        });
+                        await this.#forum.post(`issue:${rootId}`, JSON.stringify({
+                            step,
+                            issue_id: rootId,
+                            title: rootIssue.title ?? "",
+                            exit_code: exitCode,
+                            elapsed_s: roundTo(elapsedS, 1),
+                            type: "unstick",
+                        }), "orchestrator");
+                        await this.#events.emit("dag.unstick.end", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: { root_id: rootId, step, exit_code: exitCode, elapsed_s: roundTo(elapsedS, 3) },
+                        });
+                        continue;
+                    }
+                    const issue = candidates[0];
+                    const issueId = issue.id;
+                    await this.#events.emit("dag.step.start", {
+                        source: "dag_runner",
+                        issueId,
+                        payload: { root_id: rootId, step, title: issue.title ?? "" },
+                    });
+                    // 3. Claim.
+                    await this.#events.emit("dag.claim", {
+                        source: "dag_runner",
+                        issueId,
+                        payload: { root_id: rootId, step },
+                    });
+                    await this.#store.claim(issueId);
+                    // 4. Route + 5. Render + 6. Execute.
+                    const cfg = await this.#resolveConfig(issue);
+                    const { exitCode, elapsedS } = await this.#executeBackend(issue, cfg, rootId);
+                    // 7. Check postconditions.
+                    let updated = await this.#store.get(issueId);
+                    if (!updated) {
+                        final = { status: "error", steps: step, error: "issue vanished" };
+                        return final;
+                    }
+                    if (updated.status !== "closed") {
+                        updated = await this.#store.close(issueId, "failure");
+                    }
+                    // 7b. Review phase.
+                    if (review && updated.status === "closed") {
+                        updated = await this.#maybeReview(updated, rootId, step);
+                    }
+                    // 8. Log to forum.
+                    await this.#forum.post(`issue:${issueId}`, JSON.stringify({
+                        step,
+                        issue_id: issueId,
+                        title: issue.title,
+                        exit_code: exitCode,
+                        outcome: updated.outcome,
+                        elapsed_s: roundTo(elapsedS, 1),
+                    }), "orchestrator");
+                    await this.#events.emit("dag.step.end", {
+                        source: "dag_runner",
+                        issueId,
+                        payload: {
+                            root_id: rootId,
+                            step,
+                            exit_code: exitCode,
+                            elapsed_s: roundTo(elapsedS, 3),
+                            outcome: updated.outcome,
+                        },
+                    });
+                    // 9. Re-orchestrate on failure / needs_work.
+                    if (updated.outcome && this.#reorchestrateOutcomes.has(updated.outcome)) {
+                        await this.#reopenForOrchestration(issueId, { reason: `outcome=${updated.outcome}`, step });
+                    }
+                }
+                final = { status: "max_steps_exhausted", steps: maxSteps, error: "" };
+                return final;
+            }
+            catch (err) {
+                final = { status: "error", steps: 0, error: err instanceof Error ? err.message : String(err) };
+                return final;
+            }
+            finally {
+                if (final) {
+                    await this.#events.emit("dag.run.end", {
+                        source: "dag_runner",
+                        issueId: rootId,
+                        payload: { root_id: rootId, status: final.status, steps: final.steps, error: final.error },
+                    });
+                }
+            }
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { DagResult } from "./dag_runner.js";
+export { DagRunner } from "./dag_runner.js";
+export type { BackendRunner, BackendRunOpts } from "./pi_backend.js";
+export { PiCliBackend, piStreamHasError } from "./pi_backend.js";
+export type { PromptMeta } from "./prompt.js";
+export { buildRoleCatalog, extractDescription, readPromptMeta, renderPromptTemplate, splitFrontmatter, } from "./prompt.js";
+export declare function orchestratorHello(): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACjE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAGrB,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { DagRunner } from "./dag_runner.js";
+export { PiCliBackend, piStreamHasError } from "./pi_backend.js";
+export { buildRoleCatalog, extractDescription, readPromptMeta, renderPromptTemplate, splitFrontmatter, } from "./prompt.js";
+// Back-compat placeholder API used by other packages/tests.
+export function orchestratorHello() {
+    return "orchestrator(forum,issue)";
+}

package/dist/pi_backend.d.ts

@@ -0,0 +1,21 @@
+export type BackendRunOpts = {
+    issueId: string;
+    prompt: string;
+    model: string;
+    thinking: string;
+    cwd: string;
+    cli: string;
+    promptPath: string | null;
+    logSuffix: string;
+    onLine?: (line: string) => void;
+    teePath?: string;
+};
+export interface BackendRunner {
+    run(opts: BackendRunOpts): Promise<number>;
+}
+export declare function piStreamHasError(line: string): boolean;
+export declare class PiCliBackend implements BackendRunner {
+    #private;
+    run(opts: BackendRunOpts): Promise<number>;
+}
+//# sourceMappingURL=pi_backend.d.ts.map

package/dist/pi_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi_backend.d.ts","sourceRoot":"","sources":["../src/pi_backend.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,WAAW,aAAa;IAC7B,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CA4BtD;AAED,qBAAa,YAAa,YAAW,aAAa;;IAKpC,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;CA0DvD"}

package/dist/pi_backend.js

@@ -0,0 +1,87 @@
+import { spawn } from "node:child_process";
+import { mkdir, open } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { PassThrough } from "node:stream";
+export function piStreamHasError(line) {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    const etype = event?.type;
+    if (etype === "message_update") {
+        const assistantEvent = event?.assistantMessageEvent;
+        if (assistantEvent && typeof assistantEvent === "object" && assistantEvent.type === "error") {
+            return true;
+        }
+    }
+    if (etype === "message_end") {
+        const message = event?.message;
+        if (!message || typeof message !== "object") {
+            return false;
+        }
+        if (message.role !== "assistant") {
+            return false;
+        }
+        return message.stopReason === "error" || message.stopReason === "aborted";
+    }
+    return false;
+}
+export class PiCliBackend {
+    #buildArgv(prompt, model, thinking) {
+        return ["pi", "--mode", "json", "--no-session", "--model", model, "--thinking", thinking, prompt];
+    }
+    async run(opts) {
+        if (opts.cli !== "pi") {
+            throw new Error(`unsupported backend cli=${JSON.stringify(opts.cli)} (only "pi" is supported)`);
+        }
+        const argv = this.#buildArgv(opts.prompt, opts.model, opts.thinking);
+        let teeFh = null;
+        try {
+            if (opts.teePath) {
+                await mkdir(dirname(opts.teePath), { recursive: true });
+                teeFh = await open(opts.teePath, "w");
+            }
+            const proc = spawn(argv[0], argv.slice(1), {
+                cwd: opts.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const merged = new PassThrough();
+            proc.stdout?.pipe(merged);
+            proc.stderr?.pipe(merged);
+            let sawAssistantError = false;
+            const rl = createInterface({ input: merged, crlfDelay: Number.POSITIVE_INFINITY });
+            const readLoop = (async () => {
+                for await (const line of rl) {
+                    const trimmed = String(line);
+                    if (piStreamHasError(trimmed)) {
+                        sawAssistantError = true;
+                    }
+                    opts.onLine?.(trimmed);
+                    if (teeFh) {
+                        // Preserve Python's JSONL tee behavior: write one line per line.
+                        await teeFh.write(`${trimmed}\n`);
+                    }
+                }
+            })();
+            const exitCode = await new Promise((resolve, reject) => {
+                proc.once("error", (err) => reject(err));
+                proc.once("close", (code) => resolve(code ?? 0));
+            });
+            // Ensure the reader finishes (and flushes tee writes).
+            await readLoop;
+            if (exitCode === 0 && sawAssistantError) {
+                return 1;
+            }
+            return exitCode;
+        }
+        finally {
+            if (teeFh) {
+                await teeFh.close();
+            }
+        }
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,17 @@
+import type { Issue } from "@femtomc/mu-core";
+export type PromptMeta = Record<string, unknown>;
+export declare function splitFrontmatter(text: string): {
+    meta: PromptMeta;
+    body: string;
+};
+export declare function extractDescription(meta: PromptMeta, body: string): {
+    description: string;
+    source: string;
+};
+export declare function readPromptMeta(path: string): Promise<PromptMeta>;
+export declare function buildRoleCatalog(repoRoot: string): Promise<string>;
+export declare function renderPromptTemplate(path: string, issue: Pick<Issue, "id" | "title" | "body">, opts?: {
+    repoRoot?: string;
+}): Promise<string>;
+export declare function resolvePromptPath(repoRoot: string, promptPath: string): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAyCjD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6BjF;AAYD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAW1G;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAItE;AAMD,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwCxE;AAED,wBAAsB,oBAAoB,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,GAAG,MAAM,CAAC,EAC3C,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK9E"}

package/dist/prompt.js

@@ -0,0 +1,153 @@
+import { readdir, readFile } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+function stripQuotes(s) {
+    const trimmed = s.trim();
+    if (trimmed.length >= 2) {
+        const first = trimmed[0];
+        const last = trimmed[trimmed.length - 1];
+        if ((first === `"` && last === `"`) || (first === `'` && last === `'`)) {
+            return trimmed.slice(1, -1);
+        }
+    }
+    return trimmed;
+}
+function parseSimpleYamlFrontmatter(text) {
+    // We only need a small subset: flat `key: value` mappings.
+    // If parsing fails, we return {} (mirrors Python behavior).
+    const out = {};
+    const lines = text.split(/\r?\n/);
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            continue;
+        }
+        if (line.startsWith("#")) {
+            continue;
+        }
+        const idx = line.indexOf(":");
+        if (idx <= 0) {
+            continue;
+        }
+        const key = line.slice(0, idx).trim();
+        if (!key) {
+            continue;
+        }
+        const value = stripQuotes(line.slice(idx + 1));
+        out[key] = value;
+    }
+    return out;
+}
+export function splitFrontmatter(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines.length === 0 || lines[0]?.trim() !== "---") {
+        return { meta: {}, body: text };
+    }
+    // Find the terminating `---` line.
+    let endIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === "---") {
+            endIdx = i;
+            break;
+        }
+    }
+    if (endIdx < 0) {
+        return { meta: {}, body: text };
+    }
+    try {
+        const metaText = lines.slice(1, endIdx).join("\n");
+        const body = lines
+            .slice(endIdx + 1)
+            .join("\n")
+            .replace(/^\n+/, "");
+        const meta = parseSimpleYamlFrontmatter(metaText);
+        return { meta, body };
+    }
+    catch {
+        return { meta: {}, body: text };
+    }
+}
+function firstNonEmptyLine(text) {
+    for (const line of text.split(/\r?\n/)) {
+        const stripped = line.trim();
+        if (stripped) {
+            return stripped;
+        }
+    }
+    return "";
+}
+export function extractDescription(meta, body) {
+    const raw = meta.description;
+    const desc = typeof raw === "string" ? raw.trim() : "";
+    if (desc) {
+        return { description: desc, source: "frontmatter" };
+    }
+    const bodyDesc = firstNonEmptyLine(body);
+    if (bodyDesc) {
+        return { description: bodyDesc, source: "body" };
+    }
+    return { description: "", source: "none" };
+}
+export async function readPromptMeta(path) {
+    const text = await readFile(path, "utf8");
+    const { meta } = splitFrontmatter(text);
+    return meta;
+}
+function toPosixPath(path) {
+    return path.replaceAll("\\", "/");
+}
+export async function buildRoleCatalog(repoRoot) {
+    const rolesDir = join(repoRoot, ".mu", "roles");
+    let entries;
+    try {
+        entries = await readdir(rolesDir);
+    }
+    catch {
+        return "";
+    }
+    const roleFiles = entries.filter((e) => e.endsWith(".md")).sort();
+    const sections = [];
+    for (const file of roleFiles) {
+        const abs = join(rolesDir, file);
+        const text = await readFile(abs, "utf8");
+        const { meta, body } = splitFrontmatter(text);
+        const name = file.replace(/\.md$/, "");
+        const promptPath = toPosixPath(relative(repoRoot, abs));
+        const { description, source } = extractDescription(meta, body);
+        const parts = [];
+        for (const key of ["cli", "model", "reasoning"]) {
+            if (key in meta) {
+                parts.push(`${key}: ${String(meta[key])}`);
+            }
+        }
+        const configLine = parts.length > 0 ? parts.join(" | ") : "default config";
+        const catalogDesc = description || "No description provided.";
+        sections.push(`### ${name}\n` +
+            `description: ${catalogDesc}\n` +
+            `description_source: ${source}\n` +
+            `prompt: ${promptPath}\n` +
+            `config: ${configLine}`);
+    }
+    return sections.join("\n\n");
+}
+export async function renderPromptTemplate(path, issue, opts = {}) {
+    const text = await readFile(path, "utf8");
+    const { body } = splitFrontmatter(text);
+    let promptText = issue.title ?? "";
+    if (issue.body) {
+        promptText += `\n\n${issue.body}`;
+    }
+    let rendered = body;
+    rendered = rendered.replaceAll("{{PROMPT}}", promptText);
+    rendered = rendered.replaceAll("{{ISSUE_ID}}", issue.id ?? "");
+    if (rendered.includes("{{ROLES}}")) {
+        const catalog = opts.repoRoot ? await buildRoleCatalog(opts.repoRoot) : "";
+        rendered = rendered.replaceAll("{{ROLES}}", catalog);
+    }
+    return rendered;
+}
+export function resolvePromptPath(repoRoot, promptPath) {
+    if (isAbsolute(promptPath)) {
+        return promptPath;
+    }
+    return join(repoRoot, promptPath);
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@femtomc/mu-orchestrator",
+	"version": "0.1.0",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": ["dist/**"],
+	"dependencies": {
+		"@femtomc/mu-core": "0.1.0",
+		"@femtomc/mu-forum": "0.1.0",
+		"@femtomc/mu-issue": "0.1.0"
+	}
+}