@amalgm/tools 0.1.7-preview.37556891038 → 0.1.7-preview.39065361112

package/PURPOSE.md

@@ -7,7 +7,7 @@ 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, GraphQL, 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
+only its granted capabilities, and the SDK, MCP, and HTTP surfaces all observe
 and execute the same catalog.
 
 Amalgm Shell is the active machine composition root. This repository owns the
@@ -22,8 +22,8 @@ and parity evidence only.
 - A **tool** is a stable provider or connector identity and its execution
   source.
 - An **action** is one model-callable capability owned by exactly one tool.
-- A **Toolbox** is the sole catalog and mutation authority for one local state
-  directory.
+- A **Toolbox** is the sole catalog and mutation authority for the folders its
+  host hands it.
 - A **tool deployment** is one immutable definition of a stable tool identity,
   including its complete authoritative action set; activation appends the
   deployment and moves that tool's current pointer atomically.
@@ -75,13 +75,13 @@ locked dependency graph on the supported Node toolchain.
 2. Tool ids are stable, globally unique within one Toolbox, and never change
    as a side effect of renaming display text.
 3. A tool's portable source of truth is its immutable deployment history and
-   current deployment pointer. SQLite tables, WAL files, catalog indexes, and
-   compatibility artifacts are local projections; SDK, CLI, MCP, HTTP, and UI
+   current deployment pointer. SQLite tables, WAL files, the catalog index, and
+   each tool's `.amalgm-tool.json` are projections; SDK, CLI, MCP, HTTP, and UI
    adapters never keep parallel registries.
 4. Applying a semantically changed tool definition mints one deployment and
    atomically activates its complete action set. Applying equal semantics is a
-   no-op; rollback and deletion mint new deployments rather than rewriting or
-   removing history.
+   no-op; rollback and deletion mint new deployments rather than rewriting
+   history.
 5. Deleting a tool deletes all of its actions in the same transaction; an
    orphan action can never be observed.
 6. Disabled tools expose and execute no actions. Disabled actions are likewise
@@ -122,17 +122,19 @@ locked dependency graph on the supported Node toolchain.
     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.
+    unchanged system projection already present in its index; boot never
+    rewrites those bytes merely to stamp the current time.
 22. The Toolbox exposes the versioned `deployment.activate` operation and its
     exact definition through one Live surface; SQLite pages are never part of
     that contract. A received activation materializes locally without echo,
     retries are idempotent, and an existing deployment id can never acquire
     different bytes.
-23. A host may separate the synced deployment directory from its machine-local
-    database. Amalgm Shell stores immutable deployment documents beneath
-    `users/<email>/toolbox/<tool-id>/deployments/` while keeping SQLite
-    coordination state below the machine boundary.
+23. The host hands the Toolbox three folders and Tools never picks one. `root`
+    holds one `<Tool Name>/` folder per user tool with `.amalgm-tool.json`,
+    immutable `history/<deployment-id>.json` records, and a computer-only
+    `.private/`; `dir` holds `tools.db` and `index.json`; `parked` receives a
+    deleted tool's `.private/`. A tool's folder follows its name, and deleting
+    the tool removes the files Tools wrote there.
 24. A Chat preparation selects one catalog `revisionId` derived from exact
     current deployment ids and system projections. Preparation either resolves
     that exact revision or fails; it never silently substitutes newer tools.
@@ -174,8 +176,7 @@ locked dependency graph on the supported Node toolchain.
 
 Applying the same definition twice produces the same catalog and no second
 deployment. Reopening the
-same system projection produces the same portable index bytes on every
-machine. Applying a changed action set replaces the old set atomically.
+same system projection leaves the index bytes unchanged. Applying a changed action set replaces the old set atomically.
 Selecting a whole tool
 grants all of its enabled actions; selecting one action grants only that
 action. Disabling or deleting a tool immediately removes all of its actions

package/README.md

@@ -8,7 +8,7 @@ into the machine product by `@amalgm/shell`.
 ```js
 import { defineTool, Toolbox } from '@amalgm/tools';
 
-const toolbox = new Toolbox({ stateDir: './.tools' });
+const toolbox = new Toolbox({ root: './toolbox', dir: './.tools', parked: './.tools/parked' });
 await toolbox.apply(defineTool({
   id: 'hello',
   name: 'Hello',
@@ -29,54 +29,53 @@ const result = await toolbox.call('hello.say', { name: 'Ada' });
 toolbox.close();
 ```
 
-## State directory
+## Folders
 
-Given no options, the Toolbox resolves its state directory through the
-one product state-dir law in `@amalgm/core`: `AMALGM_TOOLS_DIR` is used
-verbatim when set, then `AMALGM_DIR/toolbox`, then the scoped layout
-`~/.amalgm/users/<scope>/toolbox`. Passing `stateDir` or `databaseFile`
-bypasses resolution entirely.
-
-Platform hosts should separate portable deployment documents from local
-coordination state:
+The Toolbox never picks a folder; its host hands it three. In Amalgm, Shell
+passes the user's folders from `@amalgm/core/identity`:
 
 ```js
+const user = userLayout(userRoot);
 const toolbox = new Toolbox({
-  deploymentDir: '/amalgm/users/person@example.com/toolbox',
-  databaseFile: '/machine-state/services/tools/tools.db',
+  root: user.toolbox,
+  dir: user.computer.tools,
+  parked: user.computer.parked,
 });
 ```
 
-An intentional semantic change appends
-`<deploymentDir>/<tool-id>/deployments/<deployment-id>.json` and atomically
-advances the local head. The database, WAL, `toolbox.index.json`, and legacy
-flat artifacts are projections and must not be synchronized. `catalog()`
-exposes both a local numeric `revision` for presentation freshness and the
-immutable `revisionId` that Chat must use for preparation.
+```
+<root>/<Tool Name>/.amalgm-tool.json   the tool and every action it owns
+<root>/<Tool Name>/history/<id>.json   one immutable record per deployment
+<root>/<Tool Name>/.private/           computer-only files for the tool
+<dir>/tools.db                         the catalog of record
+<dir>/index.json                       the whole catalog, system tools included
+```
+
+A tool's folder is named for the tool and follows a rename; a second tool
+with the same name gets `-2`. An intentional semantic change appends
+`history/<deployment-id>.json` and atomically advances the local head.
+Deleting a tool moves its `.private/` to `<parked>/tool/<id>/` and removes the
+files Tools wrote. `tools.db`, its WAL and `index.json` stay on the computer.
+`catalog()` exposes both a local numeric `revision` for presentation freshness
+and the immutable `revisionId` that Chat must use for preparation.
 
 `deploymentSurface()` implements the `amalgm.tools.deployments@1` Live
 surface. Its operation is the shared `deployment.activate` envelope. Remote
 application is idempotent and does not echo; `deploymentSnapshot()` and
 `applyDeploymentSnapshot()` are the hydration/recovery boundary.
 
-## CLI
-
-```sh
-amalgm-tools apply ./tool.mjs
-amalgm-tools list
-amalgm-tools run hello.say --input '{"name":"Ada"}'
-amalgm-tools disable hello.say
-amalgm-tools link canvas app-3f1c
-amalgm-tools connections
-```
+## App links
 
 A tool may belong to an app: `appId` on the tool is the reverse edge of the
 app manifest's `toolIds`, and sharing either side carries the other. The host
 that composes Tools and Apps may pass `environment(tool)` so a linked tool
 runs knowing where its app listens.
 
-`amalgm-tools-mcp` serves Toolbox management and enabled action tools over
-newline-delimited MCP stdio.
+## MCP
+
+`createMcpServer({ toolbox })` from `@amalgm/tools` answers MCP JSON-RPC
+over the one Toolbox the host already holds. The Amalgm runtime serves it at
+`/mcp/tools`, and the `amalgm tools …` command calls it there.
 
 ## HTTP
 
@@ -84,14 +83,14 @@ newline-delimited MCP stdio.
 import { Toolbox } from '@amalgm/tools';
 import { createToolboxHttpServer } from '@amalgm/tools/http';
 
-const toolbox = new Toolbox({ stateDir: './.tools' });
+const toolbox = new Toolbox({ root: './toolbox', dir: './.tools', parked: './.tools/parked' });
 const server = createToolboxHttpServer({ toolbox });
 await server.listen(8083);
 ```
 
 The adapter serves `GET /toolbox`,
 `GET /toolbox/tools?id=...`, and `GET /toolbox/actions?id=...` routes over
-the same live Toolbox used by CLI and MCP consumers. `POST /toolbox/tools`
+the same live Toolbox used by MCP consumers. `POST /toolbox/tools`
 connects a definition with optional write-only credentials. `PATCH /toolbox/tools`
 with `{ id, status: "disabled" }` disconnects it. `DELETE /toolbox/tools` removes
 it. `POST /toolbox/actions/call` invokes `{ id, input }`.
@@ -150,7 +149,7 @@ once, and installs that tarball on Linux, macOS and Windows before publication.
 `preview` has no checks: a push to it builds, packs and publishes directly.
 The `candidate-main`/`candidate-preview` tags are release-assembly inputs and
 never select installed runtimes. `package.json` declares this owner's gates,
-CLI probes, peer-only exports and lifecycle permissions. The standalone runner
+peer-only exports and lifecycle permissions. The standalone runner
 under `scripts/release/` is intentionally copied across owners to preserve
 private repository access boundaries. The final publish step uses the `NPM_TOKEN`
 secret in the `npm-release` environment. Where npm trusted publishing is

package/dist/artifacts.d.ts

@@ -2,14 +2,13 @@ import type { ActionRecord, Catalog, ToolRecord } from './types.js';
 /**
  * Tool artifact format laws — the portable representation of a tool.
  *
- * One compatibility artifact projects one current tool and every action it
- * owns together; a file never carries a second tool. Immutable deployment
- * documents are the portable source of truth. These artifacts, the Toolbox
- * database, and `toolbox.index.json` are derived views retained for current
- * Engine/UI readers.
+ * One artifact (a tool folder's `.amalgm-tool.json`) holds one current tool
+ * and every action it owns together; a file never carries a second tool.
+ * Immutable deployment documents are the portable source of truth. These
+ * artifacts and the index are derived views of the Toolbox database.
  *
- * Pure laws only: nothing here touches the filesystem. `artifact-files.ts`
- * is the host adapter that executes these documents and plans.
+ * Pure laws only: nothing here touches the filesystem. `tool-files.ts`
+ * writes these documents.
  *
  * DELIBERATE DEVIATION: Engine recognizes system tools by its managed
  * artifact list; this product's system tools are embedder projections
@@ -20,9 +19,7 @@ import type { ActionRecord, Catalog, ToolRecord } from './types.js';
  */
 declare const TOOL_ARTIFACT_SCHEMA_VERSION = 1;
 declare const TOOL_ARTIFACT_KIND = "amalgm-tool";
-declare const LEGACY_TOOLBOX_FILE_NAME = "toolbox.json";
-declare const LEGACY_TOOLBOX_BACKUP_FILE_NAME = "toolbox.legacy.json";
-declare const TOOLBOX_INDEX_FILE_NAME = "toolbox.index.json";
+declare const TOOLBOX_INDEX_FILE_NAME = "index.json";
 type ArtifactRecord = Record<string, unknown>;
 interface ToolArtifactDocument {
     schemaVersion: typeof TOOL_ARTIFACT_SCHEMA_VERSION;
@@ -35,21 +32,7 @@ interface ToolboxIndexDocument {
     tools: Record<string, unknown>;
     toolActions: Record<string, unknown>;
 }
-interface ArtifactFileWrite {
-    fileName: string;
-    document: ToolArtifactDocument;
-}
-interface LegacyMigrationPlan {
-    migrated: boolean;
-    files: ArtifactFileWrite[];
-    index: ToolboxIndexDocument | null;
-    rename: {
-        from: string;
-        to: string;
-    } | null;
-}
 declare function safeToolId(value: unknown): string;
-declare function userArtifactFileName(toolId: unknown): string;
 declare function artifactDocument(input: {
     tool: ToolRecord;
     actions?: readonly ActionRecord[];
@@ -59,10 +42,5 @@ declare function toolboxIndexDocument(tools: Record<string, unknown>, toolAction
 declare function catalogIndexDocument(catalog: Pick<Catalog, 'tools' | 'actions'>): ToolboxIndexDocument;
 declare function portableRecordSemantic(value: ToolRecord | ActionRecord): string;
 declare function preserveProjectionTime<T extends ToolRecord | ActionRecord>(candidate: T, previous: unknown): T;
-/** The migration of one legacy aggregate `toolbox.json` catalog, as a pure
- * plan: every user tool becomes a per-tool artifact write, the whole legacy
- * catalog becomes the index, and the aggregate file is renamed out of the
- * way only after each record has a per-tool replacement. */
-declare function legacyMigrationPlan(legacy: unknown): LegacyMigrationPlan;
-export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, portableRecordSemantic, preserveProjectionTime, toolboxIndexDocument, userArtifactFileName, };
-export type { ArtifactFileWrite, LegacyMigrationPlan, ToolArtifactDocument, ToolboxIndexDocument };
+export { TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, safeToolId, portableRecordSemantic, preserveProjectionTime, toolboxIndexDocument, };
+export type { ToolArtifactDocument, ToolboxIndexDocument };

package/dist/artifacts.js

@@ -1,14 +1,13 @@
 /**
  * Tool artifact format laws — the portable representation of a tool.
  *
- * One compatibility artifact projects one current tool and every action it
- * owns together; a file never carries a second tool. Immutable deployment
- * documents are the portable source of truth. These artifacts, the Toolbox
- * database, and `toolbox.index.json` are derived views retained for current
- * Engine/UI readers.
+ * One artifact (a tool folder's `.amalgm-tool.json`) holds one current tool
+ * and every action it owns together; a file never carries a second tool.
+ * Immutable deployment documents are the portable source of truth. These
+ * artifacts and the index are derived views of the Toolbox database.
  *
- * Pure laws only: nothing here touches the filesystem. `artifact-files.ts`
- * is the host adapter that executes these documents and plans.
+ * Pure laws only: nothing here touches the filesystem. `tool-files.ts`
+ * writes these documents.
  *
  * DELIBERATE DEVIATION: Engine recognizes system tools by its managed
  * artifact list; this product's system tools are embedder projections
@@ -19,9 +18,7 @@
  */
 const TOOL_ARTIFACT_SCHEMA_VERSION = 1;
 const TOOL_ARTIFACT_KIND = 'amalgm-tool';
-const LEGACY_TOOLBOX_FILE_NAME = 'toolbox.json';
-const LEGACY_TOOLBOX_BACKUP_FILE_NAME = 'toolbox.legacy.json';
-const TOOLBOX_INDEX_FILE_NAME = 'toolbox.index.json';
+const TOOLBOX_INDEX_FILE_NAME = 'index.json';
 function safeToolId(value) {
     return String(value || '')
         .trim()
@@ -30,12 +27,6 @@ function safeToolId(value) {
         .replace(/\.+/g, '.')
         .replace(/^[._-]+|[._-]+$/g, '');
 }
-function userArtifactFileName(toolId) {
-    const id = safeToolId(toolId);
-    if (!id)
-        throw new Error('tool artifact requires a stable tool id');
-    return `tool-${id}.json`;
-}
 function artifactDocument(input) {
     const { tool, actions = [] } = input;
     if (!tool || typeof tool !== 'object' || !safeToolId(tool.id)) {
@@ -94,32 +85,4 @@ function preserveProjectionTime(candidate, previous) {
         return candidate;
     return { ...candidate, createdAt: record.createdAt, updatedAt: record.updatedAt };
 }
-/** The migration of one legacy aggregate `toolbox.json` catalog, as a pure
- * plan: every user tool becomes a per-tool artifact write, the whole legacy
- * catalog becomes the index, and the aggregate file is renamed out of the
- * way only after each record has a per-tool replacement. */
-function legacyMigrationPlan(legacy) {
-    const parsed = legacy;
-    if (!parsed || typeof parsed !== 'object' || !parsed.tools || typeof parsed.tools !== 'object') {
-        return { migrated: false, files: [], index: null, rename: null };
-    }
-    const files = [];
-    for (const [rawId, rawTool] of Object.entries(parsed.tools)) {
-        const toolId = safeToolId(rawTool?.id || rawId);
-        if (!toolId || !rawTool || typeof rawTool !== 'object' || rawTool.origin === 'system')
-            continue;
-        const actions = Object.values(parsed.toolActions || {})
-            .filter((action) => action && action.toolId === toolId);
-        files.push({
-            fileName: userArtifactFileName(toolId),
-            document: artifactDocument({ tool: { ...rawTool, id: toolId }, actions }),
-        });
-    }
-    return {
-        migrated: true,
-        files,
-        index: toolboxIndexDocument(parsed.tools || {}, parsed.toolActions || {}),
-        rename: { from: LEGACY_TOOLBOX_FILE_NAME, to: LEGACY_TOOLBOX_BACKUP_FILE_NAME },
-    };
-}
-export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, portableRecordSemantic, preserveProjectionTime, toolboxIndexDocument, userArtifactFileName, };
+export { TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, safeToolId, portableRecordSemantic, preserveProjectionTime, toolboxIndexDocument, };

package/dist/http.d.ts

@@ -1,5 +1,5 @@
-import { Toolbox } from './toolbox.js';
-import type { Catalog, ToolboxOptions } from './types.js';
+import type { Toolbox } from './toolbox.js';
+import type { Catalog } from './types.js';
 /**
  * Toolbox read API.
  *
@@ -13,7 +13,7 @@ import type { Catalog, ToolboxOptions } from './types.js';
  * - domain errors are JSON with status 400; unknown routes are 404.
  *
  * Mutation routes consume current SDK definitions. The authenticated composing
- * host supplies the Toolbox owner; request bodies cannot select one.
+ * host supplies the one Toolbox it holds; request bodies cannot select one.
  */
 type Json = Record<string, unknown>;
 interface ToolboxHttpServer {
@@ -23,8 +23,8 @@ interface ToolboxHttpServer {
     close(): Promise<void>;
 }
 declare function catalogDocument(catalog: Catalog): Json;
-declare function createToolboxHttpServer(options?: ToolboxOptions & {
-    toolbox?: Toolbox;
+declare function createToolboxHttpServer({ toolbox }: {
+    toolbox: Toolbox;
 }): ToolboxHttpServer;
 export { catalogDocument, createToolboxHttpServer };
 export type { ToolboxHttpServer };

package/dist/http.js

@@ -1,6 +1,5 @@
 import { createServer } from 'node:http';
 import { toolboxIndexDocument } from './artifacts.js';
-import { Toolbox } from './toolbox.js';
 import { mutateToolbox } from './http-mutations.js';
 function sourceWithoutType(source) {
     const { type: _type, ...value } = source;
@@ -37,9 +36,7 @@ async function readBody(req) {
         return {};
     return JSON.parse(Buffer.concat(chunks).toString('utf8'));
 }
-function createToolboxHttpServer(options = {}) {
-    const toolbox = options.toolbox ?? new Toolbox(options);
-    const ownsToolbox = options.toolbox === undefined;
+function createToolboxHttpServer({ toolbox }) {
     const server = createServer((req, res) => {
         void (async () => {
             const method = req.method ?? 'GET';
@@ -112,8 +109,6 @@ function createToolboxHttpServer(options = {}) {
         close() {
             return new Promise((resolve, reject) => {
                 server.close((error) => {
-                    if (ownsToolbox)
-                        toolbox.close();
                     if (error)
                         reject(error);
                     else

package/dist/index.d.ts

@@ -1,9 +1,5 @@
-export { ArtifactFiles } from './artifact-files.js';
-export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, } from './artifacts.js';
-export type { ArtifactFileWrite, LegacyMigrationPlan, ToolArtifactDocument, ToolboxIndexDocument, } from './artifacts.js';
-export { runCli } from './cli.js';
-export { createToolboxCommands } from './commands.js';
-export type { ToolCommands } from './commands.js';
+export { TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, safeToolId, toolboxIndexDocument, } from './artifacts.js';
+export type { ToolArtifactDocument, ToolboxIndexDocument } from './artifacts.js';
 export { defineTool, normalizeDefinition } from './definition.js';
 export { defineHostMcpTool } from './host-mcp-tool.js';
 export { TOOL_DEPLOYMENT_CONTRACT, TOOL_DEPLOYMENT_KIND, TOOL_DEPLOYMENT_SCHEMA_VERSION, assertToolDeploymentActivation, createToolDeployment, deploymentRevisionId, emptyToolDeploymentSnapshot, } from './deployments.js';

package/dist/index.js

@@ -1,7 +1,4 @@
-export { ArtifactFiles } from './artifact-files.js';
-export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, } from './artifacts.js';
-export { runCli } from './cli.js';
-export { createToolboxCommands } from './commands.js';
+export { TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, safeToolId, toolboxIndexDocument, } from './artifacts.js';
 export { defineTool, normalizeDefinition } from './definition.js';
 export { defineHostMcpTool } from './host-mcp-tool.js';
 export { TOOL_DEPLOYMENT_CONTRACT, TOOL_DEPLOYMENT_KIND, TOOL_DEPLOYMENT_SCHEMA_VERSION, assertToolDeploymentActivation, createToolDeployment, deploymentRevisionId, emptyToolDeploymentSnapshot, } from './deployments.js';

package/dist/mcp-server.d.ts

@@ -1,20 +1,18 @@
-import readline from 'node:readline';
-import type { Readable, Writable } from 'node:stream';
-import { Toolbox } from './toolbox.js';
+import type { Toolbox } from './toolbox.js';
 import type { ToolboxView } from './toolbox-view.js';
-import type { McpOptions, ToolboxOptions } from './types.js';
+import type { McpOptions } from './types.js';
 interface Request {
     jsonrpc?: string;
     id?: string | number;
     method: string;
     params?: Record<string, any>;
 }
-declare function createMcpServer<T extends Toolbox | ToolboxView = Toolbox>(options?: ToolboxOptions & {
-    toolbox?: T;
+/** MCP JSON-RPC over the one Toolbox (or prepared view) the host already holds. */
+declare function createMcpServer<T extends Toolbox | ToolboxView>(options: {
+    toolbox: T;
     mcp?: McpOptions;
 }): {
     toolbox: T;
     handle: (request: Request, context?: unknown) => Promise<unknown>;
-    start: (input?: Readable, output?: Writable) => readline.Interface;
 };
 export { createMcpServer };

package/dist/mcp-server.js

@@ -1,12 +1,11 @@
-import readline from 'node:readline';
 import { callMcpTool, createMcpTools } from './mcp.js';
-import { Toolbox } from './toolbox.js';
 function descriptor(tool) {
     const { handler, ...definition } = tool;
     return definition;
 }
-function createMcpServer(options = {}) {
-    const toolbox = options.toolbox || new Toolbox(options);
+/** MCP JSON-RPC over the one Toolbox (or prepared view) the host already holds. */
+function createMcpServer(options) {
+    const { toolbox } = options;
     const mcpOptions = options.mcp || {};
     /** Context is supplied by the trusted transport host, never parsed from MCP input. */
     async function handle(request, context) {
@@ -37,27 +36,6 @@ function createMcpServer(options = {}) {
             return undefined;
         throw Object.assign(new Error(`Method not found: ${request.method}`), { code: -32601 });
     }
-    function start(input = process.stdin, output = process.stdout) {
-        const lines = readline.createInterface({ input, crlfDelay: Infinity });
-        lines.on('line', async (line) => {
-            let request;
-            try {
-                request = JSON.parse(line);
-                const result = await handle(request);
-                if (request.id !== undefined && result !== undefined)
-                    output.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`);
-            }
-            catch (error) {
-                if (request?.id === undefined)
-                    return;
-                output.write(`${JSON.stringify({
-                    jsonrpc: '2.0', id: request.id,
-                    error: { code: error?.code || -32603, message: error instanceof Error ? error.message : String(error) },
-                })}\n`);
-            }
-        });
-        return lines;
-    }
-    return { toolbox, handle, start };
+    return { toolbox, handle };
 }
 export { createMcpServer };

package/dist/results.d.ts

@@ -1,9 +1,6 @@
 import type { ToolResult } from './types.js';
 declare function textResult(value: unknown): ToolResult;
 declare function structuredResult(value: unknown): ToolResult;
-/** The inverse of `structuredResult`'s envelope: a value that is not a plain
- * object is carried as `{ result: value }`, and this returns it unchanged. */
-declare function structuredValue(structuredContent: ToolResult['structuredContent']): unknown;
 declare function errorResult(value: unknown): ToolResult;
 declare function boundedResult(result: ToolResult, maximum: number): ToolResult;
-export { boundedResult, errorResult, structuredResult, structuredValue, textResult };
+export { boundedResult, errorResult, structuredResult, textResult };

package/dist/results.js

@@ -7,14 +7,6 @@ function structuredResult(value) {
         ? value : { result: value ?? null };
     return { ...textResult(value), structuredContent };
 }
-/** The inverse of `structuredResult`'s envelope: a value that is not a plain
- * object is carried as `{ result: value }`, and this returns it unchanged. */
-function structuredValue(structuredContent) {
-    return structuredContent
-        && Object.keys(structuredContent).length === 1
-        && 'result' in structuredContent
-        ? structuredContent.result : structuredContent;
-}
 function errorResult(value) {
     return { ...textResult(value instanceof Error ? value.message : value), isError: true };
 }
@@ -29,4 +21,4 @@ function boundedResult(result, maximum) {
         ...(result.isError ? { isError: true } : {}), truncated: true,
     };
 }
-export { boundedResult, errorResult, structuredResult, structuredValue, textResult };
+export { boundedResult, errorResult, structuredResult, textResult };

package/dist/store.d.ts

@@ -6,7 +6,6 @@ declare class Store {
     revision(): number;
     private bump;
     getTool(id: string): ToolRecord | null;
-    getAction(id: string): ActionRecord | null;
     actionsFor(toolId: string): ActionRecord[];
     heads(): Record<string, string>;
     catalog(): Catalog;
@@ -15,8 +14,6 @@ declare class Store {
     deploymentsFor(toolId: string): ToolDeployment[];
     allDeployments(): ToolDeployment[];
     deploymentSnapshot(): ToolDeploymentSnapshot;
-    /** Add a baseline for a pre-deployment database without changing its catalog bytes. */
-    adoptDeployment(activation: ToolDeploymentActivation): void;
     applyDeployment(activation: ToolDeploymentActivation): {
         changed: boolean;
         result: ApplyResult | null;

package/dist/store.js

@@ -26,9 +26,6 @@ class Store {
     getTool(id) {
         return parse(this.db.prepare('SELECT record_json FROM tools WHERE id = ?').get(id));
     }
-    getAction(id) {
-        return parse(this.db.prepare('SELECT record_json FROM actions WHERE id = ?').get(id));
-    }
     actionsFor(toolId) {
         return this.db.prepare('SELECT record_json FROM actions WHERE tool_id = ? ORDER BY id')
             .all(toolId).map((row) => parse(row)).filter(Boolean);
@@ -77,16 +74,6 @@ class Store {
             heads: this.heads(),
         };
     }
-    /** Add a baseline for a pre-deployment database without changing its catalog bytes. */
-    adoptDeployment(activation) {
-        const deployment = activation.deployment;
-        this.db.transaction(() => {
-            if (this.getDeployment(deployment.id))
-                return;
-            this.insertDeployment(deployment);
-            this.setHead(deployment.subjectId, deployment.id);
-        })();
-    }
     applyDeployment(activation) {
         const deployment = activation.deployment;
         return this.db.transaction(() => {

package/dist/tool-files.d.ts

@@ -0,0 +1,40 @@
+import type { ToolboxIndexDocument } from './artifacts.js';
+import type { ActionRecord, Catalog, ToolDeployment, ToolRecord } from './types.js';
+/**
+ * The Toolbox's files, written from `tools.db` (the catalog of record) and
+ * never read back as catalog:
+ *
+ *   <root>/<Tool Name>/.amalgm-tool.json   the tool and every action it owns
+ *   <root>/<Tool Name>/history/<id>.json   each of its deployments, immutable
+ *   <root>/<Tool Name>/.private/           computer-only; parked when it is deleted
+ *   <dir>/index.json                       the whole catalog, system tools included
+ *
+ * A tool's folder is found by the id in its identity file and follows the
+ * tool's name. Writes go through a temporary file and are skipped when the
+ * bytes are unchanged.
+ */
+declare class ToolFiles {
+    private readonly folders;
+    constructor(folders: {
+        root: string;
+        dir: string;
+        parked: string;
+    });
+    writeTool(entry: {
+        tool: ToolRecord;
+        actions: ActionRecord[];
+    }, history: readonly ToolDeployment[]): void;
+    /** Park the tool's `.private/`, then remove the files Tools wrote. The
+     * folder goes too unless the user keeps files of their own in it. */
+    removeTool(toolId: string): void;
+    writeIndex(catalog: Catalog): void;
+    readIndex(): ToolboxIndexDocument | null;
+    private indexFile;
+    /** The tool's folder, created or renamed to follow its name. */
+    private place;
+    private entries;
+    private folderOf;
+    /** Tool ids can be used again, so a second parking of one id gets "-2", "-3", …. */
+    private parkTarget;
+}
+export { ToolFiles };