@amalgm/tools 0.1.5 → 0.1.6

package/dist/toolbox-projection.js

@@ -0,0 +1,41 @@
+/** Current-catalog compatibility projections; deployments remain authority. */
+class ToolboxProjection {
+    artifacts;
+    catalog;
+    onChange;
+    constructor(artifacts, catalog, onChange) {
+        this.artifacts = artifacts;
+        this.catalog = catalog;
+        this.onChange = onChange;
+    }
+    boot() {
+        this.artifacts.migrateLegacy();
+        this.artifacts.materialize(this.catalog());
+    }
+    async changed(toolId) {
+        const catalog = this.catalog();
+        const tool = catalog.tools.find((candidate) => candidate.id === toolId);
+        if (tool && tool.origin !== 'system') {
+            this.artifacts.writeTool({
+                tool,
+                actions: catalog.actions.filter((action) => action.toolId === toolId),
+            });
+        }
+        else if (!tool) {
+            this.artifacts.removeTool(toolId);
+        }
+        this.artifacts.writeIndex(catalog);
+        await this.onChange?.(catalog);
+    }
+    async replaced(previousToolIds) {
+        const catalog = this.catalog();
+        const currentToolIds = new Set(catalog.tools.map((tool) => tool.id));
+        for (const toolId of previousToolIds) {
+            if (!currentToolIds.has(toolId))
+                this.artifacts.removeTool(toolId);
+        }
+        this.artifacts.materialize(catalog);
+        await this.onChange?.(catalog);
+    }
+}
+export { ToolboxProjection };

package/dist/toolbox-view.d.ts

@@ -0,0 +1,35 @@
+import type { ActionRecord, ApplyResult, CallOptions, Catalog, LoadoutInput, ToolDriver, ToolQuery, ToolRecord, ToolResult } from './types.js';
+declare class ToolboxView {
+    private readonly readCatalog;
+    private readonly drivers;
+    constructor(readCatalog: () => Catalog, drivers: ReadonlyMap<string, ToolDriver>);
+    catalog(): Catalog;
+    list(loadout?: LoadoutInput): Array<{
+        tool: ToolRecord;
+        actions: ActionRecord[];
+    }>;
+    query(filters?: ToolQuery): {
+        tool: ToolRecord;
+        actions: ActionRecord[];
+    }[];
+    callable(loadout?: LoadoutInput, filters?: ToolQuery): {
+        tool: ToolRecord;
+        action: ActionRecord;
+    }[];
+    get(toolId: string): ApplyResult | null;
+    action(actionId: string): ActionRecord | null;
+    resolve(toolId: string, actionReference: string, loadout?: LoadoutInput): {
+        tool: ToolRecord;
+        action: ActionRecord;
+    } | null;
+    resolveCallable(toolId: string, actionReference: string, loadout?: LoadoutInput, filters?: ToolQuery): {
+        tool: ToolRecord;
+        action: ActionRecord;
+    } | null;
+    connections(loadout?: LoadoutInput): ToolRecord[];
+    call(actionId: string, input?: unknown, options?: CallOptions): Promise<ToolResult>;
+    hasDriver(tool: ToolRecord): boolean;
+    callMcp(name: string, input?: unknown, options?: CallOptions): Promise<ToolResult>;
+    private driverFor;
+}
+export { ToolboxView };

package/dist/toolbox-view.js

@@ -0,0 +1,75 @@
+import { id, mcpName } from './ids.js';
+import { validateInput } from './input.js';
+import { callableActions, queryTools, resolveAction, resolveCallableAction } from './query.js';
+import { findSelected, selected } from './selection.js';
+class ToolboxView {
+    readCatalog;
+    drivers;
+    constructor(readCatalog, drivers) {
+        this.readCatalog = readCatalog;
+        this.drivers = drivers;
+    }
+    catalog() { return this.readCatalog(); }
+    list(loadout) {
+        const catalog = this.catalog();
+        const runnable = selected(catalog, loadout);
+        return catalog.tools.flatMap((tool) => {
+            const actions = runnable.filter((item) => item.tool.id === tool.id).map((item) => item.action);
+            if (loadout !== undefined && actions.length === 0)
+                return [];
+            return [{ tool, actions }];
+        });
+    }
+    query(filters = {}) { return queryTools(this, filters); }
+    callable(loadout, filters = {}) {
+        return callableActions(this, loadout, filters);
+    }
+    get(toolId) {
+        const value = id(toolId, 'tool id');
+        const catalog = this.catalog();
+        const tool = catalog.tools.find((candidate) => candidate.id === value);
+        return tool ? { tool, actions: catalog.actions.filter((action) => action.toolId === value) } : null;
+    }
+    action(actionId) {
+        const value = id(actionId, 'action id');
+        return this.catalog().actions.find((action) => action.id === value) || null;
+    }
+    resolve(toolId, actionReference, loadout) {
+        return resolveAction(this, toolId, actionReference, loadout);
+    }
+    resolveCallable(toolId, actionReference, loadout, filters = {}) {
+        return resolveCallableAction(this, toolId, actionReference, loadout, filters);
+    }
+    connections(loadout) {
+        const catalog = this.catalog();
+        const ids = loadout === undefined ? null : new Set(Array.isArray(loadout) ? loadout : loadout.toolIds);
+        return catalog.tools.filter((tool) => {
+            if (tool.status !== 'enabled' || tool.source.type !== 'mcp' || tool.origin === 'system')
+                return false;
+            if (!ids)
+                return true;
+            return ids.has(tool.id) || catalog.actions.some((action) => action.toolId === tool.id && ids.has(action.id));
+        });
+    }
+    async call(actionId, input = {}, options = {}) {
+        const resolved = findSelected(this.catalog(), id(actionId, 'action id'), options.loadout);
+        if (!resolved)
+            throw new Error(`Action is unavailable: ${actionId}`);
+        const driver = this.driverFor(resolved.tool);
+        if (!driver)
+            throw new Error(`No ${resolved.tool.source.type} driver is configured for ${resolved.tool.id}`);
+        return driver.call({ ...resolved, input: validateInput(resolved.action.inputSchema, input), options });
+    }
+    hasDriver(tool) { return this.driverFor(tool) !== null; }
+    async callMcp(name, input = {}, options = {}) {
+        const resolved = selected(this.catalog(), options.loadout).find(({ action }) => mcpName(action) === name);
+        if (!resolved)
+            throw new Error(`Unknown MCP tool: ${name}`);
+        return this.call(resolved.action.id, input, options);
+    }
+    driverFor(tool) {
+        const driver = this.drivers.get(tool.source.type);
+        return driver && (driver.supports?.(tool) ?? true) ? driver : null;
+    }
+}
+export { ToolboxView };

package/dist/toolbox.d.ts

@@ -1,10 +1,11 @@
-import type { ActionDefinition, ActionPatch, ActionRecord, ApplyResult, CallOptions, Catalog, LoadoutInput, ToolDefinition, ToolboxOptions, ToolPatch, ToolQuery, ToolRecord, ToolResult } from './types.js';
+import type { ActionDefinition, ActionPatch, ActionRecord, ApplyResult, CallOptions, Catalog, LoadoutInput, ToolDefinition, ToolboxOptions, ToolDeployment, ToolDeploymentActivation, ToolDeploymentSnapshot, ToolDeploymentSurface, ToolPatch, ToolQuery, ToolRecord, ToolResult } from './types.js';
 declare class Toolbox {
     private readonly store;
-    private readonly artifacts;
+    private readonly deploymentService;
+    private readonly projection;
     private readonly system;
     private readonly drivers;
-    private readonly onChange?;
+    private readonly view;
     constructor(options?: ToolboxOptions);
     catalog(): Catalog;
     list(loadout?: LoadoutInput): Array<{
@@ -35,12 +36,19 @@ declare class Toolbox {
     updateAction(actionId: string, patch: ActionPatch): Promise<ActionRecord>;
     setStatus(recordId: string, status: 'enabled' | 'disabled'): Promise<ToolRecord | ActionRecord>;
     remove(recordId: string): Promise<ToolRecord | ActionRecord>;
+    currentDeployment(toolId: string): ToolDeployment | null;
+    deployment(deploymentId: string): ToolDeployment | null;
+    deploymentHistory(toolId: string): ToolDeployment[];
+    deploymentSnapshot(): ToolDeploymentSnapshot;
+    /** Apply an officially ordered remote activation without emitting it again. */
+    activateDeployment(activation: ToolDeploymentActivation): Promise<ApplyResult | null>;
+    /** Replace local materialization during Live hydration or gap recovery. */
+    applyDeploymentSnapshot(snapshot: ToolDeploymentSnapshot): Promise<void>;
+    deploymentSurface(): ToolDeploymentSurface;
     connections(loadout?: LoadoutInput): ToolRecord[];
     call(actionId: string, input?: unknown, options?: CallOptions): Promise<ToolResult>;
     hasDriver(tool: ToolRecord): boolean;
     callMcp(name: string, input?: unknown, options?: CallOptions): Promise<ToolResult>;
-    private changed;
-    private driverFor;
     close(): void;
 }
 export { Toolbox };

package/dist/toolbox.js

@@ -2,19 +2,19 @@ import os from 'node:os';
 import path from 'node:path';
 import { resolveProductStateDir } from '@amalgm/core/identity';
 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 { DeploymentFiles } from './deployment-files.js';
+import { deploymentRevisionId } from './deployments.js';
 import { normalizeDefinition } from './definition.js';
-import { assertMcpNamesUnique, id, mcpName } from './ids.js';
-import { validateInput } from './input.js';
-import { callableActions, queryTools, resolveAction, resolveCallableAction } from './query.js';
-import { findSelected, selected } from './selection.js';
+import { assertMcpNamesUnique, id } from './ids.js';
 import { Store } from './store.js';
-import { updateAction, updateTool, upsertAction } from './updates.js';
-function semantic(value) {
-    const { createdAt, updatedAt, ...record } = value;
-    return JSON.stringify(record);
-}
+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';
 function defaultDatabase(options) {
     if (options.databaseFile)
         return path.resolve(options.databaseFile);
@@ -32,15 +32,17 @@ function defaultDatabase(options) {
 }
 class Toolbox {
     store;
-    artifacts;
+    deploymentService;
+    projection;
     system;
     drivers = new Map();
-    onChange;
+    view;
     constructor(options = {}) {
         const databaseFile = defaultDatabase(options);
         this.store = new Store(databaseFile);
-        this.artifacts = new ArtifactFiles(path.dirname(databaseFile));
-        this.onChange = options.onChange;
+        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 || [])])
             this.drivers.set(driver.type, driver);
         const tools = [];
@@ -49,13 +51,31 @@ class Toolbox {
             const normalized = normalizeDefinition({ ...definition, origin: 'system' });
             if (tools.some((tool) => tool.id === normalized.tool.id))
                 throw new Error(`Duplicate system tool: ${normalized.tool.id}`);
-            tools.push(normalized.tool);
-            actions.push(...normalized.actions);
+            tools.push(preserveProjectionTime(normalized.tool, priorIndex?.tools[normalized.tool.id]));
+            actions.push(...normalized.actions.map((action) => preserveProjectionTime(action, priorIndex?.toolActions[action.id])));
         }
         assertMcpNamesUnique(actions);
-        this.system = { version: 1, revision: 0, tools, actions };
-        this.artifacts.migrateLegacy();
-        this.artifacts.materialize(this.catalog());
+        this.system = {
+            version: 1,
+            revision: 0,
+            revisionId: deploymentRevisionId({ heads: {}, systemTools: tools, systemActions: actions }),
+            deployments: {},
+            tools,
+            actions,
+        };
+        this.projection = new ToolboxProjection(artifacts, () => this.catalog(), options.onChange);
+        this.deploymentService = new ToolboxDeployments({
+            store: this.store,
+            files: deploymentFiles,
+            systemTools: this.system.tools,
+            systemActions: this.system.actions,
+            project: (toolId) => this.projection.changed(toolId),
+            replaceProjection: (previousToolIds) => this.projection.replaced(previousToolIds),
+            ...(options.onDeployment ? { onDeployment: options.onDeployment } : {}),
+        });
+        this.deploymentService.adoptLegacy();
+        this.view = new ToolboxView(() => this.catalog(), this.drivers);
+        this.projection.boot();
     }
     catalog() {
         const persisted = this.store.catalog();
@@ -64,66 +84,37 @@ class Toolbox {
         const userActions = persisted.actions.filter((action) => !systemIds.has(action.toolId));
         const catalog = {
             version: 1, revision: persisted.revision,
+            revisionId: deploymentRevisionId({
+                heads: persisted.deployments,
+                systemTools: this.system.tools,
+                systemActions: this.system.actions,
+            }),
+            deployments: persisted.deployments,
             tools: [...this.system.tools, ...userTools].sort((a, b) => a.id.localeCompare(b.id)),
             actions: [...this.system.actions, ...userActions].sort((a, b) => a.id.localeCompare(b.id)),
         };
         assertMcpNamesUnique(catalog.actions);
         return catalog;
     }
-    list(loadout) {
-        const catalog = this.catalog();
-        const runnable = selected(catalog, loadout);
-        return catalog.tools.flatMap((tool) => {
-            const actions = runnable.filter((item) => item.tool.id === tool.id).map((item) => item.action);
-            if (loadout !== undefined && actions.length === 0)
-                return [];
-            return [{ tool, actions }];
-        });
-    }
-    query(filters = {}) { return queryTools(this, filters); }
-    callable(loadout, filters = {}) { return callableActions(this, loadout, filters); }
-    get(toolId) {
-        const value = id(toolId, 'tool id');
-        const catalog = this.catalog();
-        const tool = catalog.tools.find((candidate) => candidate.id === value);
-        return tool ? { tool, actions: catalog.actions.filter((action) => action.toolId === value) } : null;
-    }
-    action(actionId) {
-        const value = id(actionId, 'action id');
-        return this.catalog().actions.find((action) => action.id === value) || null;
-    }
+    list(loadout) { return this.view.list(loadout); }
+    query(filters = {}) { return this.view.query(filters); }
+    callable(loadout, filters = {}) { return this.view.callable(loadout, filters); }
+    get(toolId) { return this.view.get(toolId); }
+    action(actionId) { return this.view.action(actionId); }
     resolve(toolId, actionReference, loadout) {
-        return resolveAction(this, toolId, actionReference, loadout);
+        return this.view.resolve(toolId, actionReference, loadout);
     }
     resolveCallable(toolId, actionReference, loadout, filters = {}) {
-        return resolveCallableAction(this, toolId, actionReference, loadout, filters);
+        return this.view.resolveCallable(toolId, actionReference, loadout, filters);
     }
     async apply(definition) {
-        const normalizedId = id(definition.id, 'tool.id', 64);
-        if (definition.origin === 'system')
-            throw new Error('System tools can only be supplied by the embedder');
-        if (this.system.tools.some((tool) => tool.id === normalizedId))
-            throw new Error(`System tool is immutable: ${normalizedId}`);
-        const existing = this.store.getTool(normalizedId);
-        const oldActions = new Map(this.store.actionsFor(normalizedId).map((action) => [action.id, action]));
-        const normalized = normalizeDefinition(definition, existing || undefined);
-        normalized.actions = normalized.actions.map((action) => ({
-            ...action, createdAt: oldActions.get(action.id)?.createdAt || action.createdAt,
-        }));
-        const candidateActions = [
-            ...this.system.actions,
-            ...this.store.catalog().actions.filter((action) => action.toolId !== normalized.tool.id),
-            ...normalized.actions,
-        ];
-        assertMcpNamesUnique(candidateActions);
-        const unchanged = existing && semantic(existing) === semantic(normalized.tool)
-            && normalized.actions.length === oldActions.size
-            && normalized.actions.every((action) => semantic(action) === semantic(oldActions.get(action.id)));
-        if (unchanged)
-            return { tool: existing, actions: [...oldActions.values()].sort((a, b) => a.id.localeCompare(b.id)) };
-        const result = this.store.apply(normalized);
-        await this.changed(normalized.tool.id);
-        return result;
+        return applyDefinition({
+            definition,
+            store: this.store,
+            deployments: this.deploymentService,
+            systemTools: this.system.tools,
+            systemActions: this.system.actions,
+        });
     }
     async update(toolId, patch) {
         return updateTool(this, toolId, patch);
@@ -139,65 +130,50 @@ class Toolbox {
         if (this.system.tools.some((tool) => tool.id === value)
             || this.system.actions.some((action) => action.id === value))
             throw new Error(`System record is immutable: ${value}`);
-        const updated = this.store.setStatus(value, status, new Date().toISOString());
-        if (!updated)
+        const tool = this.get(value);
+        if (tool)
+            return tool.tool.status === status ? tool.tool : (await this.update(value, { status })).tool;
+        const action = this.action(value);
+        if (!action)
             throw new Error(`Unknown tool or action: ${value}`);
-        await this.changed('toolId' in updated ? updated.toolId : updated.id);
-        return updated;
+        return action.status === status ? action : this.updateAction(value, { status });
     }
     async remove(recordId) {
         const value = id(recordId, 'record id');
         if (this.system.tools.some((tool) => tool.id === value)
             || this.system.actions.some((action) => action.id === value))
             throw new Error(`System record is immutable: ${value}`);
-        const removed = this.store.remove(value);
-        if (!removed)
-            throw new Error(`Unknown tool or action: ${value}`);
-        await this.changed('toolId' in removed ? removed.toolId : removed.id);
-        return removed;
+        const tool = this.get(value);
+        if (tool) {
+            await this.deploymentService.activateLocal(null, value);
+            return tool.tool;
+        }
+        return removeAction(this, value);
+    }
+    currentDeployment(toolId) { return this.deploymentService.current(toolId); }
+    deployment(deploymentId) { return this.deploymentService.get(deploymentId); }
+    deploymentHistory(toolId) { return this.deploymentService.history(toolId); }
+    deploymentSnapshot() { return this.deploymentService.snapshot(); }
+    /** Apply an officially ordered remote activation without emitting it again. */
+    async activateDeployment(activation) {
+        return this.deploymentService.activateRemote(activation);
+    }
+    /** Replace local materialization during Live hydration or gap recovery. */
+    async applyDeploymentSnapshot(snapshot) {
+        return this.deploymentService.applySnapshot(snapshot);
+    }
+    deploymentSurface() {
+        return this.deploymentService.surface();
     }
     connections(loadout) {
-        const catalog = this.catalog();
-        const ids = loadout === undefined ? null : new Set(Array.isArray(loadout) ? loadout : loadout.toolIds);
-        return catalog.tools.filter((tool) => {
-            if (tool.status !== 'enabled' || tool.source.type !== 'mcp' || tool.origin === 'system')
-                return false;
-            if (!ids)
-                return true;
-            return ids.has(tool.id) || catalog.actions.some((action) => action.toolId === tool.id && ids.has(action.id));
-        });
+        return this.view.connections(loadout);
     }
     async call(actionId, input = {}, options = {}) {
-        const resolved = findSelected(this.catalog(), id(actionId, 'action id'), options.loadout);
-        if (!resolved)
-            throw new Error(`Action is unavailable: ${actionId}`);
-        const driver = this.driverFor(resolved.tool);
-        if (!driver)
-            throw new Error(`No ${resolved.tool.source.type} driver is configured for ${resolved.tool.id}`);
-        return driver.call({ ...resolved, input: validateInput(resolved.action.inputSchema, input), options });
-    }
-    hasDriver(tool) { return this.driverFor(tool) !== null; }
-    async callMcp(name, input = {}, options = {}) {
-        const resolved = selected(this.catalog(), options.loadout).find(({ action }) => mcpName(action) === name);
-        if (!resolved)
-            throw new Error(`Unknown MCP tool: ${name}`);
-        return this.call(resolved.action.id, input, options);
-    }
-    async changed(toolId) {
-        const catalog = this.catalog();
-        const tool = catalog.tools.find((candidate) => candidate.id === toolId);
-        if (tool && tool.origin !== 'system') {
-            this.artifacts.writeTool({ tool, actions: catalog.actions.filter((action) => action.toolId === toolId) });
-        }
-        else if (!tool) {
-            this.artifacts.removeTool(toolId);
-        }
-        this.artifacts.writeIndex(catalog);
-        await this.onChange?.(catalog);
+        return this.view.call(actionId, input, options);
     }
-    driverFor(tool) {
-        const driver = this.drivers.get(tool.source.type);
-        return driver && (driver.supports?.(tool) ?? true) ? driver : null;
+    hasDriver(tool) { return this.view.hasDriver(tool); }
+    async callMcp(name, input = {}, options = {}) {
+        return this.view.callMcp(name, input, options);
     }
     close() { this.store.close(); }
 }

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+import type { ToolDeploymentActivation } from './deployment-types.js';
 type JsonSchema = {
     type: 'object';
     properties?: Record<string, {
@@ -41,6 +42,8 @@ interface McpSource extends BaseSource {
     args?: string[];
     cwd?: string;
     serverName?: string;
+    /** Absolute path mounted by the composing host for `transport: host`. */
+    route?: string;
     secretHeaders?: SecretReferences;
     secretEnv?: SecretReferences;
 }
@@ -109,7 +112,12 @@ interface ActionRecord extends Omit<ActionDefinition, 'id' | 'status' | 'inputSc
 }
 interface Catalog {
     version: 1;
+    /** Local materialization counter. Never used as immutable authority. */
     revision: number;
+    /** Exact digest of current user deployments and system projections. */
+    revisionId: string;
+    /** Current deployment id per stable user tool, including tombstones. */
+    deployments: Record<string, string>;
     tools: ToolRecord[];
     actions: ActionRecord[];
 }
@@ -151,9 +159,13 @@ interface ToolDriver {
 interface ToolboxOptions {
     stateDir?: string;
     databaseFile?: string;
+    /** Portable immutable deployment documents; may differ from databaseFile. */
+    deploymentDir?: string;
     systemTools?: ToolDefinition[];
     drivers?: ToolDriver[];
     onChange?: (catalog: Catalog) => void | Promise<void>;
+    /** Outbound local Live operation. Remote application never calls it. */
+    onDeployment?: (activation: ToolDeploymentActivation) => void | Promise<void>;
 }
 interface McpTool {
     name: string;
@@ -164,9 +176,26 @@ 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, 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, HostMcpToolDefinitionInput, HostMcpToolDescriptor, 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';

package/dist/updates.d.ts

@@ -4,4 +4,5 @@ type UpdatePort = Pick<Toolbox, 'action' | 'apply' | 'get'>;
 declare function updateTool(toolbox: UpdatePort, toolId: string, patch: ToolPatch): Promise<ApplyResult>;
 declare function upsertAction(toolbox: UpdatePort, toolId: string, definition: ActionDefinition): Promise<ActionRecord>;
 declare function updateAction(toolbox: UpdatePort, actionId: string, patch: ActionPatch): Promise<ActionRecord>;
-export { updateAction, updateTool, upsertAction };
+declare function removeAction(toolbox: UpdatePort, actionId: string): Promise<ActionRecord>;
+export { removeAction, updateAction, updateTool, upsertAction };

package/dist/updates.js

@@ -54,4 +54,15 @@ async function updateAction(toolbox, actionId, patch) {
         metadata: mergedObject(definition.metadata, patch.metadata),
     });
 }
-export { updateAction, updateTool, upsertAction };
+async function removeAction(toolbox, actionId) {
+    const action = toolbox.action(actionId);
+    if (!action)
+        throw new Error(`Unknown action: ${actionId}`);
+    const current = toolbox.get(action.toolId);
+    await toolbox.apply({
+        ...toolDefinition(current),
+        actions: current.actions.filter((candidate) => candidate.id !== actionId).map(actionDefinition),
+    });
+    return action;
+}
+export { removeAction, updateAction, updateTool, upsertAction };

package/docs/ENGINE_INTEGRATION.md

@@ -1,57 +1,13 @@
-# Engine integration
+# Historical Engine integration
 
-`@amalgm/tools` is the canonical Tools and Toolbox product. Amalgm Engine is a
-composition root and must adapt this public service rather than maintain a
-second registry.
+Amalgm Engine is deprecated. Its Toolbox tables, MCP-connection registry,
+notification adapter, and copied product output are read-only migration and
+parity evidence. They are not active persistence, a source-flow destination,
+or a runtime fallback.
 
-## Tools owns
+The old workflow copied generated Tools output into Engine and imported legacy
+records. Active composition now installs the published package in
+`@amalgm/shell`, which supplies host effects and projects other products
+through their official MCP descriptors.
 
-- tool and action definition, validation, identity, and persistence;
-- atomic apply, enable, disable, and removal behavior;
-- loadout selection semantics and deterministic MCP action names;
-- CLI and HTTP API execution drivers and output bounds;
-- SDK, CLI, Toolbox management MCP tools, and action MCP projection;
-- the connection projection consumed by an MCP session host.
-
-## Engine owns
-
-- first-party action implementations supplied as `systemTools` and drivers;
-- authenticated capability context and the execution-time secret resolver;
-- the long-lived MCP connection/session host;
-- state-event projection, REST shape translation, UI composition, and one-time
-  import from Engine's superseded Toolbox tables or JSON file.
-
-Agents owns agent records and their loadout ids. Tools treats those ids as
-input to product-owned selection. Neither product is allowed to rewrite the
-other through a Core adapter.
-
-Engine adapters call one `Toolbox` instance. They do not write its SQLite
-database or independently normalize, select, name, or execute tool actions.
-An absent loadout must be passed as `undefined`; an explicitly empty loadout
-must be passed as `[]`.
-
-For external MCP tools, Engine supplies a `ToolDriver` with type `mcp`. That
-driver delegates to Engine's existing MCP session owner. The Toolbox exposes
-connection definitions through `connections(loadout)` but never starts a
-parallel client or owns the same remote session twice.
-
-System tools are injected at construction and remain outside user storage.
-Engine can therefore update its built-in catalog with its own release while
-all standalone Toolbox behavior remains canonical in this package.
-
-## Source flow and completed cutover
-
-Engine now consumes Tools as follows:
-
-1. Build this repository.
-2. Copy generated `dist/`, `PURPOSE.md`, and package metadata into
-   `runtime/products/tools/` with a deterministic source manifest.
-3. Mount the package CLI and MCP definitions over Engine's single Toolbox
-   service.
-4. Import existing records once, preserving canonical ids and status.
-5. Remove Engine's superseded Toolbox tables after successful import.
-
-Product changes begin here. Generated Engine copies are never edited by hand.
-Engine runtime readers and writers use only this product database. The importer
-is the only module allowed to understand the superseded storage shapes, and
-malformed source data blocks destructive cleanup.
+See [SHELL_INTEGRATION.md](./SHELL_INTEGRATION.md) for the current boundary.