poe-code 3.0.197 → 3.0.199

package/packages/superintendent/dist/runtime/loop.js

@@ -0,0 +1,446 @@
+import path from "node:path";
+import * as fsPromises from "node:fs/promises";
+import { lockWorkflow, makeRunLogFileName, resolveWorkflowPath } from "@poe-code/agent-harness-tools";
+import { spawn } from "@poe-code/agent-spawn";
+import { parseSuperintendentDoc } from "../document/parse.js";
+import { parseTaskBoard } from "../document/tasks.js";
+import { updateStatus } from "../document/write.js";
+import { createLoopState } from "../state/machine.js";
+import { runBuilder } from "./run-builder.js";
+import { runInspector } from "./run-inspector.js";
+import { runOwnerReview } from "./run-owner-review.js";
+import { runSuperintendent } from "./run-superintendent.js";
+import { collectReferencedInspectors } from "./templates.js";
+export async function runLoop(input, callbacks) {
+    const options = normalizeOptions(input, callbacks);
+    const releaseLock = await lockWorkflow(options.docPath, {
+        fs: options.fs
+    });
+    try {
+        return await withInjectedAgentRunner(options, async () => {
+            let state = createLoopState(await readDocument(options.fs, options.docPath));
+            let context = {
+                inspectors: {},
+                inspectorLogs: {}
+            };
+            while (true) {
+                const stopReason = readLoopStopReason(options, state);
+                if (stopReason) {
+                    return finishLoop(options.callbacks, state, stopReason);
+                }
+                if (state.state === "in_progress") {
+                    const roundStartState = { ...state };
+                    const roundSnapshot = await readDocumentContent(options.fs, options.docPath);
+                    state = beginRound(state);
+                    emitStateChange(options.callbacks, state);
+                    await writeLoopState(options.fs, options.docPath, state);
+                    options.callbacks.onBuilderStart?.();
+                    let builderResult;
+                    try {
+                        builderResult = await options.runners.builder(await readDocument(options.fs, options.docPath), createTemplateContext(context), buildRoleOptions(options, "builder"));
+                    }
+                    catch (error) {
+                        await restoreDocument(options.fs, options.docPath, roundSnapshot);
+                        const normalizedError = toError(error);
+                        options.callbacks.onBuilderFailed?.(normalizedError);
+                        throw normalizedError;
+                    }
+                    options.callbacks.onBuilderComplete?.(builderResult);
+                    context = {
+                        ...context,
+                        builder: builderResult,
+                        inspectors: {},
+                        inspectorLogs: {}
+                    };
+                    await writeLoopState(options.fs, options.docPath, state);
+                    const stopReason = readInterruptionReason(options, state);
+                    if (stopReason) {
+                        if (stopReason === "aborted") {
+                            state = await rollbackRoundStatus(options, roundStartState);
+                        }
+                        return finishLoop(options.callbacks, state, stopReason);
+                    }
+                    const docForInspectors = await readDocument(options.fs, options.docPath);
+                    const inspectorEntries = filterAutoRunInspectors(docForInspectors);
+                    for (const [name, config] of inspectorEntries) {
+                        options.callbacks.onInspectorStart?.(name);
+                        const inspectorSnapshot = await readDocumentContent(options.fs, options.docPath);
+                        let inspectorResult;
+                        try {
+                            inspectorResult = await options.runners.inspector(name, config, await readDocument(options.fs, options.docPath), createTemplateContext(context), buildRoleOptions(options, `inspector-${name}`));
+                        }
+                        catch (error) {
+                            await restoreDocument(options.fs, options.docPath, inspectorSnapshot);
+                            const normalizedError = toError(error);
+                            options.callbacks.onInspectorFailed?.(name, normalizedError);
+                            throw normalizedError;
+                        }
+                        options.callbacks.onInspectorComplete?.(inspectorResult);
+                        context = {
+                            ...context,
+                            inspectors: {
+                                ...context.inspectors,
+                                [inspectorResult.name]: inspectorResult.summary
+                            },
+                            inspectorLogs: {
+                                ...context.inspectorLogs,
+                                ...(inspectorResult.log_path
+                                    ? { [inspectorResult.name]: inspectorResult.log_path }
+                                    : {})
+                            }
+                        };
+                        await writeLoopState(options.fs, options.docPath, state);
+                        const stopReason = readInterruptionReason(options, state);
+                        if (stopReason) {
+                            if (stopReason === "aborted") {
+                                state = await rollbackRoundStatus(options, roundStartState);
+                            }
+                            return finishLoop(options.callbacks, state, stopReason);
+                        }
+                    }
+                    const superintendentResult = await executeSuperintendent(options, context);
+                    context = {
+                        ...context,
+                        superintendentSummary: superintendentResult.summary,
+                        ...(superintendentResult.log_path
+                            ? { superintendentLogPath: superintendentResult.log_path }
+                            : {})
+                    };
+                    if (superintendentResult.transition?.action === "request_review") {
+                        context = {
+                            ...context,
+                            ownerFeedback: undefined
+                        };
+                        state = {
+                            ...state,
+                            state: "review",
+                            reviewTurn: 0
+                        };
+                        emitStateChange(options.callbacks, state);
+                    }
+                    await writeLoopState(options.fs, options.docPath, state);
+                    if (state.state === "in_progress") {
+                        options.callbacks.onRoundComplete?.(state.round);
+                    }
+                    {
+                        const stopReason = readLoopStopReason(options, state);
+                        if (stopReason) {
+                            if (stopReason === "aborted" && state.state === "in_progress") {
+                                state = await rollbackRoundStatus(options, roundStartState);
+                            }
+                            return finishLoop(options.callbacks, state, stopReason);
+                        }
+                    }
+                    continue;
+                }
+                if (context.ownerFeedback &&
+                    shouldContinueReview(await readDocument(options.fs, options.docPath))) {
+                    const superintendentResult = await executeSuperintendent(options, context);
+                    if (superintendentResult.transition?.action !== "request_review") {
+                        throw new Error("Superintendent must call request_review to continue a review exchange");
+                    }
+                    context = {
+                        ...context,
+                        superintendentSummary: superintendentResult.summary,
+                        ...(superintendentResult.log_path
+                            ? { superintendentLogPath: superintendentResult.log_path }
+                            : {}),
+                        ownerFeedback: undefined
+                    };
+                    await writeLoopState(options.fs, options.docPath, state);
+                    {
+                        const stopReason = readInterruptionReason(options, state);
+                        if (stopReason) {
+                            return finishLoop(options.callbacks, state, stopReason);
+                        }
+                    }
+                    continue;
+                }
+                options.callbacks.onOwnerStart?.();
+                const ownerSnapshot = await readDocumentContent(options.fs, options.docPath);
+                let ownerResult;
+                try {
+                    ownerResult = await options.runners.ownerReview(await readDocument(options.fs, options.docPath), createTemplateContext(context), buildRoleOptions(options, "owner"));
+                }
+                catch (error) {
+                    await restoreDocument(options.fs, options.docPath, ownerSnapshot);
+                    throw toError(error);
+                }
+                options.callbacks.onOwnerComplete?.(ownerResult);
+                if (ownerResult.transition.action === "approve_completion") {
+                    context = {
+                        ...context,
+                        ...(ownerResult.log_path ? { ownerLogPath: ownerResult.log_path } : {})
+                    };
+                    state = {
+                        ...state,
+                        state: "completed"
+                    };
+                }
+                else {
+                    context = {
+                        ...context,
+                        ownerFeedback: ownerResult.transition.feedback,
+                        ...(ownerResult.log_path ? { ownerLogPath: ownerResult.log_path } : {})
+                    };
+                    state = applyOwnerFeedback(state, shouldContinueReview(await readDocument(options.fs, options.docPath)));
+                }
+                emitStateChange(options.callbacks, state);
+                await writeLoopState(options.fs, options.docPath, state);
+                if (state.state !== "review") {
+                    options.callbacks.onRoundComplete?.(state.round);
+                }
+                {
+                    const stopReason = readLoopStopReason(options, state);
+                    if (stopReason) {
+                        return finishLoop(options.callbacks, state, stopReason);
+                    }
+                }
+            }
+        });
+    }
+    finally {
+        await releaseLock();
+    }
+}
+function normalizeOptions(input, callbacks) {
+    if (typeof input !== "string") {
+        return {
+            docPath: resolveWorkflowPath(input.docPath, input.cwd, input.homeDir),
+            cwd: input.cwd,
+            homeDir: input.homeDir,
+            fs: input.fs ?? createDefaultFs(),
+            callbacks: input.callbacks ?? {},
+            runners: resolveRunners(input.runners),
+            ...(input.runAgent ? { runAgent: input.runAgent } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.logDir ? { logDir: input.logDir } : {})
+        };
+    }
+    const cwd = process.cwd();
+    const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
+    return {
+        docPath: resolveWorkflowPath(input, cwd, homeDir),
+        cwd,
+        homeDir,
+        fs: createDefaultFs(),
+        callbacks: callbacks ?? {},
+        runners: resolveRunners()
+    };
+}
+function resolveRunners(overrides) {
+    return {
+        builder: overrides?.builder ?? runBuilder,
+        inspector: overrides?.inspector ?? runInspector,
+        superintendent: overrides?.superintendent ?? runSuperintendent,
+        ownerReview: overrides?.ownerReview ?? runOwnerReview
+    };
+}
+function createDefaultFs() {
+    const fs = {
+        readFile: fsPromises.readFile,
+        writeFile: fsPromises.writeFile,
+        readdir: fsPromises.readdir,
+        open: (filePath, flags) => fsPromises.open(filePath, flags),
+        stat: async (filePath) => {
+            const stat = await fsPromises.stat(filePath);
+            return {
+                isFile: () => stat.isFile(),
+                isDirectory: () => stat.isDirectory(),
+                mtimeMs: stat.mtimeMs
+            };
+        },
+        unlink: async (filePath) => {
+            await fsPromises.unlink(filePath);
+        },
+        mkdir: async (filePath, options) => {
+            await fsPromises.mkdir(filePath, options);
+        },
+        rmdir: async (filePath) => {
+            await fsPromises.rmdir(filePath);
+        },
+        rename: async (oldPath, newPath) => {
+            await fsPromises.rename(oldPath, newPath);
+        }
+    };
+    return fs;
+}
+async function readDocument(fs, docPath) {
+    const content = await readDocumentContent(fs, docPath);
+    return parseSuperintendentDoc(docPath, content);
+}
+async function readDocumentContent(fs, docPath) {
+    return fs.readFile(docPath, "utf8");
+}
+async function writeLoopState(fs, docPath, state) {
+    const content = await fs.readFile(docPath, "utf8");
+    const updatedContent = updateStatus(docPath, content, {
+        state: state.state,
+        round: state.round,
+        review_turn: state.reviewTurn
+    });
+    await fs.writeFile(docPath, updatedContent, { encoding: "utf8" });
+}
+async function restoreDocument(fs, docPath, content) {
+    await fs.writeFile(docPath, content, { encoding: "utf8" });
+}
+async function rollbackRoundStatus(options, state) {
+    await writeLoopState(options.fs, options.docPath, state);
+    emitStateChange(options.callbacks, state);
+    return state;
+}
+function createTemplateContext(context) {
+    return {
+        ...(context.builder ? { builder: context.builder } : {}),
+        inspectors: { ...context.inspectors },
+        inspector_logs: { ...context.inspectorLogs },
+        ...(context.superintendentSummary
+            ? {
+                superintendent: {
+                    summary: context.superintendentSummary,
+                    ...(context.superintendentLogPath ? { log_path: context.superintendentLogPath } : {})
+                }
+            }
+            : {}),
+        ...(context.ownerFeedback
+            ? {
+                owner: {
+                    feedback: context.ownerFeedback,
+                    ...(context.ownerLogPath ? { log_path: context.ownerLogPath } : {})
+                }
+            }
+            : {})
+    };
+}
+function beginRound(state) {
+    return {
+        ...state,
+        state: "in_progress",
+        round: state.round + 1,
+        reviewTurn: 0
+    };
+}
+function applyOwnerFeedback(state, continueReview) {
+    const nextReviewTurn = state.reviewTurn + 1;
+    if (continueReview && nextReviewTurn < state.maxReviewTurns) {
+        return {
+            ...state,
+            state: "review",
+            reviewTurn: nextReviewTurn
+        };
+    }
+    return {
+        ...state,
+        state: "in_progress",
+        reviewTurn: 0
+    };
+}
+async function executeSuperintendent(options, context) {
+    options.callbacks.onSuperintendentStart?.();
+    const snapshot = await readDocumentContent(options.fs, options.docPath);
+    try {
+        const doc = await readDocument(options.fs, options.docPath);
+        const result = await options.runners.superintendent(doc, createTemplateContext(context), buildRoleOptions(options, "superintendent"));
+        options.callbacks.onSuperintendentComplete?.(result);
+        return result;
+    }
+    catch (error) {
+        await restoreDocument(options.fs, options.docPath, snapshot);
+        throw toError(error);
+    }
+}
+function buildRoleOptions(options, role) {
+    return {
+        defaultCwd: options.cwd,
+        ...(options.logDir ? { logPath: path.join(options.logDir, makeRunLogFileName(role)) } : {})
+    };
+}
+function shouldContinueReview(doc) {
+    return parseTaskBoard(doc.body).allDone;
+}
+function emitStateChange(callbacks, state) {
+    callbacks.onStateChange?.({ ...state });
+}
+function readLoopStopReason(options, state) {
+    if (state.state === "completed") {
+        return "completed";
+    }
+    if (state.state === "in_progress" && state.round >= state.maxRounds) {
+        return "max_rounds";
+    }
+    return readInterruptionReason(options, state);
+}
+function readInterruptionReason(options, _state) {
+    if (options.signal?.aborted) {
+        return "aborted";
+    }
+    if (options.callbacks.shouldStop?.() === true) {
+        return "stopped";
+    }
+    if (options.callbacks.shouldPause?.() === true) {
+        return "paused";
+    }
+    return undefined;
+}
+function finishLoop(callbacks, state, stopReason) {
+    const snapshot = {
+        ...state,
+        stopReason
+    };
+    callbacks.onLoopComplete?.(snapshot);
+    return snapshot;
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function filterAutoRunInspectors(doc) {
+    const inspectors = doc.frontmatter.inspectors ?? {};
+    const configuredNames = new Set(Object.keys(inspectors));
+    const selected = new Set();
+    const queue = [...collectReferencedInspectors(doc.frontmatter.superintendent.prompt)].filter((name) => configuredNames.has(name));
+    while (queue.length > 0) {
+        const name = queue.shift();
+        if (selected.has(name)) {
+            continue;
+        }
+        selected.add(name);
+        const inspectorPrompt = inspectors[name]?.prompt ?? "";
+        for (const referenced of collectReferencedInspectors(inspectorPrompt)) {
+            if (configuredNames.has(referenced) && !selected.has(referenced)) {
+                queue.push(referenced);
+            }
+        }
+    }
+    return Object.entries(inspectors).filter(([name]) => selected.has(name));
+}
+async function withInjectedAgentRunner(options, operation) {
+    if (!options.runAgent) {
+        return operation();
+    }
+    const spawnApi = spawn;
+    const originalAutonomous = spawnApi.autonomous;
+    spawnApi.autonomous = async (agent, input) => {
+        const result = await options.runAgent?.({
+            agent,
+            prompt: input.prompt,
+            cwd: input.cwd ?? process.cwd(),
+            ...(input.mode ? { mode: input.mode } : {}),
+            ...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
+            ...(input.logPath ? { logPath: input.logPath } : {}),
+            ...(options.signal ? { signal: options.signal } : {})
+        });
+        if (!result) {
+            throw new Error(`Agent \`${agent}\` returned no result.`);
+        }
+        if (result.exitCode !== 0) {
+            throw new Error(result.stderr || result.stdout || `Agent \`${agent}\` failed with exit code ${result.exitCode}`);
+        }
+        return result;
+    };
+    try {
+        return await operation();
+    }
+    finally {
+        spawnApi.autonomous = originalAutonomous;
+    }
+}

package/packages/superintendent/dist/runtime/resolve-cwd.d.ts

@@ -0,0 +1,2 @@
+import type { AgentRoleConfig } from "../document/parse.js";
+export declare function resolveRoleCwd(role: AgentRoleConfig, docPath: string, defaultCwd: string): string;

package/packages/superintendent/dist/runtime/resolve-cwd.js

@@ -0,0 +1,10 @@
+import path from "node:path";
+export function resolveRoleCwd(role, docPath, defaultCwd) {
+    if (role.cwd === undefined) {
+        return defaultCwd;
+    }
+    if (path.isAbsolute(role.cwd)) {
+        return role.cwd;
+    }
+    return path.resolve(path.dirname(docPath), role.cwd);
+}

package/packages/superintendent/dist/runtime/run-builder.d.ts

@@ -0,0 +1,13 @@
+import type { SuperintendentDoc } from "../document/parse.js";
+import { type TemplateContext } from "./templates.js";
+export type BuilderResult = {
+    summary: string;
+    log: string;
+    log_path: string;
+};
+export type RunBuilderOptions = {
+    promptOverride?: string;
+    defaultCwd: string;
+    logPath?: string;
+};
+export declare function runBuilder(doc: SuperintendentDoc, context: Partial<TemplateContext>, options: RunBuilderOptions): Promise<BuilderResult>;

package/packages/superintendent/dist/runtime/run-builder.js

@@ -0,0 +1,102 @@
+import { spawn } from "@poe-code/agent-spawn";
+import { resolveRoleCwd } from "./resolve-cwd.js";
+import { resolveTemplate } from "./templates.js";
+export async function runBuilder(doc, context, options) {
+    const prompt = options.promptOverride ??
+        resolveTemplate(doc.frontmatter.builder.prompt, buildTemplateContext(doc, context));
+    const result = await runAutonomous({
+        agent: doc.frontmatter.builder.agent,
+        mode: doc.frontmatter.builder.mode,
+        prompt,
+        cwd: resolveRoleCwd(doc.frontmatter.builder, doc.filePath, options.defaultCwd),
+        mcpServers: buildMcpServers(doc),
+        ...(options.logPath ? { logPath: options.logPath } : {})
+    });
+    const log = extractLog(result);
+    return {
+        summary: extractSummary(result, log),
+        log,
+        log_path: extractLogPath(result, options)
+    };
+}
+function buildMcpServers(doc) {
+    const merged = {
+        ...(doc.frontmatter.mcp ?? {}),
+        ...(doc.frontmatter.builder.mcp ?? {})
+    };
+    if (Object.keys(merged).length === 0) {
+        return undefined;
+    }
+    const servers = {};
+    for (const [name, config] of Object.entries(merged)) {
+        servers[name] = {
+            command: config.command,
+            ...(config.args ? { args: [...config.args] } : {}),
+            ...(config.timeout !== undefined ? { timeout: config.timeout } : {})
+        };
+    }
+    return servers;
+}
+function buildTemplateContext(doc, context) {
+    return {
+        ...context,
+        plan: {
+            ...(context.plan ?? { path: doc.filePath }),
+            path: doc.filePath
+        }
+    };
+}
+async function runAutonomous(input) {
+    const spawnApi = spawn;
+    if (typeof spawnApi.autonomous === "function") {
+        return spawnApi.autonomous(input.agent, {
+            cwd: input.cwd,
+            prompt: input.prompt,
+            mode: input.mode,
+            ...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
+            ...(input.logPath ? { logPath: input.logPath } : {})
+        });
+    }
+    const result = await spawn(input.agent, {
+        cwd: input.cwd,
+        prompt: input.prompt,
+        mode: input.mode,
+        ...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
+        ...(input.logPath ? { logPath: input.logPath } : {})
+    });
+    return {
+        stdout: result.stdout,
+        ...(result.logFile ? { logFile: result.logFile } : {})
+    };
+}
+function extractLog(result) {
+    if (typeof result === "string") {
+        return result;
+    }
+    return readString(result.log) ?? readString(result.output) ?? readString(result.stdout) ?? readString(result.text) ?? "";
+}
+function extractLogPath(result, options) {
+    if (typeof result !== "string") {
+        const logFile = readString(result.logFile);
+        if (logFile) {
+            return logFile;
+        }
+    }
+    return options.logPath ?? "";
+}
+function extractSummary(result, log) {
+    if (typeof result !== "string") {
+        const explicitSummary = readString(result.summary)?.trim();
+        if (explicitSummary) {
+            return explicitSummary;
+        }
+    }
+    const firstNonEmptyLine = log
+        .split("\n")
+        .map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line).trim())
+        .find((line) => line.length > 0);
+    return firstNonEmptyLine ?? "Builder completed without output.";
+}
+function readString(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/packages/superintendent/dist/runtime/run-inspector.d.ts

@@ -0,0 +1,16 @@
+import type { AgentRoleConfig, SuperintendentDoc } from "../document/parse.js";
+import { type TemplateContext } from "./templates.js";
+export type InspectorResult = {
+    name: string;
+    summary: string;
+    log_path?: string;
+};
+export type RunInspectorOptions = {
+    promptOverride?: string;
+    defaultCwd: string;
+    logPath?: string;
+};
+export declare function runInspector(name: string, config: AgentRoleConfig, doc: SuperintendentDoc, context: Partial<TemplateContext>, options: RunInspectorOptions): Promise<InspectorResult>;
+export declare function runAllInspectors(doc: SuperintendentDoc, context: Partial<TemplateContext>, options: {
+    defaultCwd: string;
+}): Promise<InspectorResult[]>;