@kamilio/wire 0.1.9 → 0.1.11

package/node_modules/toolcraft/README.md

@@ -6,18 +6,108 @@ 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:
 
 - `runCLI` — argv parsing, `--help`, kebab/snake flags, exit codes.
 - `createMCPServer` / `runMCP` — JSON-RPC over stdio with auto-generated tool schemas.
 - `createSDK` — typed in-process function calls.
+- `toolcraftCommands` — register a whole library in Safe Bash with captured help, local status and streaming output.
 
 Same handler runs everywhere. Schema, secrets, preconditions, and human-in-loop gating are declared once.
 
 Building from an OpenAPI spec? Use [`toolcraft-openapi`](../toolcraft-openapi/) to generate toolcraft commands from the API contract.
 
+## Use a library inside Safe Bash
+
+Install `toolcraft` and `@poe-platform/safe-bash` in the application that owns the shell.
+
+```ts
+import { Shell, createMemoryFileSystem } from "@poe-platform/safe-bash";
+import { toolcraftCommands, toolcraftDefaults } from "toolcraft/safe-bash";
+
+const shell = new Shell({ fs: createMemoryFileSystem(), env: {} });
+shell.use(toolcraftCommands(myToolcraftLibrary));
+const result = await shell.exec("tools list-users --limit 10 --output json");
+await shell.dispose();
+```
+
+Each root name, its kebab-case spelling and aliases become virtual commands. Nested groups, command aliases,
+default commands, positional arguments, schema defaults, scalar/enum/array/object/
+record/union inputs and CLI scope filtering reuse Toolcraft's CLI parser. Hidden
+commands are excluded from this surface. Standalone CLI behavior remains unchanged.
+No CLI subprocess or per-tool adapter is needed.
+
+Configure services or declared parameter defaults once for the library:
+
+```ts
+shell.use(toolcraftCommands(myToolcraftLibrary, {
+  services: { baseUrl: "https://api.example.com", api: existingApiClient },
+  defaults: toolcraftDefaults(myToolcraftLibrary, {
+    "users/list_users": { limit: 25 },
+  }),
+  version: "1.0.0",
+}));
+```
+
+The `toolcraftDefaults` helper infers declaration paths and parameter types from
+`defineGroup`/`defineCommand` metadata; keep child arrays as tuples (`as const`) for
+precise inference. Runtime defaults also accept a record. Paths use original
+names, separated by `/`, relative to a single root; arrays of roots require the
+root name prefix. Aliases share the same defaults. Unknown paths/parameters and
+invalid values fail at registration. Schema defaults come first, then plugin
+defaults, then explicit argv (including false, zero, empty strings and null).
+Arrays and objects replace the lower-priority value as a whole. Defaults are
+snapshotted, and resolved parameters are validated before requirements and approvals.
+Service objects retain their client identities and cannot override runtime fields.
+
+`createToolcraftCommandExecutor(library, options).execute(argv, invocation)` is the
+same public execution contract without plugin registration. A single-root executor
+accepts arguments after the root command; a multiple-root executor expects the root
+name/alias as its first token. `ToolcraftInvocation` supplies async byte sinks,
+stdin, cancellation, virtual filesystem/cwd, explicit environment, services and
+optional authorized fetch/human-in-loop capabilities. The result is `{ exitCode }`.
+Help/version/results use stdout; errors and diagnostics use stderr. Both sinks are
+awaited, and streaming commands wait for writes before consuming the next event.
+Cancellation preserves the abort reason and closes the active iterator. A sink
+failure propagates to the shell, including its output budget failures. The plugin
+never sets host exit status, installs host signal listeners or prompts host stdin.
+`confirm` commands require explicit `--yes`; wire approval policy with the optional
+`humanInLoop` runtime. `controls` configures existing output formats and log controls.
+
+Handlers are trusted application code; this adapter does not sandbox JavaScript.
+The filesystem bridge uses the invocation's virtual cwd and original filesystem,
+including middleware and budget state. Text reads/writes support Node encodings;
+writes support `w`, `wx` and `a`. Other flags fail explicitly. Missing fetch is
+denied; there is no native network fallback. Callers own supplied capabilities;
+plugin disposal does not close them. Synchronous rendering is bounded to 1 MiB of
+pending output; use `defineStreamCommand` or the invocation's async sinks for larger
+outputs. Binary/artifact results have no automatic binary renderer; existing MCP
+structured/text rendering is retained.
+
+Native plugins currently exclude MCP proxy discovery, host fixture loading,
+file presets, interactive parameter resolvers and detached approval runners.
+Use an explicitly supplied in-process approval provider; providers that spawn a
+runner remain application code. Shell `capabilities` supplies borrowed `services`,
+authorized `fetch`, and `humanInLoop` to each library automatically. Per-execution
+capabilities override shell defaults; explicit `undefined` revokes a capability.
+`agentCommands({ regexExecutor, regex })` also supplies its exact bounded regex
+provider and effective limits as `ctx.regex.executor` and `ctx.regex.limits`.
+`BoundedRegexProvider`, `RegexExecutionOptions`, and `RegexExecutor` are public
+safe-bash exports; missing regex never gains a native JavaScript fallback. Native
+handlers can use `signal`, byte `stdin`/`stdout`/`stderr`, `cwd`, `inputBudget`,
+`invoke` and `registerCleanup`. Dry-run readback uses an explicitly supplied mock
+or overlay filesystem. Library services combine with invocation services, with
+invocation-owned services taking precedence on name collisions. Runtime capability
+names are reserved and cannot be replaced through services. Explicitly revoking
+`humanInLoop` also disables a library-configured approval provider.
+Schema `pattern` and `patternProperties` validation is unsupported in this native
+surface: registration rejects these keywords in parameter and stream-event schemas,
+including nested JSON Schema definitions, instead of using the host regex engine.
+Tools that need regex work can use the injected bounded provider in their handlers.
+CLI-excluded roots are also inaccessible through the public command executor.
+
 ## What the owner decides
 
 Before writing toolcraft code, make a small tool map. For each script or MCP tool, write down:
@@ -30,7 +120,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 +128,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
 
@@ -46,7 +136,7 @@ Once the tool map exists, the rest is mechanical: add commands to `root`, expose
 npm install toolcraft
 ```
 
-`toolcraft-schema` is a dependency and its `S` builders are re-exported from `toolcraft`. Requires Node 20+.
+`toolcraft-schema` is a dependency and its `S` builders are re-exported from `toolcraft`. Requires Node.js >= 18.18.
 
 ## Hello world
 
@@ -181,7 +271,9 @@ The same `root` flows into all three. No duplication.
 
 **Tree**: the `root` group is a `defineGroup` whose children are commands and sub-groups. Any depth. CLI flags, MCP tool names, and SDK methods are derived from the path.
 
-**CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters render as positional tokens like `<name>` or `[name]` depending on whether they are required. Command-specific `--help` still shows the detailed parameter table.
+**Validation**: CLI, MCP, SDK, and preset-file inputs all enforce the same `toolcraft-schema` constraints, including string lengths and patterns, numeric ranges and integer schemas, and array `minItems`/`maxItems`. CLI array options also accept negative numeric array values when the item schema allows them instead of treating those values as new flags.
+
+**CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters render as positional tokens like `<name>` or `[name]` depending on whether they are required. Command-specific `--help` still shows the detailed parameter table. When `controls.output` is enabled, `--help --output json` returns a stable JSON help document for groups and commands, including usage, visible commands, options, positional markers, secrets, and examples. Unknown help targets fail with suggestions and a pointer to the nearest valid help command.
 
 **Examples**: commands may declare `examples: Array<{ title, params }>` alongside their params.
 CLI help renders an `Examples` section for the command, and MCP tool descriptions include the
@@ -255,6 +347,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.
@@ -277,6 +426,28 @@ defineCommand({
 });
 ```
 
+MCP assumes an unannotated tool may mutate data destructively, is not safe to retry, and can
+interact with an open world. Declare the standard hints on each MCP command so clients can present
+the operation accurately:
+
+```ts
+defineCommand({
+  name: "inspect",
+  title: "Inspect deployment",
+  description: "Inspect a deployment without changing it.",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  scope: ["mcp"],
+  params: S.Object({ deploymentId: S.String() }),
+  result: S.Object({ status: S.String() }),
+  handler: async ({ params }) => inspectDeployment(params.deploymentId)
+});
+```
+
 ## HTTP errors
 
 Toolcraft exports a fixed HTTP error hierarchy for transports and generated API clients:
@@ -297,7 +468,16 @@ Toolcraft exports a fixed HTTP error hierarchy for transports and generated API
 Each error carries `status`, optional `code`, optional `requestId`, and serializable `request` and
 `response` context.
 
-CLI picks `rich` by default, `--json` switches to `json`. SDK calls return the raw handler value. MCP calls with `result:` return the handler value as `structuredContent` using the configured MCP casing; MCP calls without `result:` keep content-block behavior.
+CLI picks `rich` by default. Enable the generated output selector when starting the CLI:
+
+```ts
+await runCLI(root, { controls: { output: true } });
+```
+
+Then choose structured output with `mytool command --output json`. The selector also accepts `rich`,
+`md`, and `markdown`. SDK calls return the raw handler value. MCP calls with `result:` return the
+handler value as `structuredContent` using the configured MCP casing; MCP calls without `result:`
+keep content-block behavior.
 
 ## MCP proxy: adopt an existing MCP server
 
@@ -359,22 +539,24 @@ Modes:
 - `sync` — handler waits for approval before running.
 - `async` — toolcraft enqueues the command, returns a pending marker, and runs it in a fresh process when an operator approves via the reserved `approvals` group.
 
-Wire the same `humanInLoop` options into every entrypoint:
+The runtime never ships with the core entrypoints — it loads only through the `toolcraft/human-in-loop` export, and providers are surfaced from the same export. Wire the same runtime into every entrypoint:
 
 ```ts
-const humanInLoop = {
-  provider: slackApprovalProvider({ channel: "#deploys", client }),
+import { createHumanInLoop, osascriptProvider } from "toolcraft/human-in-loop";
+
+const humanInLoop = createHumanInLoop({
+  provider: osascriptProvider({ title: "Approval needed" }), // required
   taskList: { dir: ".toolcraft/approvals.yaml", format: "yaml-file" as const }
-};
+});
 
-await runCLI(root, { humanInLoop });
-createMCPServer(root, { name: "mytool", version: "0.1.0", humanInLoop });
-const sdk = createSDK(root, { humanInLoop });
+await runCLI(root, { humanInLoop, approvals: true });
+createMCPServer(root, { name: "mytool", version: "0.1.0", humanInLoop, approvals: true });
+const sdk = createSDK(root, { humanInLoop, approvals: true });
 ```
 
-If `provider` is omitted, toolcraft picks a default lazily on first use: `osascriptProvider` on macOS; otherwise a stub that throws `UserError("no human-in-loop provider configured for this platform")`.
+`provider` is required — there is no implicit platform default. `defaultProviderForPlatform()` (osascript on macOS, a throwing stub elsewhere) is exported for callers that want that behavior explicitly. A command that declares `humanInLoop` config while no runtime is wired fails at startup, as does `approvals: true` without a runtime.
 
-A built-in `approvals` group is auto-merged into every root:
+With `approvals: true`, the built-in `approvals` group is merged into the root:
 
 - `approvals list` — list pending tasks (CLI, MCP, SDK).
 - `approvals show --approval-id <id>` — show one task.
@@ -382,7 +564,7 @@ A built-in `approvals` group is auto-merged into every root:
 
 The name `approvals` is reserved. Defining your own `approvals` group fails at startup.
 
-The async runner re-execs your binary (`process.execPath` + `process.argv[1]` by default; override via `humanInLoop.binPath`). Re-exec calls the same toolcraft entrypoint with the same `humanInLoop` options — do not branch on `argv` before calling `runCLI`/`runMCP`/`createSDK`.
+The async runner re-execs your binary (`process.execPath` + `process.argv[1]` by default; override via the `binPath` option of `createHumanInLoop`). Re-exec calls the same toolcraft entrypoint with the same wired runtime — do not branch on `argv` before calling `runCLI`/`runMCP`/`createSDK`.
 
 Async results must be JSON-serializable; non-serializable returns mark the approval as failed instead of being persisted.
 
@@ -393,7 +575,7 @@ import type {
   ApprovalRequest,
   ApprovalResult,
   HumanInLoopProvider
-} from "@poe-code/agent-human-in-loop";
+} from "toolcraft/human-in-loop";
 
 export function slackApprovalProvider(opts: {
   channel: string;
@@ -428,10 +610,16 @@ export function slackApprovalProvider(opts: {
 
 Throw `UserError` for expected, user-facing failures. The CLI prints the message without a stack trace and sets exit code 1; MCP and SDK surface the message as the error body. Usage mistakes include a pointer to the relevant command help. Any other thrown error is treated as unexpected and shows a trimmed stack with `--debug`; use `--debug=raw` to include framework and runtime frames.
 
-HTTP-style errors with request/response context print the request, status, and a response-body snippet by default. `--verbose` or `--debug` prints headers and the full request/response bodies, with authorization headers redacted.
+HTTP-style errors with request/response context print the request, status, and a concise summary by default. The summary extracts common fields such as error code, message, request id, retry-after, hints, and field errors when they are present, then falls back to a response-body snippet. `--verbose` or `--debug` prints headers and the full request/response bodies, with authorization headers redacted.
 
 Enable structured error reports with `errorReports: true`, `errorReports: { dir }`, or `TOOLCRAFT_ERROR_REPORTS=1`. Reports are written under `.toolcraft/errors` by default, include argv, parsed params, resolved secret presence, structured error fields, stack/cause chains, and HTTP transcripts, and redact declared secrets plus parameter names that look sensitive.
 
+## Runtime diagnostics
+
+Handlers receive `diagnostics` and `progress` in the shared runtime context. `progress(message)` emits an info-level progress diagnostic. `diagnostics.emit({ level, message, category, data })` supports `error`, `warn`, `info`, `debug`, and `trace` events for categories such as `runtime`, `http`, `auth`, `retry`, and `progress`.
+
+CLI, SDK, and MCP runtimes share the same logger and log-level gates. The default diagnostic level is `warn`; `silent` suppresses diagnostic events. CLI apps can enable `controls.logLevel` to expose `--log-level <silent|error|warn|info|debug|trace>`, and `controls.verbose` maps `--verbose` to trace-level diagnostics when no explicit log level is passed.
+
 ## Migrating from a folder of scripts
 
 Pattern for adopting toolcraft incrementally:
@@ -445,22 +633,55 @@ Pattern for adopting toolcraft incrementally:
 
 If you have an existing MCP server you want to keep running, use the MCP proxy: a `defineGroup` with an `mcp` field pulls its tools into your tree without rewriting them.
 
-## Environment variables
+## Standalone Bundles
+
+Toolcraft supports standalone ESM CLI bundles built with esbuild `0.28.1`. The release workflow builds and starts the same recipe on Node.js `18.18.0`, `20`, `22`, and `24`. Use `node18` as the compilation target so one artifact runs across those supported runtimes.
+
+Install the supported bundler with `npm install --save-dev esbuild@0.28.1`.
+
+```js
+import { build } from "esbuild";
+
+await build({
+  entryPoints: ["src/cli.ts"],
+  outfile: "dist/cli.js",
+  bundle: true,
+  format: "esm",
+  platform: "node",
+  target: "node18",
+  splitting: false,
+  sourcemap: "external",
+  sourcesContent: true
+});
+```
+
+Import the command definitions from `toolcraft` and the CLI runner from `toolcraft/cli`. A command tree that does not configure MCP proxies, process runners, or human-in-loop gates leaves those optional integrations out of the bundle.
+
+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
 
 - `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 human-in-loop approvals are wired explicitly with `createHumanInLoop` from `toolcraft/human-in-loop`.
+
 ## API reference
 
 ### `defineCommand(config)`
 
 - `name: string`
+- `title?: string` — human-readable MCP display name.
 - `description?: string`
+- `annotations?: { title?; readOnlyHint?; destructiveHint?; idempotentHint?; openWorldHint? }` — standard MCP behavior hints passed through unchanged.
 - `aliases?: string[]`
 - `positional?: string[]` — parameter names mapped from CLI argv order.
 - `params: S.Object(...)` — input schema from `toolcraft-schema`.
 - `result?: S.Object(...)` — structured result schema for MCP `outputSchema`; must be a root object.
+- `mcpResult?: (result) => Record<string, unknown>` — optional MCP-only projection applied before `result` validation; CLI and SDK still return the raw handler result. Requires `result`.
 - `secrets?: Record<string, { env: string; description?: string; optional?: boolean }>`
 - `scope?: Array<"cli" | "mcp" | "sdk">` — defaults to `["cli", "sdk"]`.
 - `confirm?: boolean` — deprecated CLI-only TTY confirmation; use `humanInLoop` instead. Cannot be combined with `humanInLoop`.
@@ -488,11 +709,17 @@ additional long CLI flags. For example, `rawResponse` normally maps to `--raw-re
 ### `runCLI(root, options)`
 
 - `casing?: "kebab" | "snake"` — generated CLI flag style.
+- `argv?: readonly string[]` — explicit argv vector for embedded runners and tests. Defaults to `process.argv` and is used for routing, help rendering, version lookup, error reports, and output-mode detection.
+- `controls?: { debug?: boolean; logLevel?: boolean; output?: boolean; verbose?: boolean; yes?: boolean }` — opts into global CLI controls such as `--debug`, `--log-level`, `--output`, `--verbose`, and `--yes`.
+- `logLevel?: "silent" | "error" | "warn" | "info" | "debug" | "trace"` — default runtime diagnostic level.
+- `logger?: RuntimeLogger | ((event) => void)` — receives diagnostic events that pass the configured log level.
 - `services?: TServices` — merged into every handler context.
 - `version?: string` — surfaced via `--version`.
 - `presets?: boolean` — enables `--preset <path>` for loading parameter defaults from JSON files.
+- `controls?: { debug?, logLevel?, output?, verbose?, yes? }` — enables generated global CLI controls. Set `output: true` to expose `--output <rich|md|markdown|json>`.
 - `apiVersion?: string` — for `requires.apiVersion`.
-- `humanInLoop?: HumanInLoopRuntimeOptions`
+- `humanInLoop?: HumanInLoopRuntime` — from `createHumanInLoop` (`toolcraft/human-in-loop`); required for commands with `humanInLoop` config.
+- `approvals?: boolean` — merge the built-in `approvals` group; requires `humanInLoop`.
 - `errorReports?: boolean | { dir?: string }`
 - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 
@@ -501,6 +728,8 @@ additional long CLI flags. For example, `rawResponse` normally maps to `--raw-re
 - `casing?: "camel"` — generated SDK member style.
 - `services?` / `humanInLoop?` / `apiVersion?` / `errorReports?`
 - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
+- `logLevel?: "silent" | "error" | "warn" | "info" | "debug" | "trace"` — default runtime diagnostic level.
+- `logger?: RuntimeLogger | ((event) => void)` — receives diagnostic events that pass the configured log level.
 
 ### `createMCPServer(root, options)` / `runMCP(root, options)`
 
@@ -508,21 +737,27 @@ additional long CLI flags. For example, `rawResponse` normally maps to `--raw-re
 - `version: string`
 - `services?` / `humanInLoop?` / `apiVersion?` / `errorReports?`
 - `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
+- `logLevel?: "silent" | "error" | "warn" | "info" | "debug" | "trace"` — default runtime diagnostic level.
+- `logger?: RuntimeLogger | ((event) => void)` — receives diagnostic events that pass the configured log level.
 - `tools?: string[]` — allowlist of MCP tool names or group prefixes. Tool names are `__`-joined snake_case path segments (`root__bot__create`); a prefix like `root__bot` includes every descendant tool.
 - `omitRootToolNamePrefix?: boolean` — defaults to `false`. Set to `true` to omit the root group name from single-root MCP tool names (`bot__create`).
 - `casing?: "snake" | "camel"` — affects MCP input-schema property names, output-schema property names, and structured result keys. Tool names always stay `__`-joined snake_case.
 
-### `HumanInLoopRuntimeOptions`
+### `createHumanInLoop(options)` (from `toolcraft/human-in-loop`)
 
 ```ts
+import { createHumanInLoop, defaultProviderForPlatform, osascriptProvider } from "toolcraft/human-in-loop";
+
 type HumanInLoopRuntimeOptions = {
-  provider?: HumanInLoopProvider;
+  provider: HumanInLoopProvider; // required
   taskList?: TaskList | { dir: string; format: "markdown-dir" | "yaml-file" };
   listName?: string; // defaults to "approvals"
   binPath?: { execPath: string; entryArgs: readonly string[] };
 };
 ```
 
+Returns the `HumanInLoopRuntime` accepted by `runCLI` / `createMCPServer` / `createSDK`.
+
 ### Handler context
 
 - `params` — inferred from the command `params` schema.
@@ -530,6 +765,7 @@ type HumanInLoopRuntimeOptions = {
 - `fetch: typeof globalThis.fetch`
 - `fs: { readFile, writeFile, exists }`
 - `env: { get(key: string): string | undefined }`
+- `diagnostics: RuntimeLogger`
 - `progress(message: string): void`
 - All `services` keys merged in.
 
@@ -538,7 +774,7 @@ type HumanInLoopRuntimeOptions = {
 - `defineCommand`, `defineGroup`
 - `S`, `toJsonSchema`, type helpers — re-exported from `toolcraft-schema`
 - `UserError`, `ApprovalDeclinedError`, `HttpError` and the HTTP error subclasses.
-- Type exports: `Command`, `Group`, `Scope`, `HandlerContext`, `HumanInLoopConfig`, `HumanInLoopPending`, `HumanInLoopRuntimeOptions`, schema types from `toolcraft-schema`.
+- Type exports: `Command`, `Group`, `Scope`, `HandlerContext`, `HumanInLoopConfig`, `HumanInLoopPending`, `HumanInLoopRuntime`, schema types from `toolcraft-schema`.
 
 Subpath imports:
 
@@ -547,3 +783,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/node_modules/toolcraft/composition.json

@@ -0,0 +1,165 @@
+{
+  "schemaVersion": 1,
+  "packages": [
+    {
+      "name": "@noble/hashes",
+      "version": "2.4.0",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/agent-defs",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/agent-human-in-loop",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/agent-mcp-config",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/config-mutations",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/frontmatter",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/process-runner",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/safe-fs",
+      "version": "0.0.0-dev",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/task-list",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/terminal-text",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/user-error",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "@poe-code/xml-ast",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "auth-store",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "fast-string-truncated-width",
+      "version": "3.0.3",
+      "license": "MIT"
+    },
+    {
+      "name": "fast-string-width",
+      "version": "3.0.2",
+      "license": "MIT"
+    },
+    {
+      "name": "fast-wrap-ansi",
+      "version": "0.2.2",
+      "license": "MIT"
+    },
+    {
+      "name": "ignore",
+      "version": "5.3.2",
+      "license": "MIT"
+    },
+    {
+      "name": "jose",
+      "version": "6.2.3",
+      "license": "MIT"
+    },
+    {
+      "name": "jsonc-parser",
+      "version": "3.3.1",
+      "license": "MIT"
+    },
+    {
+      "name": "mcp-oauth",
+      "version": "0.0.1",
+      "license": "MIT"
+    },
+    {
+      "name": "mcp-oauth-server",
+      "version": "0.1.0",
+      "license": "MIT"
+    },
+    {
+      "name": "saxes",
+      "version": "6.0.0",
+      "license": "ISC"
+    },
+    {
+      "name": "sisteransi",
+      "version": "1.0.5",
+      "license": "MIT"
+    },
+    {
+      "name": "smol-toml",
+      "version": "1.7.0",
+      "license": "BSD-3-Clause"
+    },
+    {
+      "name": "tiny-http-mcp-server",
+      "version": "0.1.131",
+      "license": "MIT"
+    },
+    {
+      "name": "tiny-mcp-client",
+      "version": "0.1.0",
+      "license": "MIT"
+    },
+    {
+      "name": "tiny-stdio-mcp-server",
+      "version": "0.1.29",
+      "license": "MIT"
+    },
+    {
+      "name": "toolcraft",
+      "version": "0.0.893",
+      "license": "MIT"
+    },
+    {
+      "name": "toolcraft-design",
+      "version": "0.0.2",
+      "license": "MIT"
+    },
+    {
+      "name": "toolcraft-schema",
+      "version": "0.0.893",
+      "license": "MIT"
+    },
+    {
+      "name": "xmlchars",
+      "version": "2.2.0",
+      "license": "MIT"
+    },
+    {
+      "name": "yaml",
+      "version": "2.9.0",
+      "license": "ISC"
+    }
+  ]
+}

package/node_modules/toolcraft/dist/agent-defs.d.ts

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

package/node_modules/toolcraft/dist/agent-defs.js

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

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

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

package/node_modules/toolcraft/dist/agent-mcp-config.js

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

package/node_modules/toolcraft/dist/applied-default.d.ts

@@ -0,0 +1,3 @@
+import { type AnySchema } from "toolcraft-schema";
+import type { ValidationError } from "./validation-errors.js";
+export declare function validateAppliedDefault(schema: AnySchema, label: string, errors: ValidationError[]): unknown;