@amalgm/tools 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+import type { Writable } from 'node:stream';
+type JsonSchema = {
+    type: 'object';
+    properties?: Record<string, {
+        type?: string;
+        description?: string;
+        [key: string]: unknown;
+    }>;
+    required?: string[];
+    additionalProperties?: boolean;
+    description?: string;
+    [key: string]: unknown;
+};
+type ToolType = 'cli' | 'api' | 'mcp';
+type Origin = 'user' | 'catalog' | 'system';
+type Status = 'enabled' | 'disabled';
+type SecretReferences = Record<string, string>;
+interface BaseSource {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+interface CliSource extends BaseSource {
+    type: 'cli';
+    command: string;
+    args?: string[];
+    cwd?: string;
+    inputMode?: 'json-stdin' | 'argv' | 'none';
+    outputMode?: 'json' | 'text';
+    secretEnv?: SecretReferences;
+}
+interface ApiSource extends BaseSource {
+    type: 'api';
+    baseUrl: string;
+    secretHeaders?: SecretReferences;
+}
+interface McpSource extends BaseSource {
+    type: 'mcp';
+    transport: 'http' | 'sse' | 'stdio' | 'host';
+    url?: string;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    serverName?: string;
+    secretHeaders?: SecretReferences;
+    secretEnv?: SecretReferences;
+}
+type ToolSource = CliSource | ApiSource | McpSource;
+interface CliTarget {
+    args?: string[];
+}
+interface ApiTarget {
+    method: string;
+    path: string;
+}
+interface McpTarget {
+    name: string;
+}
+type ActionTarget = CliTarget | ApiTarget | McpTarget;
+interface ActionDefinition {
+    name: string;
+    id?: string;
+    displayName?: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: Record<string, unknown>;
+    status?: Status;
+    target?: ActionTarget;
+    policy?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface ToolDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    owner?: string;
+    origin?: Origin;
+    status?: Status;
+    source: ToolSource;
+    actions?: ActionDefinition[];
+    display?: Record<string, unknown>;
+    policy?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface ToolQuery {
+    type?: ToolType;
+    owner?: string;
+    origin?: Origin;
+    origins?: Origin[];
+    status?: Status;
+}
+type ToolPatch = Omit<Partial<ToolDefinition>, 'id' | 'source'> & {
+    source?: Partial<CliSource> | Partial<ApiSource> | Partial<McpSource>;
+};
+type ActionPatch = Omit<Partial<ActionDefinition>, 'id'>;
+interface ToolRecord extends Omit<ToolDefinition, 'actions'> {
+    origin: Origin;
+    status: Status;
+    owner: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ActionRecord extends Omit<ActionDefinition, 'id' | 'status' | 'inputSchema'> {
+    id: string;
+    toolId: string;
+    status: Status;
+    inputSchema: JsonSchema;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Catalog {
+    version: 1;
+    revision: number;
+    tools: ToolRecord[];
+    actions: ActionRecord[];
+}
+interface ApplyResult {
+    tool: ToolRecord;
+    actions: ActionRecord[];
+}
+interface Loadout {
+    toolIds: string[];
+}
+type LoadoutInput = Loadout | string[];
+interface ToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+    truncated?: boolean;
+}
+type SecretResolver = (reference: string) => string | undefined | Promise<string | undefined>;
+interface CallOptions {
+    loadout?: LoadoutInput;
+    signal?: AbortSignal;
+    resolveSecret?: SecretResolver;
+    context?: unknown;
+}
+interface DriverCall {
+    tool: ToolRecord;
+    action: ActionRecord;
+    input: Record<string, unknown>;
+    options: CallOptions;
+}
+interface ToolDriver {
+    type: ToolType;
+    supports?(tool: ToolRecord): boolean;
+    call(request: DriverCall): Promise<ToolResult>;
+}
+interface ToolboxOptions {
+    stateDir?: string;
+    databaseFile?: string;
+    systemTools?: ToolDefinition[];
+    drivers?: ToolDriver[];
+    onChange?: (catalog: Catalog) => void | Promise<void>;
+}
+interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    handler(input?: Record<string, unknown>): Promise<ToolResult>;
+}
+interface McpOptions extends CallOptions {
+    includeManagement?: boolean;
+}
+interface CliIo {
+    stdout?: Writable;
+    stderr?: Writable;
+    toolbox?: import('./toolbox.js').Toolbox;
+}
+export type { ActionDefinition, ActionRecord, ActionTarget, ApiSource, ApiTarget, ApplyResult, CallOptions, Catalog, CliIo, CliSource, CliTarget, DriverCall, JsonSchema, Loadout, LoadoutInput, McpOptions, McpSource, McpTarget, McpTool, Origin, SecretResolver, Status, ToolDefinition, ToolDriver, ToolboxOptions, ToolRecord, ToolResult, ToolPatch, ActionPatch, ToolQuery, ToolSource, ToolType, };

package/dist/types.js

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

package/dist/updates.d.ts

@@ -0,0 +1,7 @@
+import type { Toolbox } from './toolbox.js';
+import type { ActionDefinition, ActionPatch, ActionRecord, ApplyResult, ToolPatch } from './types.js';
+type UpdatePort = Pick<Toolbox, 'action' | 'apply' | 'get'>;
+declare function updateTool(toolbox: UpdatePort, toolId: string, patch: ToolPatch): Promise<ApplyResult>;
+declare function upsertAction(toolbox: UpdatePort, toolId: string, definition: ActionDefinition): Promise<ActionRecord>;
+declare function updateAction(toolbox: UpdatePort, actionId: string, patch: ActionPatch): Promise<ActionRecord>;
+export { updateAction, updateTool, upsertAction };

package/dist/updates.js

@@ -0,0 +1,57 @@
+function actionDefinition(action) {
+    const { id, toolId: _toolId, createdAt: _createdAt, updatedAt: _updatedAt, ...definition } = action;
+    return { ...structuredClone(definition), id };
+}
+function toolDefinition(result) {
+    const { createdAt: _createdAt, updatedAt: _updatedAt, ...tool } = result.tool;
+    return { ...structuredClone(tool), actions: result.actions.map(actionDefinition) };
+}
+function mergedObject(current, patch) {
+    return patch === undefined ? current : { ...(current || {}), ...patch };
+}
+async function updateTool(toolbox, toolId, patch) {
+    const current = toolbox.get(toolId);
+    if (!current)
+        throw new Error(`Unknown tool: ${toolId}`);
+    const definition = toolDefinition(current);
+    return toolbox.apply({
+        ...definition,
+        ...patch,
+        id: definition.id,
+        source: mergedObject(definition.source, patch.source),
+        display: mergedObject(definition.display, patch.display),
+        policy: mergedObject(definition.policy, patch.policy),
+        metadata: mergedObject(definition.metadata, patch.metadata),
+        actions: patch.actions === undefined ? definition.actions : patch.actions,
+    });
+}
+async function upsertAction(toolbox, toolId, definition) {
+    const current = toolbox.get(toolId);
+    if (!current)
+        throw new Error(`Unknown tool: ${toolId}`);
+    const actions = current.actions.map(actionDefinition);
+    const canonicalId = `${current.tool.id}.${definition.name}`;
+    const index = actions.findIndex((action) => action.id === canonicalId);
+    if (index === -1)
+        actions.push(definition);
+    else
+        actions[index] = definition;
+    const result = await toolbox.apply({ ...toolDefinition(current), actions });
+    return result.actions.find((action) => action.id === canonicalId);
+}
+async function updateAction(toolbox, actionId, patch) {
+    const current = toolbox.action(actionId);
+    if (!current)
+        throw new Error(`Unknown action: ${actionId}`);
+    const definition = actionDefinition(current);
+    return upsertAction(toolbox, current.toolId, {
+        ...definition,
+        ...patch,
+        id: definition.id,
+        name: definition.name,
+        target: mergedObject(definition.target, patch.target),
+        policy: mergedObject(definition.policy, patch.policy),
+        metadata: mergedObject(definition.metadata, patch.metadata),
+    });
+}
+export { updateAction, updateTool, upsertAction };

package/docs/ENGINE_INTEGRATION.md

@@ -0,0 +1,57 @@
+# Engine integration
+
+`@amalgm/tools` is the canonical Tools and Toolbox product. Amalgm Engine is a
+composition root and must adapt this public service rather than maintain a
+second registry.
+
+## Tools owns
+
+- tool and action definition, validation, identity, and persistence;
+- atomic apply, enable, disable, and removal behavior;
+- loadout selection semantics and deterministic MCP action names;
+- CLI and HTTP API execution drivers and output bounds;
+- SDK, CLI, Toolbox management MCP tools, and action MCP projection;
+- the connection projection consumed by an MCP session host.
+
+## Engine owns
+
+- first-party action implementations supplied as `systemTools` and drivers;
+- authenticated capability context and the execution-time secret resolver;
+- the long-lived MCP connection/session host;
+- state-event projection, REST shape translation, UI composition, and one-time
+  import from Engine's superseded Toolbox tables or JSON file.
+
+Agents owns agent records and their loadout ids. Tools treats those ids as
+input to product-owned selection. Neither product is allowed to rewrite the
+other through a Core adapter.
+
+Engine adapters call one `Toolbox` instance. They do not write its SQLite
+database or independently normalize, select, name, or execute tool actions.
+An absent loadout must be passed as `undefined`; an explicitly empty loadout
+must be passed as `[]`.
+
+For external MCP tools, Engine supplies a `ToolDriver` with type `mcp`. That
+driver delegates to Engine's existing MCP session owner. The Toolbox exposes
+connection definitions through `connections(loadout)` but never starts a
+parallel client or owns the same remote session twice.
+
+System tools are injected at construction and remain outside user storage.
+Engine can therefore update its built-in catalog with its own release while
+all standalone Toolbox behavior remains canonical in this package.
+
+## Source flow and completed cutover
+
+Engine now consumes Tools as follows:
+
+1. Build this repository.
+2. Copy generated `dist/`, `PURPOSE.md`, and package metadata into
+   `runtime/products/tools/` with a deterministic source manifest.
+3. Mount the package CLI and MCP definitions over Engine's single Toolbox
+   service.
+4. Import existing records once, preserving canonical ids and status.
+5. Remove Engine's superseded Toolbox tables after successful import.
+
+Product changes begin here. Generated Engine copies are never edited by hand.
+Engine runtime readers and writers use only this product database. The importer
+is the only module allowed to understand the superseded storage shapes, and
+malformed source data blocks destructive cleanup.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@amalgm/tools",
+  "version": "0.1.0",
+  "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
+  "license": "UNLICENSED",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amalgm-inc/amalgm-tools.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "default": "./dist/mcp.js"
+    }
+  },
+  "bin": {
+    "amalgm-tools": "./dist/bin/tools.js",
+    "amalgm-tools-mcp": "./dist/bin/mcp.js"
+  },
+  "files": [
+    "docs",
+    "dist",
+    "PURPOSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
+    "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+    "test": "tsx --test --test-concurrency=1 --test-timeout=30000 test/*.test.ts",
+    "verify": "npm run check && npm run build && npm test",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@amalgm/core": "^0.1.0",
+    "better-sqlite3": "^12.6.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.19.43",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3"
+  }
+}