@amalgm/tools 0.1.0

package/PURPOSE.md

@@ -0,0 +1,87 @@
+# Amalgm Tools
+
+## Purpose
+
+Amalgm Tools lets a user define, keep, select, and run agent capabilities
+without installing Amalgm Engine. 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.
+
+## Primitives
+
+- 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 **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.
+- A **system tool** is an embedder-owned definition projected into the catalog;
+  it is not user state.
+
+## Axioms
+
+1. Every action belongs to exactly one tool and has the canonical id
+   `<tool-id>.<action-name>`.
+2. Tool ids are stable, globally unique within one Toolbox, and never change
+   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.
+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
+   absent from every runnable surface.
+7. A missing loadout means all enabled actions; an explicit empty loadout
+   means none. Selection never grants a capability not present in the catalog.
+8. Tool and action selection use ids only. Display names, ordering, and MCP
+   names never confer authority.
+9. MCP action names are a deterministic, collision-checked projection of
+   canonical action ids.
+10. Drivers declare which normalized tools they can execute, receive validated
+    object input, and never read or mutate Toolbox state.
+11. CLI execution never invokes a shell. API execution never changes origin
+    from the registered base URL, including through redirects.
+12. Credentials are supplied at execution time by the embedder. Secret values
+    are never stored in a tool or action record.
+13. Output is bounded before it enters an agent context, and cancellation or a
+    timeout terminates the underlying execution.
+14. MCP tools are connection definitions. Their actions are advertised only
+    when the composing MCP host supplies a driver that supports that exact
+    connection; Toolbox does not invent a second MCP session owner.
+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.
+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.
+
+## 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
+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
+therefore get the same identities, validation, selection, and execution rules.

package/README.md

@@ -0,0 +1,62 @@
+# 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.
+
+```js
+import { defineTool, Toolbox } from '@amalgm/tools';
+
+const toolbox = new Toolbox({ stateDir: './.tools' });
+await toolbox.apply(defineTool({
+  id: 'hello',
+  name: 'Hello',
+  source: { type: 'cli', command: 'node', inputMode: 'json-stdin', outputMode: 'json' },
+  actions: [{
+    name: 'say',
+    target: { args: ['./hello.mjs'] },
+    inputSchema: {
+      type: 'object',
+      required: ['name'],
+      properties: { name: { type: 'string' } },
+      additionalProperties: false,
+    },
+  }],
+}));
+
+const result = await toolbox.call('hello.say', { name: 'Ada' });
+toolbox.close();
+```
+
+## State directory
+
+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.
+
+## 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 connections
+```
+
+`amalgm-tools-mcp` serves Toolbox management and enabled action tools over
+newline-delimited MCP stdio.
+
+## Tool types
+
+- `cli`: executed directly with `spawn`; a shell is never involved.
+- `api`: same-origin HTTP actions with redirects refused.
+- `mcp`: a connection plus action projection. The composing MCP host supplies
+  the one MCP driver that owns discovery, sessions, and calls.
+
+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.

package/dist/api-driver.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDriver } from './types.js';
+declare const apiDriver: ToolDriver;
+export { apiDriver };

package/dist/api-driver.js

@@ -0,0 +1,92 @@
+import { boundedResult, errorResult, structuredResult, textResult } from './results.js';
+import { resolveReferences } from './secrets.js';
+function fillPath(path, input) {
+    const params = (input.pathParams || input);
+    return path.replace(/\{([^}]+)\}/g, (_, key) => {
+        if (params[key] === undefined)
+            throw new Error(`Missing API path parameter: ${key}`);
+        return encodeURIComponent(String(params[key]));
+    });
+}
+async function readBody(response, maximum) {
+    if (!response.body)
+        return { text: '', truncated: false };
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        const room = Math.max(0, maximum - size);
+        if (value.length > room)
+            truncated = true;
+        if (room > 0) {
+            chunks.push(value.subarray(0, room));
+            size += Math.min(room, value.length);
+        }
+    }
+    return { text: Buffer.concat(chunks).toString('utf8'), truncated };
+}
+function timeoutSignal(timeoutMs, parent) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(parent?.reason);
+    parent?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs);
+    timer.unref();
+    return {
+        signal: controller.signal,
+        close() { clearTimeout(timer); parent?.removeEventListener('abort', abort); },
+    };
+}
+const apiDriver = {
+    type: 'api',
+    async call({ tool, action, input, options }) {
+        const source = tool.source;
+        const target = action.target;
+        const base = new URL(source.baseUrl);
+        const url = new URL(fillPath(target.path, input), base);
+        if (url.origin !== base.origin)
+            throw new Error(`API action ${action.id} leaves its registered origin`);
+        const query = input.query;
+        if (query && (typeof query !== 'object' || Array.isArray(query)))
+            throw new Error('input.query must be an object');
+        for (const [key, value] of Object.entries((query || {}))) {
+            if (value !== undefined && value !== null)
+                url.searchParams.append(key, String(value));
+        }
+        const headers = await resolveReferences(source.secretHeaders, options.resolveSecret);
+        const method = target.method.toUpperCase();
+        const timed = timeoutSignal(source.timeoutMs, options.signal);
+        try {
+            const response = await fetch(url, {
+                method, redirect: 'manual', signal: timed.signal,
+                headers: { 'content-type': 'application/json', ...headers },
+                body: ['GET', 'HEAD'].includes(method) ? undefined : JSON.stringify(input.body ?? input),
+            });
+            if (response.status >= 300 && response.status < 400)
+                return errorResult(`API tool ${action.id} refused redirect`);
+            const body = await readBody(response, source.maxOutputBytes);
+            if (!response.ok)
+                return errorResult(`HTTP ${response.status} ${response.statusText}\n\n${body.text}`);
+            let result;
+            try {
+                result = structuredResult(JSON.parse(body.text));
+            }
+            catch {
+                result = textResult(body.text);
+            }
+            return { ...boundedResult(result, source.maxOutputBytes), ...(body.truncated ? { truncated: true } : {}) };
+        }
+        catch (error) {
+            if (timed.signal.aborted)
+                return errorResult(options.signal?.aborted ? `Tool ${action.id} was cancelled` : `Tool ${action.id} timed out`);
+            throw error;
+        }
+        finally {
+            timed.close();
+        }
+    },
+};
+export { apiDriver };

package/dist/artifact-files.d.ts

@@ -0,0 +1,28 @@
+import type { ActionRecord, Catalog, ToolRecord } from './types.js';
+declare class ArtifactFiles {
+    private readonly directory;
+    constructor(directory: string);
+    private file;
+    writeTool(entry: {
+        tool: ToolRecord;
+        actions: ActionRecord[];
+    }): string;
+    removeTool(toolId: string): void;
+    writeIndex(catalog: Catalog): void;
+    /** 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. */
+    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
+     * aggregate file. */
+    migrateLegacy(): boolean;
+    /** Read every valid per-tool artifact back. A document only counts when
+     * its file carries the exact name its tool id demands — a copied or
+     * renamed file never smuggles in a second identity. */
+    read(): {
+        tools: Record<string, ToolRecord>;
+        toolActions: Record<string, ActionRecord>;
+    };
+}
+export { ArtifactFiles };

package/dist/artifact-files.js

@@ -0,0 +1,115 @@
+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
+ * (tmp file + rename) and skipped when the bytes are unchanged, matching
+ * Engine `lib/storage.js`.
+ *
+ * DELIBERATE DEVIATION: Engine keeps the index and the legacy backup
+ * beside — not inside — its cloud-backed toolbox folder. A standalone
+ * state directory already holds the local `tools.db` cache, so both files
+ * live inside it, next to the database.
+ */
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJsonIfChanged(file, value) {
+    if (JSON.stringify(readJson(file)) === JSON.stringify(value))
+        return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2));
+    fs.renameSync(temporary, file);
+}
+class ArtifactFiles {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    file(name) { return path.join(this.directory, name); }
+    writeTool(entry) {
+        const target = this.file(userArtifactFileName(entry.tool.id));
+        writeJsonIfChanged(target, artifactDocument(entry));
+        return target;
+    }
+    removeTool(toolId) {
+        try {
+            fs.unlinkSync(this.file(userArtifactFileName(toolId)));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    writeIndex(catalog) {
+        writeJsonIfChanged(this.file(TOOLBOX_INDEX_FILE_NAME), catalogIndexDocument(catalog));
+    }
+    /** 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. */
+    materialize(catalog) {
+        for (const tool of catalog.tools) {
+            if (tool.origin === 'system')
+                continue;
+            this.writeTool({ tool, actions: catalog.actions.filter((action) => action.toolId === tool.id) });
+        }
+        this.writeIndex(catalog);
+    }
+    /** Execute the legacy `toolbox.json` migration plan: per-tool artifacts
+     * first, then the index, and only then the rename that retires the
+     * aggregate file. */
+    migrateLegacy() {
+        const legacy = this.file(LEGACY_TOOLBOX_FILE_NAME);
+        if (!fs.existsSync(legacy))
+            return false;
+        const plan = legacyMigrationPlan(readJson(legacy));
+        if (!plan.migrated || !plan.rename)
+            return false;
+        for (const write of plan.files)
+            writeJsonIfChanged(this.file(write.fileName), write.document);
+        if (plan.index)
+            writeJsonIfChanged(this.file(TOOLBOX_INDEX_FILE_NAME), plan.index);
+        let target = this.file(plan.rename.to);
+        if (fs.existsSync(target))
+            target = this.file(`toolbox.legacy-${Date.now()}.json`);
+        fs.renameSync(legacy, target);
+        return true;
+    }
+    /** Read every valid per-tool artifact back. A document only counts when
+     * its file carries the exact name its tool id demands — a copied or
+     * renamed file never smuggles in a second identity. */
+    read() {
+        const tools = {};
+        const toolActions = {};
+        let entries = [];
+        try {
+            entries = fs.readdirSync(this.directory, { withFileTypes: true });
+        }
+        catch {
+            return { tools, toolActions };
+        }
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.json') || entry.name === LEGACY_TOOLBOX_FILE_NAME)
+                continue;
+            const document = readJson(path.join(this.directory, entry.name));
+            if (!isToolArtifactDocument(document))
+                continue;
+            const toolId = safeToolId(document.tool.id);
+            if (userArtifactFileName(toolId) !== entry.name)
+                continue;
+            tools[toolId] = { ...document.tool, id: toolId };
+            for (const action of document.actions) {
+                toolActions[String(action.id)] = { ...action, toolId };
+            }
+        }
+        return { tools, toolActions };
+    }
+}
+export { ArtifactFiles };

package/dist/artifacts.d.ts

@@ -0,0 +1,66 @@
+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`.
+ *
+ * Pure laws only: nothing here touches the filesystem. `artifact-files.ts`
+ * is the host adapter that executes these documents and plans.
+ *
+ * DELIBERATE DEVIATION: Engine recognizes system tools by its managed
+ * artifact list; this product's system tools are embedder projections
+ * (Axiom 15) and are recognized by `origin: 'system'`. The portable-source
+ * law is unchanged: a system tool's `127.0.0.1:<port>` binding is a device
+ * fact, never tool identity, so its artifact carries
+ * `{ transport: 'amalgm-runtime', service: 'mcp' }` instead.
+ */
+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";
+type ArtifactRecord = Record<string, unknown>;
+interface ToolArtifactDocument {
+    schemaVersion: typeof TOOL_ARTIFACT_SCHEMA_VERSION;
+    kind: typeof TOOL_ARTIFACT_KIND;
+    tool: ArtifactRecord;
+    actions: ArtifactRecord[];
+}
+interface ToolboxIndexDocument {
+    version: 1;
+    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[];
+}): ToolArtifactDocument;
+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;
+/** 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 type { ArtifactFileWrite, LegacyMigrationPlan, ToolArtifactDocument, ToolboxIndexDocument };

package/dist/artifacts.js

@@ -0,0 +1,112 @@
+/**
+ * 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`.
+ *
+ * Pure laws only: nothing here touches the filesystem. `artifact-files.ts`
+ * is the host adapter that executes these documents and plans.
+ *
+ * DELIBERATE DEVIATION: Engine recognizes system tools by its managed
+ * artifact list; this product's system tools are embedder projections
+ * (Axiom 15) and are recognized by `origin: 'system'`. The portable-source
+ * law is unchanged: a system tool's `127.0.0.1:<port>` binding is a device
+ * fact, never tool identity, so its artifact carries
+ * `{ transport: 'amalgm-runtime', service: 'mcp' }` instead.
+ */
+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';
+function safeToolId(value) {
+    return String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/g, '.')
+        .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)) {
+        throw new Error('tool artifact requires a tool with an id');
+    }
+    const toolId = safeToolId(tool.id);
+    const normalizedActions = Array.isArray(actions)
+        ? actions.filter((action) => action && action.toolId === toolId)
+        : [];
+    const portableTool = tool.origin === 'system'
+        ? {
+            ...tool,
+            id: toolId,
+            // `127.0.0.1:<port>` is a device binding, not tool identity. The
+            // embedder resolves the current runtime endpoint when serving the
+            // local tool surface.
+            source: { transport: 'amalgm-runtime', service: 'mcp' },
+        }
+        : { ...tool, id: toolId };
+    return {
+        schemaVersion: TOOL_ARTIFACT_SCHEMA_VERSION,
+        kind: TOOL_ARTIFACT_KIND,
+        tool: portableTool,
+        actions: normalizedActions
+            .map((action) => ({ ...action, toolId }))
+            .sort((left, right) => String(left.id).localeCompare(String(right.id))),
+    };
+}
+function isToolArtifactDocument(value) {
+    const document = value;
+    return !!document
+        && document.schemaVersion === TOOL_ARTIFACT_SCHEMA_VERSION
+        && document.kind === TOOL_ARTIFACT_KIND
+        && !!document.tool
+        && typeof document.tool === 'object'
+        && !!safeToolId(document.tool.id)
+        && Array.isArray(document.actions)
+        && document.actions.every((action) => action && action.toolId === safeToolId(document.tool.id));
+}
+function toolboxIndexDocument(tools, toolActions) {
+    return { version: 1, tools: tools || {}, toolActions: toolActions || {} };
+}
+function catalogIndexDocument(catalog) {
+    return toolboxIndexDocument(Object.fromEntries(catalog.tools.map((tool) => [tool.id, tool])), Object.fromEntries(catalog.actions.map((action) => [action.id, action])));
+}
+/** 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, toolboxIndexDocument, userArtifactFileName, };

package/dist/bin/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/mcp.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { createMcpServer } from '../mcp-server.js';
+const args = process.argv.slice(2);
+const stateIndex = args.indexOf('--state-dir');
+const stateDir = stateIndex >= 0 ? args[stateIndex + 1] : undefined;
+const server = createMcpServer({ stateDir });
+server.start();
+const close = () => {
+    server.toolbox.close();
+    process.exit(0);
+};
+process.once('SIGINT', close);
+process.once('SIGTERM', close);

package/dist/bin/tools.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/tools.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from '../cli.js';
+void runCli(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/dist/cli-driver.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDriver } from './types.js';
+declare const cliDriver: ToolDriver;
+export { cliDriver };

package/dist/cli-driver.js

@@ -0,0 +1,52 @@
+import { runCommand } from './process.js';
+import { errorResult, structuredResult, textResult } from './results.js';
+import { resolveReferences } from './secrets.js';
+function inputArguments(input) {
+    const args = input.args;
+    if (!Array.isArray(args) || args.some((value) => typeof value !== 'string')) {
+        throw new Error('CLI argv input requires a string array at input.args');
+    }
+    return args;
+}
+const cliDriver = {
+    type: 'cli',
+    async call({ tool, action, input, options }) {
+        const source = tool.source;
+        const target = action.target;
+        const environment = await resolveReferences(source.secretEnv, options.resolveSecret);
+        const args = [...(source.args || []), ...(target.args || [])];
+        if (source.inputMode === 'argv')
+            args.push(...inputArguments(input));
+        const output = await runCommand({
+            command: source.command, args, cwd: source.cwd,
+            env: { ...process.env, ...environment },
+            stdin: source.inputMode === 'json-stdin' ? `${JSON.stringify(input)}\n` : undefined,
+            timeoutMs: source.timeoutMs, maximumBytes: source.maxOutputBytes, signal: options.signal,
+        });
+        const stdout = output.stdout.trim();
+        const stderr = output.stderr.trim();
+        if (output.timedOut)
+            return errorResult(`Tool ${action.id} timed out after ${source.timeoutMs}ms`);
+        if (output.aborted)
+            return errorResult(`Tool ${action.id} was cancelled`);
+        if (output.code !== 0) {
+            return errorResult([
+                `Tool ${action.id} exited with ${output.code ?? output.signal ?? 'unknown'}.`,
+                stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`,
+            ].filter(Boolean).join('\n\n'));
+        }
+        let result;
+        if (source.outputMode === 'json' && stdout) {
+            try {
+                result = structuredResult(JSON.parse(stdout));
+            }
+            catch {
+                return errorResult(`Tool ${action.id} returned invalid JSON`);
+            }
+        }
+        else
+            result = textResult(stdout || `Tool ${action.id} completed.`);
+        return { ...result, ...(output.truncated ? { truncated: true } : {}) };
+    },
+};
+export { cliDriver };

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+import type { CliIo, LoadoutInput } from './types.js';
+declare const HELP = "Usage: amalgm-tools [--state-dir DIR] [--loadout IDS] <command>\n\nCommands:\n  apply <definition.js|json>  Apply one tool or an array of tools\n  list                        List tools and enabled actions\n  catalog                     Print the complete canonical catalog\n  show <tool-or-action-id>    Show one record\n  enable <tool-or-action-id>  Enable one record\n  disable <tool-or-action-id> Disable one record\n  remove <tool-or-action-id>  Remove one record\n  run <action-id> [--input JSON]\n                              Run an action\n  connections                 List MCP connections for a composing host";
+interface Parsed {
+    command?: string;
+    args: string[];
+    stateDir?: string;
+    loadout?: LoadoutInput;
+    input: Record<string, unknown>;
+}
+declare function parse(argv: string[]): Parsed;
+declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+export { HELP, parse, runCli };
+export type { Parsed };