toolcraft 0.0.93 → 0.0.95

package/README.md

@@ -6,7 +6,7 @@ Define a command once. Get a typed CLI, an MCP server, and a typed SDK from the
 
 ## Why
 
-You have a folder of one-off scripts and a couple of MCP servers. Each one re-derives its own argument parsing, env handling, and help text. Running them from a chatbot needs another adapter. Calling them from another script means subprocessing.
+You have one-off scripts and MCP servers. Each one re-derives argument parsing, env handling, and help text. Running them from a chatbot needs another adapter. Calling them from another script means subprocessing.
 
 `toolcraft` is the consolidation step. You write each operation as one `defineCommand`, group them, and pick which surfaces to expose:
 
@@ -30,7 +30,7 @@ Before writing toolcraft code, make a small tool map. For each script or MCP too
 - **Surfaces** — where it should appear: CLI, MCP, SDK, or all three.
 - **Safety** — whether it needs approval, auth, or another precondition.
 
-Keep the first migration boring:
+Keep the first migration direct:
 
 1. Wrap existing scripts as thin `defineCommand` handlers.
 2. Proxy existing MCP servers with `defineGroup({ mcp })` when you do not want to rewrite them yet.
@@ -38,7 +38,7 @@ Keep the first migration boring:
 4. Add MCP scope only to tools that are safe and useful for agents.
 5. Document exposed env vars and config options in the package README.
 
-Once the tool map exists, the rest is mechanical: add commands to `root`, expose the same tree through CLI, MCP, and SDK, and remove old entrypoints when they are no longer needed.
+After the tool map exists, add commands to `root`, expose the same tree through CLI, MCP, and SDK, and remove old entrypoints when they are no longer needed.
 
 ## Install
 
@@ -255,6 +255,63 @@ defineCommand<Services>({
 
 Services are merged into the handler context alongside the built-ins (`fetch`, `fs`, `env`, `progress`).
 
+## Testing commands
+
+Use `createCommandTestHarness` to exercise the same command pipeline as the SDK without assembling a handler context by hand:
+
+```ts
+import { expect, it } from "vitest";
+import { createCommandTestHarness, fakeService } from "toolcraft/testing";
+import { root } from "./root.js";
+
+it("creates a deployment", async () => {
+  const deployments = fakeService({
+    create: async (name: string) => ({ id: "dep-1", name })
+  });
+  const harness = createCommandTestHarness(root, {
+    services: { deployments },
+    env: { HOME: "/test/home" },
+    secrets: { apiKey: "test-token" },
+    fs: { "/test/input.json": "{}" },
+    fetch: [{ method: "POST", url: "https://api.example.com/deployments", json: { ok: true } }],
+    confirmations: "approve",
+    apiVersion: "1.2.0",
+    logLevel: "debug"
+  });
+
+  const result = await harness.run<{ id: string }>(["deploy", "create"], {
+    name: "production"
+  });
+
+  expect(result).toMatchObject({ ok: true, value: { id: "dep-1" } });
+});
+```
+
+Harness options provide injected `services`, an explicit `env`, named `secrets`, an initial file map or `HandlerFs`, a fetch implementation or `fakeFetch` routes, confirmation behavior (`"approve"`, `"decline"`, or a callback), `apiVersion`, and `logLevel`. `fakeService`, `fakeFetch`, and `createMemoryFs` are also exported for standalone tests.
+
+Each `run()` returns a `RunResult` instead of throwing. Assert `ok`, `value`, or `error`, and use `failedAt` to identify the pipeline stage: `resolve`, `secrets`, `requirements`, `params`, `confirm`, `handler`, or `render`. The result also captures `pending`, diagnostic `logs`, `progress`, `confirmations`, the ordered effect `timeline`, `fsChanges`, and rendered rich, Markdown, and JSON output. Pre-handler validation can therefore be asserted directly:
+
+```ts
+const result = await harness.run(["deploy", "create"], { name: 42 });
+
+expect(result.ok).toBe(false);
+expect(result.failedAt).toBe("params");
+expect(result.timeline).toEqual([]);
+expect(deployments.calls).toEqual([]);
+```
+
+The harness is hermetic by default: it never falls back to `process.env`, starts with an in-memory filesystem, blocks unmatched network requests, records injected service and effect calls, and uses deterministic timestamp-free pending approval data. Provide every external input through the harness options.
+
+Use `parity()` when a command must behave identically through the real SDK, MCP, and CLI adapters:
+
+```ts
+const parity = await harness.parity(["deploy", "create"], { name: "production" });
+
+expect(parity.agree, parity.diff).toBe(true);
+expect(parity.sdk.value).toEqual(parity.mcp.value);
+expect(parity.mcp.value).toEqual(parity.cli.value);
+```
+
 ## Output rendering
 
 Handlers return raw values. Add `result:` when a command returns structured data and may be exposed over MCP; Toolcraft turns that schema into MCP `outputSchema`, validates the returned object, returns it as `structuredContent`, and keeps a JSON text backstop for older MCP clients.
@@ -471,12 +528,16 @@ Import the command definitions from `toolcraft` and the CLI runner from `toolcra
 
 esbuild records dependency paths relative to the build layout. A standalone install can produce `node_modules/toolcraft/...`, while a hoisted workspace can produce `../../node_modules/toolcraft/...` in module-label comments and source-map `sources`. For layout-independent artifacts, canonicalize every dependency path by keeping the substring from the first `node_modules/` segment onward. Parse the source map as JSON and apply the same operation to each string in `sources`; do not modify application source paths. Serialize the map, then hash or publish the canonical bundle and map.
 
-## Environment variables
+## Environment Variables
 
 - `TOOLCRAFT_MCP_REFRESH` — MCP proxy cache refresh (`unset` = use cache, `1`/`true` = refresh all, comma-separated names = refresh those).
 - `TOOLCRAFT_ERROR_REPORTS=1` — enables structured error report files for CLI, MCP, and SDK surfaces that wire `errorReports`.
 - Per-command `secrets` declarations name additional env vars. They are read at command run time and passed to the handler.
 
+## Configuration Options
+
+Toolcraft configuration is code-first. Use `defineCommand(config)` and `defineGroup(config)` for the command tree, then pass runtime options to `runCLI`, `createSDK`, `createMCPServer`, or `runMCP`. MCP proxy schemas are cached under `.toolcraft/mcp`, and optional human-in-loop state is configured with `HumanInLoopRuntimeOptions`.
+
 ## API reference
 
 ### `defineCommand(config)`
@@ -573,3 +634,12 @@ Subpath imports:
 - `toolcraft/mcp` — `runMCP`, `createMCPServer`
 - `toolcraft/human-in-loop` — provider helpers
 - `toolcraft/mcp-proxy` — proxy internals
+
+## Manual QA
+
+Use these package-local walkthroughs after behavior changes:
+
+- [Help output](QA-help-output.md)
+- [Error UX](QA-error-ux.md)
+- [Human-in-loop](QA-human-in-loop.md)
+- [MCP proxy](QA-mcp-proxy.md)

package/composition.json

@@ -48,7 +48,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.93",
+      "version": "0.0.95",
       "license": "MIT"
     },
     {

package/dist/agent-defs.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/agent-defs";

package/dist/agent-defs.js

@@ -0,0 +1 @@
+export * from "@poe-code/agent-defs";

package/dist/agent-human-in-loop.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/agent-human-in-loop";

package/dist/agent-human-in-loop.js

@@ -0,0 +1 @@
+export * from "@poe-code/agent-human-in-loop";

package/dist/agent-mcp-config.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/agent-mcp-config";

package/dist/agent-mcp-config.js

@@ -0,0 +1 @@
+export * from "@poe-code/agent-mcp-config";

package/dist/auth-store.d.ts

@@ -0,0 +1 @@
+export * from "auth-store";

package/dist/auth-store.js

@@ -0,0 +1 @@
+export * from "auth-store";

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 import "./node-require-shim.js";
 import { configureTheme } from "toolcraft-design";
-import type { Group, LogLevel, RuntimeLoggerInput } from "./index.js";
+import type { Group, HandlerFs, LogLevel, RuntimeLoggerInput } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import type { HumanInLoopRuntimeOptions } from "./human-in-loop/types.js";
 export { renderErrorReport } from "./error-report.js";
@@ -20,10 +20,13 @@ export interface RunCLIOptions<TServices extends object = Record<string, unknown
     argv?: readonly string[];
     casing?: Casing;
     controls?: CLIControls;
+    env?: Record<string, string>;
     fetch?: typeof globalThis.fetch;
+    fs?: HandlerFs;
     humanInLoop?: HumanInLoopRuntimeOptions;
     logLevel?: LogLevel;
     logger?: RuntimeLoggerInput;
+    outputEmitter?: (entry: string) => void;
     projectRoot?: string;
     rootDisplayName?: string;
     rootUsageName?: string;

package/dist/cli.js

@@ -1,5 +1,5 @@
 import "./node-require-shim.js";
-import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
 import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
@@ -16,21 +16,10 @@ import { renderSourceSnippet } from "./source-snippet.js";
 import { enableSourceMaps, formatDebugStack } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
+import { RESERVED_SERVICE_NAMES, createEnv, createFs, validateServices } from "./runtime/io.js";
 export { renderErrorReport } from "./error-report.js";
 configureTheme({ brand: "blue", label: "Toolcraft" });
 export { configureTheme };
-const RESERVED_SERVICE_NAMES = new Set([
-    "params",
-    "secrets",
-    "fetch",
-    "fs",
-    "env",
-    "diagnostics",
-    "progress",
-    "runtimeOptions",
-    "root"
-]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 const NULL_OPTION_VALUE = Symbol("toolcraft.cli.null");
 const optionalModulePaths = {
     approvals: "./human-in-loop/approvals-commands.js",
@@ -350,7 +339,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
             longAliases: [...(childSchema.cliAliases ?? [])].map((alias) => alias.startsWith("--") ? alias : `--${alias}`),
             shortFlag: childSchema.short,
             schema: childSchema,
-            description: childSchema.description,
+            description: childSchema.cliDescription ?? childSchema.description,
             optional: runtimeOptional,
             hasDefault: childSchema.default !== undefined,
             defaultValue: childSchema.default,
@@ -1889,33 +1878,6 @@ async function withOutputFormat(output, fn) {
         resetOutputFormatCache();
     }
 }
-function createFs() {
-    return {
-        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
-        writeFile: async (path, contents, options) => {
-            await writeFile(path, contents, options);
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        lstat: async (path) => lstat(path),
-        rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path)
-    };
-}
-function createEnv(values = process.env) {
-    return {
-        get(key) {
-            return values[key];
-        }
-    };
-}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2317,16 +2279,16 @@ function createFixtureEnvValues(command) {
     }
     return values;
 }
-async function resolveFixtureRuntime(command, services, requirementOptions, runtimeFetch) {
+async function resolveFixtureRuntime(command, services, requirementOptions, runtimeFetch, runtimeEnv, runtimeFs) {
     const selector = process.env.TOOLCRAFT_FIXTURE;
     if (selector === undefined || selector.length === 0) {
         return {
-            env: createEnv(),
+            env: createEnv(runtimeEnv),
             fetch: runtimeFetch,
-            fs: createFs(),
+            fs: createFs(runtimeFs),
             isFixture: false,
             requirementOptions,
-            secrets: resolveCommandSecrets(command),
+            secrets: resolveCommandSecrets(command, runtimeEnv),
             services
         };
     }
@@ -2373,8 +2335,8 @@ function renderApprovalDeclined(error) {
     logger.error(error.message);
     process.exitCode = 1;
 }
-function renderCliErrorPattern(pattern) {
-    const logger = createLogger();
+function renderCliErrorPattern(pattern, outputEmitter) {
+    const logger = createLogger(outputEmitter);
     if (pattern.kind === "usage") {
         logger.error(appendUsagePointer(pattern.message, {
             rootUsageName: pattern.rootUsageName,
@@ -2417,13 +2379,6 @@ function renderCliErrorPattern(pattern) {
     }
     process.exitCode = 1;
 }
-function validateServices(services) {
-    for (const name of Object.keys(services)) {
-        if (RESERVED_SERVICE_NAMES.has(name)) {
-            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
-        }
-    }
-}
 function getNestedValue(target, path) {
     return path.reduce((current, segment) => current !== null && typeof current === "object"
         ? current[segment]
@@ -2981,8 +2936,8 @@ function getResolvedFlags(command) {
     const flags = command.optsWithGlobals();
     return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, diagnosticsOptions, onErrorReportContext) {
-    const logger = createLogger();
+async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, runtimeEnv, runtimeFs, outputEmitter, diagnosticsOptions, onErrorReportContext) {
+    const logger = createLogger(outputEmitter);
     const primitives = {
         logger,
         renderTable,
@@ -3000,7 +2955,7 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
         logger: diagnosticsOptions.logger ?? writeCLIDiagnosticEvent
     });
     const shouldPrompt = !resolvedFlags.yes && Boolean(process.stdin.isTTY);
-    const runtime = await resolveFixtureRuntime(state.command, services, requirementOptions, runtimeFetch);
+    const runtime = await resolveFixtureRuntime(state.command, services, requirementOptions, runtimeFetch, runtimeEnv, runtimeFs);
     const preflightContext = {
         ...runtime.services,
         secrets: runtime.secrets,
@@ -3059,7 +3014,9 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
                 renderHumanInLoopPending(result);
                 return;
             }
-            const renderStatus = renderResult(state.command, result, output, primitives);
+            const renderStatus = renderResult(state.command, result, output, primitives, outputEmitter === undefined
+                ? undefined
+                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk));
             if (renderStatus.mcpError) {
                 process.exitCode = 1;
             }
@@ -3270,7 +3227,7 @@ function renderHttpError(error, options) {
     }
 }
 async function handleRunError(error, options) {
-    const logger = createLogger();
+    const logger = createLogger(options.outputEmitter);
     await withOutputFormat(options.output, async () => {
         if (error instanceof UserError) {
             renderCliErrorPattern(options.userErrorPattern === "definition"
@@ -3289,7 +3246,7 @@ async function handleRunError(error, options) {
                     : {
                         kind: "runtime-user",
                         message: error.message
-                    });
+                    }, options.outputEmitter);
             return;
         }
         if (error instanceof Error && error.name === "ToolcraftBugError") {
@@ -3297,7 +3254,7 @@ async function handleRunError(error, options) {
                 kind: "toolcraft-bug",
                 error,
                 debugStackMode: options.debugStackMode
-            });
+            }, options.outputEmitter);
             return;
         }
         if (error instanceof CommanderError) {
@@ -3341,7 +3298,7 @@ async function handleRunError(error, options) {
             message,
             stack: error instanceof Error ? error.stack : undefined,
             debugStackMode: options.debugStackMode
-        });
+        }, options.outputEmitter);
     });
 }
 function formatCommanderErrorMessage(error) {
@@ -3560,7 +3517,7 @@ function isCommandNameCharacter(character) {
     const isLowercaseLetter = code >= 97 && code <= 122;
     const isUppercaseLetter = code >= 65 && code <= 90;
     const isDigit = code >= 48 && code <= 57;
-    return isLowercaseLetter || isUppercaseLetter || isDigit || character === "-" || character === "_";
+    return (isLowercaseLetter || isUppercaseLetter || isDigit || character === "-" || character === "_");
 }
 function getDefaultCommanderCommandName(command) {
     const candidate = command;
@@ -3612,7 +3569,8 @@ export async function runCLI(roots, options = {}) {
             root
         };
         const requirementOptions = {
-            apiVersion: options.apiVersion
+            apiVersion: options.apiVersion,
+            env: options.env
         };
         validateServices(services);
         if (hasHelpFlag(argv)) {
@@ -3642,7 +3600,7 @@ export async function runCLI(roots, options = {}) {
         const execute = async (state) => {
             lastActionCommand = state.actionCommand;
             resolvedCommandPath = formatCliCommandPath(state.commandPath);
-            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, {
+            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, options.env, options.fs, options.outputEmitter, {
                 logLevel: options.logLevel,
                 logger: options.logger,
                 verboseControlEnabled: controls.verbose
@@ -3707,6 +3665,7 @@ export async function runCLI(roots, options = {}) {
             argv,
             rootUsageName,
             commandPath: resolvedCommandPath,
+            outputEmitter: options.outputEmitter,
             userErrorPattern: errorReportContext?.params === undefined ? userErrorPattern : "runtime-user"
         });
     }

package/dist/composition.json

@@ -48,7 +48,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.93",
+      "version": "0.0.95",
       "license": "MIT"
     },
     {

package/dist/config-mutations.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/config-mutations";

package/dist/config-mutations.js

@@ -0,0 +1 @@
+export * from "@poe-code/config-mutations";

package/dist/frontmatter.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/frontmatter";

package/dist/frontmatter.js

@@ -0,0 +1 @@
+export * from "@poe-code/frontmatter";

package/dist/human-in-loop/gate.d.ts

@@ -1,4 +1,8 @@
 import type { Command, HandlerContext } from "../index.js";
+import { enqueueApproval } from "./approval-tasks.js";
 import type { HumanInLoopPending, HumanInLoopProvider, HumanInLoopRuntimeOptions } from "./types.js";
 export declare function resolveProvider(runtimeOptions: HumanInLoopRuntimeOptions | undefined): HumanInLoopProvider;
-export declare function invokeWithHumanInLoop<T>(node: Command<any, any, any, T>, ctx: HandlerContext<any, any, any>, runtimeOptions: HumanInLoopRuntimeOptions | undefined, commandPath: string): Promise<T | HumanInLoopPending>;
+export declare function invokeWithHumanInLoop<T>(node: Command<any, any, any, T>, ctx: HandlerContext<any, any, any>, runtimeOptions: HumanInLoopRuntimeOptions | undefined, commandPath: string, options?: {
+    enqueueApproval?: typeof enqueueApproval;
+    spawnRunner?: boolean;
+}): Promise<T | HumanInLoopPending>;

package/dist/human-in-loop/gate.js

@@ -20,37 +20,39 @@ export function resolveProvider(runtimeOptions) {
     providersByRuntime.set(runtimeOptions, provider);
     return provider;
 }
-export async function invokeWithHumanInLoop(node, ctx, runtimeOptions, commandPath) {
+export async function invokeWithHumanInLoop(node, ctx, runtimeOptions, commandPath, options = {}) {
     if (!node.humanInLoop) {
         return node.handler(ctx);
     }
     const message = node.humanInLoop.message({
         params: ctx.params,
-        commandPath,
+        commandPath
     });
     if (node.humanInLoop.mode === "async") {
         const { tasks } = await ensureApprovalList(runtimeOptions);
-        const { approvalId, pending } = await enqueueApproval({
+        const { approvalId, pending } = await (options.enqueueApproval ?? enqueueApproval)({
             tasks,
             payload: {
                 commandPath,
                 params: ctx.params,
                 message,
-                declineInputPrompt: node.humanInLoop.declineInputPrompt,
-            },
+                declineInputPrompt: node.humanInLoop.declineInputPrompt
+            }
         });
-        spawnApprovalRunner(approvalId, runtimeOptions);
+        if (options.spawnRunner !== false) {
+            spawnApprovalRunner(approvalId, runtimeOptions);
+        }
         return pending;
     }
     const provider = resolveProvider(runtimeOptions);
     const result = await provider.requestApproval({
         message,
-        declineInputPrompt: node.humanInLoop.declineInputPrompt,
+        declineInputPrompt: node.humanInLoop.declineInputPrompt
     });
     if (result.outcome === "declined") {
         throw new ApprovalDeclinedError({
             reason: result.reason,
-            commandPath,
+            commandPath
         });
     }
     return node.handler(ctx);

package/dist/human-in-loop/runner.js

@@ -1,6 +1,6 @@
-import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { InvalidTransitionError } from "@poe-code/task-list";
 import { UserError, resolveCommandSecrets } from "../index.js";
+import { createEnv, createFs } from "../runtime/io.js";
 import { ensureApprovalList } from "./approval-tasks.js";
 import { resolveProvider } from "./gate.js";
 import { createRuntimeLogger } from "../runtime-logging.js";
@@ -184,33 +184,6 @@ function createHandlerContext(command, params) {
         }
     };
 }
-function createFs() {
-    return {
-        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
-        writeFile: async (path, contents, options) => {
-            await writeFile(path, contents, options);
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        lstat: async (path) => lstat(path),
-        rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path)
-    };
-}
-function createEnv(values = process.env) {
-    return {
-        get(key) {
-            return values[key];
-        }
-    };
-}
 function serializeJsonResult(value) {
     try {
         const serialized = JSON.stringify(value);

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { type SDKTransport, type Server as TinyServer } from "tiny-stdio-mcp-server";
-import type { Group, LogLevel, RuntimeLoggerInput } from "./index.js";
+import type { Group, HandlerFs, LogLevel, RuntimeLoggerInput } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import { type HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type Casing = "snake" | "camel";
@@ -7,8 +7,11 @@ type CmdkitServer = Omit<TinyServer, "connect"> & {
     connect(transport: SDKTransport): Promise<void>;
 };
 export interface RunMCPOptions<TServices extends object = Record<string, unknown>> {
+    apiVersion?: string;
     approvals?: boolean;
+    env?: Record<string, string>;
     fetch?: typeof globalThis.fetch;
+    fs?: HandlerFs;
     name: string;
     version?: string;
     humanInLoop?: HumanInLoopRuntimeOptions;

package/dist/mcp.js

@@ -1,4 +1,3 @@
-import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { createServer, JSON_RPC_ERROR_CODES, ToolError } from "tiny-stdio-mcp-server";
 import { toJsonSchema } from "toolcraft-schema";
 import { createHttpErrorEnvelope, isHttpErrorLike } from "./api-error-summary.js";
@@ -14,18 +13,7 @@ import { enableSourceMaps } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
 import { createRuntimeLogger } from "./runtime-logging.js";
-const RESERVED_SERVICE_NAMES = new Set([
-    "params",
-    "secrets",
-    "fetch",
-    "fs",
-    "env",
-    "diagnostics",
-    "progress",
-    "runtimeOptions",
-    "root"
-]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
+import { createEnv, createFs, validateServices } from "./runtime/io.js";
 function normalizeRoots(roots) {
     if (!Array.isArray(roots)) {
         return roots;
@@ -93,40 +81,6 @@ function isOptional(schema) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function createFs() {
-    return {
-        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
-        writeFile: async (path, contents, options) => {
-            await writeFile(path, contents, options);
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        lstat: async (path) => lstat(path),
-        rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path)
-    };
-}
-function createEnv(values = process.env) {
-    return {
-        get(key) {
-            return values[key];
-        }
-    };
-}
-function validateServices(services) {
-    for (const name of Object.keys(services)) {
-        if (RESERVED_SERVICE_NAMES.has(name)) {
-            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
-        }
-    }
-}
 function formatAvailableList(values) {
     return `Available: ${[...values].sort().join(", ")}.`;
 }
@@ -779,19 +733,22 @@ function createResolvedMCPServer(root, options) {
             let params;
             let secrets;
             try {
-                secrets = resolveCommandSecrets(tool.command);
+                secrets = resolveCommandSecrets(tool.command, options.env);
                 const baseContext = {
                     ...servicesWithBuiltIns,
                     secrets,
                     fetch: runtimeFetch,
-                    fs: createFs(),
-                    env: createEnv(),
+                    fs: createFs(options.fs),
+                    env: createEnv(options.env),
                     diagnostics,
                     progress(message) {
                         diagnostics.emit({ level: "info", message, category: "progress" });
                     }
                 };
-                await assertCommandRequirements(tool.command, { ...baseContext, params: undefined });
+                await assertCommandRequirements(tool.command, { ...baseContext, params: undefined }, {
+                    apiVersion: options.apiVersion,
+                    env: options.env
+                });
                 params = validateToolArguments(tool.command.params, argumentsValue, casing);
                 const result = await invokeWithHumanInLoop(tool.command, {
                     ...baseContext,

package/dist/process-runner.d.ts

@@ -0,0 +1 @@
+export * from "@poe-code/process-runner";

package/dist/process-runner.js

@@ -0,0 +1 @@
+export * from "@poe-code/process-runner";

package/dist/runtime/io.d.ts

@@ -0,0 +1,5 @@
+import type { HandlerEnv, HandlerFs } from "../index.js";
+export declare const RESERVED_SERVICE_NAMES: Set<string>;
+export declare function createFs(fs?: HandlerFs): HandlerFs;
+export declare function createEnv(values?: Record<string, string | undefined>): HandlerEnv;
+export declare function validateServices(services: object): void;