@amalgm/tools 0.1.7-preview.34436591947 → 0.1.7-preview.34547098528

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.
 

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

@@ -8,45 +8,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: { ...process.env, ...(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,15 @@
+import { isActionMcpName } from './ids.js';
+import { callMcpTool } from './mcp.js';
+function unwrap(name, result) {
+    if (result.isError)
+        throw new Error(result.content.map((item) => item.text).join('\n'));
+    return isActionMcpName(name) ? result : result.structuredContent;
+}
+function createToolboxCommands(toolbox, loadout) {
+    return {
+        async execute(name, args) {
+            return unwrap(name, await callMcpTool(toolbox, name, args, { loadout }));
+        },
+    };
+}
+export { createToolboxCommands };

package/dist/definition.js

@@ -140,6 +140,7 @@ function normalizeDefinition(definition, existing, now = new Date().toISOString(
         owner: definition.owner?.trim() || 'user', origin,
         status: definition.status || 'enabled',
         ...(definition.description?.trim() ? { description: definition.description.trim() } : {}),
+        ...(definition.appId?.trim() ? { appId: definition.appId.trim() } : {}),
         ...(definition.display ? { display: structuredClone(definition.display) } : {}),
         ...(definition.policy ? { policy: structuredClone(definition.policy) } : {}),
         ...(definition.metadata ? { metadata: structuredClone(definition.metadata) } : {}),

package/dist/host-mcp-tool.d.ts

@@ -1,4 +1,20 @@
-import type { HostMcpToolDefinitionInput, ToolDefinition } from './types.js';
+import type { JsonSchema, ToolDefinition } from './types.js';
+interface HostMcpToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+}
+interface HostMcpToolDefinitionInput {
+    id: string;
+    name: string;
+    description?: string;
+    serverName: string;
+    route: string;
+    tools: readonly HostMcpToolDescriptor[];
+    owner?: string;
+    display?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
 /**
  * Project an owning SDK's MCP descriptors into one immutable first-party
  * Toolbox tool. The descriptors remain authoritative; this adapter does not
@@ -6,3 +22,4 @@ import type { HostMcpToolDefinitionInput, ToolDefinition } from './types.js';
  */
 declare function defineHostMcpTool(input: HostMcpToolDefinitionInput): ToolDefinition;
 export { defineHostMcpTool };
+export type { HostMcpToolDefinitionInput, HostMcpToolDescriptor };

package/dist/ids.d.ts

@@ -3,5 +3,7 @@ declare function id(value: unknown, label?: string, maximumLength?: number): str
 declare function actionName(value: unknown): string;
 declare function actionId(toolId: string, name: string): string;
 declare function mcpName(action: Pick<ActionRecord, 'id'>): string;
+/** Action tools carry the double-underscore prefix; management tools never do. */
+declare function isActionMcpName(name: string): boolean;
 declare function assertMcpNamesUnique(actions: Pick<ActionRecord, 'id'>[]): void;
-export { actionId, actionName, assertMcpNamesUnique, id, mcpName };
+export { actionId, actionName, assertMcpNamesUnique, id, isActionMcpName, mcpName };

package/dist/ids.js

@@ -21,8 +21,13 @@ function actionId(toolId, name) {
 function safeMcpName(value) {
     return value.replace(/[^A-Za-z0-9_-]+/g, '_').replace(/_+/g, '_');
 }
+const MCP_ACTION_PREFIX = 'toolbox__';
 function mcpName(action) {
-    return `toolbox__${safeMcpName(action.id)}`;
+    return `${MCP_ACTION_PREFIX}${safeMcpName(action.id)}`;
+}
+/** Action tools carry the double-underscore prefix; management tools never do. */
+function isActionMcpName(name) {
+    return name.startsWith(MCP_ACTION_PREFIX);
 }
 function assertMcpNamesUnique(actions) {
     const names = new Map();
@@ -35,4 +40,4 @@ function assertMcpNamesUnique(actions) {
         names.set(name, action.id);
     }
 }
-export { actionId, actionName, assertMcpNamesUnique, id, mcpName };
+export { actionId, actionName, assertMcpNamesUnique, id, isActionMcpName, mcpName };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { ArtifactFiles } from './artifact-files.js';
 export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, } from './artifacts.js';
 export type { ArtifactFileWrite, LegacyMigrationPlan, ToolArtifactDocument, ToolboxIndexDocument, } from './artifacts.js';
+export { createToolboxCommands } from './commands.js';
+export type { ToolCommands } from './commands.js';
 export { defineTool, normalizeDefinition } from './definition.js';
 export { defineHostMcpTool } from './host-mcp-tool.js';
 export { TOOL_DEPLOYMENT_CONTRACT, TOOL_DEPLOYMENT_KIND, TOOL_DEPLOYMENT_SCHEMA_VERSION, assertToolDeploymentActivation, createToolDeployment, deploymentRevisionId, emptyToolDeploymentSnapshot, } from './deployments.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { ArtifactFiles } from './artifact-files.js';
 export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, } from './artifacts.js';
+export { createToolboxCommands } from './commands.js';
 export { defineTool, normalizeDefinition } from './definition.js';
 export { defineHostMcpTool } from './host-mcp-tool.js';
 export { TOOL_DEPLOYMENT_CONTRACT, TOOL_DEPLOYMENT_KIND, TOOL_DEPLOYMENT_SCHEMA_VERSION, assertToolDeploymentActivation, createToolDeployment, deploymentRevisionId, emptyToolDeploymentSnapshot, } from './deployments.js';

package/dist/mcp.d.ts

@@ -2,7 +2,7 @@ import type { Toolbox } from './toolbox.js';
 import type { JsonSchema, McpOptions, McpTool } from './types.js';
 declare function portable(schema: JsonSchema): JsonSchema;
 declare function managementToolDescriptors(): Array<Omit<McpTool, 'handler'>>;
-declare function managementTools(toolbox: Toolbox): McpTool[];
+declare function managementTools(toolbox: Toolbox, options?: McpOptions): McpTool[];
 declare function actionTools(toolbox: Toolbox, options?: McpOptions): McpTool[];
 declare function createMcpTools(toolbox: Toolbox, options?: McpOptions): McpTool[];
 declare function findMcpTool(toolbox: Toolbox, name: string, options?: McpOptions): McpTool | null;

package/dist/mcp.js

@@ -29,7 +29,12 @@ function managementToolDescriptors() {
             inputSchema: { type: 'object', properties: {}, additionalProperties: false },
         },
         {
-            name: 'toolbox_tool_get', description: 'Get one tool and its actions.',
+            name: 'toolbox_tools_selected',
+            description: 'List tools with their selected actions: the loadout, or every enabled action.',
+            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        },
+        {
+            name: 'toolbox_tool_get', description: 'Get one tool and its actions, or one action.',
             inputSchema: { type: 'object', properties: idProperty, required: ['id'], additionalProperties: false },
         },
         {
@@ -51,27 +56,41 @@ function managementToolDescriptors() {
             name: 'toolbox_record_remove', description: 'Remove one user-owned tool or action.',
             inputSchema: { type: 'object', properties: idProperty, required: ['id'], additionalProperties: false },
         },
+        {
+            name: 'toolbox_tool_link', description: 'Link one user-owned tool to the app it belongs to.',
+            inputSchema: {
+                type: 'object', required: ['id', 'app_id'], additionalProperties: false,
+                properties: { ...idProperty, app_id: { type: 'string', description: 'App id' } },
+            },
+        },
+        {
+            name: 'toolbox_tool_unlink', description: 'Detach one user-owned tool from its app.',
+            inputSchema: { type: 'object', properties: idProperty, required: ['id'], additionalProperties: false },
+        },
         {
             name: 'toolbox_mcp_connections', description: 'List external MCP connections for the composing host.',
             inputSchema: { type: 'object', properties: {}, additionalProperties: false },
         },
     ];
 }
-function managementTools(toolbox) {
-    const [list, get, apply, enable, disable, remove, connections] = managementToolDescriptors();
+function managementTools(toolbox, options = {}) {
+    const [list, selected, get, apply, enable, disable, remove, link, unlink, connections,] = managementToolDescriptors();
     return [
         managed(list, () => toolbox.catalog()),
+        managed(selected, () => toolbox.list(options.loadout)),
         managed(get, ({ id }) => {
-            const result = toolbox.get(String(id));
+            const result = toolbox.get(String(id)) || toolbox.action(String(id));
             if (!result)
-                throw new Error(`Unknown tool: ${id}`);
+                throw new Error(`Unknown tool or action: ${id}`);
             return result;
         }),
         managed(apply, ({ tool }) => toolbox.apply(tool)),
         managed(enable, ({ id }) => toolbox.setStatus(String(id), 'enabled')),
         managed(disable, ({ id }) => toolbox.setStatus(String(id), 'disabled')),
         managed(remove, ({ id }) => toolbox.remove(String(id))),
-        managed(connections, () => toolbox.connections()),
+        managed(link, ({ id, app_id }) => toolbox.link(String(id), String(app_id))),
+        managed(unlink, ({ id }) => toolbox.link(String(id), null)),
+        managed(connections, () => toolbox.connections(options.loadout)),
     ];
 }
 function actionTools(toolbox, options = {}) {
@@ -91,7 +110,7 @@ function actionTools(toolbox, options = {}) {
 }
 function createMcpTools(toolbox, options = {}) {
     return [
-        ...(options.includeManagement === false ? [] : managementTools(toolbox)),
+        ...(options.includeManagement === false ? [] : managementTools(toolbox, options)),
         ...actionTools(toolbox, options),
     ];
 }

package/dist/toolbox.d.ts

@@ -34,8 +34,11 @@ declare class Toolbox {
     update(toolId: string, patch: ToolPatch): Promise<ApplyResult>;
     upsertAction(toolId: string, definition: ActionDefinition): Promise<ActionRecord>;
     updateAction(actionId: string, patch: ActionPatch): Promise<ActionRecord>;
-    setStatus(recordId: string, status: 'enabled' | 'disabled'): Promise<ToolRecord | ActionRecord>;
-    remove(recordId: string): Promise<ToolRecord | ActionRecord>;
+    setStatus(recordId: string, status: 'enabled' | 'disabled'): Promise<ActionRecord | ToolRecord>;
+    /** Link one user tool to the app it belongs to; `null` unlinks it. */
+    link(toolId: string, appId: string | null): Promise<ToolRecord>;
+    isSystemTool(toolId: string): boolean;
+    remove(recordId: string): Promise<ActionRecord | ToolRecord>;
     currentDeployment(toolId: string): ToolDeployment | null;
     deployment(deploymentId: string): ToolDeployment | null;
     deploymentHistory(toolId: string): ToolDeployment[];

package/dist/toolbox.js

@@ -5,7 +5,7 @@ import { apiDriver } from './api-driver.js';
 import { applyDefinition } from './apply-definition.js';
 import { ArtifactFiles } from './artifact-files.js';
 import { preserveProjectionTime } from './artifacts.js';
-import { cliDriver } from './cli-driver.js';
+import { createCliDriver } from './cli-driver.js';
 import { DeploymentFiles } from './deployment-files.js';
 import { deploymentRevisionId } from './deployments.js';
 import { normalizeDefinition } from './definition.js';
@@ -14,7 +14,7 @@ import { Store } from './store.js';
 import { ToolboxDeployments } from './toolbox-deployments.js';
 import { ToolboxProjection } from './toolbox-projection.js';
 import { ToolboxView } from './toolbox-view.js';
-import { removeAction, updateAction, updateTool, upsertAction } from './updates.js';
+import { linkTool, removeAction, updateAction, updateTool, upsertAction } from './updates.js';
 function defaultDatabase(options) {
     if (options.databaseFile)
         return path.resolve(options.databaseFile);
@@ -43,7 +43,7 @@ class Toolbox {
         const artifacts = new ArtifactFiles(path.dirname(databaseFile));
         const deploymentFiles = new DeploymentFiles(path.resolve(options.deploymentDir || options.stateDir || path.dirname(databaseFile)));
         const priorIndex = artifacts.readIndex();
-        for (const driver of [cliDriver, apiDriver, ...(options.drivers || [])])
+        for (const driver of [createCliDriver(options.environment), apiDriver, ...(options.drivers || [])])
             this.drivers.set(driver.type, driver);
         const tools = [];
         const actions = [];
@@ -138,6 +138,11 @@ class Toolbox {
             throw new Error(`Unknown tool or action: ${value}`);
         return action.status === status ? action : this.updateAction(value, { status });
     }
+    /** Link one user tool to the app it belongs to; `null` unlinks it. */
+    async link(toolId, appId) {
+        return linkTool(this, toolId, appId);
+    }
+    isSystemTool(toolId) { return this.system.tools.some((tool) => tool.id === toolId); }
     async remove(recordId) {
         const value = id(recordId, 'record id');
         if (this.system.tools.some((tool) => tool.id === value)

package/dist/types.d.ts

@@ -75,6 +75,8 @@ interface ToolDefinition {
     id: string;
     name: string;
     description?: string;
+    /** The app this tool belongs to: the reverse edge of the app manifest's `toolIds`. */
+    appId?: string;
     owner?: string;
     origin?: Origin;
     status?: Status;
@@ -163,6 +165,8 @@ interface ToolboxOptions {
     deploymentDir?: string;
     systemTools?: ToolDefinition[];
     drivers?: ToolDriver[];
+    /** Host-supplied process environment for one CLI tool call, such as where its linked app listens. */
+    environment?: (tool: ToolRecord) => Record<string, string> | Promise<Record<string, string>>;
     onChange?: (catalog: Catalog) => void | Promise<void>;
     /** Outbound local Live operation. Remote application never calls it. */
     onDeployment?: (activation: ToolDeploymentActivation) => void | Promise<void>;
@@ -176,26 +180,11 @@ interface McpTool {
 interface McpOptions extends CallOptions {
     includeManagement?: boolean;
 }
-interface HostMcpToolDescriptor {
-    name: string;
-    description?: string;
-    inputSchema?: JsonSchema;
-}
-interface HostMcpToolDefinitionInput {
-    id: string;
-    name: string;
-    description?: string;
-    serverName: string;
-    route: string;
-    tools: readonly HostMcpToolDescriptor[];
-    owner?: string;
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-}
 interface CliIo {
     stdout?: Writable;
     stderr?: Writable;
-    toolbox?: import('./toolbox.js').Toolbox;
+    commands?: import('./commands.js').ToolCommands;
 }
-export type { ActionDefinition, ActionRecord, ActionTarget, ApiSource, ApiTarget, ApplyResult, CallOptions, Catalog, CliIo, CliSource, CliTarget, DriverCall, HostMcpToolDefinitionInput, HostMcpToolDescriptor, JsonSchema, Loadout, LoadoutInput, McpOptions, McpSource, McpTarget, McpTool, Origin, SecretResolver, Status, ToolDefinition, ToolDriver, ToolboxOptions, ToolRecord, ToolResult, ToolPatch, ActionPatch, ToolQuery, ToolSource, ToolType, };
+export type { ActionDefinition, ActionRecord, ActionTarget, ApiSource, ApiTarget, ApplyResult, CallOptions, Catalog, CliIo, CliSource, CliTarget, DriverCall, JsonSchema, Loadout, LoadoutInput, McpOptions, McpSource, McpTarget, McpTool, Origin, SecretResolver, Status, ToolDefinition, ToolDriver, ToolboxOptions, ToolRecord, ToolResult, ToolPatch, ActionPatch, ToolQuery, ToolSource, ToolType, };
 export type { ToolDeployment, ToolDeploymentActivation, ToolDeploymentSnapshot, ToolDeploymentSurface, } from './deployment-types.js';
+export type { HostMcpToolDefinitionInput, HostMcpToolDescriptor } from './host-mcp-tool.js';

package/dist/updates.d.ts

@@ -1,8 +1,13 @@
 import type { Toolbox } from './toolbox.js';
-import type { ActionDefinition, ActionPatch, ActionRecord, ApplyResult, ToolPatch } from './types.js';
+import type { ActionDefinition, ActionPatch, ActionRecord, ApplyResult, ToolPatch, ToolRecord } from './types.js';
 type UpdatePort = Pick<Toolbox, 'action' | 'apply' | 'get'>;
+type LinkPort = UpdatePort & Pick<Toolbox, 'update'> & {
+    isSystemTool(toolId: string): boolean;
+};
 declare function updateTool(toolbox: UpdatePort, toolId: string, patch: ToolPatch): Promise<ApplyResult>;
+/** Link one user tool to its app; `null` unlinks. The record is unchanged when the link already holds. */
+declare function linkTool(toolbox: LinkPort, toolId: string, appId: string | null): Promise<ToolRecord>;
 declare function upsertAction(toolbox: UpdatePort, toolId: string, definition: ActionDefinition): Promise<ActionRecord>;
 declare function updateAction(toolbox: UpdatePort, actionId: string, patch: ActionPatch): Promise<ActionRecord>;
 declare function removeAction(toolbox: UpdatePort, actionId: string): Promise<ActionRecord>;
-export { removeAction, updateAction, updateTool, upsertAction };
+export { linkTool, removeAction, updateAction, updateTool, upsertAction };

package/dist/updates.js

@@ -1,3 +1,4 @@
+import { id } from './ids.js';
 function actionDefinition(action) {
     const { id, toolId: _toolId, createdAt: _createdAt, updatedAt: _updatedAt, ...definition } = action;
     return { ...structuredClone(definition), id };
@@ -25,6 +26,19 @@ async function updateTool(toolbox, toolId, patch) {
         actions: patch.actions === undefined ? definition.actions : patch.actions,
     });
 }
+/** Link one user tool to its app; `null` unlinks. The record is unchanged when the link already holds. */
+async function linkTool(toolbox, toolId, appId) {
+    const value = id(toolId, 'tool id');
+    if (toolbox.isSystemTool(value))
+        throw new Error(`System record is immutable: ${value}`);
+    const current = toolbox.get(value);
+    if (!current)
+        throw new Error(`Unknown tool: ${value}`);
+    const trimmed = appId?.trim() || null;
+    if ((current.tool.appId ?? null) === trimmed)
+        return current.tool;
+    return (await toolbox.update(value, { appId: trimmed ?? undefined })).tool;
+}
 async function upsertAction(toolbox, toolId, definition) {
     const current = toolbox.get(toolId);
     if (!current)
@@ -65,4 +79,4 @@ async function removeAction(toolbox, actionId) {
     });
     return action;
 }
-export { removeAction, updateAction, updateTool, upsertAction };
+export { linkTool, removeAction, updateAction, updateTool, upsertAction };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.7-preview.34436591947",
+  "version": "0.1.7-preview.34547098528",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -87,11 +87,11 @@
       "package.json"
     ]
   },
-  "gitHead": "9a662da6b5fe55eceffd52aac34cdf954e015b07",
+  "gitHead": "16bda6108cbbd03c67fa4d6892a7b24b58e343e3",
   "amalgmSource": {
     "repository": "amalgm-inc/amalgm-tools",
     "branch": "preview",
-    "commit": "9a662da6b5fe55eceffd52aac34cdf954e015b07",
-    "occurrence": "34436591947"
+    "commit": "16bda6108cbbd03c67fa4d6892a7b24b58e343e3",
+    "occurrence": "34547098528"
   }
 }

package/skills/tools/SKILL.md

@@ -144,10 +144,16 @@ amalgm-tools show hello.say
 amalgm-tools enable hello.say
 amalgm-tools disable hello.say
 amalgm-tools remove hello
+amalgm-tools link canvas app-3f1c
+amalgm-tools unlink canvas
 amalgm-tools run hello.say --input '{"name":"Ada"}'
 amalgm-tools connections
 ```
 
+`link` records the app a tool belongs to (`appId`, the reverse edge of the app
+manifest's `toolIds`); sharing the app carries the tool and sharing the tool
+carries the app. The MCP twins are `toolbox_tool_link` and `toolbox_tool_unlink`.
+
 Use `--state-dir DIR` to select a Toolbox and `--loadout one,two` to bound
 `list`, `run`, or connection projection.