poe-code 3.0.196 → 3.0.198

package/packages/superintendent/dist/index.js

@@ -0,0 +1,15 @@
+// Document
+export { parseSuperintendentDoc, superintendentBaseDocumentSchema, superintendentBaseDocumentSchemaId, superintendentDocumentSchema, superintendentDocumentSchemaId } from "./document/parse.js";
+export { updateStatus, transitionState, incrementRound } from "./document/write.js";
+export { parseTaskBoard, hasTaskBoard } from "./document/tasks.js";
+// Runtime
+export { runLoop } from "./runtime/loop.js";
+export { runBuilder } from "./runtime/run-builder.js";
+export { runInspector, runAllInspectors } from "./runtime/run-inspector.js";
+export { resolveTemplate } from "./runtime/templates.js";
+// State
+export { createLoopState, applyTransition, isComplete } from "./state/machine.js";
+// Commands (for composition)
+export { superintendentGroup } from "./commands/index.js";
+// Config
+export { superintendentConfigScope } from "./config-scope.js";

package/packages/superintendent/dist/mcp.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { type Server } from "tiny-stdio-mcp-server";
+import { superintendentMcpGroup } from "./commands/index.js";
+import { parseSuperintendentDoc, type StatusBlock } from "./document/parse.js";
+import { runBuilder } from "./runtime/run-builder.js";
+import { runInspector } from "./runtime/run-inspector.js";
+export type SuperintendentToolsPayload = {
+    docPath: string;
+    state: StatusBlock["state"];
+    inspectorNames: string[];
+};
+export type McpRunners = {
+    superintendentMcpGroup?: typeof superintendentMcpGroup;
+    runBuilder?: typeof runBuilder;
+    runInspector?: typeof runInspector;
+    parseSuperintendentDoc?: typeof parseSuperintendentDoc;
+};
+export type MainOptions = {
+    runners?: McpRunners;
+};
+export declare function createSuperintendentMcpServer(runners?: McpRunners): Omit<Server, "connect"> & {
+    connect(transport: import("tiny-stdio-mcp-server").SDKTransport): Promise<void>;
+};
+export declare function main(argv?: string[], options?: MainOptions): Promise<void>;

package/packages/superintendent/dist/mcp.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+import * as fsPromises from "node:fs/promises";
+import { createMCPServer } from "toolcraft/mcp";
+import { createServer } from "tiny-stdio-mcp-server";
+import { isDirectExecution } from "./direct-execution.js";
+import { superintendentMcpGroup } from "./commands/index.js";
+import { parseSuperintendentDoc } from "./document/parse.js";
+import { runBuilder } from "./runtime/run-builder.js";
+import { runInspector } from "./runtime/run-inspector.js";
+import { createWorkflowTool, parseWorkflowCall } from "./runtime/workflow-tool.js";
+import { createBuilderTool, createInspectorTool, parseBuilderRunInput, parseInspectorRunInput } from "./runtime/agentic-tools.js";
+const MCP_NAME = "superintendent";
+const MCP_VERSION = "0.0.1";
+const SUPERINTENDENT_TOOLS_SUBCOMMAND = "superintendent-tools";
+const SUPERINTENDENT_TOOLS_SERVER_NAME = "superintendent-agentic-tools";
+const WORKFLOW_TRANSITION_SUBCOMMAND = "workflow-transition";
+const WORKFLOW_TRANSITION_SERVER_NAME = "superintendent-workflow-transition";
+function resolveMcpRunners(overrides) {
+    return {
+        superintendentMcpGroup: overrides?.superintendentMcpGroup ?? superintendentMcpGroup,
+        runBuilder: overrides?.runBuilder ?? runBuilder,
+        runInspector: overrides?.runInspector ?? runInspector,
+        parseSuperintendentDoc: overrides?.parseSuperintendentDoc ?? parseSuperintendentDoc
+    };
+}
+export function createSuperintendentMcpServer(runners) {
+    const resolved = resolveMcpRunners(runners);
+    return createMCPServer([resolved.superintendentMcpGroup], {
+        name: MCP_NAME,
+        version: MCP_VERSION
+    });
+}
+export async function main(argv = process.argv, options = {}) {
+    const runners = resolveMcpRunners(options.runners);
+    const originalArgv = process.argv;
+    process.argv = argv;
+    try {
+        if (argv[2] === SUPERINTENDENT_TOOLS_SUBCOMMAND) {
+            await runSuperintendentToolsServer(argv[3], runners);
+            return;
+        }
+        if (argv[2] === WORKFLOW_TRANSITION_SUBCOMMAND) {
+            await runWorkflowTransitionServer(argv[3]);
+            return;
+        }
+        await createSuperintendentMcpServer(options.runners).listen();
+    }
+    finally {
+        process.argv = originalArgv;
+    }
+}
+async function runSuperintendentToolsServer(encodedPayload, runners) {
+    const payload = decodeSuperintendentToolsPayload(encodedPayload);
+    const server = createServer({
+        name: SUPERINTENDENT_TOOLS_SERVER_NAME,
+        version: MCP_VERSION
+    });
+    registerWorkflowTool(server, payload.state);
+    registerBuilderTool(server, payload.docPath, runners);
+    registerInspectorTool(server, payload.docPath, payload.inspectorNames, runners);
+    await server.listen();
+}
+function registerWorkflowTool(server, state) {
+    const tool = createWorkflowTool("superintendent", state);
+    registerWorkflowToolDefinition(server, tool);
+}
+async function runWorkflowTransitionServer(encodedTool) {
+    const tool = decodeWorkflowTool(encodedTool);
+    const server = createServer({
+        name: WORKFLOW_TRANSITION_SERVER_NAME,
+        version: MCP_VERSION
+    });
+    registerWorkflowToolDefinition(server, tool);
+    await server.listen();
+}
+function registerWorkflowToolDefinition(server, tool) {
+    server.tool(tool.name, tool.description, tool.inputSchema, async (input) => {
+        const transition = parseWorkflowCall(input);
+        assertAllowedAction(tool, transition.action);
+        return `Recorded workflow transition: ${transition.action}`;
+    });
+}
+function registerBuilderTool(server, docPath, runners) {
+    const tool = createBuilderTool();
+    server.tool(tool.name, tool.description, tool.inputSchema, async (input) => {
+        const { prompt } = parseBuilderRunInput(input);
+        const freshDoc = await readSuperintendentDoc(docPath, runners);
+        const result = await runners.runBuilder(freshDoc, {}, {
+            promptOverride: prompt,
+            defaultCwd: process.cwd()
+        });
+        return JSON.stringify(result);
+    });
+}
+function registerInspectorTool(server, docPath, inspectorNames, runners) {
+    const tool = createInspectorTool(inspectorNames);
+    server.tool(tool.name, tool.description, tool.inputSchema, async (input) => {
+        const parsed = parseInspectorRunInput(input, inspectorNames);
+        const freshDoc = await readSuperintendentDoc(docPath, runners);
+        const config = freshDoc.frontmatter.inspectors?.[parsed.name];
+        if (!config) {
+            throw new Error(`Inspector "${parsed.name}" is not configured in ${docPath}`);
+        }
+        const result = await runners.runInspector(parsed.name, config, freshDoc, {}, {
+            defaultCwd: process.cwd(),
+            ...(parsed.prompt ? { promptOverride: parsed.prompt } : {})
+        });
+        return JSON.stringify(result);
+    });
+}
+async function readSuperintendentDoc(docPath, runners) {
+    const content = await fsPromises.readFile(docPath, "utf8");
+    return runners.parseSuperintendentDoc(docPath, content);
+}
+function decodeSuperintendentToolsPayload(encodedPayload) {
+    if (typeof encodedPayload !== "string" || encodedPayload.trim().length === 0) {
+        throw invalidSuperintendentToolsPayloadError();
+    }
+    try {
+        const decoded = Buffer.from(encodedPayload, "base64").toString("utf8");
+        const parsed = JSON.parse(decoded);
+        if (!isSuperintendentToolsPayload(parsed)) {
+            throw invalidSuperintendentToolsPayloadError();
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message === invalidSuperintendentToolsPayloadError().message) {
+            throw error;
+        }
+        throw invalidSuperintendentToolsPayloadError();
+    }
+}
+function assertAllowedAction(tool, action) {
+    const allowedActions = tool.inputSchema.properties.action.enum ?? [];
+    if (!allowedActions.includes(action)) {
+        throw new Error(`workflow_transition action "${action}" is not allowed for this role/state`);
+    }
+}
+function invalidSuperintendentToolsPayloadError() {
+    return new Error("Invalid superintendent-tools payload");
+}
+function decodeWorkflowTool(encodedTool) {
+    if (typeof encodedTool !== "string" || encodedTool.trim().length === 0) {
+        throw invalidWorkflowTransitionPayloadError();
+    }
+    try {
+        const decoded = Buffer.from(encodedTool, "base64").toString("utf8");
+        const parsed = JSON.parse(decoded);
+        if (!isWorkflowToolDefinition(parsed)) {
+            throw invalidWorkflowTransitionPayloadError();
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message === invalidWorkflowTransitionPayloadError().message) {
+            throw error;
+        }
+        throw invalidWorkflowTransitionPayloadError();
+    }
+}
+function invalidWorkflowTransitionPayloadError() {
+    return new Error("Invalid workflow-transition payload");
+}
+function isWorkflowToolDefinition(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.name !== "workflow_transition" || typeof value.description !== "string") {
+        return false;
+    }
+    const inputSchema = value.inputSchema;
+    if (!isRecord(inputSchema) || inputSchema.type !== "object") {
+        return false;
+    }
+    const properties = inputSchema.properties;
+    if (!isRecord(properties) || !isRecord(properties.action)) {
+        return false;
+    }
+    return properties.action.type === "string";
+}
+function isSuperintendentToolsPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.docPath === "string" &&
+        value.docPath.length > 0 &&
+        isStatusState(value.state) &&
+        Array.isArray(value.inspectorNames) &&
+        value.inspectorNames.every((name) => typeof name === "string"));
+}
+function isStatusState(value) {
+    return value === "in_progress" || value === "review" || value === "completed";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+if (await isDirectExecution(import.meta.url, process.argv)) {
+    await main();
+}

package/packages/superintendent/dist/runtime/agentic-tools.d.ts

@@ -0,0 +1,33 @@
+type StringProperty = {
+    type: "string";
+    description: string;
+    enum?: string[];
+};
+type ObjectSchema = {
+    type: "object";
+    additionalProperties: false;
+    properties: Record<string, StringProperty>;
+    required: string[];
+};
+export type BuilderToolDefinition = {
+    name: "builder_run";
+    description: string;
+    inputSchema: ObjectSchema;
+};
+export type InspectorToolDefinition = {
+    name: "inspector_run";
+    description: string;
+    inputSchema: ObjectSchema;
+};
+export type BuilderRunInput = {
+    prompt: string;
+};
+export type InspectorRunInput = {
+    name: string;
+    prompt?: string;
+};
+export declare function createBuilderTool(): BuilderToolDefinition;
+export declare function createInspectorTool(inspectorNames: string[]): InspectorToolDefinition;
+export declare function parseBuilderRunInput(input: unknown): BuilderRunInput;
+export declare function parseInspectorRunInput(input: unknown, inspectorNames: string[]): InspectorRunInput;
+export {};

package/packages/superintendent/dist/runtime/agentic-tools.js

@@ -0,0 +1,74 @@
+export function createBuilderTool() {
+    return {
+        name: "builder_run",
+        description: "Run the builder agent with a prompt you compose. Returns the builder's summary and the path to its session log. Use this to make targeted changes mid-round without waiting for the next auto-run.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                prompt: {
+                    type: "string",
+                    description: "Full prompt for the builder. Replaces the frontmatter `builder.prompt` template for this call only."
+                }
+            },
+            required: ["prompt"]
+        }
+    };
+}
+export function createInspectorTool(inspectorNames) {
+    const namesAvailable = inspectorNames.length > 0;
+    return {
+        name: "inspector_run",
+        description: namesAvailable
+            ? `Re-run a specific inspector. Returns the inspector's summary. Available inspectors: ${inspectorNames.join(", ")}.`
+            : "Re-run a specific inspector. No inspectors are configured for this document.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Name of the inspector to run, as defined under `inspectors:` in the frontmatter.",
+                    ...(namesAvailable ? { enum: inspectorNames } : {})
+                },
+                prompt: {
+                    type: "string",
+                    description: "Optional prompt that replaces the inspector's frontmatter `prompt` template for this call only. Omit to use the configured prompt."
+                }
+            },
+            required: ["name"]
+        }
+    };
+}
+export function parseBuilderRunInput(input) {
+    if (!isRecord(input)) {
+        throw new Error("builder_run requires an object input with a `prompt` field");
+    }
+    const prompt = input.prompt;
+    if (typeof prompt !== "string" || prompt.trim().length === 0) {
+        throw new Error("builder_run `prompt` must be a non-empty string");
+    }
+    return { prompt };
+}
+export function parseInspectorRunInput(input, inspectorNames) {
+    if (!isRecord(input)) {
+        throw new Error("inspector_run requires an object input with a `name` field");
+    }
+    const name = input.name;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error("inspector_run `name` must be a non-empty string");
+    }
+    if (inspectorNames.length > 0 && !inspectorNames.includes(name)) {
+        throw new Error(`inspector_run name "${name}" is not configured. Available inspectors: ${inspectorNames.join(", ")}`);
+    }
+    if (input.prompt === undefined) {
+        return { name };
+    }
+    if (typeof input.prompt !== "string" || input.prompt.trim().length === 0) {
+        throw new Error("inspector_run `prompt` must be a non-empty string when provided");
+    }
+    return { name, prompt: input.prompt };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/superintendent/dist/runtime/loop.d.ts

@@ -0,0 +1,88 @@
+import { type McpSpawnConfig } from "@poe-code/agent-spawn";
+import { type LoopState } from "../state/machine.js";
+import { runBuilder, type BuilderResult } from "./run-builder.js";
+import { runInspector, type InspectorResult } from "./run-inspector.js";
+import { runOwnerReview, type OwnerResult } from "./run-owner-review.js";
+import { runSuperintendent, type SuperintendentResult } from "./run-superintendent.js";
+export type SuperintendentStopReason = "completed" | "max_rounds" | "paused" | "stopped" | "aborted";
+export type SuperintendentRunResult = LoopState & {
+    stopReason: SuperintendentStopReason;
+};
+export interface SuperintendentFileStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    mtimeMs: number;
+}
+export interface SuperintendentFileSystem {
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: string, options?: {
+        encoding?: BufferEncoding;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<SuperintendentFileStat>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+}
+export interface AgentRunInput {
+    agent: string;
+    prompt: string;
+    cwd: string;
+    mode?: string;
+    mcpServers?: McpSpawnConfig;
+    signal?: AbortSignal;
+    logPath?: string;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+}
+export interface AgentRunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    summary?: string;
+    log?: string;
+    logFile?: string;
+    output?: string;
+    text?: string;
+    transition?: unknown;
+    toolCalls?: unknown;
+    sessionResult?: unknown;
+}
+export type LoopCallbacks = {
+    onBuilderStart?: () => void;
+    onBuilderComplete?: (result: BuilderResult) => void;
+    onBuilderFailed?: (error: Error) => void;
+    onInspectorStart?: (name: string) => void;
+    onInspectorComplete?: (result: InspectorResult) => void;
+    onInspectorFailed?: (name: string, error: Error) => void;
+    onSuperintendentStart?: () => void;
+    onSuperintendentComplete?: (result: SuperintendentResult) => void;
+    onOwnerStart?: () => void;
+    onOwnerComplete?: (result: OwnerResult) => void;
+    onRoundComplete?: (round: number) => void;
+    onLoopComplete?: (state: SuperintendentRunResult) => void;
+    onStateChange?: (state: LoopState) => void;
+    shouldPause?: () => boolean;
+    shouldStop?: () => boolean;
+};
+export type LoopRunners = {
+    builder?: typeof runBuilder;
+    inspector?: typeof runInspector;
+    superintendent?: typeof runSuperintendent;
+    ownerReview?: typeof runOwnerReview;
+};
+export type RunLoopOptions = {
+    docPath: string;
+    cwd: string;
+    homeDir: string;
+    fs?: SuperintendentFileSystem;
+    callbacks?: LoopCallbacks;
+    runAgent?: (input: AgentRunInput) => Promise<AgentRunResult>;
+    runners?: LoopRunners;
+    signal?: AbortSignal;
+    logDir?: string;
+};
+export declare function runLoop(docPath: string, callbacks?: LoopCallbacks): Promise<SuperintendentRunResult>;
+export declare function runLoop(options: RunLoopOptions): Promise<SuperintendentRunResult>;