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

package/PURPOSE.md

@@ -5,7 +5,7 @@
 Amalgm Tools lets a user define, keep, select, and run agent capabilities as a
 standalone product or inside Amalgm. It serves people building agents,
 automations, and applications that need one small local source of truth for
-CLI, HTTP API, and MCP tools. When the product is healthy, every callable
+CLI, HTTP API, GraphQL, 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.
@@ -30,6 +30,10 @@ and parity evidence only.
 - 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 **connection** is a tool's current admission to execution, with credential
+  references resolved by the host's encrypted vault; it is not another catalog.
+- **Exposure** is an agent loadout's presentation of a granted action: direct,
+  searchable, or hidden. An action override is more specific than its tool default.
 - 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;
@@ -133,6 +137,34 @@ locked dependency graph on the supported Node toolchain.
     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.
+27. Preparing an exact catalog revision captures a read-only loadout whose
+    definitions and scope cannot change. Later catalog edits affect future
+    preparation; already prepared calls use their captured definitions and the
+    host's current credential and execution effects.
+28. Disconnect disables the parent tool and removes its saved authentication;
+    it retains the definition and action schemas for reconnection. Current parent
+    admission gates every invocation, including an already prepared execution.
+    A loadout edit never connects, disconnects, or changes the parent Toolbox.
+29. A loadout grants only its selected tool/action ids. Omitted exposure means
+    direct; an explicit action exposure overrides its selected tool's exposure.
+    Hidden actions appear in neither listing, search, prompt descriptions, nor
+    invocation. Search exposes only searchable descriptors and its scoped call
+    action. An exposure entry cannot grant an unselected capability.
+30. Every tool type crosses the same scoped MCP action boundary. ACP describes
+    the server supplied to an agent; MCP describes action schemas and results.
+    Native adapters do not discover tools or decide exposure. CLI descriptions
+    may inform system instructions, but never substitute for execution admission.
+31. Connecting an MCP source discovers and stores its complete official action
+    schemas before activation. Invocation uses those captured schemas and exact
+    target names; a later remote catalog cannot expand an agent's grant.
+32. OAuth access, refresh, and client secrets remain in the host vault.
+    Header, environment, and query authentication use source-bound vault references. Refresh
+    is serialized per credential, preserves rotated tokens, and cannot restore a
+    disconnected credential. Credential references are bound to the registered
+    source, so editing an endpoint cannot send an earlier secret to a new authority.
+33. GraphQL actions store one operation document and send validated input as its
+    variables to the registered endpoint. API and GraphQL redirects never forward
+    credentials to another endpoint; callers cannot override registered targets.
 
 ## Predictable behavior
 

package/README.md

@@ -89,10 +89,14 @@ const server = createToolboxHttpServer({ toolbox });
 await server.listen(8083);
 ```
 
-The read adapter serves the legacy-compatible `GET /toolbox`,
+The adapter serves `GET /toolbox`,
 `GET /toolbox/tools?id=...`, and `GET /toolbox/actions?id=...` routes over
-the same live Toolbox used by CLI and MCP consumers. Mutation routes return
-405 until their legacy record fields can be represented without data loss.
+the same live Toolbox used by CLI and MCP consumers. `POST /toolbox/tools`
+connects a definition with optional write-only credentials. `PATCH /toolbox/tools`
+with `{ id, status: "disabled" }` disconnects it. `DELETE /toolbox/tools` removes
+it. `POST /toolbox/actions/call` invokes `{ id, input }`.
+The authenticated host selects the owner. OAuth authorization and callback
+use `POST /toolbox/oauth/authorize` and `POST /toolbox/oauth/callback`.
 
 ## Notifications
 
@@ -108,11 +112,31 @@ and must not be presented as a second Channels implementation.
 
 - `cli`: executed directly with `spawn`; a shell is never involved.
 - `api`: same-origin HTTP actions with redirects refused.
+- `graphql`: a saved operation document with validated input as its variables.
 - `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`.
+Secret values are never part of definitions. `secretEnv`, `secretHeaders`,
+and `secretQuery` contain opaque references resolved at invocation. A host
+supplies `credentials: { get, set, delete }` backed by its encrypted vault.
+`toolbox.connect({ definition, credentials })` stores authentication separately
+and discovers MCP actions before activation. `toolbox.disconnect(id)` removes
+authentication and disables execution while retaining the definition and actions.
+
+A loadout contains `toolIds` (whole-tool or action ids) and optional `exposure`:
+
+```js
+const selected = toolbox.prepare(toolbox.catalog().revisionId, {
+  toolIds: ['service'],
+  exposure: { service: 'search', 'service.read': 'direct', 'service.erase': 'hidden' },
+});
+```
+
+Direct actions are listed normally. Searchable actions are reachable only through
+`toolbox_search` and its scoped `toolbox_call`. Hidden actions cannot be listed,
+searched, or invoked. Every type uses this same MCP surface; ACP supplies the
+server to each agent adapter. A prepared view keeps its captured definitions
+but still honors a subsequent parent disconnect.
 See [PURPOSE.md](./PURPOSE.md) for the complete contract and
 [SHELL_INTEGRATION.md](./docs/SHELL_INTEGRATION.md) for active composition.
 The [Engine integration](./docs/ENGINE_INTEGRATION.md) page is historical only.

package/dist/api-driver.d.ts

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

package/dist/api-driver.js

@@ -26,13 +26,20 @@ async function readBody(response, maximum) {
             chunks.push(value.subarray(0, room));
             size += Math.min(room, value.length);
         }
+        if (truncated) {
+            await reader.cancel();
+            break;
+        }
     }
     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 });
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
     const timer = setTimeout(() => controller.abort(new Error('timeout')), timeoutMs);
     timer.unref();
     return {
@@ -40,53 +47,65 @@ function timeoutSignal(timeoutMs, parent) {
         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);
+async function callHttp({ tool, action, input, options }) {
+    const source = tool.source;
+    if (source.type !== 'api' && source.type !== 'graphql')
+        throw new Error('HTTP tool source required');
+    const target = action.target;
+    const graphql = action.target;
+    const base = new URL(source.type === 'api' ? source.baseUrl : source.url);
+    const url = source.type === 'api' ? new URL(fillPath(target.path, input), base) : base;
+    if (url.origin !== base.origin)
+        throw new Error(`API action ${action.id} leaves its registered origin`);
+    const query = source.type === 'api' ? input.query : undefined;
+    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 secretQuery = await resolveReferences(source.secretQuery, options.resolveSecret);
+    for (const [key, value] of Object.entries(secretQuery))
+        url.searchParams.set(key, value);
+    const headers = await resolveReferences(source.secretHeaders, options.resolveSecret);
+    const method = source.type === 'api' ? target.method.toUpperCase() : 'POST';
+    const requestBody = source.type === 'api' ? (input.body ?? input) : {
+        query: graphql.document, variables: input,
+        ...(graphql.operationName ? { operationName: graphql.operationName } : {}),
+    };
+    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(requestBody),
+        });
+        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 {
-            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 } : {}) };
+            const value = JSON.parse(body.text);
+            result = structuredResult(value);
+            if (source.type === 'graphql' && Array.isArray(value?.errors) && value.errors.length)
+                result.isError = true;
         }
-        catch (error) {
-            if (timed.signal.aborted)
-                return errorResult(options.signal?.aborted ? `Tool ${action.id} was cancelled` : `Tool ${action.id} timed out`);
-            throw error;
+        catch {
+            result = textResult(body.text);
         }
-        finally {
-            timed.close();
-        }
-    },
-};
-export { apiDriver };
+        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();
+    }
+}
+const apiDriver = { type: 'api', call: callHttp };
+const graphqlDriver = { type: 'graphql', call: callHttp };
+export { apiDriver, graphqlDriver };

package/dist/cli-driver.js

@@ -1,4 +1,5 @@
 import { runCommand } from './process.js';
+import { getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { errorResult, structuredResult, textResult } from './results.js';
 import { resolveReferences } from './secrets.js';
 function inputArguments(input) {
@@ -20,7 +21,7 @@ function createCliDriver(environment = () => ({})) {
                 args.push(...inputArguments(input));
             const output = await runCommand({
                 command: source.command, args, cwd: source.cwd,
-                env: { ...process.env, ...(await environment(tool)), ...secrets },
+                env: { ...getDefaultEnvironment(), ...(await environment(tool)), ...secrets },
                 stdin: source.inputMode === 'json-stdin' ? `${JSON.stringify(input)}\n` : undefined,
                 timeoutMs: source.timeoutMs, maximumBytes: source.maxOutputBytes, signal: options.signal,
             });

package/dist/commands.js

@@ -1,9 +1,10 @@
 import { isActionMcpName } from './ids.js';
 import { callMcpTool } from './mcp.js';
+import { structuredValue } from './results.js';
 function unwrap(name, result) {
     if (result.isError)
-        throw new Error(result.content.map((item) => item.text).join('\n'));
-    return isActionMcpName(name) ? result : result.structuredContent;
+        throw new Error(result.content.filter((item) => item.type === 'text').map((item) => item.text).join('\n'));
+    return isActionMcpName(name) ? result : structuredValue(result.structuredContent);
 }
 function createToolboxCommands(toolbox, loadout) {
     return {

package/dist/connection-auth.d.ts

@@ -0,0 +1,11 @@
+import type { ToolCredential, ToolCredentialStore } from './connection-types.js';
+import type { SecretResolver } from './types.js';
+export declare function validateCredential(value: ToolCredential): ToolCredential;
+/** Token refresh belongs to the connection; encryption belongs to the host. */
+export declare class ToolAuthentication {
+    #private;
+    readonly store?: ToolCredentialStore | undefined;
+    private readonly fallback?;
+    constructor(store?: ToolCredentialStore | undefined, fallback?: SecretResolver | undefined);
+    resolve: (reference: string) => Promise<string | undefined>;
+}

package/dist/connection-auth.js

@@ -0,0 +1,98 @@
+import { credentialOperations } from './credential-operations.js';
+export function validateCredential(value) {
+    if (value.type === 'secret') {
+        if (typeof value.value !== 'string' || !value.value)
+            throw new Error('A non-empty tool secret is required');
+        return { type: 'secret', value: value.value };
+    }
+    if (value.type !== 'oauth' || !value.accessToken || !value.clientId || !value.tokenUrl) {
+        throw new Error('OAuth requires accessToken, clientId, and tokenUrl');
+    }
+    const url = new URL(value.tokenUrl);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('Invalid OAuth token endpoint');
+    if (value.expiresAt && !Number.isFinite(Date.parse(value.expiresAt)))
+        throw new Error('Invalid OAuth token expiry');
+    if (value.tokenEndpointAuthMethod && !['none', 'client_secret_basic', 'client_secret_post'].includes(value.tokenEndpointAuthMethod)) {
+        throw new Error('Unsupported OAuth token endpoint authentication');
+    }
+    return structuredClone(value);
+}
+async function refresh(current) {
+    if (!current.refreshToken)
+        throw new Error('Tool authorization expired; reconnect the tool');
+    const body = new URLSearchParams({ grant_type: 'refresh_token', refresh_token: current.refreshToken, client_id: current.clientId });
+    const headers = { 'content-type': 'application/x-www-form-urlencoded' };
+    if (current.clientSecret) {
+        if (current.tokenEndpointAuthMethod === 'client_secret_basic') {
+            headers.Authorization = `Basic ${Buffer.from(`${encodeURIComponent(current.clientId)}:${encodeURIComponent(current.clientSecret)}`).toString('base64')}`;
+        }
+        else
+            body.set('client_secret', current.clientSecret);
+    }
+    if (current.scope)
+        body.set('scope', current.scope);
+    if (current.resource)
+        body.set('resource', current.resource);
+    const response = await fetch(current.tokenUrl, {
+        method: 'POST', headers, body, redirect: 'manual', signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok)
+        throw new Error(`Tool authorization refresh failed (${response.status}); reconnect the tool`);
+    const value = await response.json();
+    if (typeof value.access_token !== 'string' || !value.access_token)
+        throw new Error('OAuth refresh returned no access token');
+    if (value.token_type && String(value.token_type).toLowerCase() !== 'bearer')
+        throw new Error('Unsupported OAuth token type');
+    const { expiresAt: _previousExpiry, ...retained } = current;
+    return {
+        ...retained, accessToken: value.access_token,
+        ...(typeof value.refresh_token === 'string' && value.refresh_token ? { refreshToken: value.refresh_token } : {}),
+        ...(typeof value.expires_in === 'number' && value.expires_in > 0 ? { expiresAt: new Date(Date.now() + value.expires_in * 1000).toISOString() } : {}),
+        ...(typeof value.scope === 'string' ? { scope: value.scope } : {}),
+    };
+}
+/** Token refresh belongs to the connection; encryption belongs to the host. */
+export class ToolAuthentication {
+    store;
+    fallback;
+    #refreshing = new Map();
+    constructor(store, fallback) {
+        this.store = store;
+        this.fallback = fallback;
+        this.store = store && credentialOperations(store);
+    }
+    resolve = async (reference) => {
+        if (!reference.startsWith('tools:'))
+            return this.fallback?.(reference);
+        const pending = this.#refreshing.get(reference);
+        if (pending)
+            return pending;
+        const work = this.#resolve(reference);
+        this.#refreshing.set(reference, work);
+        try {
+            return await work;
+        }
+        finally {
+            if (this.#refreshing.get(reference) === work)
+                this.#refreshing.delete(reference);
+        }
+    };
+    async #resolve(reference) {
+        const encoded = await this.store?.get(reference);
+        if (encoded === undefined)
+            return undefined;
+        const credential = validateCredential(JSON.parse(encoded));
+        if (credential.type === 'secret')
+            return credential.value;
+        if (!credential.expiresAt || Date.parse(credential.expiresAt) > Date.now() + 30_000) {
+            return `Bearer ${credential.accessToken}`;
+        }
+        const renewed = await refresh(credential);
+        // A disconnect or a new authorization wins over an in-flight refresh.
+        if (!await credentialOperations(this.store).replace(reference, encoded, JSON.stringify(renewed))) {
+            throw new Error('Tool authorization changed during refresh');
+        }
+        return `Bearer ${renewed.accessToken}`;
+    }
+}

package/dist/connection-source.d.ts

@@ -0,0 +1,23 @@
+import type { ConnectToolInput } from './connection-types.js';
+import type { ActionDefinition, ToolSource } from './types.js';
+export declare function sourceReferences(source: ToolSource): string[];
+/** Credentials are authority-bound references, never portable definition bytes. */
+export declare function connectionSource(input: ConnectToolInput): {
+    definition: {
+        source: ToolSource;
+        status: "enabled";
+        actions: ActionDefinition[];
+        origin: import("./types.js").Origin;
+        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;
+        display?: Record<string, unknown> | undefined;
+    };
+    staged: Map<string, string>;
+};

package/dist/connection-source.js

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './deployments.js';
+import { normalizeDefinition } from './definition.js';
+import { validateCredential } from './connection-auth.js';
+export function sourceReferences(source) {
+    return [...new Set([
+            ...('secretHeaders' in source ? Object.values(source.secretHeaders || {}) : []),
+            ...('secretQuery' in source ? Object.values(source.secretQuery || {}) : []),
+            ...('secretEnv' in source ? Object.values(source.secretEnv || {}) : []),
+        ])];
+}
+/** Credentials are authority-bound references, never portable definition bytes. */
+export function connectionSource(input) {
+    const { tool, actions } = normalizeDefinition(input.definition);
+    if (tool.origin === 'system' || (tool.source.type === 'mcp' && tool.source.transport === 'host')) {
+        throw new Error('Host-owned tools cannot be connected by a user');
+    }
+    const source = structuredClone(tool.source);
+    const identity = { ...source };
+    delete identity.secretHeaders;
+    delete identity.secretEnv;
+    delete identity.secretQuery;
+    const authority = createHash('sha256').update(canonicalJson(identity)).digest('hex').slice(0, 24);
+    const prefix = `tools:${tool.id}:${authority}:`;
+    const staged = new Map();
+    const add = (surface, name, value) => {
+        if (!name || /[\r\n]/.test(name))
+            throw new Error('Invalid tool credential field');
+        const field = surface === 'headers' ? 'secretHeaders' : surface === 'query' ? 'secretQuery' : 'secretEnv';
+        if (surface !== 'env' && (source.type === 'cli' || (source.type === 'mcp' && source.transport === 'stdio'))) {
+            throw new Error('This tool uses environment credentials, not HTTP headers');
+        }
+        if (surface === 'env' && source.type !== 'cli' && !(source.type === 'mcp' && source.transport === 'stdio')) {
+            throw new Error('This tool uses HTTP header credentials, not environment variables');
+        }
+        const target = source;
+        const refs = { ...target[field] };
+        const canonicalName = surface === 'headers' ? name.toLowerCase() : name;
+        for (const existing of Object.keys(refs))
+            if ((surface === 'headers' ? existing.toLowerCase() : existing) === canonicalName)
+                delete refs[existing];
+        const reference = `${prefix}${surface}:${canonicalName}`;
+        refs[name] = reference;
+        target[field] = refs;
+        staged.set(reference, JSON.stringify(validateCredential(value)));
+    };
+    for (const [name, value] of Object.entries(input.credentials?.headers || {}))
+        add('headers', name, { type: 'secret', value });
+    for (const [name, value] of Object.entries(input.credentials?.query || {}))
+        add('query', name, { type: 'secret', value });
+    for (const [name, value] of Object.entries(input.credentials?.env || {}))
+        add('env', name, { type: 'secret', value });
+    if (input.credentials?.oauth) {
+        const resource = source.type === 'mcp' ? source.url : source.type === 'graphql' ? source.url : source.type === 'api' ? source.baseUrl : undefined;
+        add('headers', 'Authorization', { ...input.credentials.oauth, type: 'oauth', ...(resource ? { resource } : {}) });
+    }
+    for (const ref of sourceReferences(source)) {
+        if (!ref.startsWith(prefix))
+            throw new Error('Tool credential reference belongs to another source; reconnect with its credentials');
+    }
+    return { definition: { ...tool, source, status: 'enabled', actions: actions }, staged };
+}

package/dist/connection-types.d.ts

@@ -0,0 +1,34 @@
+import type { ToolDefinition } from './types.js';
+/** The host owns encryption and physical persistence; Tools owns these bytes. */
+export interface ToolCredentialStore {
+    get(reference: string): string | undefined | Promise<string | undefined>;
+    set(reference: string, value: string): void | Promise<void>;
+    delete(reference: string): void | Promise<void>;
+}
+export interface OAuthCredential {
+    type: 'oauth';
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret?: string;
+    tokenEndpointAuthMethod?: 'client_secret_basic' | 'client_secret_post' | 'none';
+    scope?: string;
+    resource?: string;
+}
+export type ToolCredential = {
+    type: 'secret';
+    value: string;
+} | OAuthCredential;
+export interface ConnectionCredentials {
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    env?: Record<string, string>;
+    oauth?: OAuthCredential;
+}
+export interface ConnectToolInput {
+    definition: ToolDefinition;
+    /** Write-only. Values never enter the definition, response, or deployment. */
+    credentials?: ConnectionCredentials;
+}

package/dist/connection-types.js

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

package/dist/connections.d.ts

@@ -0,0 +1,14 @@
+import type { ConnectToolInput, ToolCredentialStore } from './connection-types.js';
+import type { Toolbox } from './toolbox.js';
+import type { ToolDriver, ToolRecord } from './types.js';
+/** Connection transitions mutate the one Toolbox and the host-owned vault. */
+export declare class ToolConnections {
+    #private;
+    private readonly toolbox;
+    private readonly drivers;
+    private readonly store?;
+    constructor(toolbox: Toolbox, drivers: ReadonlyMap<string, ToolDriver>, store?: ToolCredentialStore | undefined);
+    connect(input: ConnectToolInput, guard?: () => Promise<void>): Promise<import("./types.js").ApplyResult>;
+    disconnect(toolId: string): Promise<import("./types.js").ApplyResult>;
+    forget(tool: ToolRecord, retained?: Set<string>): Promise<void>;
+}

package/dist/connections.js

@@ -0,0 +1,98 @@
+import { credentialOperations } from './credential-operations.js';
+import { ToolAuthentication } from './connection-auth.js';
+import { authorizationReference } from './oauth.js';
+import { connectionSource, sourceReferences } from './connection-source.js';
+/** Connection transitions mutate the one Toolbox and the host-owned vault. */
+export class ToolConnections {
+    toolbox;
+    drivers;
+    store;
+    #pending = new Map();
+    constructor(toolbox, drivers, store) {
+        this.toolbox = toolbox;
+        this.drivers = drivers;
+        this.store = store;
+        this.store = store && credentialOperations(store);
+    }
+    connect(input, guard) {
+        const { definition, staged } = connectionSource(input);
+        return this.#ordered(definition.id, async () => {
+            await guard?.();
+            if (this.toolbox.isSystemTool(definition.id))
+                throw new Error('System tools are immutable');
+            if (staged.size && !this.store)
+                throw new Error('Tool credential vault is unavailable');
+            const previous = this.toolbox.get(definition.id)?.tool;
+            const original = new Map();
+            const overlay = {
+                get: (ref) => staged.has(ref) ? staged.get(ref) : this.store?.get(ref),
+                set: (ref, value) => { staged.set(ref, value); },
+                delete: (ref) => { staged.delete(ref); },
+            };
+            const auth = new ToolAuthentication(overlay);
+            for (const ref of sourceReferences(definition.source)) {
+                if (await auth.resolve(ref) === undefined)
+                    throw new Error('Tool authorization is missing; reconnect with credentials');
+            }
+            const driver = this.drivers.get(definition.source.type);
+            if (!driver || !(driver.supports?.(definition) ?? true))
+                throw new Error(`No ${definition.source.type} driver is configured`);
+            if (definition.source.type === 'mcp') {
+                if (!driver.discover)
+                    throw new Error('MCP action discovery is unavailable');
+                definition.actions = await driver.discover(definition, { resolveSecret: auth.resolve });
+            }
+            try {
+                await guard?.();
+                for (const [ref, value] of staged) {
+                    original.set(ref, await this.store.get(ref));
+                    await this.store.set(ref, value);
+                }
+                const result = await this.toolbox.apply(definition);
+                await this.store?.delete(authorizationReference(definition.id));
+                if (previous) {
+                    const retained = new Set(sourceReferences(result.tool.source));
+                    await this.forget(previous, retained);
+                }
+                return result;
+            }
+            catch (error) {
+                for (const [ref, value] of original) {
+                    if (value === undefined)
+                        await this.store.delete(ref);
+                    else
+                        await this.store.set(ref, value);
+                }
+                throw error;
+            }
+        });
+    }
+    disconnect(toolId) {
+        return this.#ordered(toolId, async () => {
+            const current = this.toolbox.get(toolId);
+            if (!current)
+                throw new Error(`Unknown tool: ${toolId}`);
+            await this.toolbox.setStatus(toolId, 'disabled');
+            return this.toolbox.get(toolId);
+        });
+    }
+    async forget(tool, retained = new Set()) {
+        await this.store?.delete(authorizationReference(tool.id));
+        for (const ref of sourceReferences(tool.source)) {
+            if (ref.startsWith(`tools:${tool.id}:`) && !retained.has(ref))
+                await this.store?.delete(ref);
+        }
+    }
+    async #ordered(key, operation) {
+        const previous = this.#pending.get(key) || Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        this.#pending.set(key, current);
+        try {
+            return await current;
+        }
+        finally {
+            if (this.#pending.get(key) === current)
+                this.#pending.delete(key);
+        }
+    }
+}

package/dist/credential-operations.d.ts

@@ -0,0 +1,7 @@
+import type { ToolCredentialStore } from './connection-types.js';
+interface SerializedStore extends ToolCredentialStore {
+    replace(reference: string, expected: string | undefined, value: string | undefined): Promise<boolean>;
+}
+/** All credential writes share an order; a stale refresh never recreates a deletion. */
+export declare function credentialOperations(store: ToolCredentialStore): SerializedStore;
+export {};