@amalgm/tools 0.1.4 → 0.1.6

package/PURPOSE.md

@@ -2,19 +2,20 @@
 
 ## Purpose
 
-Amalgm Tools lets a user define, keep, select, and run agent capabilities
-without installing Amalgm Engine. It serves people building agents,
+Amalgm Tools lets a user define, keep, select, and run agent capabilities as a
+standalone product or inside Amalgm. It serves people building agents,
 automations, and applications that need one small local source of truth for
 CLI, HTTP API, and MCP tools. When the product is healthy, every callable
 action has one stable identity and one owning tool, a selected loadout exposes
 only its granted capabilities, and the SDK, CLI, and MCP surfaces all observe
 and execute the same catalog.
 
-Amalgm Engine is the composition root for the complete Amalgm runtime. This
-repository owns the Tools product and its Toolbox. Engine may provide
-first-party actions, credentials, agent loadouts, state events, and UI
-composition through public adapters, but it does not maintain a second tool
-registry or execution implementation.
+Amalgm Shell is the active machine composition root. This repository owns the
+Tools product and its Toolbox. Shell may provide first-party product
+projections, credential resolution, agent loadouts, state events, and route
+mounting through public adapters, but it does not maintain a second tool
+registry or execution implementation. Amalgm Engine is deprecated historical
+and parity evidence only.
 
 ## Primitives
 
@@ -33,11 +34,14 @@ registry or execution implementation.
   one or more tools; selecting a tool never changes that server's identity.
 - A **system tool** is an embedder-owned definition projected into the catalog;
   it is not user state.
-- A **notification** is one request to inform the current user; a channel
-  adapter turns that intent into delivery.
+- A **notification compatibility adapter** is the retained legacy projection
+  of `notifications.notify_user`; Channels owns current durable delivery.
 
 ## Axioms
 
+Managed releases bind to one exact published Core version and build from the
+locked dependency graph on the supported Node toolchain.
+
 1. Every action belongs to exactly one tool and has the canonical id
    `<tool-id>.<action-name>`.
 2. Tool ids are stable, globally unique within one Toolbox, and never change
@@ -74,19 +78,21 @@ registry or execution implementation.
 15. System tools are immutable projections supplied by the embedder. Removing
     an embedder projection removes it from the catalog without mutating user
     state.
-16. The SDK owns behavior. CLI, MCP, HTTP, UI, and Engine integrations only
-    adapt the public Toolbox service.
+16. The SDK owns behavior. CLI, MCP, HTTP, UI, Shell, and other host
+    integrations only adapt the public Toolbox service.
 17. TypeScript under `src/` is the product source of truth. JavaScript and
     declarations under `dist/` are generated together and are never edited by
     hand.
 18. Tools may store opaque references owned by another product, but neither
     Tools nor a Core adapter silently rewrites that product. A cross-product
     workflow has one explicit product owner.
-19. `notifications.notify_user` addresses only the current user. Callers may
-    supply content and severity, never a recipient or delivery credential.
-20. Notification channels are host capabilities. Tools owns validation and
-    result semantics; an injected channel adapter owns formatting, recipient
-    lookup, credentials, and delivery.
+19. The retained `notifications.notify_user` compatibility adapter addresses
+    only the current user. Callers may supply content and severity, never a
+    recipient or delivery credential.
+20. Channels owns current notification validation, persistence, formatting,
+    recipient lookup, credentials, and delivery. Tools may project Channels'
+    official MCP descriptors or expose its explicitly legacy email adapter; it
+    never becomes a second durable delivery authority.
 21. Reopening a Toolbox preserves the temporal fields of every semantically
     unchanged system projection already present in its portable index; boot
     never rewrites tracked bytes merely to stamp the current machine's time.
@@ -119,5 +125,5 @@ grants all of its enabled actions; selecting one action grants only that
 action. Disabling or deleting a tool immediately removes all of its actions
 from list and call surfaces. CLI arguments are passed directly to a process,
 API paths stay under their registered origin, and MCP calls cross only the
-driver boundary supplied by the composing host. Engine and standalone users
+driver boundary supplied by the composing host. Shell and standalone users
 therefore get the same identities, validation, selection, and execution rules.

package/README.md

@@ -1,8 +1,9 @@
 # Amalgm Tools
 
-`@amalgm/tools` is the standalone Tools product from Amalgm Engine. It owns
-tool definitions, the local Toolbox catalog, loadout selection, execution,
-and MCP projection. It can be used without the rest of Amalgm.
+`@amalgm/tools` is the standalone Tools product. It owns tool definitions, the
+local Toolbox catalog, immutable deployments, loadout selection, execution,
+and MCP projection. It can be used without the rest of Amalgm and is composed
+into the machine product by `@amalgm/shell`.
 
 ```js
 import { defineTool, Toolbox } from '@amalgm/tools';
@@ -82,18 +83,20 @@ const server = createToolboxHttpServer({ toolbox });
 await server.listen(8083);
 ```
 
-The read adapter serves the Engine-compatible `GET /toolbox`,
+The read adapter serves the legacy-compatible `GET /toolbox`,
 `GET /toolbox/tools?id=...`, and `GET /toolbox/actions?id=...` routes over
 the same live Toolbox used by CLI and MCP consumers. Mutation routes return
 405 until their legacy record fields can be represented without data loss.
 
 ## Notifications
 
-`Notifications` projects the first-party `notifications.notify_user` action
-into the Toolbox. The action validates one channel-neutral request and hands
-it to an injected email delivery adapter; recipient lookup and credentials
-never enter the tool record. `createNotificationsHttpServer` exposes
-`GET /email` as the channel capability document used by the shell.
+Channels is the current owner of durable notification delivery. Shell projects
+the official `@amalgm/channels` MCP descriptors into Toolbox as the
+`channels` first-party tool. Tools still exports `Notifications`,
+`notificationToolDefinition`, and `createNotificationsHttpServer` as a legacy
+compatibility adapter for the retired `notifications.notify_user` and
+`GET /email` shapes; that adapter is not the current platform delivery store
+and must not be presented as a second Channels implementation.
 
 ## Tool types
 
@@ -105,4 +108,5 @@ never enter the tool record. `createNotificationsHttpServer` exposes
 Secret values are never part of definitions. `secretEnv` and `secretHeaders`
 contain opaque references resolved through `CallOptions.resolveSecret`.
 See [PURPOSE.md](./PURPOSE.md) for the complete contract and
-[ENGINE_INTEGRATION.md](./docs/ENGINE_INTEGRATION.md) for composition.
+[SHELL_INTEGRATION.md](./docs/SHELL_INTEGRATION.md) for active composition.
+The [Engine integration](./docs/ENGINE_INTEGRATION.md) page is historical only.

package/docs/ENGINE_INTEGRATION.md

@@ -1,60 +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;
-- 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;
-- 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;
-- 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
-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, 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 `[]`.
-
-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.4",
+  "version": "0.1.6",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -36,20 +36,21 @@
     "docs",
     "dist",
     "PURPOSE.md",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
+    "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"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "dependencies": {
-    "@amalgm/core": "0.2.0",
+    "@amalgm/core": "0.4.7",
     "better-sqlite3": "^12.6.2"
   },
   "devDependencies": {

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.