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

package/PURPOSE.md

@@ -133,6 +133,10 @@ locked dependency graph on the supported Node toolchain.
     when a first-party release currently maps them one-to-one.
 26. A scoped Toolbox MCP server advertises and calls only the selected loadout;
     management actions are included only when the composing host asks for them.
+27. Preparing an exact catalog revision captures a read-only loadout whose
+    definitions and scope cannot change. Later catalog edits affect future
+    preparation; already prepared calls use their captured definitions and the
+    host's current credential and execution effects.
 
 ## Predictable behavior
 

package/dist/index.d.ts

@@ -14,4 +14,5 @@ export type { EmailDelivery, EmailDeliveryReceipt, EmailNotificationRequest, Not
 export { createProxyEmailDelivery } from './proxy-email.js';
 export type { ProxyEmailDeliveryOptions } from './proxy-email.js';
 export { Toolbox } from './toolbox.js';
+export type { ToolboxView as PreparedToolbox } from './toolbox-view.js';
 export type * from './types.js';

package/dist/mcp-server.d.ts

@@ -1,6 +1,7 @@
 import readline from 'node:readline';
 import type { Readable, Writable } from 'node:stream';
 import { Toolbox } from './toolbox.js';
+import type { ToolboxView } from './toolbox-view.js';
 import type { McpOptions, ToolboxOptions } from './types.js';
 interface Request {
     jsonrpc?: string;
@@ -8,11 +9,11 @@ interface Request {
     method: string;
     params?: Record<string, any>;
 }
-declare function createMcpServer(options?: ToolboxOptions & {
-    toolbox?: Toolbox;
+declare function createMcpServer<T extends Toolbox | ToolboxView = Toolbox>(options?: ToolboxOptions & {
+    toolbox?: T;
     mcp?: McpOptions;
 }): {
-    toolbox: Toolbox;
+    toolbox: T;
     handle: (request: Request) => Promise<unknown>;
     start: (input?: Readable, output?: Writable) => readline.Interface;
 };

package/dist/mcp.d.ts

@@ -1,10 +1,11 @@
 import type { Toolbox } from './toolbox.js';
+import type { ToolboxView } from './toolbox-view.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 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;
-declare function callMcpTool(toolbox: Toolbox, name: string, input?: Record<string, unknown>, options?: McpOptions): Promise<import("./types.js").ToolResult>;
+declare function actionTools(toolbox: Toolbox | ToolboxView, options?: McpOptions): McpTool[];
+declare function createMcpTools(toolbox: Toolbox | ToolboxView, options?: McpOptions): McpTool[];
+declare function findMcpTool(toolbox: Toolbox | ToolboxView, name: string, options?: McpOptions): McpTool | null;
+declare function callMcpTool(toolbox: Toolbox | ToolboxView, name: string, input?: Record<string, unknown>, options?: McpOptions): Promise<import("./types.js").ToolResult>;
 export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, managementToolDescriptors, portable, };

package/dist/mcp.js

@@ -90,6 +90,9 @@ function actionTools(toolbox, options = {}) {
     }));
 }
 function createMcpTools(toolbox, options = {}) {
+    if (options.includeManagement !== false && !('apply' in toolbox)) {
+        throw new Error('A prepared Toolbox does not expose management actions');
+    }
     return [
         ...(options.includeManagement === false ? [] : managementTools(toolbox)),
         ...actionTools(toolbox, options),

package/dist/prepared-catalog.d.ts

@@ -0,0 +1,3 @@
+import type { Catalog, LoadoutInput } from './types.js';
+/** Capture exact definitions; a caller cannot expand a prepared loadout later. */
+export declare function preparedCatalog(catalog: Catalog, revisionId: string, loadout: LoadoutInput): Catalog;

package/dist/prepared-catalog.js

@@ -0,0 +1,25 @@
+import { selected } from './selection.js';
+/** Capture exact definitions; a caller cannot expand a prepared loadout later. */
+export function preparedCatalog(catalog, revisionId, loadout) {
+    if (catalog.revisionId !== revisionId) {
+        throw new Error(`Toolbox deployment revision changed: expected ${revisionId}, current ${catalog.revisionId}`);
+    }
+    const ids = new Set(Array.isArray(loadout) ? loadout : loadout.toolIds);
+    for (const id of ids) {
+        const action = catalog.actions.find((item) => item.id === id);
+        const tool = catalog.tools.find((item) => item.id === (action?.toolId || id));
+        if (!tool)
+            throw new Error(`Selected tool is not installed: ${id}`);
+        if (tool.status !== 'enabled')
+            throw new Error(`Selected tool is disabled: ${id}`);
+        if (action && action.status !== 'enabled')
+            throw new Error(`Selected tool action is disabled: ${id}`);
+    }
+    const actions = selected(catalog, loadout).map(({ action }) => action);
+    const owners = new Set(actions.map((action) => action.toolId));
+    return structuredClone({
+        ...catalog,
+        tools: catalog.tools.filter((tool) => ids.has(tool.id) || owners.has(tool.id)),
+        actions,
+    });
+}

package/dist/toolbox-state-dir.d.ts

@@ -0,0 +1,2 @@
+import type { ToolboxOptions } from './types.js';
+export declare function defaultDatabase(options: ToolboxOptions): string;

package/dist/toolbox-state-dir.js

@@ -0,0 +1,18 @@
+import os from 'node:os';
+import path from 'node:path';
+import { resolveProductStateDir } from '@amalgm/core/identity';
+export function defaultDatabase(options) {
+    if (options.databaseFile)
+        return path.resolve(options.databaseFile);
+    // The state-dir LAW lives in @amalgm/core; only the effectful reads
+    // (process.env, os.homedir) happen here at the construction boundary.
+    // Precedence: AMALGM_TOOLS_DIR, then AMALGM_DIR/toolbox, then the
+    // scoped layout <home>/.amalgm/users/<scope>/toolbox.
+    const state = options.stateDir || resolveProductStateDir({
+        product: 'tools',
+        primitive: 'toolbox',
+        env: process.env,
+        homedir: path.join(os.homedir(), '.amalgm'),
+    });
+    return path.join(path.resolve(state), 'tools.db');
+}

package/dist/toolbox.d.ts

@@ -1,3 +1,4 @@
+import { ToolboxView } from './toolbox-view.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;
@@ -12,6 +13,8 @@ declare class Toolbox {
         tool: ToolRecord;
         actions: ActionRecord[];
     }>;
+    /** Pin one exact deployment revision and loadout for an execution. */
+    prepare(revisionId: string, loadout: LoadoutInput): ToolboxView;
     query(filters?: ToolQuery): {
         tool: ToolRecord;
         actions: ActionRecord[];

package/dist/toolbox.js

@@ -1,6 +1,5 @@
-import os from 'node:os';
 import path from 'node:path';
-import { resolveProductStateDir } from '@amalgm/core/identity';
+import { defaultDatabase } from './toolbox-state-dir.js';
 import { apiDriver } from './api-driver.js';
 import { applyDefinition } from './apply-definition.js';
 import { ArtifactFiles } from './artifact-files.js';
@@ -9,27 +8,13 @@ import { cliDriver } from './cli-driver.js';
 import { DeploymentFiles } from './deployment-files.js';
 import { deploymentRevisionId } from './deployments.js';
 import { normalizeDefinition } from './definition.js';
+import { preparedCatalog } from './prepared-catalog.js';
 import { assertMcpNamesUnique, id } from './ids.js';
 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';
-function defaultDatabase(options) {
-    if (options.databaseFile)
-        return path.resolve(options.databaseFile);
-    // The state-dir LAW lives in @amalgm/core; only the effectful reads
-    // (process.env, os.homedir) happen here at the construction boundary.
-    // Precedence: AMALGM_TOOLS_DIR, then AMALGM_DIR/toolbox, then the
-    // scoped layout <home>/.amalgm/users/<scope>/toolbox.
-    const state = options.stateDir || resolveProductStateDir({
-        product: 'tools',
-        primitive: 'toolbox',
-        env: process.env,
-        homedir: path.join(os.homedir(), '.amalgm'),
-    });
-    return path.join(path.resolve(state), 'tools.db');
-}
 class Toolbox {
     store;
     deploymentService;
@@ -97,6 +82,11 @@ class Toolbox {
         return catalog;
     }
     list(loadout) { return this.view.list(loadout); }
+    /** Pin one exact deployment revision and loadout for an execution. */
+    prepare(revisionId, loadout) {
+        const catalog = preparedCatalog(this.catalog(), revisionId, loadout);
+        return new ToolboxView(() => structuredClone(catalog), new Map(this.drivers));
+    }
     query(filters = {}) { return this.view.query(filters); }
     callable(loadout, filters = {}) { return this.view.callable(loadout, filters); }
     get(toolId) { return this.view.get(toolId); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.7-main.34436367218",
+  "version": "0.1.7-main.34746904064",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -87,11 +87,11 @@
       "package.json"
     ]
   },
-  "gitHead": "6cb5d2097ad78d31dedf44872f9b843a8007d225",
+  "gitHead": "717394b057c4db6911f9e99e2ebfc8f3d438891a",
   "amalgmSource": {
     "repository": "amalgm-inc/amalgm-tools",
     "branch": "main",
-    "commit": "6cb5d2097ad78d31dedf44872f9b843a8007d225",
-    "occurrence": "34436367218"
+    "commit": "717394b057c4db6911f9e99e2ebfc8f3d438891a",
+    "occurrence": "34746904064"
   }
 }