toolcraft 0.0.2 → 0.0.3

package/dist/mcp-proxy.js

@@ -0,0 +1,383 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createLogger } from "@poe-code/design-system";
+import { HttpTransport, McpClient, StdioTransport } from "tiny-mcp-client";
+import { convertJsonSchema } from "./json-schema-converter.js";
+const GROUP_CONFIG_SYMBOL_DESCRIPTION = "toolcraft.group.config";
+const MCP_PROXY_SCHEMA_URL = "https://poe-platform.github.io/poe-code/schemas/toolcraft/mcp-proxy.schema.json";
+const DEFAULT_CLIENT_INFO = {
+    name: "toolcraft",
+    version: "0.0.1",
+};
+const proxyNodeSymbol = Symbol("toolcraft.mcpProxyNode");
+const proxyConnectionSymbol = Symbol("toolcraft.mcpProxyConnection");
+const shutdownDisposers = new Set();
+function getInternalGroupConfig(group) {
+    const symbol = Object.getOwnPropertySymbols(group).find((candidate) => candidate.description === GROUP_CONFIG_SYMBOL_DESCRIPTION);
+    if (symbol === undefined) {
+        return {};
+    }
+    return (group[symbol] ??
+        {});
+}
+function isProxyNode(node) {
+    return node[proxyNodeSymbol] === true;
+}
+function markProxyNode(node) {
+    Object.defineProperty(node, proxyNodeSymbol, {
+        configurable: false,
+        enumerable: false,
+        value: true,
+        writable: false,
+    });
+    return node;
+}
+function cloneSecrets(secrets) {
+    return { ...secrets };
+}
+function cloneScope(scope) {
+    return scope === undefined ? undefined : [...scope];
+}
+function registerShutdownDispose(dispose) {
+    shutdownDisposers.add(dispose);
+}
+function getProxyConnection(group) {
+    return group[proxyConnectionSymbol];
+}
+function setProxyConnection(group, connection) {
+    group[proxyConnectionSymbol] = connection;
+}
+function createProxyGroup(parent, name) {
+    return markProxyNode({
+        kind: "group",
+        name,
+        description: undefined,
+        aliases: [],
+        scope: cloneScope(parent.scope),
+        secrets: cloneSecrets(parent.secrets),
+        requires: parent.requires,
+        children: [],
+        default: undefined,
+    });
+}
+function createProxyCommand(parent, tool, commandName, connection) {
+    const params = convertJsonSchema(tool.inputSchema);
+    if (params.kind !== "object") {
+        throw new Error(`upstream tool "${tool.name}" must define an object input schema`);
+    }
+    return markProxyNode({
+        kind: "command",
+        name: commandName,
+        description: tool.description,
+        aliases: [],
+        positional: [],
+        params,
+        secrets: cloneSecrets(parent.secrets),
+        scope: cloneScope(parent.scope) ?? ["cli", "sdk"],
+        confirm: false,
+        requires: parent.requires,
+        handler: async (ctx) => {
+            const client = await ensureConnected(connection);
+            return client.callTool({
+                name: tool.name,
+                arguments: ctx.params,
+            });
+        },
+        render: undefined,
+    });
+}
+function removeProxyChildren(group) {
+    group.children = group.children.filter((child) => !isProxyNode(child));
+    for (const child of group.children) {
+        if (child.kind === "group") {
+            removeProxyChildren(child);
+        }
+    }
+}
+function findChild(group, name) {
+    return group.children.find((child) => child.name === name);
+}
+function filterAllowlistedTools(tools, allowlist) {
+    if (allowlist === undefined) {
+        return tools;
+    }
+    const allowedNames = new Set(allowlist);
+    return tools.filter((tool) => allowedNames.has(tool.name));
+}
+function validateRenameMap(name, tools, rename) {
+    if (rename === undefined) {
+        return;
+    }
+    const toolNames = new Set(tools.map((tool) => tool.name));
+    for (const upstreamToolName of Object.keys(rename)) {
+        if (!toolNames.has(upstreamToolName)) {
+            throw new Error(`couldn't discover MCP ${name}: rename references unknown upstream tool "${upstreamToolName}"`);
+        }
+    }
+}
+function createConnection(name, config) {
+    const connection = {
+        name,
+        config,
+        async dispose() {
+            shutdownDisposers.delete(connection.dispose);
+            connection.connecting = undefined;
+            if (connection.client === undefined) {
+                return;
+            }
+            const client = connection.client;
+            connection.client = undefined;
+            await client.close();
+        },
+    };
+    registerShutdownDispose(connection.dispose);
+    return connection;
+}
+async function ensureConnected(connection) {
+    if (connection.client !== undefined && connection.client.state === "ready") {
+        return connection.client;
+    }
+    if (connection.connecting !== undefined) {
+        return connection.connecting;
+    }
+    connection.connecting = dialUpstream(connection.name, connection.config)
+        .then((client) => {
+        connection.client = client;
+        return client;
+    })
+        .finally(() => {
+        connection.connecting = undefined;
+    });
+    return connection.connecting;
+}
+async function readCache(cachePath) {
+    try {
+        const raw = await readFile(cachePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            !Array.isArray(parsed.tools) ||
+            parsed.upstream === undefined ||
+            typeof parsed.upstream.name !== "string" ||
+            typeof parsed.upstream.version !== "string") {
+            return undefined;
+        }
+        return {
+            $schema: typeof parsed.$schema === "string" ? parsed.$schema : MCP_PROXY_SCHEMA_URL,
+            fetchedAt: typeof parsed.fetchedAt === "string" ? parsed.fetchedAt : new Date(0).toISOString(),
+            tools: parsed.tools,
+            upstream: parsed.upstream,
+            version: parsed.version === 1 ? 1 : 1,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || error instanceof SyntaxError) {
+            return undefined;
+        }
+        return undefined;
+    }
+}
+async function writeCache(cachePath, cache) {
+    const directory = path.dirname(cachePath);
+    const tempPath = `${cachePath}.tmp`;
+    await mkdir(directory, { recursive: true });
+    await writeFile(tempPath, `${JSON.stringify(cache, null, 2)}\n`);
+    await rename(tempPath, cachePath);
+}
+async function fetchCache(name, config, cachePath) {
+    const logger = createLogger((message) => {
+        process.stderr.write(`${message}\n`);
+    });
+    logger.info(`MCP ${name}: connecting`);
+    const client = await dialUpstream(name, config);
+    try {
+        logger.info(`MCP ${name}: listing tools`);
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor === undefined ? {} : { cursor });
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor !== undefined);
+        logger.info(`MCP ${name}: found ${tools.length} tools`);
+        const upstream = client.serverInfo ?? {
+            name,
+            version: "unknown",
+        };
+        const cache = {
+            $schema: MCP_PROXY_SCHEMA_URL,
+            version: 1,
+            upstream,
+            fetchedAt: new Date().toISOString(),
+            tools,
+        };
+        await writeCache(cachePath, cache);
+        logger.info(`MCP ${name}: wrote ${cachePath}`);
+        return cache;
+    }
+    finally {
+        await client.close();
+    }
+}
+async function deleteCacheIfPresent(cachePath) {
+    try {
+        await unlink(cachePath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+function populateGroupFromTools(group, tools, rename, connection) {
+    removeProxyChildren(group);
+    for (const tool of tools) {
+        const targetPath = rename?.[tool.name] ?? tool.name;
+        const segments = rename !== undefined && Object.prototype.hasOwnProperty.call(rename, tool.name)
+            ? targetPath.split(".")
+            : [tool.name];
+        const commandName = segments[segments.length - 1];
+        if (commandName === undefined || commandName.length === 0) {
+            throw new Error(`command path "${targetPath}" collides with an existing child`);
+        }
+        let parent = group;
+        for (const segment of segments.slice(0, -1)) {
+            const existing = findChild(parent, segment);
+            if (existing === undefined) {
+                const created = createProxyGroup(parent, segment);
+                parent.children.push(created);
+                parent = created;
+                continue;
+            }
+            if (existing.kind !== "group") {
+                throw new Error(`command path "${targetPath}" collides with an existing child`);
+            }
+            parent = existing;
+        }
+        if (findChild(parent, commandName) !== undefined) {
+            throw new Error(`command path "${targetPath}" collides with an existing child`);
+        }
+        parent.children.push(createProxyCommand(parent, tool, commandName, connection));
+    }
+}
+function isRefreshRequested(name, refresh) {
+    if (refresh === "all") {
+        return true;
+    }
+    return refresh?.has(name) === true;
+}
+async function resolveSingleProxy(group) {
+    const internal = getInternalGroupConfig(group);
+    const config = internal.mcp;
+    if (config === undefined) {
+        return;
+    }
+    const name = group.name;
+    try {
+        const cachePath = resolveCachePath(name);
+        const refresh = parseRefreshEnv(process.env.TOOLCRAFT_MCP_REFRESH);
+        let cache;
+        if (isRefreshRequested(name, refresh)) {
+            await deleteCacheIfPresent(cachePath);
+            cache = await fetchCache(name, config, cachePath);
+        }
+        else {
+            cache = (await readCache(cachePath)) ?? (await fetchCache(name, config, cachePath));
+        }
+        const tools = filterAllowlistedTools(cache.tools, internal.tools);
+        validateRenameMap(name, tools, internal.rename);
+        const previousConnection = getProxyConnection(group);
+        const nextConnection = createConnection(name, config);
+        try {
+            populateGroupFromTools(group, tools, internal.rename, nextConnection);
+            setProxyConnection(group, nextConnection);
+        }
+        catch (error) {
+            await nextConnection.dispose();
+            throw error;
+        }
+        if (previousConnection !== undefined && previousConnection !== nextConnection) {
+            await previousConnection.dispose();
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(`couldn't discover MCP ${name}:`)) {
+            throw error;
+        }
+        throw new Error(`couldn't discover MCP ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function collectProxyGroups(root) {
+    const groups = [];
+    function visit(group) {
+        if (getInternalGroupConfig(group).mcp !== undefined) {
+            groups.push(group);
+        }
+        for (const child of group.children) {
+            if (child.kind === "group") {
+                visit(child);
+            }
+        }
+    }
+    visit(root);
+    return groups;
+}
+export function hasMcpProxyGroups(root) {
+    return collectProxyGroups(root).length > 0;
+}
+export function resolveCachePath(name, projectRoot) {
+    if (projectRoot !== undefined) {
+        return path.join(projectRoot, ".toolcraft", "mcp", `${name}.json`);
+    }
+    let current = process.cwd();
+    while (true) {
+        if (existsSync(path.join(current, "package.json"))) {
+            return path.join(current, ".toolcraft", "mcp", `${name}.json`);
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`Could not find package.json above "${process.cwd()}" while resolving MCP cache path.`);
+        }
+        current = parent;
+    }
+}
+export function parseRefreshEnv(value) {
+    const trimmed = value?.trim();
+    if (trimmed === undefined || trimmed.length === 0) {
+        return undefined;
+    }
+    if (trimmed === "1" || trimmed === "true") {
+        return "all";
+    }
+    const names = trimmed
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return names.length === 0 ? undefined : new Set(names);
+}
+export async function dialUpstream(name, config) {
+    const client = new McpClient({
+        clientInfo: {
+            name: `${DEFAULT_CLIENT_INFO.name}-${name}`,
+            version: DEFAULT_CLIENT_INFO.version,
+        },
+    });
+    const transport = config.transport === "stdio"
+        ? new StdioTransport({
+            command: config.command,
+            ...(config.args === undefined ? {} : { args: config.args }),
+            ...(config.env === undefined ? {} : { env: config.env }),
+        })
+        : new HttpTransport({
+            url: config.url,
+            ...(config.headers === undefined ? {} : { headers: config.headers }),
+        });
+    await client.connect(transport);
+    return client;
+}
+export async function resolveMcpProxies(root) {
+    const groups = collectProxyGroups(root);
+    await Promise.all(groups.map((group) => resolveSingleProxy(group)));
+}

package/dist/mcp.compile-check.js

@@ -19,6 +19,7 @@ const ignoredOptions = {
     version: "1.0.0",
     tools: ["usage"],
     casing: "snake",
+    humanInLoop: {},
 };
 const ignoredServer = createMCPServer(ignoredRoot, ignoredOptions);
 const ignoredServerArray = createMCPServer([ignoredRoot], ignoredOptions);

package/dist/mcp.d.ts

@@ -1,5 +1,6 @@
 import { type SDKTransport, type Server as TinyServer } from "tiny-stdio-mcp-server";
 import type { Group } from "./index.js";
+import { type HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type Casing = "snake" | "camel";
 type CmdkitServer = Omit<TinyServer, "connect"> & {
     connect(transport: SDKTransport): Promise<void>;
@@ -7,6 +8,7 @@ type CmdkitServer = Omit<TinyServer, "connect"> & {
 export interface RunMCPOptions<TServices extends object = Record<string, unknown>> {
     name: string;
     version: string;
+    humanInLoop?: HumanInLoopRuntimeOptions;
     /**
      * Optional allowlist of MCP tool names or group prefixes.
      *

package/dist/mcp.js

@@ -2,6 +2,9 @@ import { access, readFile, writeFile } from "node:fs/promises";
 import { createServer, JSON_RPC_ERROR_CODES, ToolError, } from "tiny-stdio-mcp-server";
 import { toJsonSchema } from "toolcraft-schema";
 import { UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
+import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
+import { ApprovalDeclinedError, invokeWithHumanInLoop, } from "./human-in-loop/index.js";
+import { hasMcpProxyGroups, resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
 import { filterSchemaForScope } from "./schema-scope.js";
 const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
@@ -160,12 +163,12 @@ function formatToolName(path) {
 }
 function enumerateTools(root, casing, allowlist) {
     const tools = [];
-    function visit(node, path) {
+    function visit(node, toolPath, commandPath) {
         if (node.kind === "command") {
             if (!node.scope.includes("mcp")) {
                 return;
             }
-            const name = formatToolName([...path, node.name]);
+            const name = formatToolName([...toolPath, node.name]);
             const params = filterSchemaForScope(node.params, "mcp");
             if (!matchesAllowlist(name, allowlist)) {
                 return;
@@ -175,23 +178,67 @@ function enumerateTools(root, casing, allowlist) {
             }
             tools.push({
                 command: node,
+                commandPath: [...commandPath, node.name].join("."),
                 name,
                 description: buildToolDescription(node.description, params, casing),
                 inputSchema: applySchemaCasing(toJsonSchema(params), casing),
             });
             return;
         }
-        const nextPath = [...path, node.name];
+        const nextToolPath = [...toolPath, node.name];
+        const nextCommandPath = [...commandPath, node.name];
         for (const child of node.children) {
-            visit(child, nextPath);
+            visit(child, nextToolPath, nextCommandPath);
         }
     }
     const rootPath = root.name.length === 0 ? [] : [root.name];
     for (const child of root.children) {
-        visit(child, rootPath);
+        visit(child, rootPath, []);
     }
     return tools;
 }
+function isHumanInLoopPending(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        result.status === "pending-approval" &&
+        typeof result.approvalId === "string" &&
+        typeof result.message === "string" &&
+        typeof result.enqueuedAt === "string");
+}
+function renderPendingApproval(pending) {
+    return {
+        isError: false,
+        content: [
+            {
+                type: "text",
+                text: `Queued for human approval (id: ${pending.approvalId}). Track with \`toolcraft approvals show ${pending.approvalId}\`.`,
+            },
+            {
+                type: "text",
+                text: JSON.stringify(pending),
+            },
+        ],
+    };
+}
+function renderDeclinedApproval(error) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: error.reason === undefined ? "Declined." : `Declined: ${error.reason}`,
+            },
+            {
+                type: "text",
+                text: JSON.stringify({
+                    outcome: "declined",
+                    reason: error.reason,
+                    commandPath: error.commandPath,
+                }),
+            },
+        ],
+    };
+}
 function validateEnum(value, schema, label) {
     if (!schema.values.includes(value)) {
         throw new UserError(`Invalid value for "${label}". Expected one of: ${schema.values.map((candidate) => String(candidate)).join(", ")}.`);
@@ -307,10 +354,15 @@ function toToolError(error) {
     }
     return new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, String(error));
 }
-export function createMCPServer(roots, options) {
-    const root = normalizeRoots(roots);
+function createResolvedMCPServer(root, options) {
     const casing = options.casing ?? "snake";
     const services = (options.services ?? {});
+    const runtimeOptions = options.humanInLoop ?? {};
+    const servicesWithBuiltIns = {
+        ...services,
+        runtimeOptions,
+        root,
+    };
     validateServices(services);
     const tools = enumerateTools(root, casing, options.tools);
     const server = createServer({ name: options.name, version: options.version });
@@ -319,7 +371,7 @@ export function createMCPServer(roots, options) {
             try {
                 const secrets = resolveCommandSecrets(tool.command);
                 const baseContext = {
-                    ...services,
+                    ...servicesWithBuiltIns,
                     secrets,
                     fetch: globalThis.fetch,
                     fs: createFs(),
@@ -330,13 +382,19 @@ export function createMCPServer(roots, options) {
                 };
                 await assertCommandRequirements(tool.command, { ...baseContext, params: undefined });
                 const params = validateToolArguments(tool.command.params, argumentsValue, casing);
-                const result = await tool.command.handler({
+                const result = await invokeWithHumanInLoop(tool.command, {
                     ...baseContext,
                     params,
-                });
+                }, runtimeOptions, tool.commandPath);
+                if (isHumanInLoopPending(result)) {
+                    return renderPendingApproval(result);
+                }
                 return toToolContent(result);
             }
             catch (error) {
+                if (error instanceof ApprovalDeclinedError) {
+                    return renderDeclinedApproval(error);
+                }
                 throw toToolError(error);
             }
         });
@@ -348,7 +406,41 @@ export function createMCPServer(roots, options) {
         },
     };
 }
+function createDeferredMCPServer(root, options) {
+    let serverPromise;
+    const resolveServer = () => {
+        serverPromise ??= (async () => {
+            await resolveMcpProxies(root);
+            return createResolvedMCPServer(root, options);
+        })();
+        return serverPromise;
+    };
+    return new Proxy({
+        listen() {
+            return resolveServer().then((server) => server.listen());
+        },
+        connect(transport) {
+            return resolveServer().then((server) => server.connect(transport));
+        },
+    }, {
+        get(target, property, receiver) {
+            if (property === "then") {
+                return resolveServer().then.bind(resolveServer());
+            }
+            return Reflect.get(target, property, receiver);
+        },
+    });
+}
+export function createMCPServer(roots, options) {
+    const root = mergeApprovalsGroup(normalizeRoots(roots));
+    if (!hasMcpProxyGroups(root)) {
+        return createResolvedMCPServer(root, options);
+    }
+    return createDeferredMCPServer(root, options);
+}
 export async function runMCP(roots, options) {
-    const server = createMCPServer(roots, options);
+    const root = mergeApprovalsGroup(normalizeRoots(roots));
+    await resolveMcpProxies(root);
+    const server = createResolvedMCPServer(root, options);
     await server.listen();
 }

package/dist/sdk.compile-check.js

@@ -39,6 +39,49 @@ const ignoredRoot = defineGroup({
                             params: S.Object({}),
                             handler: async () => "hidden",
                         }),
+                        defineCommand({
+                            name: "queued",
+                            scope: ["sdk"],
+                            params: S.Object({
+                                prompt_text: S.String(),
+                            }),
+                            humanInLoop: {
+                                mode: "async",
+                                message: () => "queue it",
+                            },
+                            handler: async ({ params }) => ({
+                                content: params.prompt_text,
+                            }),
+                        }),
+                    ],
+                }),
+                defineGroup({
+                    name: "review",
+                    scope: ["sdk"],
+                    humanInLoop: {
+                        mode: "async",
+                        message: () => "needs review",
+                    },
+                    children: [
+                        defineCommand({
+                            name: "submit",
+                            params: S.Object({
+                                target_name: S.String(),
+                            }),
+                            handler: async ({ params }) => ({
+                                target: params.target_name,
+                            }),
+                        }),
+                        defineCommand({
+                            name: "skip",
+                            params: S.Object({
+                                target_name: S.String(),
+                            }),
+                            humanInLoop: null,
+                            handler: async ({ params }) => ({
+                                target: params.target_name,
+                            }),
+                        }),
                     ],
                 }),
             ],
@@ -50,6 +93,7 @@ const ignoredOptions = {
     services: {
         logger: console,
     },
+    humanInLoop: {},
 };
 const ignoredSdk = createSDK(ignoredRoot, ignoredOptions);
 const ignoredResult = ignoredSdk.poeCode.generate.text({
@@ -67,6 +111,27 @@ const ignoredHttpServerResult = ignoredSdk.poeCode.generate.httpServer({
 void ignoredHttpServerResult.then((value) => {
     void value.apiKey;
 });
+const ignoredQueuedResult = ignoredSdk.poeCode.generate.queued({
+    promptText: "hello",
+});
+void ignoredQueuedResult.then((value) => {
+    const pending = value;
+    void pending.approvalId;
+    void pending.message;
+});
+const ignoredInheritedAsyncResult = ignoredSdk.poeCode.review.submit({
+    targetName: "prod",
+});
+void ignoredInheritedAsyncResult.then((value) => {
+    void value.status;
+    void value.enqueuedAt;
+});
+const ignoredOptedOutResult = ignoredSdk.poeCode.review.skip({
+    targetName: "prod",
+});
+void ignoredOptedOutResult.then((value) => {
+    void value.target;
+});
 // @ts-expect-error cli-only commands are not exposed in the SDK surface
 void ignoredSdk.poeCode.generate.cliOnly;
 // @ts-expect-error wrong parameter name
@@ -77,3 +142,15 @@ ignoredSdk.poeCode.generate.text({ promptText: 123 });
 void ignoredSdk.poeCode.generate.hTTPServer;
 // @ts-expect-error acronym parameter names should camel-case cleanly
 ignoredSdk.poeCode.generate.httpServer({ aPIKey: "secret" });
+void ignoredQueuedResult.then((value) => {
+    // @ts-expect-error async human-in-loop commands return the pending marker, not the handler result
+    void value.content;
+});
+void ignoredInheritedAsyncResult.then((value) => {
+    // @ts-expect-error inherited async human-in-loop mode also returns the pending marker
+    void value.target;
+});
+void ignoredOptedOutResult.then((value) => {
+    // @ts-expect-error opting out of inherited human-in-loop keeps the handler result type
+    void value.approvalId;
+});