@amalgm/tools 0.1.5 → 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
 
@@ -23,13 +24,18 @@ registry or execution implementation.
 - 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 **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.
 - A **loadout** is a set of tool or action ids used to derive a read-only view
   of the Toolbox.
 - A **driver** executes actions for one tool type.
+- An **MCP server** is a separately identified runtime endpoint that may expose
+  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
 
@@ -40,13 +46,14 @@ locked dependency graph on the supported Node toolchain.
    `<tool-id>.<action-name>`.
 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 definition is its artifact file: one file per tool,
-   the tool and all of its actions together, never a second tool in the
-   same file. The Toolbox database is a derived index maintained for
-   runtime and realtime sync; SDK, CLI, and MCP adapters never keep
-   parallel registries.
-4. Applying a tool definition is atomic and authoritative for that tool: its
-   supplied action set replaces the previous set completely.
+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
+   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.
 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
@@ -71,27 +78,52 @@ locked dependency graph on the supported Node toolchain.
 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.
+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.
+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.
+25. A host MCP source names both its server and its route. Tool identity,
+    action identity, server identity, and transport location are distinct even
+    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.
 
 ## Predictable behavior
 
-Applying the same definition twice produces the same catalog. Applying a
-changed action set replaces the old set atomically. Selecting a whole tool
+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.
+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
 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';
@@ -36,6 +37,28 @@ 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:
+
+```js
+const toolbox = new Toolbox({
+  deploymentDir: '/amalgm/users/person@example.com/toolbox',
+  databaseFile: '/machine-state/services/tools/tools.db',
+});
+```
+
+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.
+
+`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
@@ -60,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
 
@@ -83,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/dist/apply-definition.d.ts

@@ -0,0 +1,12 @@
+import { Store } from './store.js';
+import { ToolboxDeployments } from './toolbox-deployments.js';
+import type { ActionRecord, ApplyResult, ToolDefinition, ToolRecord } from './types.js';
+/** Normalize and deploy one authoritative user definition. */
+declare function applyDefinition(options: {
+    definition: ToolDefinition;
+    store: Store;
+    deployments: ToolboxDeployments;
+    systemTools: readonly ToolRecord[];
+    systemActions: readonly ActionRecord[];
+}): Promise<ApplyResult>;
+export { applyDefinition };

package/dist/apply-definition.js

@@ -0,0 +1,33 @@
+import { portableRecordSemantic } from './artifacts.js';
+import { normalizeDefinition } from './definition.js';
+import { assertMcpNamesUnique, id } from './ids.js';
+/** Normalize and deploy one authoritative user definition. */
+async function applyDefinition(options) {
+    const { definition, store, deployments, systemTools, systemActions } = options;
+    const normalizedId = id(definition.id, 'tool.id', 64);
+    if (definition.origin === 'system')
+        throw new Error('System tools can only be supplied by the embedder');
+    if (systemTools.some((tool) => tool.id === normalizedId))
+        throw new Error(`System tool is immutable: ${normalizedId}`);
+    const existing = store.getTool(normalizedId);
+    const oldActions = new Map(store.actionsFor(normalizedId).map((action) => [action.id, action]));
+    const normalized = normalizeDefinition(definition, existing || undefined);
+    normalized.actions = normalized.actions.map((action) => ({
+        ...action, createdAt: oldActions.get(action.id)?.createdAt || action.createdAt,
+    }));
+    assertMcpNamesUnique([
+        ...systemActions,
+        ...store.catalog().actions.filter((action) => action.toolId !== normalized.tool.id),
+        ...normalized.actions,
+    ]);
+    const unchanged = existing && portableRecordSemantic(existing) === portableRecordSemantic(normalized.tool)
+        && normalized.actions.length === oldActions.size
+        && normalized.actions.every((action) => portableRecordSemantic(action)
+            === portableRecordSemantic(oldActions.get(action.id)));
+    if (unchanged) {
+        return { tool: existing, actions: [...oldActions.values()].sort((a, b) => a.id.localeCompare(b.id)) };
+    }
+    await deployments.activateLocal(normalized);
+    return normalized;
+}
+export { applyDefinition };

package/dist/artifact-files.d.ts

@@ -1,3 +1,4 @@
+import type { ToolboxIndexDocument } from './artifacts.js';
 import type { ActionRecord, Catalog, ToolRecord } from './types.js';
 declare class ArtifactFiles {
     private readonly directory;
@@ -9,9 +10,10 @@ declare class ArtifactFiles {
     }): string;
     removeTool(toolId: string): void;
     writeIndex(catalog: Catalog): void;
+    readIndex(): ToolboxIndexDocument | null;
     /** Give every persisted user tool its portable artifact and refresh the
      * index. Additive only: a file for a tool this catalog does not know is
-     * never deleted here — removal is an explicit mutation. */
+     * never deleted here — removal or snapshot hydration is explicit. */
     materialize(catalog: Catalog): void;
     /** Execute the legacy `toolbox.json` migration plan: per-tool artifacts
      * first, then the index, and only then the rename that retires the

package/dist/artifact-files.js

@@ -2,8 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { LEGACY_TOOLBOX_FILE_NAME, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, userArtifactFileName, } from './artifacts.js';
 /**
- * The host adapter for tool artifacts: it executes the pure documents and
- * plans from `artifacts.ts` against one state directory. Writes are atomic
+ * The host adapter for current compatibility projections: it executes the
+ * pure documents and plans from `artifacts.ts` against one local state
+ * directory. Writes are atomic
  * (tmp file + rename) and skipped when the bytes are unchanged, matching
  * Engine `lib/storage.js`.
  *
@@ -51,9 +52,16 @@ class ArtifactFiles {
     writeIndex(catalog) {
         writeJsonIfChanged(this.file(TOOLBOX_INDEX_FILE_NAME), catalogIndexDocument(catalog));
     }
+    readIndex() {
+        const value = readJson(this.file(TOOLBOX_INDEX_FILE_NAME));
+        if (!value || value.version !== 1 || !value.tools || typeof value.tools !== 'object'
+            || !value.toolActions || typeof value.toolActions !== 'object')
+            return null;
+        return value;
+    }
     /** Give every persisted user tool its portable artifact and refresh the
      * index. Additive only: a file for a tool this catalog does not know is
-     * never deleted here — removal is an explicit mutation. */
+     * never deleted here — removal or snapshot hydration is explicit. */
     materialize(catalog) {
         for (const tool of catalog.tools) {
             if (tool.origin === 'system')

package/dist/artifacts.d.ts

@@ -2,11 +2,11 @@ import type { ActionRecord, Catalog, ToolRecord } from './types.js';
 /**
  * Tool artifact format laws — the portable representation of a tool.
  *
- * One tool is one artifact file: the tool definition and every action it
- * owns travel together, and a file never carries a second tool. Artifact
- * files are the portable definition; the Toolbox database and
- * `toolbox.index.json` are derived caches. The format is ported byte-exact
- * from Engine `runtime/scripts/amalgm-mcp/toolbox/artifacts.js`.
+ * 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.
  *
  * Pure laws only: nothing here touches the filesystem. `artifact-files.ts`
  * is the host adapter that executes these documents and plans.
@@ -57,10 +57,12 @@ declare function artifactDocument(input: {
 declare function isToolArtifactDocument(value: unknown): value is ToolArtifactDocument;
 declare function toolboxIndexDocument(tools: Record<string, unknown>, toolActions: Record<string, unknown>): ToolboxIndexDocument;
 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, toolboxIndexDocument, userArtifactFileName, };
+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 };

package/dist/artifacts.js

@@ -1,11 +1,11 @@
 /**
  * Tool artifact format laws — the portable representation of a tool.
  *
- * One tool is one artifact file: the tool definition and every action it
- * owns travel together, and a file never carries a second tool. Artifact
- * files are the portable definition; the Toolbox database and
- * `toolbox.index.json` are derived caches. The format is ported byte-exact
- * from Engine `runtime/scripts/amalgm-mcp/toolbox/artifacts.js`.
+ * 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.
  *
  * Pure laws only: nothing here touches the filesystem. `artifact-files.ts`
  * is the host adapter that executes these documents and plans.
@@ -81,6 +81,19 @@ function toolboxIndexDocument(tools, toolActions) {
 function catalogIndexDocument(catalog) {
     return toolboxIndexDocument(Object.fromEntries(catalog.tools.map((tool) => [tool.id, tool])), Object.fromEntries(catalog.actions.map((action) => [action.id, action])));
 }
+function portableRecordSemantic(value) {
+    const { createdAt, updatedAt, ...portable } = value;
+    return JSON.stringify(portable);
+}
+function preserveProjectionTime(candidate, previous) {
+    if (!previous || typeof previous !== 'object')
+        return candidate;
+    const record = previous;
+    if (typeof record.createdAt !== 'string' || typeof record.updatedAt !== 'string'
+        || portableRecordSemantic(record) !== portableRecordSemantic(candidate))
+        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
@@ -109,4 +122,4 @@ function legacyMigrationPlan(legacy) {
         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, toolboxIndexDocument, userArtifactFileName, };
+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, };

package/dist/definition.js

@@ -32,6 +32,15 @@ function refs(value, label) {
         result[string(key, label)] = string(reference, `${label}.${key}`);
     return result;
 }
+function hostRoute(value) {
+    if (value === undefined)
+        return undefined;
+    const route = string(value, 'source.route');
+    if (!route.startsWith('/') || route.startsWith('//') || route.includes('?') || route.includes('#')) {
+        throw new Error('source.route must be an absolute path without query or fragment');
+    }
+    return route.replace(/\/+$/, '') || '/';
+}
 function base(source) {
     return {
         timeoutMs: positive(source.timeoutMs, DEFAULT_TIMEOUT, 'source.timeoutMs'),
@@ -91,6 +100,7 @@ function normalizeSource(source) {
             ...(strings(source.args, 'source.args') ? { args: strings(source.args, 'source.args') } : {}),
             ...(source.cwd ? { cwd: string(source.cwd, 'source.cwd') } : {}),
             ...(source.serverName ? { serverName: string(source.serverName, 'source.serverName') } : {}),
+            ...(hostRoute(source.route) ? { route: hostRoute(source.route) } : {}),
             ...(refs(source.secretHeaders, 'source.secretHeaders') ? { secretHeaders: refs(source.secretHeaders, 'source.secretHeaders') } : {}),
             ...(refs(source.secretEnv, 'source.secretEnv') ? { secretEnv: refs(source.secretEnv, 'source.secretEnv') } : {}),
         };

package/dist/deployment-files.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDeployment } from './types.js';
+/** Host effect for the portable, immutable deployment document tree. */
+declare class DeploymentFiles {
+    private readonly root;
+    constructor(root: string);
+    file(deployment: ToolDeployment): string;
+    write(deployment: ToolDeployment): string;
+    materialize(deployments: readonly ToolDeployment[]): void;
+}
+export { DeploymentFiles };

package/dist/deployment-files.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson } from './deployments.js';
+/** Host effect for the portable, immutable deployment document tree. */
+class DeploymentFiles {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    file(deployment) {
+        return path.join(this.root, deployment.subjectId, 'deployments', `${deployment.id}.json`);
+    }
+    write(deployment) {
+        const target = this.file(deployment);
+        const bytes = `${JSON.stringify(deployment, null, 2)}\n`;
+        try {
+            const existing = fs.readFileSync(target, 'utf8');
+            if (canonicalJson(JSON.parse(existing)) !== canonicalJson(deployment)) {
+                throw new Error(`Deployment file is immutable: ${deployment.id}`);
+            }
+            return target;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        const temporary = `${target}.tmp`;
+        fs.writeFileSync(temporary, bytes, { flag: 'wx' });
+        fs.renameSync(temporary, target);
+        return target;
+    }
+    materialize(deployments) {
+        for (const deployment of deployments)
+            this.write(deployment);
+    }
+}
+export { DeploymentFiles };

package/dist/deployment-types.d.ts

@@ -0,0 +1,32 @@
+import type { ApplyResult } from './types.js';
+interface ToolDeployment {
+    schemaVersion: 1;
+    kind: 'amalgm-tool-deployment';
+    id: string;
+    /** The stable tool id, named generically to match @amalgm/live. */
+    subjectId: string;
+    previousDeploymentId: string | null;
+    definition: ApplyResult | null;
+    contentHash: string;
+    createdAt: string;
+}
+interface ToolDeploymentActivation {
+    type: 'deployment.activate';
+    deployment: ToolDeployment;
+}
+interface ToolDeploymentSnapshot {
+    version: 1;
+    deployments: Record<string, ToolDeployment>;
+    heads: Record<string, string>;
+}
+interface ToolDeploymentSurface {
+    readonly contract: 'amalgm.tools.deployments@1';
+    observeEdits(emit: (operation: ToolDeploymentActivation) => void): () => void;
+    applyRemote(operation: ToolDeploymentActivation, context: {
+        readonly hydrating: boolean;
+    }): void | Promise<void>;
+    applySnapshot(snapshot: ToolDeploymentSnapshot, context: {
+        readonly reason: 'hydration' | 'recovery';
+    }): void | Promise<void>;
+}
+export type { ToolDeployment, ToolDeploymentActivation, ToolDeploymentSnapshot, ToolDeploymentSurface, };

package/dist/deployment-types.js

@@ -0,0 +1 @@
+export {};

package/dist/deployments.d.ts

@@ -0,0 +1,19 @@
+import type { ActionRecord, ApplyResult, ToolDeploymentActivation, ToolDeploymentSnapshot, ToolRecord } from './types.js';
+declare const TOOL_DEPLOYMENT_CONTRACT: "amalgm.tools.deployments@1";
+declare const TOOL_DEPLOYMENT_KIND: "amalgm-tool-deployment";
+declare const TOOL_DEPLOYMENT_SCHEMA_VERSION: 1;
+declare function canonicalJson(value: unknown): string;
+declare function createToolDeployment(input: {
+    toolId: string;
+    previousDeploymentId: string | null;
+    definition: ApplyResult | null;
+    createdAt: string;
+}): ToolDeploymentActivation;
+declare function assertToolDeploymentActivation(value: unknown): asserts value is ToolDeploymentActivation;
+declare function deploymentRevisionId(input: {
+    heads: Readonly<Record<string, string>>;
+    systemTools?: readonly ToolRecord[];
+    systemActions?: readonly ActionRecord[];
+}): string;
+declare function emptyToolDeploymentSnapshot(): ToolDeploymentSnapshot;
+export { TOOL_DEPLOYMENT_CONTRACT, TOOL_DEPLOYMENT_KIND, TOOL_DEPLOYMENT_SCHEMA_VERSION, assertToolDeploymentActivation, canonicalJson, createToolDeployment, deploymentRevisionId, emptyToolDeploymentSnapshot, };

package/dist/deployments.js

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto';
+const TOOL_DEPLOYMENT_CONTRACT = 'amalgm.tools.deployments@1';
+const TOOL_DEPLOYMENT_KIND = 'amalgm-tool-deployment';
+const TOOL_DEPLOYMENT_SCHEMA_VERSION = 1;
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]));
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonical(value));
+}
+function sha256(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+function createToolDeployment(input) {
+    const contentHash = sha256(input.definition);
+    const identity = sha256({
+        subjectId: input.toolId,
+        previousDeploymentId: input.previousDeploymentId,
+        contentHash,
+        createdAt: input.createdAt,
+    });
+    return Object.freeze({
+        type: 'deployment.activate',
+        deployment: Object.freeze({
+            schemaVersion: TOOL_DEPLOYMENT_SCHEMA_VERSION,
+            kind: TOOL_DEPLOYMENT_KIND,
+            id: `tooldep_${identity}`,
+            subjectId: input.toolId,
+            previousDeploymentId: input.previousDeploymentId,
+            definition: input.definition,
+            contentHash,
+            createdAt: input.createdAt,
+        }),
+    });
+}
+function assertRecord(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+}
+function assertToolDeploymentActivation(value) {
+    assertRecord(value, 'Tool deployment activation');
+    if (value.type !== 'deployment.activate')
+        throw new Error('Tool deployment operation must be deployment.activate');
+    assertRecord(value.deployment, 'Tool deployment');
+    const deployment = value.deployment;
+    if (deployment.schemaVersion !== TOOL_DEPLOYMENT_SCHEMA_VERSION || deployment.kind !== TOOL_DEPLOYMENT_KIND) {
+        throw new Error('Unsupported tool deployment document');
+    }
+    if (typeof deployment.id !== 'string' || !deployment.id
+        || typeof deployment.subjectId !== 'string' || !deployment.subjectId
+        || typeof deployment.createdAt !== 'string' || !deployment.createdAt
+        || (deployment.previousDeploymentId !== null && typeof deployment.previousDeploymentId !== 'string')) {
+        throw new Error('Tool deployment identity is incomplete');
+    }
+    if (deployment.definition !== null) {
+        assertRecord(deployment.definition, 'Tool deployment definition');
+        assertRecord(deployment.definition.tool, 'Tool deployment tool');
+        if (deployment.definition.tool.id !== deployment.subjectId) {
+            throw new Error('Tool deployment subject does not match its tool');
+        }
+        if (deployment.definition.tool.origin === 'system') {
+            throw new Error('System tools cannot arrive as user deployments');
+        }
+        if (!Array.isArray(deployment.definition.actions)
+            || deployment.definition.actions.some((action) => action.toolId !== deployment.subjectId)) {
+            throw new Error('Tool deployment actions must all belong to its subject');
+        }
+    }
+    if (deployment.contentHash !== sha256(deployment.definition)) {
+        throw new Error(`Tool deployment content hash is invalid: ${deployment.id}`);
+    }
+    const expected = createToolDeployment({
+        toolId: deployment.subjectId,
+        previousDeploymentId: deployment.previousDeploymentId,
+        definition: deployment.definition,
+        createdAt: deployment.createdAt,
+    }).deployment.id;
+    if (deployment.id !== expected)
+        throw new Error(`Tool deployment id is invalid: ${deployment.id}`);
+}
+function deploymentRevisionId(input) {
+    return `toolbox_${sha256({
+        heads: input.heads,
+        systemTools: input.systemTools || [],
+        systemActions: input.systemActions || [],
+    })}`;
+}
+function emptyToolDeploymentSnapshot() {
+    return { version: 1, deployments: {}, heads: {} };
+}
+export { TOOL_DEPLOYMENT_CONTRACT, TOOL_DEPLOYMENT_KIND, TOOL_DEPLOYMENT_SCHEMA_VERSION, assertToolDeploymentActivation, canonicalJson, createToolDeployment, deploymentRevisionId, emptyToolDeploymentSnapshot, };

package/dist/host-mcp-tool.d.ts

@@ -0,0 +1,8 @@
+import type { HostMcpToolDefinitionInput, ToolDefinition } from './types.js';
+/**
+ * Project an owning SDK's MCP descriptors into one immutable first-party
+ * Toolbox tool. The descriptors remain authoritative; this adapter does not
+ * copy or reinterpret action schemas.
+ */
+declare function defineHostMcpTool(input: HostMcpToolDefinitionInput): ToolDefinition;
+export { defineHostMcpTool };