poe-code 3.0.202 → 3.0.204

package/packages/superintendent/dist/commands/run.d.ts

@@ -1,4 +1,6 @@
+import { type RuntimeOverrideOptions } from "@poe-code/agent-harness-tools";
 import { select, type Dashboard } from "@poe-code/design-system";
+import { type Integrations } from "@poe-code/poe-code-config";
 import { type AgentRunInput, type AgentRunResult, type RunLoopOptions, type SuperintendentFileSystem, type SuperintendentRunResult } from "../runtime/loop.js";
 export type SuperintendentRunCommandResult = SuperintendentRunResult & {
     docPath: string;
@@ -9,6 +11,12 @@ export type RunCommandOptions = {
     homeDir: string;
     docPath?: string;
     builderAgent?: string;
+    runtime?: "host" | "docker" | "e2b";
+    runtimeImage?: string;
+    runtimeTemplate?: string;
+    detach?: boolean;
+    mountPoeCode?: boolean;
+    runnerSync?: RuntimeOverrideOptions["runnerSync"];
     configuredDefaultAgent?: string | null;
     planDirectory?: string;
     assumeYes?: boolean;
@@ -40,17 +48,30 @@ export type RunCommandOptions = {
     openInEditor?: (absolutePath: string, env: Record<string, string | undefined>) => void;
     stderr?: NodeJS.WritableStream;
     exit?: (code: number) => never;
+    integrations?: Integrations | null;
 };
 export declare const runCommand: import("toolcraft").Command<{
     [x: string]: never;
 }, import("toolcraft-schema").ObjectSchema<{
     readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
     readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+    readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
     readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
 }>, undefined, SuperintendentRunCommandResult> & {
     readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"run", import("toolcraft-schema").ObjectSchema<{
         readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
         readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+        readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
         readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
     }>, SuperintendentRunCommandResult, ("cli" | "sdk")[], undefined>;
 };
@@ -62,11 +83,23 @@ export declare function createRunMcpCommand(runners?: RunMcpCommandRunners): imp
 }, import("toolcraft-schema").ObjectSchema<{
     readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
     readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+    readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
     readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
 }>, undefined, SuperintendentRunCommandResult> & {
     readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"run", import("toolcraft-schema").ObjectSchema<{
         readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
         readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+        readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
         readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
     }>, SuperintendentRunCommandResult, "mcp"[], undefined>;
 };
@@ -75,11 +108,23 @@ export declare const runMcpCommand: import("toolcraft").Command<{
 }, import("toolcraft-schema").ObjectSchema<{
     readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
     readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+    readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+    readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
     readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
 }>, undefined, SuperintendentRunCommandResult> & {
     readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"run", import("toolcraft-schema").ObjectSchema<{
         readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
         readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+        readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
         readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
     }>, SuperintendentRunCommandResult, "mcp"[], undefined>;
 };

package/packages/superintendent/dist/commands/run.js

@@ -7,7 +7,7 @@ import { parseAgentSpecifier } from "@poe-code/agent-defs";
 import { executePoeAgent } from "./poe-agent-runner.js";
 import { S, UserError, defineCommand } from "toolcraft";
 import { acp, cancel, createDashboard, isCancel, resolveOutputFormat, select, shouldUseInteractiveDashboard, text } from "@poe-code/design-system";
-import { planConfigScope, readMergedDocument, resolveConfigPath, resolveProjectConfigPath, resolveScope } from "@poe-code/poe-code-config";
+import { planConfigScope, loadIntegrations, mergeLoopCallbacks, readMergedDocument, resolveConfigPath, resolveProjectConfigPath, resolveScope } from "@poe-code/poe-code-config";
 import { superintendentConfigScope } from "../config-scope.js";
 import { parseSuperintendentDoc, readExplicitBuilderAgent } from "../document/parse.js";
 import { runLoop } from "../runtime/loop.js";
@@ -25,6 +25,18 @@ const runParams = S.Object({
     agent: S.Optional(S.String({
         description: "Override the builder agent for this run. Precedence: --agent > plan frontmatter builder.agent."
     })),
+    runtime: S.Optional(S.Enum(["host", "docker", "e2b"], {
+        description: "Override runtime backend: host, docker, or e2b"
+    })),
+    runtimeImage: S.Optional(S.String({ description: "Override Docker runtime image" })),
+    runtimeTemplate: S.Optional(S.String({ description: "Override E2B runtime template id" })),
+    detach: S.Optional(S.Boolean({ description: "Run as a detached runtime job" })),
+    mountPoeCode: S.Optional(S.Boolean({
+        description: "Mount the local poe-code checkout into the runtime"
+    })),
+    runnerSync: S.Optional(S.Enum(["both", "upload", "none"], {
+        description: "Override runner workspace sync: both, upload, or none"
+    })),
     tui: S.Optional(S.Boolean({ description: "Show a live dashboard while Superintendent is running" }))
 });
 export const runCommand = defineCommand({
@@ -37,19 +49,35 @@ export const runCommand = defineCommand({
         const cwd = process.cwd();
         const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
         const commandConfig = await resolveSuperintendentCommandConfig(cwd, homeDir, process.env);
+        const integrations = await loadIntegrations(commandConfig.configDoc);
         const tuiEnabled = params.tui ?? commandConfig.tui;
-        return runSuperintendentCommand({
-            cwd,
-            homeDir,
-            docPath: params.doc,
-            ...(params.agent ? { builderAgent: params.agent } : {}),
-            configuredDefaultAgent: commandConfig.configuredDefaultAgent,
-            assumeYes: process.argv.includes("--yes"),
-            interactive: Boolean(process.stdin.isTTY),
-            useDashboard: shouldUseInteractiveDashboard(tuiEnabled) && resolveOutputFormat() === "terminal",
-            env: process.env,
-            ...(commandConfig.planDirectory ? { planDirectory: commandConfig.planDirectory } : {})
-        });
+        try {
+            const runOptions = {
+                cwd,
+                homeDir,
+                docPath: params.doc,
+                ...(params.agent ? { builderAgent: params.agent } : {}),
+                ...(params.runtime ? { runtime: params.runtime } : {}),
+                ...(params.runtimeImage ? { runtimeImage: params.runtimeImage } : {}),
+                ...(params.runtimeTemplate ? { runtimeTemplate: params.runtimeTemplate } : {}),
+                ...(params.detach ? { detach: params.detach } : {}),
+                ...(params.mountPoeCode ? { mountPoeCode: params.mountPoeCode } : {}),
+                ...(params.runnerSync ? { runnerSync: params.runnerSync } : {}),
+                configuredDefaultAgent: commandConfig.configuredDefaultAgent,
+                assumeYes: process.argv.includes("--yes"),
+                interactive: Boolean(process.stdin.isTTY),
+                useDashboard: shouldUseInteractiveDashboard(tuiEnabled) && resolveOutputFormat() === "terminal",
+                env: process.env,
+                integrations,
+                ...(commandConfig.planDirectory ? { planDirectory: commandConfig.planDirectory } : {})
+            };
+            return integrations
+                ? await integrations.traceRun("superintendent", params.doc ?? "run", () => runSuperintendentCommand(runOptions))
+                : await runSuperintendentCommand(runOptions);
+        }
+        finally {
+            await integrations?.shutdown();
+        }
     },
     render: {
         rich: (result, { logger }) => {
@@ -90,19 +118,34 @@ export function createRunMcpCommand(runners) {
             const cwd = process.cwd();
             const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
             const commandConfig = await resolveSuperintendentCommandConfig(cwd, homeDir, process.env);
-            return runSuperintendentCommand({
-                cwd,
-                homeDir,
-                docPath: params.doc,
-                ...(params.agent ? { builderAgent: params.agent } : {}),
-                configuredDefaultAgent: commandConfig.configuredDefaultAgent,
-                assumeYes: true,
-                interactive: false,
-                useDashboard: false,
-                env: process.env,
-                ...(commandConfig.planDirectory ? { planDirectory: commandConfig.planDirectory } : {}),
-                ...(runners?.runLoop ? { runLoop: runners.runLoop } : {})
-            });
+            const integrations = await loadIntegrations(commandConfig.configDoc);
+            try {
+                const runOptions = {
+                    cwd,
+                    homeDir,
+                    docPath: params.doc,
+                    ...(params.agent ? { builderAgent: params.agent } : {}),
+                    ...(params.runtime ? { runtime: params.runtime } : {}),
+                    ...(params.runtimeImage ? { runtimeImage: params.runtimeImage } : {}),
+                    ...(params.runtimeTemplate ? { runtimeTemplate: params.runtimeTemplate } : {}),
+                    ...(params.detach ? { detach: params.detach } : {}),
+                    ...(params.mountPoeCode ? { mountPoeCode: params.mountPoeCode } : {}),
+                    configuredDefaultAgent: commandConfig.configuredDefaultAgent,
+                    assumeYes: true,
+                    interactive: false,
+                    useDashboard: false,
+                    env: process.env,
+                    integrations,
+                    ...(commandConfig.planDirectory ? { planDirectory: commandConfig.planDirectory } : {}),
+                    ...(runners?.runLoop ? { runLoop: runners.runLoop } : {})
+                };
+                return integrations
+                    ? await integrations.traceRun("superintendent", params.doc ?? "run", () => runSuperintendentCommand(runOptions))
+                    : await runSuperintendentCommand(runOptions);
+            }
+            finally {
+                await integrations?.shutdown();
+            }
         },
         render: runCommand.render
     });
@@ -117,13 +160,14 @@ async function resolveSuperintendentCommandConfig(cwd, homeDir, env, fs) {
         const superintendentResolved = resolveScope(superintendentConfigScope.schema, document[superintendentConfigScope.scope], env);
         const coreResolved = resolveScope(coreDefaultAgentConfigSchema, document.core, env);
         return {
+            configDoc: document,
             configuredDefaultAgent: normalizeAgentSelection(coreResolved.defaultAgent) ?? null,
             ...(planDirectory ? { planDirectory } : {}),
             tui: superintendentResolved.tui === true
         };
     }
     catch {
-        return { configuredDefaultAgent: null, tui: false };
+        return { configDoc: {}, configuredDefaultAgent: null, tui: false };
     }
 }
 async function resolveSuperintendentPlanDirectory(cwd, homeDir, env, fs) {
@@ -176,6 +220,16 @@ export async function runSuperintendentCommand(options) {
     const useDashboard = options.useDashboard ?? resolveOutputFormat() === "terminal";
     const stderr = options.stderr ?? process.stderr;
     const exitProcess = options.exit ?? ((code) => process.exit(code));
+    const integrations = options.integrations ?? null;
+    const shutdownAndExit = (code) => {
+        if (!integrations) {
+            exitProcess(code);
+            return;
+        }
+        void integrations.shutdown().finally(() => {
+            exitProcess(code);
+        });
+    };
     const selectedDocPath = await resolveDocPath({
         cwd: options.cwd,
         homeDir: options.homeDir,
@@ -214,7 +268,7 @@ export async function runSuperintendentCommand(options) {
         const headlessAbort = new AbortController();
         const headlessSigint = () => {
             headlessAbort.abort();
-            exitProcess(130);
+            shutdownAndExit(130);
         };
         process.on("SIGINT", headlessSigint);
         try {
@@ -225,7 +279,7 @@ export async function runSuperintendentCommand(options) {
                 ...(options.fs ? { fs } : {}),
                 signal: headlessAbort.signal,
                 logDir: runLogDir,
-                callbacks: {
+                callbacks: mergeLoopCallbacks({
                     onBuilderStart: () => {
                         activeStage = "builder";
                     },
@@ -256,11 +310,20 @@ export async function runSuperintendentCommand(options) {
                     onOwnerComplete: () => {
                         activeStage = undefined;
                     }
-                },
+                }, integrations?.superintendentCallbacks),
                 runAgent: createAgentRunner({
                     session: undefined,
                     executeAgent: options.executeAgent,
                     selectedBuilderAgent,
+                    integrations,
+                    runtime: {
+                        runtime: options.runtime,
+                        runtimeImage: options.runtimeImage,
+                        runtimeTemplate: options.runtimeTemplate,
+                        detach: options.detach,
+                        mountPoeCode: options.mountPoeCode,
+                        runnerSync: options.runnerSync
+                    },
                     activeStage: () => activeStage,
                     now,
                     stderr
@@ -426,7 +489,7 @@ export async function runSuperintendentCommand(options) {
         abortController.abort();
         session.dashboard.stop();
         session.dashboard.destroy();
-        exitProcess(130);
+        shutdownAndExit(130);
     };
     const handleDashboardCommand = (command) => {
         if (command === "forceQuit") {
@@ -499,13 +562,22 @@ export async function runSuperintendentCommand(options) {
                 cwd: options.cwd,
                 homeDir: options.homeDir,
                 ...(options.fs ? { fs } : {}),
-                callbacks,
+                callbacks: mergeLoopCallbacks(callbacks, integrations?.superintendentCallbacks),
                 signal: abortController.signal,
                 logDir: runLogDir,
                 runAgent: createAgentRunner({
                     session,
                     executeAgent: options.executeAgent,
                     selectedBuilderAgent,
+                    integrations,
+                    runtime: {
+                        runtime: options.runtime,
+                        runtimeImage: options.runtimeImage,
+                        runtimeTemplate: options.runtimeTemplate,
+                        detach: options.detach,
+                        mountPoeCode: options.mountPoeCode,
+                        runnerSync: options.runnerSync
+                    },
                     activeStage: () => session.activeStage,
                     now,
                     stderr
@@ -650,7 +722,8 @@ function createAgentRunner(options) {
     return async (input) => {
         const activeStage = options.activeStage();
         const agent = activeStage === "builder" ? options.selectedBuilderAgent : input.agent;
-        const executeAgent = options.executeAgent ?? executeSpawnAgent;
+        const executeAgent = options.executeAgent ??
+            ((nextAgent, nextInput) => executeSpawnAgent(nextAgent, nextInput, options.integrations));
         const stageLabel = formatStageLabel(activeStage);
         const emitLine = (kind, line) => {
             if (line.length === 0) {
@@ -672,7 +745,12 @@ function createAgentRunner(options) {
         const onStdout = (chunk) => stdoutBuffer.push(chunk);
         const onStderr = (chunk) => stderrBuffer.push(chunk);
         try {
-            const result = await executeAgent(agent, { ...input, onStdout, onStderr });
+            const result = await executeAgent(agent, {
+                ...input,
+                ...options.runtime,
+                onStdout,
+                onStderr
+            });
             if (options.session && result.usage) {
                 options.session.tokensIn += result.usage.inputTokens;
                 options.session.tokensOut += result.usage.outputTokens;
@@ -717,12 +795,12 @@ function formatStageLabel(stage) {
     }
     return `inspector:${stage.inspector}`;
 }
-async function executeSpawnAgent(agent, input) {
+async function executeSpawnAgent(agent, input, integrations) {
     if (parseAgentSpecifier(agent).agent === "poe-agent") {
         return executePoeAgent(agent, input);
     }
     if ((input.onStdout || input.onStderr) && supportsStreaming(agent)) {
-        return executeSpawnAgentStreaming(agent, input);
+        return executeSpawnAgentStreaming(agent, input, integrations);
     }
     const tee = input.onStdout || input.onStderr
         ? {
@@ -738,6 +816,12 @@ async function executeSpawnAgent(agent, input) {
         ...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
         ...(input.logPath ? { logPath: input.logPath } : {}),
+        ...(input.runtime ? { runtime: input.runtime } : {}),
+        ...(input.runtimeImage ? { runtimeImage: input.runtimeImage } : {}),
+        ...(input.runtimeTemplate ? { runtimeTemplate: input.runtimeTemplate } : {}),
+        ...(input.detach ? { detach: input.detach } : {}),
+        ...(input.mountPoeCode ? { mountPoeCode: input.mountPoeCode } : {}),
+        ...(input.runnerSync ? { runnerSync: input.runnerSync } : {}),
         ...(tee ? { tee } : {})
     });
     return {
@@ -752,7 +836,7 @@ function supportsStreaming(agent) {
     const config = getSpawnConfig(agent);
     return config?.kind === "cli";
 }
-async function executeSpawnAgentStreaming(agent, input) {
+async function executeSpawnAgentStreaming(agent, input, integrations) {
     const writer = (line) => {
         input.onStdout?.(`${line}\n`);
     };
@@ -764,6 +848,12 @@ async function executeSpawnAgentStreaming(agent, input) {
         ...(input.mode ? { mode: input.mode } : {}),
         ...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
+        ...(input.runtime ? { runtime: input.runtime } : {}),
+        ...(input.runtimeImage ? { runtimeImage: input.runtimeImage } : {}),
+        ...(input.runtimeTemplate ? { runtimeTemplate: input.runtimeTemplate } : {}),
+        ...(input.detach ? { detach: input.detach } : {}),
+        ...(input.mountPoeCode ? { mountPoeCode: input.mountPoeCode } : {}),
+        ...(input.runnerSync ? { runnerSync: input.runnerSync } : {}),
         ...(input.onStderr ? { tee: { stderr: { write: input.onStderr } } } : {})
     });
     const middlewareContext = {
@@ -778,7 +868,12 @@ async function executeSpawnAgentStreaming(agent, input) {
         ...(input.logPath ? { logPath: input.logPath } : {}),
         ...(input.mode ? { mode: input.mode } : {})
     };
-    await applyMiddlewares([spawnLog, usageCapture, sessionCapture], middlewareContext);
+    await applyMiddlewares([
+        spawnLog,
+        usageCapture,
+        sessionCapture,
+        ...(integrations?.spawnMiddleware ? [integrations.spawnMiddleware] : [])
+    ], middlewareContext);
     await acp.withAcpWriter(writer, () => renderAcpStream(middlewareContext.eventStream ?? rawEvents));
     const final = await done;
     const logFile = middlewareContext.logFile ?? final.logFile;

package/packages/superintendent/dist/commands/superintendent-group.d.ts

@@ -122,11 +122,23 @@ export declare const superintendentGroup: import("toolcraft").Group<{
     }, import("toolcraft-schema").ObjectSchema<{
         readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
         readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+        readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
         readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
     }>, undefined, import("./run.js").SuperintendentRunCommandResult> & {
         readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"run", import("toolcraft-schema").ObjectSchema<{
             readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
             readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+            readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+            readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+            readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
             readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
         }>, import("./run.js").SuperintendentRunCommandResult, ("cli" | "sdk")[], undefined>;
     }) | (import("toolcraft").Command<{
@@ -214,11 +226,23 @@ export declare function createSuperintendentMcpGroup(runners?: SuperintendentMcp
     }, import("toolcraft-schema").ObjectSchema<{
         readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
         readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+        readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
         readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
     }>, undefined, import("./run.js").SuperintendentRunCommandResult> & {
         readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"run", import("toolcraft-schema").ObjectSchema<{
             readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
             readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+            readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+            readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+            readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
             readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
         }>, import("./run.js").SuperintendentRunCommandResult, "mcp"[], undefined>;
     }) | (import("toolcraft").Command<{
@@ -305,11 +329,23 @@ export declare const superintendentMcpGroup: import("toolcraft").Group<{
     }, import("toolcraft-schema").ObjectSchema<{
         readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
         readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+        readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+        readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+        readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
         readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
     }>, undefined, import("./run.js").SuperintendentRunCommandResult> & {
         readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"run", import("toolcraft-schema").ObjectSchema<{
             readonly doc: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
             readonly agent: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly runtime: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["host", "docker", "e2b"]>>;
+            readonly runtimeImage: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly runtimeTemplate: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").StringSchema>;
+            readonly detach: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+            readonly mountPoeCode: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+            readonly runnerSync: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").EnumSchema<readonly ["both", "upload", "none"]>>;
             readonly tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
         }>, import("./run.js").SuperintendentRunCommandResult, "mcp"[], undefined>;
     }) | (import("toolcraft").Command<{

package/packages/superintendent/dist/runtime/agent-runner.d.ts

@@ -0,0 +1,31 @@
+import "@poe-code/agent-spawn/register-factories";
+import { type RuntimeOverrideOptions } from "@poe-code/agent-harness-tools";
+import { type McpSpawnConfig, type SpawnMode } from "@poe-code/agent-spawn";
+export type { McpSpawnConfig, SpawnMode };
+export type AutonomousInput = {
+    agent: string;
+    mode?: string;
+    prompt: string;
+    cwd?: string;
+    mcpServers?: McpSpawnConfig;
+    logPath?: string;
+    runtime?: RuntimeOverrideOptions["runtime"];
+    runtimeImage?: string;
+    runtimeTemplate?: string;
+    detach?: boolean;
+    mountPoeCode?: boolean;
+    runnerSync?: RuntimeOverrideOptions["runnerSync"];
+};
+export type AutonomousOutput = string | {
+    summary?: unknown;
+    log?: unknown;
+    output?: unknown;
+    stdout?: unknown;
+    text?: unknown;
+    toolCalls?: unknown;
+    sessionResult?: unknown;
+    logFile?: unknown;
+};
+type AutonomousRunner = (agent: string, options: Omit<AutonomousInput, "agent">) => Promise<AutonomousOutput>;
+export declare function withAutonomousAgentRunner<T>(runner: AutonomousRunner, operation: () => Promise<T>): Promise<T>;
+export declare function runAutonomousAgent(input: AutonomousInput): Promise<AutonomousOutput>;

package/packages/superintendent/dist/runtime/agent-runner.js

@@ -0,0 +1,121 @@
+import "@poe-code/agent-spawn/register-factories";
+import { mkdirSync, openSync, writeSync, closeSync } from "node:fs";
+import path from "node:path";
+import { resolvePoeCommandExecution, runPoeCommand } from "@poe-code/agent-harness-tools";
+import { buildSpawnArgs } from "@poe-code/agent-spawn";
+let injectedRunner;
+export async function withAutonomousAgentRunner(runner, operation) {
+    const previous = injectedRunner;
+    injectedRunner = runner;
+    try {
+        return await operation();
+    }
+    finally {
+        injectedRunner = previous;
+    }
+}
+export async function runAutonomousAgent(input) {
+    if (injectedRunner) {
+        return injectedRunner(input.agent, {
+            cwd: input.cwd,
+            prompt: input.prompt,
+            mode: input.mode,
+            ...(input.mcpServers ? { mcpServers: input.mcpServers } : {}),
+            ...(input.logPath ? { logPath: input.logPath } : {}),
+            ...(input.runtime ? { runtime: input.runtime } : {}),
+            ...(input.runtimeImage ? { runtimeImage: input.runtimeImage } : {}),
+            ...(input.runtimeTemplate ? { runtimeTemplate: input.runtimeTemplate } : {}),
+            ...(input.detach ? { detach: input.detach } : {}),
+            ...(input.mountPoeCode ? { mountPoeCode: input.mountPoeCode } : {}),
+            ...(input.runnerSync ? { runnerSync: input.runnerSync } : {})
+        });
+    }
+    const spawnArgs = buildSpawnArgs(input.agent, {
+        prompt: input.prompt,
+        mode: input.mode,
+        ...(input.mcpServers ? { mcpServers: input.mcpServers } : {})
+    });
+    const processEnv = spawnArgs.env ? { ...process.env, ...spawnArgs.env } : undefined;
+    const argv = [spawnArgs.binaryName, ...spawnArgs.args];
+    const logFd = input.logPath ? openSpawnLog(input.logPath) : undefined;
+    const execution = resolvePoeCommandExecution({
+        cwd: input.cwd ?? process.cwd(),
+        env: (processEnv ?? process.env),
+        argv,
+        tool: input.agent,
+        runtime: {
+            runtime: input.runtime,
+            runtimeImage: input.runtimeImage,
+            runtimeTemplate: input.runtimeTemplate,
+            detach: input.detach,
+            mountPoeCode: input.mountPoeCode,
+            runnerSync: input.runnerSync
+        },
+        openSpec: {
+            execution: {
+                wrapForLogTee: false,
+                stdin: "inherit",
+                stdout: "pipe",
+                stderr: "pipe",
+                env: processEnv,
+                captureOutput: true,
+                onStdout(chunk) {
+                    appendSpawnLog(logFd, chunk);
+                },
+                onStderr(chunk) {
+                    appendSpawnLog(logFd, chunk);
+                }
+            }
+        }
+    });
+    try {
+        const result = await runPoeCommand({
+            factory: execution.factory,
+            openSpec: execution.openSpec,
+            detach: execution.detach,
+            state: execution.state
+        });
+        if (result.kind === "detached") {
+            return {
+                stdout: "",
+                ...(input.logPath ? { logFile: input.logPath } : {})
+            };
+        }
+        return {
+            stdout: result.stdout ?? "",
+            ...(input.logPath ? { logFile: input.logPath } : {})
+        };
+    }
+    finally {
+        closeSpawnLog(logFd);
+    }
+}
+function openSpawnLog(filePath) {
+    try {
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        return openSync(filePath, "a");
+    }
+    catch {
+        return undefined;
+    }
+}
+function appendSpawnLog(fd, chunk) {
+    if (fd === undefined)
+        return;
+    try {
+        writeSync(fd, chunk);
+    }
+    catch {
+        // logging is best-effort
+    }
+}
+function closeSpawnLog(fd) {
+    if (fd === undefined)
+        return;
+    try {
+        closeSync(fd);
+    }
+    catch {
+        // logging is best-effort
+    }
+}