@amalgm/tools 0.1.7-main.34746904064 → 0.1.7-main.35132311462

package/PURPOSE.md

@@ -5,7 +5,7 @@
 Amalgm Tools lets a user define, keep, select, and run agent capabilities as a
 standalone product or inside Amalgm. It serves people building agents,
 automations, and applications that need one small local source of truth for
-CLI, HTTP API, and MCP tools. When the product is healthy, every callable
+CLI, HTTP API, GraphQL, and MCP tools. When the product is healthy, every callable
 action has one stable identity and one owning tool, a selected loadout exposes
 only its granted capabilities, and the SDK, CLI, and MCP surfaces all observe
 and execute the same catalog.
@@ -30,6 +30,10 @@ and parity evidence only.
 - A **loadout** is a set of tool or action ids used to derive a read-only view
   of the Toolbox.
 - A **driver** executes actions for one tool type.
+- A **connection** is a tool's current admission to execution, with credential
+  references resolved by the host's encrypted vault; it is not another catalog.
+- **Exposure** is an agent loadout's presentation of a granted action: direct,
+  searchable, or hidden. An action override is more specific than its tool default.
 - An **MCP server** is a separately identified runtime endpoint that may expose
   one or more tools; selecting a tool never changes that server's identity.
 - A **system tool** is an embedder-owned definition projected into the catalog;
@@ -39,6 +43,10 @@ and parity evidence only.
 
 ## Axioms
 
+MCP execution context belongs to each host-admitted call. It passes unchanged
+to the driver, never comes from model-supplied arguments or metadata, and never
+leaks between concurrent calls sharing a prepared Toolbox view.
+
 Consumer assembly derives exact same-branch dependency pins from the declared
 package manifests and registry candidate records. One pending composition per
 branch preserves human edits; complete consumer checks for the exact merge tree govern its
@@ -137,6 +145,30 @@ locked dependency graph on the supported Node toolchain.
     definitions and scope cannot change. Later catalog edits affect future
     preparation; already prepared calls use their captured definitions and the
     host's current credential and execution effects.
+28. Disconnect disables the parent tool and removes its saved authentication;
+    it retains the definition and action schemas for reconnection. Current parent
+    admission gates every invocation, including an already prepared execution.
+    A loadout edit never connects, disconnects, or changes the parent Toolbox.
+29. A loadout grants only its selected tool/action ids. Omitted exposure means
+    direct; an explicit action exposure overrides its selected tool's exposure.
+    Hidden actions appear in neither listing, search, prompt descriptions, nor
+    invocation. Search exposes only searchable descriptors and its scoped call
+    action. An exposure entry cannot grant an unselected capability.
+30. Every tool type crosses the same scoped MCP action boundary. ACP describes
+    the server supplied to an agent; MCP describes action schemas and results.
+    Native adapters do not discover tools or decide exposure. CLI descriptions
+    may inform system instructions, but never substitute for execution admission.
+31. Connecting an MCP source discovers and stores its complete official action
+    schemas before activation. Invocation uses those captured schemas and exact
+    target names; a later remote catalog cannot expand an agent's grant.
+32. OAuth access, refresh, and client secrets remain in the host vault.
+    Header, environment, and query authentication use source-bound vault references. Refresh
+    is serialized per credential, preserves rotated tokens, and cannot restore a
+    disconnected credential. Credential references are bound to the registered
+    source, so editing an endpoint cannot send an earlier secret to a new authority.
+33. GraphQL actions store one operation document and send validated input as its
+    variables to the registered endpoint. API and GraphQL redirects never forward
+    credentials to another endpoint; callers cannot override registered targets.
 
 ## Predictable behavior
 

package/README.md

@@ -66,9 +66,15 @@ amalgm-tools apply ./tool.mjs
 amalgm-tools list
 amalgm-tools run hello.say --input '{"name":"Ada"}'
 amalgm-tools disable hello.say
+amalgm-tools link canvas app-3f1c
 amalgm-tools connections
 ```
 
+A tool may belong to an app: `appId` on the tool is the reverse edge of the
+app manifest's `toolIds`, and sharing either side carries the other. The host
+that composes Tools and Apps may pass `environment(tool)` so a linked tool
+runs knowing where its app listens.
+
 `amalgm-tools-mcp` serves Toolbox management and enabled action tools over
 newline-delimited MCP stdio.
 
@@ -83,10 +89,14 @@ const server = createToolboxHttpServer({ toolbox });
 await server.listen(8083);
 ```
 
-The read adapter serves the legacy-compatible `GET /toolbox`,
+The adapter serves `GET /toolbox`,
 `GET /toolbox/tools?id=...`, and `GET /toolbox/actions?id=...` routes over
-the same live Toolbox used by CLI and MCP consumers. Mutation routes return
-405 until their legacy record fields can be represented without data loss.
+the same live Toolbox used by CLI and MCP consumers. `POST /toolbox/tools`
+connects a definition with optional write-only credentials. `PATCH /toolbox/tools`
+with `{ id, status: "disabled" }` disconnects it. `DELETE /toolbox/tools` removes
+it. `POST /toolbox/actions/call` invokes `{ id, input }`.
+The authenticated host selects the owner. OAuth authorization and callback
+use `POST /toolbox/oauth/authorize` and `POST /toolbox/oauth/callback`.
 
 ## Notifications
 
@@ -102,11 +112,31 @@ and must not be presented as a second Channels implementation.
 
 - `cli`: executed directly with `spawn`; a shell is never involved.
 - `api`: same-origin HTTP actions with redirects refused.
+- `graphql`: a saved operation document with validated input as its variables.
 - `mcp`: a connection plus action projection. The composing MCP host supplies
   the one MCP driver that owns discovery, sessions, and calls.
 
-Secret values are never part of definitions. `secretEnv` and `secretHeaders`
-contain opaque references resolved through `CallOptions.resolveSecret`.
+Secret values are never part of definitions. `secretEnv`, `secretHeaders`,
+and `secretQuery` contain opaque references resolved at invocation. A host
+supplies `credentials: { get, set, delete }` backed by its encrypted vault.
+`toolbox.connect({ definition, credentials })` stores authentication separately
+and discovers MCP actions before activation. `toolbox.disconnect(id)` removes
+authentication and disables execution while retaining the definition and actions.
+
+A loadout contains `toolIds` (whole-tool or action ids) and optional `exposure`:
+
+```js
+const selected = toolbox.prepare(toolbox.catalog().revisionId, {
+  toolIds: ['service'],
+  exposure: { service: 'search', 'service.read': 'direct', 'service.erase': 'hidden' },
+});
+```
+
+Direct actions are listed normally. Searchable actions are reachable only through
+`toolbox_search` and its scoped `toolbox_call`. Hidden actions cannot be listed,
+searched, or invoked. Every type uses this same MCP surface; ACP supplies the
+server to each agent adapter. A prepared view keeps its captured definitions
+but still honors a subsequent parent disconnect.
 See [PURPOSE.md](./PURPOSE.md) for the complete contract and
 [SHELL_INTEGRATION.md](./docs/SHELL_INTEGRATION.md) for active composition.
 The [Engine integration](./docs/ENGINE_INTEGRATION.md) page is historical only.

package/dist/api-driver.d.ts

@@ -1,3 +1,4 @@
 import type { ToolDriver } from './types.js';
 declare const apiDriver: ToolDriver;
-export { apiDriver };
+declare const graphqlDriver: ToolDriver;
+export { apiDriver, graphqlDriver };

package/dist/api-driver.js

@@ -26,13 +26,20 @@ async function readBody(response, maximum) {
             chunks.push(value.subarray(0, room));
             size += Math.min(room, value.length);
         }
+        if (truncated) {
+            await reader.cancel();
+            break;
+        }
     }
     return { text: Buffer.concat(chunks).toString('utf8'), truncated };
 }
 function timeoutSignal(timeoutMs, parent) {
     const controller = new AbortController();
     const abort = () => controller.abort(parent?.reason);
-    parent?.addEventListener('abort', abort, { once: true });
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
     const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs);
     timer.unref();
     return {
@@ -40,53 +47,65 @@ function timeoutSignal(timeoutMs, parent) {
         close() { clearTimeout(timer); parent?.removeEventListener('abort', abort); },
     };
 }
-const apiDriver = {
-    type: 'api',
-    async call({ tool, action, input, options }) {
-        const source = tool.source;
-        const target = action.target;
-        const base = new URL(source.baseUrl);
-        const url = new URL(fillPath(target.path, input), base);
-        if (url.origin !== base.origin)
-            throw new Error(`API action ${action.id} leaves its registered origin`);
-        const query = input.query;
-        if (query && (typeof query !== 'object' || Array.isArray(query)))
-            throw new Error('input.query must be an object');
-        for (const [key, value] of Object.entries((query || {}))) {
-            if (value !== undefined && value !== null)
-                url.searchParams.append(key, String(value));
-        }
-        const headers = await resolveReferences(source.secretHeaders, options.resolveSecret);
-        const method = target.method.toUpperCase();
-        const timed = timeoutSignal(source.timeoutMs, options.signal);
+async function callHttp({ tool, action, input, options }) {
+    const source = tool.source;
+    if (source.type !== 'api' && source.type !== 'graphql')
+        throw new Error('HTTP tool source required');
+    const target = action.target;
+    const graphql = action.target;
+    const base = new URL(source.type === 'api' ? source.baseUrl : source.url);
+    const url = source.type === 'api' ? new URL(fillPath(target.path, input), base) : base;
+    if (url.origin !== base.origin)
+        throw new Error(`API action ${action.id} leaves its registered origin`);
+    const query = source.type === 'api' ? input.query : undefined;
+    if (query && (typeof query !== 'object' || Array.isArray(query)))
+        throw new Error('input.query must be an object');
+    for (const [key, value] of Object.entries((query || {}))) {
+        if (value !== undefined && value !== null)
+            url.searchParams.append(key, String(value));
+    }
+    const secretQuery = await resolveReferences(source.secretQuery, options.resolveSecret);
+    for (const [key, value] of Object.entries(secretQuery))
+        url.searchParams.set(key, value);
+    const headers = await resolveReferences(source.secretHeaders, options.resolveSecret);
+    const method = source.type === 'api' ? target.method.toUpperCase() : 'POST';
+    const requestBody = source.type === 'api' ? (input.body ?? input) : {
+        query: graphql.document, variables: input,
+        ...(graphql.operationName ? { operationName: graphql.operationName } : {}),
+    };
+    const timed = timeoutSignal(source.timeoutMs, options.signal);
+    try {
+        const response = await fetch(url, {
+            method, redirect: 'manual', signal: timed.signal,
+            headers: { 'content-type': 'application/json', ...headers },
+            body: ['GET', 'HEAD'].includes(method) ? undefined : JSON.stringify(requestBody),
+        });
+        if (response.status >= 300 && response.status < 400)
+            return errorResult(`API tool ${action.id} refused redirect`);
+        const body = await readBody(response, source.maxOutputBytes);
+        if (!response.ok)
+            return errorResult(`HTTP ${response.status} ${response.statusText}\n\n${body.text}`);
+        let result;
         try {
-            const response = await fetch(url, {
-                method, redirect: 'manual', signal: timed.signal,
-                headers: { 'content-type': 'application/json', ...headers },
-                body: ['GET', 'HEAD'].includes(method) ? undefined : JSON.stringify(input.body ?? input),
-            });
-            if (response.status >= 300 && response.status < 400)
-                return errorResult(`API tool ${action.id} refused redirect`);
-            const body = await readBody(response, source.maxOutputBytes);
-            if (!response.ok)
-                return errorResult(`HTTP ${response.status} ${response.statusText}\n\n${body.text}`);
-            let result;
-            try {
-                result = structuredResult(JSON.parse(body.text));
-            }
-            catch {
-                result = textResult(body.text);
-            }
-            return { ...boundedResult(result, source.maxOutputBytes), ...(body.truncated ? { truncated: true } : {}) };
+            const value = JSON.parse(body.text);
+            result = structuredResult(value);
+            if (source.type === 'graphql' && Array.isArray(value?.errors) && value.errors.length)
+                result.isError = true;
         }
-        catch (error) {
-            if (timed.signal.aborted)
-                return errorResult(options.signal?.aborted ? `Tool ${action.id} was cancelled` : `Tool ${action.id} timed out`);
-            throw error;
+        catch {
+            result = textResult(body.text);
         }
-        finally {
-            timed.close();
-        }
-    },
-};
-export { apiDriver };
+        return { ...boundedResult(result, source.maxOutputBytes), ...(body.truncated ? { truncated: true } : {}) };
+    }
+    catch (error) {
+        if (timed.signal.aborted)
+            return errorResult(options.signal?.aborted ? `Tool ${action.id} was cancelled` : `Tool ${action.id} timed out`);
+        throw error;
+    }
+    finally {
+        timed.close();
+    }
+}
+const apiDriver = { type: 'api', call: callHttp };
+const graphqlDriver = { type: 'graphql', call: callHttp };
+export { apiDriver, graphqlDriver };

package/dist/cli-driver.d.ts

@@ -1,3 +1,4 @@
-import type { ToolDriver } from './types.js';
-declare const cliDriver: ToolDriver;
-export { cliDriver };
+import type { ToolDriver, ToolRecord } from './types.js';
+type Environment = (tool: ToolRecord) => Record<string, string> | Promise<Record<string, string>>;
+declare function createCliDriver(environment?: Environment): ToolDriver;
+export { createCliDriver };

package/dist/cli-driver.js

@@ -1,4 +1,5 @@
 import { runCommand } from './process.js';
+import { getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { errorResult, structuredResult, textResult } from './results.js';
 import { resolveReferences } from './secrets.js';
 function inputArguments(input) {
@@ -8,45 +9,47 @@ function inputArguments(input) {
     }
     return args;
 }
-const cliDriver = {
-    type: 'cli',
-    async call({ tool, action, input, options }) {
-        const source = tool.source;
-        const target = action.target;
-        const environment = await resolveReferences(source.secretEnv, options.resolveSecret);
-        const args = [...(source.args || []), ...(target.args || [])];
-        if (source.inputMode === 'argv')
-            args.push(...inputArguments(input));
-        const output = await runCommand({
-            command: source.command, args, cwd: source.cwd,
-            env: { ...process.env, ...environment },
-            stdin: source.inputMode === 'json-stdin' ? `${JSON.stringify(input)}\n` : undefined,
-            timeoutMs: source.timeoutMs, maximumBytes: source.maxOutputBytes, signal: options.signal,
-        });
-        const stdout = output.stdout.trim();
-        const stderr = output.stderr.trim();
-        if (output.timedOut)
-            return errorResult(`Tool ${action.id} timed out after ${source.timeoutMs}ms`);
-        if (output.aborted)
-            return errorResult(`Tool ${action.id} was cancelled`);
-        if (output.code !== 0) {
-            return errorResult([
-                `Tool ${action.id} exited with ${output.code ?? output.signal ?? 'unknown'}.`,
-                stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`,
-            ].filter(Boolean).join('\n\n'));
-        }
-        let result;
-        if (source.outputMode === 'json' && stdout) {
-            try {
-                result = structuredResult(JSON.parse(stdout));
+function createCliDriver(environment = () => ({})) {
+    return {
+        type: 'cli',
+        async call({ tool, action, input, options }) {
+            const source = tool.source;
+            const target = action.target;
+            const secrets = await resolveReferences(source.secretEnv, options.resolveSecret);
+            const args = [...(source.args || []), ...(target.args || [])];
+            if (source.inputMode === 'argv')
+                args.push(...inputArguments(input));
+            const output = await runCommand({
+                command: source.command, args, cwd: source.cwd,
+                env: { ...getDefaultEnvironment(), ...(await environment(tool)), ...secrets },
+                stdin: source.inputMode === 'json-stdin' ? `${JSON.stringify(input)}\n` : undefined,
+                timeoutMs: source.timeoutMs, maximumBytes: source.maxOutputBytes, signal: options.signal,
+            });
+            const stdout = output.stdout.trim();
+            const stderr = output.stderr.trim();
+            if (output.timedOut)
+                return errorResult(`Tool ${action.id} timed out after ${source.timeoutMs}ms`);
+            if (output.aborted)
+                return errorResult(`Tool ${action.id} was cancelled`);
+            if (output.code !== 0) {
+                return errorResult([
+                    `Tool ${action.id} exited with ${output.code ?? output.signal ?? 'unknown'}.`,
+                    stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`,
+                ].filter(Boolean).join('\n\n'));
             }
-            catch {
-                return errorResult(`Tool ${action.id} returned invalid JSON`);
+            let result;
+            if (source.outputMode === 'json' && stdout) {
+                try {
+                    result = structuredResult(JSON.parse(stdout));
+                }
+                catch {
+                    return errorResult(`Tool ${action.id} returned invalid JSON`);
+                }
             }
-        }
-        else
-            result = textResult(stdout || `Tool ${action.id} completed.`);
-        return { ...result, ...(output.truncated ? { truncated: true } : {}) };
-    },
-};
-export { cliDriver };
+            else
+                result = textResult(stdout || `Tool ${action.id} completed.`);
+            return { ...result, ...(output.truncated ? { truncated: true } : {}) };
+        },
+    };
+}
+export { createCliDriver };

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 import type { CliIo, LoadoutInput } from './types.js';
-declare const HELP = "Usage: amalgm-tools [--state-dir DIR] [--loadout IDS] <command>\n\nCommands:\n  apply <definition.js|json>  Apply one tool or an array of tools\n  list                        List tools and enabled actions\n  catalog                     Print the complete canonical catalog\n  show <tool-or-action-id>    Show one record\n  enable <tool-or-action-id>  Enable one record\n  disable <tool-or-action-id> Disable one record\n  remove <tool-or-action-id>  Remove one record\n  run <action-id> [--input JSON]\n                              Run an action\n  connections                 List MCP connections for a composing host";
+declare const HELP = "Usage: amalgm-tools [--state-dir DIR] [--loadout IDS] <command>\n\nCommands:\n  apply <definition.js|json>  Apply one tool or an array of tools\n  list                        List tools and enabled actions\n  catalog                     Print the complete canonical catalog\n  show <tool-or-action-id>    Show one record\n  enable <tool-or-action-id>  Enable one record\n  disable <tool-or-action-id> Disable one record\n  remove <tool-or-action-id>  Remove one record\n  link <tool-id> <app-id>     Link one tool to the app it belongs to\n  unlink <tool-id>            Detach one tool from its app\n  run <action-id> [--input JSON]\n                              Run an action\n  connections                 List MCP connections for a composing host";
 interface Parsed {
     command?: string;
     args: string[];
@@ -7,7 +7,12 @@ interface Parsed {
     loadout?: LoadoutInput;
     input: Record<string, unknown>;
 }
+/** One call on the command surface: an MCP tool name and its arguments. */
+interface Call {
+    name: string;
+    args: Record<string, unknown>;
+}
 declare function parse(argv: string[]): Parsed;
 declare function runCli(argv: string[], io?: CliIo): Promise<number>;
 export { HELP, parse, runCli };
-export type { Parsed };
+export type { Call, Parsed };

package/dist/cli.js

@@ -1,3 +1,5 @@
+import { createToolboxCommands } from './commands.js';
+import { id, mcpName } from './ids.js';
 import { loadDefinitions } from './module.js';
 import { Toolbox } from './toolbox.js';
 const HELP = `Usage: amalgm-tools [--state-dir DIR] [--loadout IDS] <command>
@@ -10,6 +12,8 @@ Commands:
   enable <tool-or-action-id>  Enable one record
   disable <tool-or-action-id> Disable one record
   remove <tool-or-action-id>  Remove one record
+  link <tool-id> <app-id>     Link one tool to the app it belongs to
+  unlink <tool-id>            Detach one tool from its app
   run <action-id> [--input JSON]
                               Run an action
   connections                 List MCP connections for a composing host`;
@@ -48,9 +52,44 @@ function required(value, label) {
         throw new Error(`${label} is required`);
     return value;
 }
+/** Map one parsed command line to its calls; `apply` makes one call per definition. */
+async function calls(parsed) {
+    const [first, second] = parsed.args;
+    const record = (name, label) => ({ name, args: { id: required(first, label) } });
+    switch (parsed.command) {
+        case 'apply': {
+            const definitions = await loadDefinitions(required(first, 'definition file'));
+            return definitions.map((tool) => ({ name: 'toolbox_tool_apply', args: { tool } }));
+        }
+        case 'list': return [{ name: 'toolbox_tools_selected', args: {} }];
+        case 'catalog': return [{ name: 'toolbox_tools_list', args: {} }];
+        case 'show': return [record('toolbox_tool_get', 'tool or action id')];
+        case 'enable': return [record('toolbox_record_enable', 'record id')];
+        case 'disable': return [record('toolbox_record_disable', 'record id')];
+        case 'remove': return [record('toolbox_record_remove', 'record id')];
+        case 'link': return [{
+                name: 'toolbox_tool_link',
+                args: { id: required(first, 'tool id'), app_id: required(second, 'app id') },
+            }];
+        case 'unlink': return [record('toolbox_tool_unlink', 'tool id')];
+        case 'run': return [{ name: mcpName({ id: id(first, 'action id') }), args: parsed.input }];
+        case 'connections': return [{ name: 'toolbox_mcp_connections', args: {} }];
+        default: throw new Error(`Unknown command: ${parsed.command}`);
+    }
+}
+function open(io, parsed) {
+    if (io.commands)
+        return { commands: io.commands, close() { } };
+    const toolbox = new Toolbox({ stateDir: parsed.stateDir });
+    return { commands: createToolboxCommands(toolbox, parsed.loadout), close: () => toolbox.close() };
+}
 function write(output, value) {
     output.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function fail(output, error) {
+    output.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+}
 async function runCli(argv, io = {}) {
     const stdout = io.stdout || process.stdout;
     const stderr = io.stderr || process.stderr;
@@ -59,65 +98,28 @@ async function runCli(argv, io = {}) {
         parsed = parse(argv);
     }
     catch (error) {
-        stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-        return 1;
+        return fail(stderr, error);
     }
     if (!parsed.command || ['help', '-h', '--help'].includes(parsed.command)) {
         stdout.write(`${HELP}\n`);
         return 0;
     }
-    const toolbox = io.toolbox || new Toolbox({ stateDir: parsed.stateDir });
     try {
-        const recordId = parsed.args[0];
-        switch (parsed.command) {
-            case 'apply': {
-                const definitions = await loadDefinitions(required(recordId, 'definition file'));
-                const results = [];
-                for (const definition of definitions)
-                    results.push(await toolbox.apply(definition));
-                write(stdout, results.length === 1 ? results[0] : results);
-                break;
-            }
-            case 'list':
-                write(stdout, toolbox.list(parsed.loadout));
-                break;
-            case 'catalog':
-                write(stdout, toolbox.catalog());
-                break;
-            case 'show': {
-                const value = required(recordId, 'tool or action id');
-                const result = toolbox.get(value) || toolbox.action(value);
-                if (!result)
-                    throw new Error(`Unknown tool or action: ${value}`);
-                write(stdout, result);
-                break;
-            }
-            case 'enable':
-                write(stdout, await toolbox.setStatus(required(recordId, 'record id'), 'enabled'));
-                break;
-            case 'disable':
-                write(stdout, await toolbox.setStatus(required(recordId, 'record id'), 'disabled'));
-                break;
-            case 'remove':
-                write(stdout, await toolbox.remove(required(recordId, 'record id')));
-                break;
-            case 'run':
-                write(stdout, await toolbox.call(required(recordId, 'action id'), parsed.input, { loadout: parsed.loadout }));
-                break;
-            case 'connections':
-                write(stdout, toolbox.connections(parsed.loadout));
-                break;
-            default: throw new Error(`Unknown command: ${parsed.command}`);
+        const planned = await calls(parsed);
+        const session = open(io, parsed);
+        try {
+            const results = [];
+            for (const call of planned)
+                results.push(await session.commands.execute(call.name, call.args));
+            write(stdout, results.length === 1 ? results[0] : results);
+        }
+        finally {
+            session.close();
         }
         return 0;
     }
     catch (error) {
-        stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-        return 1;
-    }
-    finally {
-        if (!io.toolbox)
-            toolbox.close();
+        return fail(stderr, error);
     }
 }
 export { HELP, parse, runCli };

package/dist/commands.d.ts

@@ -0,0 +1,27 @@
+import type { Toolbox } from './toolbox.js';
+import type { LoadoutInput } from './types.js';
+/**
+ * The one command surface. The CLI speaks only this; a host forwards it to a
+ * running runtime's MCP over HTTP, and `createToolboxCommands` runs it against
+ * a local Toolbox through that Toolbox's own MCP tools.
+ *
+ * `name` is an MCP tool name from this package's MCP surface: a management
+ * tool (`toolbox_*`, single underscore) or an action tool (`toolbox__<id>`,
+ * from `mcpName`). `args` is the MCP `arguments` object for that tool.
+ *
+ * `execute` resolves to the tool's value, unwrapped from the MCP call result:
+ * - any result with `isError: true` rejects with an Error whose message is
+ *   the result's text content (every `content[].text`, joined by newlines);
+ * - a management tool's value is `result.structuredContent` (its text
+ *   content is the same value as JSON and is never consulted);
+ * - an action tool's value is the whole MCP result (`content`,
+ *   `structuredContent`, `truncated`) exactly as the driver returned it.
+ * A remote implementation sends `name`/`args` as an MCP `tools/call` and
+ * applies these three rules to the response.
+ */
+interface ToolCommands {
+    execute(name: string, args: Record<string, unknown>): Promise<unknown>;
+}
+declare function createToolboxCommands(toolbox: Toolbox, loadout?: LoadoutInput): ToolCommands;
+export { createToolboxCommands };
+export type { ToolCommands };

package/dist/commands.js

@@ -0,0 +1,16 @@
+import { isActionMcpName } from './ids.js';
+import { callMcpTool } from './mcp.js';
+import { structuredValue } from './results.js';
+function unwrap(name, result) {
+    if (result.isError)
+        throw new Error(result.content.filter((item) => item.type === 'text').map((item) => item.text).join('\n'));
+    return isActionMcpName(name) ? result : structuredValue(result.structuredContent);
+}
+function createToolboxCommands(toolbox, loadout) {
+    return {
+        async execute(name, args) {
+            return unwrap(name, await callMcpTool(toolbox, name, args, { loadout }));
+        },
+    };
+}
+export { createToolboxCommands };

package/dist/connection-auth.d.ts

@@ -0,0 +1,11 @@
+import type { ToolCredential, ToolCredentialStore } from './connection-types.js';
+import type { SecretResolver } from './types.js';
+export declare function validateCredential(value: ToolCredential): ToolCredential;
+/** Token refresh belongs to the connection; encryption belongs to the host. */
+export declare class ToolAuthentication {
+    #private;
+    readonly store?: ToolCredentialStore | undefined;
+    private readonly fallback?;
+    constructor(store?: ToolCredentialStore | undefined, fallback?: SecretResolver | undefined);
+    resolve: (reference: string) => Promise<string | undefined>;
+}