@amalgm/tools 0.1.7-preview.34746901886 → 0.1.7-preview.34938534039

package/dist/credential-operations.js

@@ -0,0 +1,37 @@
+const stores = new WeakMap();
+/** All credential writes share an order; a stale refresh never recreates a deletion. */
+export function credentialOperations(store) {
+    const existing = stores.get(store);
+    if (existing)
+        return existing;
+    const pending = new Map();
+    async function ordered(reference, operation) {
+        const previous = pending.get(reference) || Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        pending.set(reference, current);
+        try {
+            return await current;
+        }
+        finally {
+            if (pending.get(reference) === current)
+                pending.delete(reference);
+        }
+    }
+    const wrapper = {
+        get: (reference) => ordered(reference, () => store.get(reference)),
+        set: (reference, value) => ordered(reference, () => store.set(reference, value)),
+        delete: (reference) => ordered(reference, () => store.delete(reference)),
+        replace: (reference, expected, value) => ordered(reference, async () => {
+            if (await store.get(reference) !== expected)
+                return false;
+            if (value === undefined)
+                await store.delete(reference);
+            else
+                await store.set(reference, value);
+            return true;
+        }),
+    };
+    stores.set(store, wrapper);
+    stores.set(wrapper, wrapper);
+    return wrapper;
+}

package/dist/definition.js

@@ -68,15 +68,16 @@ function normalizeSource(source) {
             ...(refs(source.secretEnv, 'source.secretEnv') ? { secretEnv: refs(source.secretEnv, 'source.secretEnv') } : {}),
         };
     }
-    if (source.type === 'api') {
-        const url = new URL(string(source.baseUrl, 'source.baseUrl'));
+    if (source.type === 'api' || source.type === 'graphql') {
+        const url = new URL(string(source.type === 'api' ? source.baseUrl : source.url, 'source URL'));
         if (!['http:', 'https:'].includes(url.protocol))
             throw new Error('source.baseUrl must use http or https');
         if (url.username || url.password)
             throw new Error('source.baseUrl cannot contain credentials');
         return {
-            type: 'api', baseUrl: url.toString(), ...base(source),
+            ...(source.type === 'api' ? { type: 'api', baseUrl: url.toString() } : { type: 'graphql', url: url.toString() }), ...base(source),
             ...(refs(source.secretHeaders, 'source.secretHeaders') ? { secretHeaders: refs(source.secretHeaders, 'source.secretHeaders') } : {}),
+            ...(refs(source.secretQuery, 'source.secretQuery') ? { secretQuery: refs(source.secretQuery, 'source.secretQuery') } : {}),
         };
     }
     if (source.type === 'mcp') {
@@ -102,6 +103,7 @@ function normalizeSource(source) {
             ...(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.secretQuery, 'source.secretQuery') ? { secretQuery: refs(source.secretQuery, 'source.secretQuery') } : {}),
             ...(refs(source.secretEnv, 'source.secretEnv') ? { secretEnv: refs(source.secretEnv, 'source.secretEnv') } : {}),
         };
     }
@@ -125,6 +127,11 @@ function target(type, value) {
         return { ...(strings(raw.args, 'action.target.args') ? { args: strings(raw.args, 'action.target.args') } : {}) };
     if (type === 'api')
         return { method: string(raw.method, 'action.target.method').toUpperCase(), path: string(raw.path, 'action.target.path') };
+    if (type === 'graphql')
+        return {
+            document: string(raw.document, 'action.target.document'),
+            ...(raw.operationName ? { operationName: string(raw.operationName, 'action.target.operationName') } : {}),
+        };
     return { name: string(raw.name, 'action.target.name') };
 }
 function normalizeDefinition(definition, existing, now = new Date().toISOString()) {

package/dist/http-mutations.d.ts

@@ -0,0 +1,63 @@
+import type { Toolbox } from './toolbox.js';
+export declare function mutateToolbox(toolbox: Toolbox, method: string, pathname: string, value: unknown): Promise<{
+    status: number;
+    body: {
+        url: string;
+        state: string;
+        toolId: string;
+    };
+} | {
+    status: number;
+    body: {
+        ok: boolean;
+        tool?: undefined;
+        actions?: undefined;
+        deleted?: undefined;
+        error?: undefined;
+    };
+} | {
+    status: number;
+    body: {
+        ok: boolean;
+        tool: {
+            type: "cli" | "api" | "graphql" | "mcp";
+            origin: import("./types.js").Origin;
+            status: import("./types.js").Status;
+            owner: string;
+            createdAt: string;
+            updatedAt: string;
+            description?: string | undefined;
+            name: string;
+            id: string;
+            policy?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            appId?: string | undefined;
+            source: import("./types.js").ToolSource;
+            display?: Record<string, unknown> | undefined;
+        };
+        actions: import("./types.js").ActionRecord[];
+        deleted?: undefined;
+        error?: undefined;
+    };
+} | {
+    status: number;
+    body: {
+        ok: boolean;
+        deleted: boolean;
+        tool?: undefined;
+        actions?: undefined;
+        error?: undefined;
+    };
+} | {
+    status: number;
+    body: import("./types.js").ToolResult;
+} | {
+    status: number;
+    body: {
+        error: string;
+        ok?: undefined;
+        tool?: undefined;
+        actions?: undefined;
+        deleted?: undefined;
+    };
+}>;

package/dist/http-mutations.js

@@ -0,0 +1,41 @@
+export async function mutateToolbox(toolbox, method, pathname, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Toolbox request must be an object');
+    const body = value;
+    if (pathname === '/toolbox/oauth/authorize' && method === 'POST') {
+        return { status: 200, body: await toolbox.authorization.begin(body) };
+    }
+    if (pathname === '/toolbox/oauth/callback' && method === 'POST') {
+        await toolbox.authorization.complete({ state: String(body.state || ''), code: String(body.code || '') });
+        return { status: 200, body: { ok: true } };
+    }
+    if (pathname === '/toolbox/tools') {
+        if (method === 'POST') {
+            const result = await toolbox.connect(body);
+            return { status: 200, body: { ok: true, tool: { ...result.tool, type: result.tool.source.type }, actions: result.actions } };
+        }
+        if (method === 'PATCH') {
+            const toolId = typeof body.id === 'string' ? body.id : '';
+            if (body.status === 'disabled') {
+                const result = await toolbox.disconnect(toolId);
+                return { status: 200, body: { ok: true, tool: { ...result.tool, type: result.tool.source.type }, actions: result.actions } };
+            }
+            if (body.status === 'enabled') {
+                const current = toolbox.get(toolId);
+                if (!current)
+                    throw new Error(`Unknown tool: ${toolId}`);
+                const result = await toolbox.connect({ definition: { ...current.tool, actions: current.actions } });
+                return { status: 200, body: { ok: true, tool: { ...result.tool, type: result.tool.source.type }, actions: result.actions } };
+            }
+            throw new Error('Tool status must be enabled or disabled; reconnect with a complete definition to edit it');
+        }
+        if (method === 'DELETE') {
+            await toolbox.remove(typeof body.id === 'string' ? body.id : '');
+            return { status: 200, body: { ok: true, deleted: true } };
+        }
+    }
+    if (pathname === '/toolbox/actions/call' && method === 'POST') {
+        return { status: 200, body: await toolbox.call(typeof body.id === 'string' ? body.id : '', body.input) };
+    }
+    return { status: 405, body: { error: 'method not allowed' } };
+}

package/dist/http.d.ts

@@ -12,9 +12,8 @@ import type { Catalog, ToolboxOptions } from './types.js';
  * - `GET /toolbox/actions?id=...` returns one action;
  * - domain errors are JSON with status 400; unknown routes are 404.
  *
- * Mutation routes remain deliberately absent until their engine record fields
- * are represented losslessly by the SDK. Returning 405 is honest; translating
- * them approximately would turn a visible parity gap into data loss.
+ * Mutation routes consume current SDK definitions. The authenticated composing
+ * host supplies the Toolbox owner; request bodies cannot select one.
  */
 type Json = Record<string, unknown>;
 interface ToolboxHttpServer {

package/dist/http.js

@@ -1,6 +1,7 @@
 import { createServer } from 'node:http';
 import { toolboxIndexDocument } from './artifacts.js';
 import { Toolbox } from './toolbox.js';
+import { mutateToolbox } from './http-mutations.js';
 function sourceWithoutType(source) {
     const { type: _type, ...value } = source;
     return value;
@@ -25,8 +26,13 @@ function catalogDocument(catalog) {
 }
 async function readBody(req) {
     const chunks = [];
-    for await (const chunk of req)
+    let size = 0;
+    for await (const chunk of req) {
+        size += Buffer.byteLength(chunk);
+        if (size > 2 * 1024 * 1024)
+            throw new Error('Toolbox request exceeds 2 MiB');
         chunks.push(Buffer.from(chunk));
+    }
     if (chunks.length === 0)
         return {};
     return JSON.parse(Buffer.concat(chunks).toString('utf8'));
@@ -45,8 +51,8 @@ function createToolboxHttpServer(options = {}) {
             try {
                 if (method !== 'GET') {
                     if (url.pathname.startsWith('/toolbox')) {
-                        await readBody(req);
-                        send(405, { error: 'method not allowed' });
+                        const result = await mutateToolbox(toolbox, method, url.pathname, await readBody(req));
+                        send(result.status, result.body);
                         return;
                     }
                     send(404, { error: 'not found' });

package/dist/index.d.ts

@@ -17,5 +17,10 @@ export type { EmailDelivery, EmailDeliveryReceipt, EmailNotificationRequest, Not
 export { createProxyEmailDelivery } from './proxy-email.js';
 export type { ProxyEmailDeliveryOptions } from './proxy-email.js';
 export { Toolbox } from './toolbox.js';
+export { createMcpDriver } from './mcp-driver.js';
+export type { McpClientPort, McpConnectionEffect } from './mcp-driver.js';
+export type { ConnectToolInput, ConnectionCredentials, OAuthCredential, ToolCredentialStore } from './connection-types.js';
+export { normalizeLoadout } from './loadout.js';
+export type { ToolAuthorizationInput } from './oauth.js';
 export type { ToolboxView as PreparedToolbox } from './toolbox-view.js';
 export type * from './types.js';

package/dist/index.js

@@ -12,3 +12,5 @@ export { createMcpServer } from './mcp-server.js';
 export { Notifications, createNotificationsDriver, notificationToolDefinition, } from './notifications.js';
 export { createProxyEmailDelivery } from './proxy-email.js';
 export { Toolbox } from './toolbox.js';
+export { createMcpDriver } from './mcp-driver.js';
+export { normalizeLoadout } from './loadout.js';

package/dist/input.js

@@ -1,43 +1,18 @@
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
 function objectInput(value) {
     if (value === undefined)
         return {};
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Tool input must be an object');
-    }
     return value;
 }
-function matchesType(value, type) {
-    if (type === 'array')
-        return Array.isArray(value);
-    if (type === 'integer')
-        return Number.isInteger(value);
-    if (type === 'number')
-        return typeof value === 'number' && Number.isFinite(value);
-    if (type === 'object')
-        return !!value && typeof value === 'object' && !Array.isArray(value);
-    if (type === 'null')
-        return value === null;
-    return typeof value === type;
-}
 function validateInput(schema, value) {
     const input = objectInput(value);
-    for (const key of schema.required || []) {
-        if (!(key in input))
-            throw new Error(`Tool input is missing required property: ${key}`);
-    }
-    if (schema.additionalProperties === false) {
-        const known = new Set(Object.keys(schema.properties || {}));
-        const extra = Object.keys(input).find((key) => !known.has(key));
-        if (extra)
-            throw new Error(`Tool input contains unknown property: ${extra}`);
-    }
-    for (const [key, property] of Object.entries(schema.properties || {})) {
-        if (!(key in input) || !property.type)
-            continue;
-        if (!matchesType(input[key], property.type)) {
-            throw new Error(`Tool input property ${key} must be ${property.type}`);
-        }
-    }
+    // Schemas may reuse $id across unrelated tools; compilation has no global namespace.
+    const validate = new AjvJsonSchemaValidator().getValidator(schema);
+    const result = validate(input);
+    if (!result.valid)
+        throw new Error(`Invalid tool input: ${result.errorMessage}`);
     return input;
 }
 export { objectInput, validateInput };

package/dist/loadout.d.ts

@@ -0,0 +1,3 @@
+import type { Loadout, LoadoutInput, ToolExposure } from './types.js';
+export declare function normalizeLoadout(input: LoadoutInput): Loadout;
+export declare function actionExposure(loadout: LoadoutInput | undefined, toolId: string, actionId: string): ToolExposure;

package/dist/loadout.js

@@ -0,0 +1,23 @@
+export function normalizeLoadout(input) {
+    const raw = Array.isArray(input) ? { toolIds: input } : input;
+    if (!raw || !Array.isArray(raw.toolIds) || raw.toolIds.some((id) => typeof id !== 'string' || !id)) {
+        throw new Error('Loadout requires toolIds');
+    }
+    const exposure = {};
+    if (raw.exposure !== undefined) {
+        if (!raw.exposure || typeof raw.exposure !== 'object' || Array.isArray(raw.exposure)) {
+            throw new Error('Loadout exposure must be a map of ids to direct, search, or hidden');
+        }
+        for (const [id, mode] of Object.entries(raw.exposure).sort(([a], [b]) => a.localeCompare(b))) {
+            if (!id || !['direct', 'search', 'hidden'].includes(mode))
+                throw new Error(`Invalid tool exposure: ${id}`);
+            exposure[id] = mode;
+        }
+    }
+    return { toolIds: [...new Set(raw.toolIds)].sort(), ...(Object.keys(exposure).length ? { exposure } : {}) };
+}
+export function actionExposure(loadout, toolId, actionId) {
+    if (!loadout || Array.isArray(loadout))
+        return 'direct';
+    return loadout.exposure?.[actionId] ?? loadout.exposure?.[toolId] ?? 'direct';
+}

package/dist/mcp-driver.d.ts

@@ -0,0 +1,16 @@
+import type { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpSource, ToolDriver } from './types.js';
+export interface McpConnectionEffect {
+    source: McpSource;
+    headers: Record<string, string>;
+    env: Record<string, string>;
+    query?: Record<string, string>;
+    signal?: AbortSignal;
+    context?: unknown;
+}
+/** One composing host owns upstream transports and their native effects. */
+export interface McpClientPort {
+    list(connection: McpConnectionEffect): Promise<Tool[]>;
+    call(connection: McpConnectionEffect, name: string, input: Record<string, unknown>): Promise<CallToolResult>;
+}
+export declare function createMcpDriver(port: McpClientPort): ToolDriver;

package/dist/mcp-driver.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { boundedResult } from './results.js';
+import { resolveReferences } from './secrets.js';
+function storedActionName(name) {
+    if (/^[a-z0-9][a-z0-9_-]{0,47}$/.test(name))
+        return name;
+    const label = name.toLowerCase().replace(/[^a-z0-9_-]+/g, '_').replace(/^[_-]+/, '').slice(0, 28) || 'action';
+    return `${label}-${createHash('sha256').update(name).digest('hex').slice(0, 16)}`;
+}
+export function createMcpDriver(port) {
+    async function connection(tool, options) {
+        if (tool.source.type !== 'mcp')
+            throw new Error('MCP source required');
+        const source = tool.source;
+        return {
+            source,
+            query: await resolveReferences(source.secretQuery, options.resolveSecret),
+            headers: await resolveReferences(source.secretHeaders, options.resolveSecret),
+            env: await resolveReferences(source.secretEnv, options.resolveSecret),
+            signal: options.signal, context: options.context,
+        };
+    }
+    return {
+        type: 'mcp',
+        async discover(tool, options) {
+            const tools = await port.list(await connection(tool, options));
+            return tools.map((tool) => ({
+                name: storedActionName(tool.name), displayName: tool.title || tool.name,
+                ...(tool.description ? { description: tool.description } : {}),
+                inputSchema: tool.inputSchema,
+                ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+                target: { name: tool.name },
+                ...(tool.annotations || tool._meta ? { metadata: {
+                        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+                        ...(tool._meta ? { _meta: tool._meta } : {}),
+                    } } : {}),
+            }));
+        },
+        async call({ tool, action, input, options }) {
+            const result = await port.call(await connection(tool, options), action.target.name, input);
+            return boundedResult(result, tool.source.maxOutputBytes);
+        },
+    };
+}

package/dist/mcp-search.d.ts

@@ -0,0 +1,8 @@
+import type { Toolbox } from './toolbox.js';
+import type { ToolboxView } from './toolbox-view.js';
+import type { ActionRecord, McpOptions, McpTool, ToolRecord } from './types.js';
+/** Search is a presentation of the same immutable grant, never another catalog. */
+export declare function searchTools(toolbox: Toolbox | ToolboxView, selected: Array<{
+    tool: ToolRecord;
+    action: ActionRecord;
+}>, options: McpOptions): McpTool[];

package/dist/mcp-search.js

@@ -0,0 +1,51 @@
+import { mcpName } from './ids.js';
+import { errorResult, structuredResult } from './results.js';
+/** Search is a presentation of the same immutable grant, never another catalog. */
+export function searchTools(toolbox, selected, options) {
+    if (!selected.length)
+        return [];
+    return [{
+            name: 'toolbox_search',
+            description: 'Find available tool actions by name or description. Use toolbox_call with a returned action id and its input schema.',
+            inputSchema: {
+                type: 'object', properties: { query: { type: 'string' } }, required: ['query'], additionalProperties: false,
+            },
+            async handler(input = {}) {
+                if (typeof input.query !== 'string')
+                    return errorResult('query must be a string');
+                const words = input.query.toLowerCase().split(/\s+/).filter(Boolean);
+                const available = new Set(toolbox.callable(options.loadout).map(({ action }) => action.id));
+                const matches = selected.filter(({ tool, action }) => {
+                    if (!available.has(action.id))
+                        return false;
+                    const text = [tool.name, action.id, action.displayName, action.description].join(' ').toLowerCase();
+                    return words.every((word) => text.includes(word));
+                });
+                return structuredResult({
+                    actions: matches.slice(0, 50).map(({ action }) => ({
+                        id: action.id, name: mcpName(action), description: action.description || action.displayName || action.name,
+                        inputSchema: action.inputSchema,
+                        ...(action.outputSchema ? { outputSchema: action.outputSchema } : {}),
+                    })),
+                    hasMore: matches.length > 50,
+                });
+            },
+        }, {
+            name: 'toolbox_call',
+            description: 'Execute one action returned by toolbox_search with arguments matching its input schema.',
+            inputSchema: {
+                type: 'object', properties: { id: { type: 'string' }, input: { type: 'object' } },
+                required: ['id', 'input'], additionalProperties: false,
+            },
+            async handler(input = {}) {
+                if (!selected.some(({ action }) => action.id === input.id))
+                    return errorResult('Action is unavailable');
+                try {
+                    return await toolbox.call(String(input.id), input.input, options);
+                }
+                catch (error) {
+                    return errorResult(error);
+                }
+            },
+        }];
+}

package/dist/mcp-types.d.ts

@@ -0,0 +1,13 @@
+import type { CallOptions, JsonSchema, ToolResult } from './types.js';
+export interface McpTool {
+    annotations?: import('@modelcontextprotocol/sdk/types.js').Tool['annotations'];
+    _meta?: Record<string, unknown>;
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: Record<string, unknown>;
+    handler(input?: Record<string, unknown>): Promise<ToolResult>;
+}
+export interface McpOptions extends CallOptions {
+    includeManagement?: boolean;
+}

package/dist/mcp-types.js

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

package/dist/mcp.js

@@ -1,12 +1,9 @@
 import { mcpName } from './ids.js';
+import { actionExposure } from './loadout.js';
+import { searchTools } from './mcp-search.js';
 import { errorResult, structuredResult } from './results.js';
 function portable(schema) {
-    const result = structuredClone(schema);
-    for (const key of ['anyOf', 'oneOf', 'allOf', 'not', 'enum'])
-        delete result[key];
-    result.type = 'object';
-    result.properties ||= {};
-    return result;
+    return structuredClone(schema);
 }
 function managed(definition, handler) {
     return {
@@ -94,19 +91,26 @@ function managementTools(toolbox, options = {}) {
     ];
 }
 function actionTools(toolbox, options = {}) {
-    return toolbox.callable(options.loadout).map(({ tool, action }) => ({
-        name: mcpName(action),
-        description: action.description || `Run ${tool.name}: ${action.displayName || action.name}.`,
-        inputSchema: portable(action.inputSchema),
-        async handler(input = {}) {
-            try {
-                return await toolbox.call(action.id, input, options);
-            }
-            catch (error) {
-                return errorResult(error);
-            }
-        },
-    }));
+    const callable = toolbox.callable(options.loadout);
+    const searchable = callable.filter(({ tool, action }) => (('exposure' in toolbox && toolbox.exposure(action) === 'search')
+        || actionExposure(options.loadout, tool.id, action.id) === 'search'));
+    const searchIds = new Set(searchable.map(({ action }) => action.id));
+    return [...callable.filter(({ action }) => !searchIds.has(action.id)).map(({ tool, action }) => ({
+            name: mcpName(action),
+            ...(action.metadata?.annotations ? { annotations: structuredClone(action.metadata.annotations) } : {}),
+            ...(action.metadata?._meta ? { _meta: structuredClone(action.metadata._meta) } : {}),
+            description: action.description || `Run ${tool.name}: ${action.displayName || action.name}.`,
+            inputSchema: portable(action.inputSchema),
+            ...(action.outputSchema ? { outputSchema: structuredClone(action.outputSchema) } : {}),
+            async handler(input = {}) {
+                try {
+                    return await toolbox.call(action.id, input, options);
+                }
+                catch (error) {
+                    return errorResult(error);
+                }
+            },
+        })), ...searchTools(toolbox, searchable, options)];
 }
 function createMcpTools(toolbox, options = {}) {
     if (options.includeManagement !== false && !('apply' in toolbox)) {

package/dist/oauth.d.ts

@@ -0,0 +1,29 @@
+import type { OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { ConnectToolInput, ToolCredentialStore } from './connection-types.js';
+import type { ApplyResult, ToolDefinition } from './types.js';
+export interface ToolAuthorizationInput {
+    definition: ToolDefinition;
+    redirectUri: string;
+    scope?: string;
+    clientId?: string;
+    clientSecret?: string;
+    /** Optional registered-provider metadata; otherwise use MCP discovery. */
+    metadata?: OAuthDiscoveryState['authorizationServerMetadata'];
+}
+export declare const authorizationReference: (toolId: string) => string;
+/** MCP's OAuth flow, with all pending and granted secrets in the host vault. */
+export declare class ToolAuthorization {
+    #private;
+    private readonly store;
+    private readonly connect;
+    constructor(store: ToolCredentialStore | undefined, connect: (input: ConnectToolInput, guard: () => Promise<void>) => Promise<ApplyResult>);
+    begin(input: ToolAuthorizationInput): Promise<{
+        url: string;
+        state: string;
+        toolId: string;
+    }>;
+    complete(input: {
+        state: string;
+        code: string;
+    }): Promise<ApplyResult>;
+}