@amalgm/tools 0.1.5 → 0.1.7-main.34175698435

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.

package/docs/SHELL_INTEGRATION.md

@@ -0,0 +1,44 @@
+# Shell integration
+
+`@amalgm/tools` is the canonical Toolbox product. `@amalgm/shell` constructs
+one Toolbox for a machine user, supplies its machine-local SQLite path and
+portable deployment directory, and mounts the product's public HTTP and MCP
+adapters.
+
+## Tools owns
+
+- stable tool and action identity;
+- immutable deployment history and current deployment heads;
+- loadout selection and deterministic MCP names;
+- CLI and API drivers, validation, cancellation, and output bounds;
+- the Toolbox management MCP surface; and
+- the versioned `deployment.activate` Live surface.
+
+## Shell owns
+
+- the exact `@amalgm/tools` package version in the Shell release;
+- the one host MCP driver and authenticated loopback routes;
+- machine-local SQLite placement and the portable deployment directory;
+- execution-time credential resolution;
+- projection of owning products' official MCP descriptors as immutable system
+  tools; and
+- binding Tools' deployment surface to broader product state when enabled.
+
+Agents stores loadout identifiers; Chat pins the exact Toolbox `revisionId`
+during preparation. Neither product writes Tools persistence.
+
+## First-party products and Channels
+
+Shell builds first-party records from the official MCP descriptors exported by
+Agents, Apps, Automations, Browser, Channels, Chat, and Tools. Selecting a
+record controls capability; it does not transfer ownership of the underlying
+product to Tools.
+
+Channels owns current notification validation and durable delivery. The
+`Notifications` class still exported by Tools is a legacy compatibility
+adapter and is not the path Shell uses for the Channels product.
+
+## Engine evidence
+
+Engine may be read to compare legacy Toolbox, MCP-connection, `/email`, or
+notification shapes. It is never composed or copied into the active runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.5",
+  "version": "0.1.7-main.34175698435",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -36,20 +36,27 @@
     "docs",
     "dist",
     "PURPOSE.md",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
     "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
     "verify": "npm run check && npm run build && npm test",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "release:admit": "node scripts/release/package.mjs admit",
+    "release:prepare": "node scripts/release/package.mjs prepare",
+    "release:examine": "node scripts/release/package.mjs examine",
+    "release:publish": "node scripts/release/package.mjs publish",
+    "release:compose": "node scripts/release/compose.mjs",
+    "test:release": "node --test scripts/release/*.test.mjs"
   },
   "engines": {
     "node": ">=24"
   },
   "dependencies": {
-    "@amalgm/core": "0.4.7",
+    "@amalgm/core": "0.4.8-main.34168902443",
     "better-sqlite3": "^12.6.2"
   },
   "devDependencies": {
@@ -57,5 +64,34 @@
     "@types/node": "^20.19.43",
     "tsx": "^4.23.1",
     "typescript": "^5.9.3"
+  },
+  "amalgmRelease": {
+    "schema": 1,
+    "workflow": "verify.yml",
+    "jobs": [
+      "verify"
+    ],
+    "verify": "verify",
+    "cli": [
+      "amalgm-tools"
+    ]
+  },
+  "allowScripts": {
+    "better-sqlite3@12.11.1": true,
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": false
+  },
+  "amalgmComposition": {
+    "schema": 1,
+    "manifests": [
+      "package.json"
+    ]
+  },
+  "gitHead": "ab131c0ae46724efb84318568125193a8432d233",
+  "amalgmSource": {
+    "repository": "amalgm-inc/amalgm-tools",
+    "branch": "main",
+    "commit": "ab131c0ae46724efb84318568125193a8432d233",
+    "occurrence": "34175698435"
   }
 }

package/skills/tools/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: tools
+description: Define, deploy, select, and execute stable Amalgm tools through @amalgm/tools. Use when creating CLI, API, or MCP tool definitions; managing immutable tool deployments and loadouts; projecting tools into MCP; resolving secrets at call time; or inspecting the local Toolbox catalog.
+---
+
+# Amalgm Tools
+
+Tools is the capability layer between an agent and the things it can do. It
+gives every tool and action a stable identity, stores user-authored tools as
+immutable deployments, selects bounded loadouts for a run, and executes CLI,
+HTTP API, or MCP actions through one result contract. It works as a standalone
+ESM package and is also composed into the Amalgm machine runtime.
+
+## Installation
+
+```bash
+npm install @amalgm/tools
+```
+
+Node.js 20 or newer is required. The package exposes:
+
+- `@amalgm/tools` for definitions, the `Toolbox`, deployments, MCP projection,
+  ids, and driver contracts.
+- `@amalgm/tools/mcp` for MCP helpers.
+- `@amalgm/tools/http` for the read-only Toolbox HTTP adapter.
+- `amalgm-tools` for local catalog management and execution.
+- `amalgm-tools-mcp` for a newline-delimited stdio MCP server.
+
+## Define and run a tool
+
+```js
+import { defineTool, Toolbox } from '@amalgm/tools';
+
+const toolbox = new Toolbox({ stateDir: './.tools' });
+
+await toolbox.apply(defineTool({
+  id: 'hello',
+  name: 'Hello',
+  source: {
+    type: 'cli',
+    command: 'node',
+    inputMode: 'json-stdin',
+    outputMode: 'json',
+  },
+  actions: [{
+    name: 'say',
+    target: { args: ['./hello.mjs'] },
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: { name: { type: 'string' } },
+      additionalProperties: false,
+    },
+  }],
+}));
+
+const result = await toolbox.call('hello.say', { name: 'Ada' });
+toolbox.close();
+```
+
+The tool id is `hello`; the derived action id is `hello.say`. Those ids are the
+references agents, loadouts, and callers keep. Display names and implementations
+can evolve without changing identity.
+
+## Tool sources
+
+Every definition has exactly one source type:
+
+- `cli` executes a command directly with `spawn`; no shell is inserted. Choose
+  JSON stdin, argv, or no input, and JSON or text output.
+- `api` calls a path beneath one declared same-origin `baseUrl`; redirects are
+  refused.
+- `mcp` projects actions from an HTTP, SSE, stdio, or host-mounted MCP server.
+  A composing host supplies the MCP driver that owns discovery, sessions, and
+  calls.
+
+Sources may set `timeoutMs` and `maxOutputBytes`. These bounds travel with the
+definition, so execution policy is visible before the call begins.
+
+## Immutable deployments and state
+
+Applying an intentional semantic change creates an immutable deployment
+document and advances the tool's local head atomically. Reapplying equivalent
+bytes resolves to the same content identity. `catalog()` exposes both:
+
+- `revision`, a local numeric freshness counter for presentation.
+- `revisionId`, the digest of the exact current user deployments and system
+  projections. Use this immutable id when preparing an agent run.
+
+By default state resolves through the shared Amalgm state-dir law:
+`AMALGM_TOOLS_DIR`, then `AMALGM_DIR/toolbox`, then the current user's scoped
+Toolbox directory. Pass `stateDir` for a self-contained Toolbox, or separate
+portable deployments from machine-local coordination state:
+
+```js
+const toolbox = new Toolbox({
+  deploymentDir: '/amalgm/users/person@example.com/toolbox',
+  databaseFile: '/machine-state/services/tools/tools.db',
+});
+```
+
+Deployment documents are portable. The SQLite database, WAL, local index, and
+legacy flat artifacts are projections and should not be synchronized.
+
+## Loadouts
+
+A loadout is a list of tool ids that bounds which enabled actions are visible
+and callable for one context:
+
+```js
+const loadout = { toolIds: ['hello', 'browser'] };
+const visible = toolbox.list(loadout);
+const result = await toolbox.call('hello.say', { name: 'Ada' }, { loadout });
+```
+
+Passing no loadout uses the enabled catalog. Passing a loadout makes exclusion
+explicit: an action outside it cannot be reached merely because it exists in
+the Toolbox.
+
+## Secrets
+
+Definitions never contain secret values. `secretEnv` and `secretHeaders` hold
+opaque references, and the caller resolves them only for the duration of an
+execution:
+
+```js
+await toolbox.call('billing.lookup', { customerId: 'cus_123' }, {
+  resolveSecret: async (reference) => secretStore.get(reference),
+});
+```
+
+This keeps portable definitions and deployment documents safe to inspect and
+synchronize.
+
+## CLI
+
+The CLI prints JSON and exits non-zero on failure:
+
+```bash
+amalgm-tools apply ./tool.mjs
+amalgm-tools list
+amalgm-tools catalog
+amalgm-tools show hello.say
+amalgm-tools enable hello.say
+amalgm-tools disable hello.say
+amalgm-tools remove hello
+amalgm-tools run hello.say --input '{"name":"Ada"}'
+amalgm-tools connections
+```
+
+Use `--state-dir DIR` to select a Toolbox and `--loadout one,two` to bound
+`list`, `run`, or connection projection.
+
+## MCP and HTTP surfaces
+
+`createMcpTools(toolbox)` projects management operations and enabled actions,
+while `createMcpServer()` creates a complete stdio server. A machine host can
+also use `defineHostMcpTool` to represent another product's official MCP
+descriptors as one system-owned Toolbox record.
+
+For read-only dashboards, mount the HTTP adapter:
+
+```js
+import { Toolbox } from '@amalgm/tools';
+import { createToolboxHttpServer } from '@amalgm/tools/http';
+
+const toolbox = new Toolbox({ stateDir: './.tools' });
+const server = createToolboxHttpServer({ toolbox });
+await server.listen(8083);
+```
+
+It serves the legacy-compatible `GET /toolbox`, `GET /toolbox/tools?id=...`,
+and `GET /toolbox/actions?id=...` catalog routes. Mutations belong through the
+SDK, CLI, or MCP surface.
+
+## How Tools fits into Amalgam
+
+The machine runtime projects the official capabilities from Agents, Apps,
+Automations, Browser, Channels, Chat, and Tools into one Toolbox without moving
+their ownership into Tools. Tools owns identity, deployment, selection, and
+execution; each product continues to own its own behavior and state.
+
+Channels is the current owner of durable notifications. The notification
+exports retained by `@amalgm/tools` are compatibility adapters for retired
+notification shapes, not a second delivery system.