@amalgm/tools 0.1.5 → 0.1.6

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.6",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -36,7 +36,8 @@
     "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",

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.