poe-code 3.0.197 → 3.0.199

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

@@ -0,0 +1,148 @@
+import path from "node:path";
+import { readFile, stat, mkdir, writeFile, unlink, readdir, chmod } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { S, UserError, defineCommand } from "toolcraft";
+import { planConfigScope, readMergedDocument, resolveConfigPath, resolveProjectConfigPath, resolveScope } from "@poe-code/poe-code-config";
+import { installSkill, resolveAgentSupport } from "@poe-code/agent-skill-config";
+import { skillPlanConfigSection } from "@poe-code/agent-harness-tools";
+const fs = {
+    readFile: (p, encoding) => readFile(p, encoding),
+    writeFile: (p, content) => writeFile(p, content),
+    mkdir: (p, options) => mkdir(p, options).then(() => undefined),
+    unlink: (p) => unlink(p),
+    stat: (p) => stat(p).then((s) => ({ mode: s.mode })),
+    readdir: (p) => readdir(p),
+    chmod: (p, mode) => chmod(p, mode)
+};
+const installParams = S.Object({
+    agent: S.String({
+        default: "claude-code",
+        description: "Agent to install the Superintendent skill for (claude-code, codex, opencode)"
+    }),
+    scope: S.Enum(["local", "global"], {
+        default: "local",
+        description: "Install scope"
+    })
+});
+export const installCommand = defineCommand({
+    name: "install",
+    description: "Install the Superintendent /superintendent skill and scaffold the shared plan directory.",
+    positional: ["agent"],
+    params: installParams,
+    scope: ["cli", "sdk"],
+    handler: async ({ params }) => {
+        const cwd = process.cwd();
+        const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
+        const scope = params.scope;
+        const support = resolveAgentSupport(params.agent);
+        if (support.status !== "supported" || !support.id) {
+            throw new UserError(`Unsupported agent: ${params.agent}`);
+        }
+        const skillContent = await loadSkillTemplate();
+        const skillResult = await installSkill(support.id, {
+            name: "poe-code-superintendent-plan",
+            content: skillContent + "\n\n" + skillPlanConfigSection("superintendent")
+        }, {
+            fs,
+            cwd,
+            homeDir,
+            scope
+        });
+        const planDirectory = await resolvePlanDirectory(cwd, homeDir, process.env);
+        const absolutePlanDirectory = resolveAbsoluteDirectory(planDirectory, cwd, homeDir);
+        let planDirectoryCreated = false;
+        if (!(await pathExists(absolutePlanDirectory))) {
+            await mkdir(absolutePlanDirectory, { recursive: true });
+            planDirectoryCreated = true;
+        }
+        return {
+            agent: support.id,
+            scope,
+            skillPath: skillResult.displayPath,
+            planDirectory,
+            planDirectoryCreated
+        };
+    },
+    render: {
+        rich: (result, { logger }) => {
+            logger.success(`Installed Superintendent skill for ${result.agent} (${result.scope}).`);
+            logger.message(`Skill: ${result.skillPath}`);
+            if (result.planDirectoryCreated) {
+                logger.message(`Created: ${result.planDirectory}`);
+            }
+        },
+        markdown: (result) => {
+            const lines = [
+                "## Superintendent install",
+                "",
+                `- Agent: ${result.agent}`,
+                `- Scope: ${result.scope}`,
+                `- Skill: ${result.skillPath}`
+            ];
+            if (result.planDirectoryCreated) {
+                lines.push(`- Created: ${result.planDirectory}`);
+            }
+            return lines.join("\n");
+        },
+        json: (result) => result
+    }
+});
+async function resolvePlanDirectory(cwd, homeDir, env) {
+    const configPath = resolveConfigPath(homeDir);
+    const projectConfigPath = resolveProjectConfigPath(cwd);
+    const document = await readMergedDocument(fs, configPath, projectConfigPath);
+    return resolveScope(planConfigScope.schema, document.plan, env).plan_directory;
+}
+function resolveAbsoluteDirectory(dir, cwd, homeDir) {
+    if (dir.startsWith("~/")) {
+        return path.join(homeDir, dir.slice(2));
+    }
+    return path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+let skillTemplateCache = null;
+async function loadSkillTemplate() {
+    if (skillTemplateCache) {
+        return skillTemplateCache;
+    }
+    const packageRoot = await findPackageRoot(fileURLToPath(import.meta.url));
+    const templateRoots = [
+        path.join(packageRoot, "src", "templates"),
+        path.join(packageRoot, "dist", "templates")
+    ];
+    for (const templateRoot of templateRoots) {
+        if (!(await pathExists(templateRoot))) {
+            continue;
+        }
+        skillTemplateCache = await readFile(path.join(templateRoot, "SKILL_superintendent.md"), "utf8");
+        return skillTemplateCache;
+    }
+    throw new Error("Unable to locate Superintendent skill template.");
+}
+async function findPackageRoot(entryFilePath) {
+    let currentPath = path.dirname(entryFilePath);
+    while (true) {
+        if (await pathExists(path.join(currentPath, "package.json"))) {
+            return currentPath;
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+            throw new Error("Unable to locate package root for Superintendent templates.");
+        }
+        currentPath = parentPath;
+    }
+}

package/packages/superintendent/dist/commands/plan-path.d.ts

@@ -0,0 +1,9 @@
+export declare const planPathCommand: import("toolcraft").Command<{
+    [x: string]: never;
+}, import("toolcraft-schema").ObjectSchema<{}>, undefined, {
+    planDirectory: string;
+}> & {
+    readonly __agentKitCommandTypeInfo: import("toolcraft").CommandTypeInfo<"plan-path", import("toolcraft-schema").ObjectSchema<{}>, {
+        planDirectory: string;
+    }, ("cli" | "sdk")[], undefined>;
+};

package/packages/superintendent/dist/commands/plan-path.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { readFile, writeFile, mkdir, unlink, stat, readdir } from "node:fs/promises";
+import { S, defineCommand } from "toolcraft";
+import { planConfigScope, readMergedDocument, resolveConfigPath, resolveProjectConfigPath, resolveScope } from "@poe-code/poe-code-config";
+const fs = {
+    readFile: (p, encoding) => readFile(p, encoding),
+    writeFile: (p, content) => writeFile(p, content),
+    mkdir: (p, options) => mkdir(p, options).then(() => undefined),
+    unlink: (p) => unlink(p),
+    stat: (p) => stat(p).then((s) => ({ mode: s.mode })),
+    readdir: (p) => readdir(p)
+};
+export const planPathCommand = defineCommand({
+    name: "plan-path",
+    description: "Print the directory where superintendent plan files should be placed.",
+    params: S.Object({}),
+    scope: ["cli", "sdk"],
+    handler: async () => {
+        const cwd = process.cwd();
+        const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
+        const configPath = resolveConfigPath(homeDir);
+        const projectConfigPath = resolveProjectConfigPath(cwd);
+        const document = await readMergedDocument(fs, configPath, projectConfigPath);
+        const planDirectory = resolveScope(planConfigScope.schema, document.plan, process.env).plan_directory;
+        return { planDirectory: resolveAbsoluteDirectory(planDirectory, cwd, homeDir) };
+    },
+    render: {
+        rich: (result) => {
+            process.stdout.write(`${result.planDirectory}\n`);
+        },
+        markdown: (result) => result.planDirectory,
+        json: (result) => result
+    }
+});
+function resolveAbsoluteDirectory(dir, cwd, homeDir) {
+    if (dir.startsWith("~/")) {
+        return path.join(homeDir, dir.slice(2));
+    }
+    return path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+}

package/packages/superintendent/dist/commands/poe-agent-runner.d.ts

@@ -0,0 +1,5 @@
+import { type AgentBuilder, type RunResult } from "@poe-code/poe-agent";
+import type { AgentRunInput } from "../runtime/loop.js";
+export type AgentFactory = () => AgentBuilder;
+export type ExecutePoeAgentResult = RunResult;
+export declare function executePoeAgent(agentSpec: string, input: AgentRunInput, createAgent?: AgentFactory): Promise<ExecutePoeAgentResult>;

package/packages/superintendent/dist/commands/poe-agent-runner.js

@@ -0,0 +1,27 @@
+import { parseAgentSpecifier } from "@poe-code/agent-defs";
+import { agent as defaultAgent, compactionPlugin, environmentPlugin, filesPlugin, openaiChatCompletionsPlugin, openaiResponsesPlugin, policyPlugin, shellPlugin, skillsPlugin, systemPromptPlugin, webPlugin } from "@poe-code/poe-agent";
+export async function executePoeAgent(agentSpec, input, createAgent = defaultAgent) {
+    const { model } = parseAgentSpecifier(agentSpec);
+    if (!model) {
+        throw new Error(`poe-agent requires a model in the agent specifier (e.g. "poe-agent:openai/gpt-5.4"); got "${agentSpec}".`);
+    }
+    return createAgent()
+        .model(model)
+        .use(openaiResponsesPlugin())
+        .use(openaiChatCompletionsPlugin())
+        .use(systemPromptPlugin())
+        .use(environmentPlugin(input.cwd))
+        .use(filesPlugin({ cwd: input.cwd }))
+        .use(shellPlugin({ cwd: input.cwd }))
+        .use(webPlugin())
+        .use(compactionPlugin())
+        .use(skillsPlugin({ definitions: {} }))
+        .use(policyPlugin({ mode: input.mode }))
+        .mcp(input.mcpServers ?? {})
+        .run(input.prompt, {
+        cwd: input.cwd,
+        signal: input.signal,
+        onStdout: input.onStdout,
+        logPath: input.logPath
+    });
+}

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

@@ -0,0 +1,86 @@
+import { select, type Dashboard } from "@poe-code/design-system";
+import { type AgentRunInput, type AgentRunResult, type RunLoopOptions, type SuperintendentFileSystem, type SuperintendentRunResult } from "../runtime/loop.js";
+export type SuperintendentRunCommandResult = SuperintendentRunResult & {
+    docPath: string;
+    builderAgent: string;
+};
+export type RunCommandOptions = {
+    cwd: string;
+    homeDir: string;
+    docPath?: string;
+    builderAgent?: string;
+    configuredDefaultAgent?: string | null;
+    planDirectory?: string;
+    assumeYes?: boolean;
+    interactive?: boolean;
+    useDashboard?: boolean;
+    env?: Record<string, string | undefined>;
+    fs?: SuperintendentFileSystem;
+    now?: () => number;
+    createDashboard?: (options?: {
+        title?: string;
+        statsTitle?: string;
+        hints?: Array<{
+            key: string;
+            label: string;
+        }>;
+        rightPaneWidth?: number;
+    }) => Dashboard;
+    selectPrompt?: typeof select;
+    runLoop?: (options: RunLoopOptions) => Promise<SuperintendentRunResult>;
+    executeAgent?: (agent: string, input: AgentRunInput) => Promise<AgentRunResult & {
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+            cachedTokens?: number;
+        };
+    }>;
+    setInterval?: typeof global.setInterval;
+    clearInterval?: typeof global.clearInterval;
+    openInEditor?: (absolutePath: string, env: Record<string, string | undefined>) => void;
+    stderr?: NodeJS.WritableStream;
+    exit?: (code: number) => never;
+};
+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 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 tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    }>, SuperintendentRunCommandResult, ("cli" | "sdk")[], undefined>;
+};
+export type RunMcpCommandRunners = {
+    runLoop?: (options: RunLoopOptions) => Promise<SuperintendentRunResult>;
+};
+export declare function createRunMcpCommand(runners?: RunMcpCommandRunners): 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 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 tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    }>, SuperintendentRunCommandResult, "mcp"[], undefined>;
+};
+export declare const runMcpCommand: 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 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 tui: import("toolcraft-schema").OptionalSchema<import("toolcraft-schema").BooleanSchema>;
+    }>, SuperintendentRunCommandResult, "mcp"[], undefined>;
+};
+export declare function runSuperintendentCommand(options: RunCommandOptions): Promise<SuperintendentRunCommandResult>;