@amalgm/tools 0.1.7-preview.34176071261 → 0.1.7-preview.34545371724

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[];

package/dist/cli.js

@@ -10,6 +10,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`;
@@ -101,6 +103,12 @@ async function runCli(argv, io = {}) {
             case 'remove':
                 write(stdout, await toolbox.remove(required(recordId, 'record id')));
                 break;
+            case 'link':
+                write(stdout, await toolbox.link(required(recordId, 'tool id'), required(parsed.args[1], 'app id')));
+                break;
+            case 'unlink':
+                write(stdout, await toolbox.link(required(recordId, 'tool id'), null));
+                break;
             case 'run':
                 write(stdout, await toolbox.call(required(recordId, 'action id'), parsed.input, { loadout: parsed.loadout }));
                 break;

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/mcp.js

@@ -51,6 +51,17 @@ 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 },
@@ -58,7 +69,7 @@ function managementToolDescriptors() {
     ];
 }
 function managementTools(toolbox) {
-    const [list, get, apply, enable, disable, remove, connections] = managementToolDescriptors();
+    const [list, get, apply, enable, disable, remove, link, unlink, connections] = managementToolDescriptors();
     return [
         managed(list, () => toolbox.catalog()),
         managed(get, ({ id }) => {
@@ -71,6 +82,8 @@ function managementTools(toolbox) {
         managed(enable, ({ id }) => toolbox.setStatus(String(id), 'enabled')),
         managed(disable, ({ id }) => toolbox.setStatus(String(id), 'disabled')),
         managed(remove, ({ id }) => toolbox.remove(String(id))),
+        managed(link, ({ id, app_id }) => toolbox.link(String(id), String(app_id))),
+        managed(unlink, ({ id }) => toolbox.link(String(id), null)),
         managed(connections, () => toolbox.connections()),
     ];
 }

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;
 }
-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.34176071261",
+  "version": "0.1.7-preview.34545371724",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -56,7 +56,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@amalgm/core": "0.4.8-preview.34168975242",
+    "@amalgm/core": "0.5.1-preview.34403852460",
     "better-sqlite3": "^12.6.2"
   },
   "devDependencies": {
@@ -87,11 +87,11 @@
       "package.json"
     ]
   },
-  "gitHead": "ba5c024d8a0975ce99ac75ab5af0a201d296ee72",
+  "gitHead": "53f469e2ce16c667c6883239cc3f98c0af6943fc",
   "amalgmSource": {
     "repository": "amalgm-inc/amalgm-tools",
     "branch": "preview",
-    "commit": "ba5c024d8a0975ce99ac75ab5af0a201d296ee72",
-    "occurrence": "34176071261"
+    "commit": "53f469e2ce16c667c6883239cc3f98c0af6943fc",
+    "occurrence": "34545371724"
   }
 }

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.