@amalgm/tools 0.1.2 → 0.1.4

package/PURPOSE.md

@@ -23,9 +23,14 @@ 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
@@ -37,13 +42,14 @@ registry or execution implementation.
    `<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
@@ -81,11 +87,34 @@ registry or execution implementation.
 20. Notification channels are host capabilities. Tools owns validation and
     result semantics; an injected channel adapter owns formatting, recipient
     lookup, credentials, and delivery.
+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,

package/README.md

@@ -36,6 +36,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

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 };

package/dist/host-mcp-tool.js

@@ -0,0 +1,40 @@
+import { defineTool } from './definition.js';
+const EMPTY_INPUT = {
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+};
+/**
+ * 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.
+ */
+function defineHostMcpTool(input) {
+    const actions = input.tools.map((tool) => ({
+        name: tool.name,
+        ...(tool.description ? { description: tool.description } : {}),
+        inputSchema: tool.inputSchema || EMPTY_INPUT,
+        target: { name: tool.name },
+    }));
+    return defineTool({
+        id: input.id,
+        name: input.name,
+        ...(input.description ? { description: input.description } : {}),
+        owner: input.owner || 'amalgm',
+        origin: 'system',
+        source: {
+            type: 'mcp',
+            transport: 'host',
+            serverName: input.serverName,
+            route: input.route,
+        },
+        actions,
+        policy: { firstParty: true },
+        ...(input.display ? { display: structuredClone(input.display) } : {}),
+        metadata: {
+            platform: true,
+            ...(input.metadata ? structuredClone(input.metadata) : {}),
+        },
+    });
+}
+export { defineHostMcpTool };

package/dist/http.js

@@ -16,7 +16,12 @@ function actionDocument(action) {
     return { ...action };
 }
 function catalogDocument(catalog) {
-    return toolboxIndexDocument(Object.fromEntries(catalog.tools.map((tool) => [tool.id, toolDocument(tool)])), Object.fromEntries(catalog.actions.map((action) => [action.id, actionDocument(action)])));
+    return {
+        ...toolboxIndexDocument(Object.fromEntries(catalog.tools.map((tool) => [tool.id, toolDocument(tool)])), Object.fromEntries(catalog.actions.map((action) => [action.id, actionDocument(action)]))),
+        revision: catalog.revision,
+        revisionId: catalog.revisionId,
+        deployments: catalog.deployments,
+    };
 }
 async function readBody(req) {
     const chunks = [];

package/dist/index.d.ts

@@ -2,10 +2,12 @@ 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 { 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';
 export { catalogDocument, createToolboxHttpServer } from './http.js';
 export type { ToolboxHttpServer } from './http.js';
 export { actionId, actionName, id, mcpName } from './ids.js';
-export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, } from './mcp.js';
+export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementToolDescriptors, managementTools, } from './mcp.js';
 export { createMcpServer } from './mcp-server.js';
 export { Notifications, createNotificationsDriver, notificationToolDefinition, } from './notifications.js';
 export type { EmailDelivery, EmailDeliveryReceipt, EmailNotificationRequest, NotificationLevel, NotificationsOptions, } from './notifications.js';

package/dist/index.js

@@ -1,9 +1,11 @@
 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 { 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';
 export { catalogDocument, createToolboxHttpServer } from './http.js';
 export { actionId, actionName, id, mcpName } from './ids.js';
-export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, } from './mcp.js';
+export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementToolDescriptors, managementTools, } from './mcp.js';
 export { createMcpServer } from './mcp-server.js';
 export { Notifications, createNotificationsDriver, notificationToolDefinition, } from './notifications.js';
 export { createProxyEmailDelivery } from './proxy-email.js';

package/dist/mcp-server.d.ts

@@ -1,7 +1,7 @@
 import readline from 'node:readline';
 import type { Readable, Writable } from 'node:stream';
 import { Toolbox } from './toolbox.js';
-import type { ToolboxOptions } from './types.js';
+import type { McpOptions, ToolboxOptions } from './types.js';
 interface Request {
     jsonrpc?: string;
     id?: string | number;
@@ -10,6 +10,7 @@ interface Request {
 }
 declare function createMcpServer(options?: ToolboxOptions & {
     toolbox?: Toolbox;
+    mcp?: McpOptions;
 }): {
     toolbox: Toolbox;
     handle: (request: Request) => Promise<unknown>;

package/dist/mcp-server.js

@@ -7,6 +7,7 @@ function descriptor(tool) {
 }
 function createMcpServer(options = {}) {
     const toolbox = options.toolbox || new Toolbox(options);
+    const mcpOptions = options.mcp || {};
     async function handle(request) {
         if (request.method === 'initialize') {
             return {
@@ -17,12 +18,12 @@ function createMcpServer(options = {}) {
         }
         if (request.method === 'ping')
             return {};
-        const tools = createMcpTools(toolbox);
+        const tools = createMcpTools(toolbox, mcpOptions);
         if (request.method === 'tools/list')
             return { tools: tools.map(descriptor) };
         if (request.method === 'tools/call') {
             try {
-                return await callMcpTool(toolbox, String(request.params?.name || ''), request.params?.arguments || {});
+                return await callMcpTool(toolbox, String(request.params?.name || ''), request.params?.arguments || {}, mcpOptions);
             }
             catch (error) {
                 if (error instanceof Error && error.message.startsWith('Unknown tool:')) {