@amalgm/tools 0.1.3 → 0.1.4

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,16 +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 { portableRecordSemantic, preserveProjectionTime } from './artifacts.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';
+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);
@@ -29,16 +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));
-        const priorIndex = this.artifacts.readIndex();
-        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 = [];
@@ -51,9 +55,27 @@ class Toolbox {
             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();
@@ -62,67 +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 && portableRecordSemantic(existing) === portableRecordSemantic(normalized.tool)
-            && normalized.actions.length === oldActions.size
-            && normalized.actions.every((action) => portableRecordSemantic(action)
-                === portableRecordSemantic(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);
@@ -138,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

@@ -8,6 +8,7 @@ second registry.
 
 - tool and action definition, validation, identity, and persistence;
 - atomic apply, enable, disable, and removal behavior;
+- immutable deployment history, current heads, and the Tools Live surface;
 - 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;
@@ -18,7 +19,8 @@ second registry.
 - 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
+- the machine-local SQLite path, portable deployment directory, Live binding,
+  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
@@ -26,7 +28,8 @@ 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.
+database, synchronize database pages, or independently normalize, select,
+name, deploy, or execute tool actions.
 An absent loadout must be passed as `undefined`; an explicitly empty loadout
 must be passed as `[]`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,