@stacklink/sdk 0.2.0 → 0.3.7

package/dist/src/sdk/index.js

@@ -1,8 +1,7 @@
+import { botApiSignaturePayload } from '../domain/bot-contract.js';
 import { materializeStacklinkWorkbenchExecutionResponse, } from '../domain/stacklink-meta-tools.js';
-import { platformMcpTools } from '../domain/platform-mcp-tools.js';
 export { StacklinkMemoryLifecycle, StacklinkMemoryLifecycleError, createStacklinkMemoryLifecycle, serializeCompletedConversationTurn, } from './memory-lifecycle.js';
-export const platformToolSurfaceNames = platformMcpTools;
-export const stacklinkTypeScriptSdkVersion = '0.2.0';
+export const stacklinkTypeScriptSdkVersion = '0.3.7';
 const workbenchReusableRunComparisonWaitMs = 120_000;
 const workbenchReusableRunComparisonPollMs = 1_000;
 export class StacklinkApiError extends Error {
@@ -17,6 +16,18 @@ export class StacklinkApiError extends Error {
         this.name = 'StacklinkApiError';
     }
 }
+function providerCatalogSdkQuery(input) {
+    return {
+        limit: input.limit,
+        cursor: input.cursor,
+        search: input.search,
+        providerKey: input.providerKeys,
+        categoryKey: input.categoryKeys,
+        projectStatus: input.projectStatus,
+        connectionStatus: input.connectionStatus,
+        tenantId: input.tenantId,
+    };
+}
 function withoutCacheControl(input) {
     const { cache: _cache, ...rest } = input;
     return rest;
@@ -35,8 +46,69 @@ function stableSdkStringify(value) {
     const record = value;
     return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableSdkStringify(record[key])}`).join(',')}}`;
 }
-function uniqueSdkStrings(values) {
-    return Array.from(new Set(values));
+const sdkDiscoveryMcpMethods = new Set([
+    'initialize',
+    'tools/list',
+    'resources/list',
+    'resources/templates/list',
+    'prompts/list',
+]);
+let sdkRequestSequence = 0;
+function mcpRequestIsDiscovery(input) {
+    const requests = Array.isArray(input) ? input : [input];
+    return requests.length > 0 && requests.every((request) => (typeof request.method === 'string' && sdkDiscoveryMcpMethods.has(request.method)));
+}
+function positiveSdkInteger(value, field) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Stacklink ${field} must be a positive integer.`);
+    }
+    return value;
+}
+function sdkString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function createSdkRequestId() {
+    const randomUuid = globalThis.crypto?.randomUUID?.();
+    if (randomUuid)
+        return randomUuid;
+    sdkRequestSequence += 1;
+    return `stacklink-${Date.now()}-${sdkRequestSequence}`;
+}
+function sdkRetrySafe(method, idempotencyKey) {
+    return method === 'GET' || method === 'HEAD' || method === 'OPTIONS' || Boolean(idempotencyKey);
+}
+function sdkRetryableStatus(status) {
+    return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
+}
+function sdkRetryDelayMs(response, attempt) {
+    const retryAfter = response?.headers.get('retry-after');
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return Math.ceil(seconds * 1000);
+        const at = Date.parse(retryAfter);
+        if (Number.isFinite(at))
+            return Math.max(0, at - Date.now());
+    }
+    return Math.min(1_000, 100 * (2 ** Math.max(0, attempt - 1)));
+}
+function sdkDelay(ms, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error('Stacklink request was aborted.'));
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(signal.reason ?? new Error('Stacklink request was aborted.'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function sdkTimeoutError(timeoutMs, requestId) {
+    return new StacklinkApiError(`Stacklink request exceeded its ${timeoutMs} ms deadline.`, 408, 'sdk_request_timeout', { requestId, timeoutMs });
 }
 function normalizeKnowledgePackSelection(value) {
     if (Array.isArray(value)) {
@@ -69,6 +141,39 @@ export async function verifyWebhookSignature(input) {
     }
     return false;
 }
+/** Sign the exact JSON bytes sent to a saved inbound Bot webhook. Reuse requestId when retrying. */
+export async function signBotTriggerRequest(input) {
+    const cryptoImpl = globalThis.crypto ?? (await import('node:crypto')).webcrypto;
+    const timestamp = String(Math.floor((input.now ?? new Date()).getTime() / 1000));
+    const requestId = input.requestId ?? cryptoImpl.randomUUID();
+    const digest = await cryptoImpl.subtle.digest('SHA-256', utf8(input.body));
+    const digestHex = Array.from(new Uint8Array(digest), value => value.toString(16).padStart(2, '0')).join('');
+    const key = await cryptoImpl.subtle.importKey('raw', utf8(input.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await cryptoImpl.subtle.sign('HMAC', key, utf8(JSON.stringify(['stacklink-trigger-v1', input.triggerId, timestamp, requestId, digestHex])));
+    return { 'content-type': 'application/json', 'stacklink-timestamp': timestamp, 'stacklink-request-id': requestId, 'stacklink-signature': Array.from(new Uint8Array(signature), value => value.toString(16).padStart(2, '0')).join('') };
+}
+/** Verify the original request bytes before using identity. consumeRequestId must atomically reject replays. */
+export async function verifyBotApiRequest(input) {
+    const headers = new Headers(input.headers);
+    const get = (name) => headers.get(`x-stacklink-${name}`) ?? '';
+    const keyId = get('key-id'), timestamp = get('timestamp'), requestId = get('request-id');
+    const key = input.keys[keyId], projectId = get('project'), tenantId = get('tenant'), userId = get('customer');
+    const secret = typeof key === 'string' ? key : key?.secret;
+    const seconds = Number(timestamp), now = Math.floor((input.now ?? new Date()).getTime() / 1000), tolerance = input.toleranceSeconds ?? 300;
+    if (key && typeof key !== 'string' && key.validUntil !== null && (!Number.isFinite(Date.parse(key.validUntil)) || Date.parse(key.validUntil) <= now * 1000))
+        return null;
+    if (typeof secret !== 'string' || !secret || !tenantId || !requestId || projectId !== input.projectId || !Number.isInteger(seconds) || Math.abs(now - seconds) > tolerance)
+        return null;
+    const cryptoImpl = globalThis.crypto ?? (await import('node:crypto')).webcrypto;
+    const digest = await cryptoImpl.subtle.digest('SHA-256', utf8(input.body));
+    const bodySha256 = Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
+    const expected = await hmacSha256Base64(secret, botApiSignaturePayload({ method: input.method, url: input.url, requestId, timestamp, keyId, projectId, tenantId, userId, bodySha256 }));
+    if (!constantTimeStringEqual(get('signature'), `v1,${expected}`))
+        return null;
+    if (!await input.consumeRequestId(requestId, new Date((seconds + tolerance) * 1000)))
+        return null;
+    return { tenantId, userId: userId || null, requestId };
+}
 function signatureCandidates(header) {
     const candidates = [];
     for (const entry of header.split(' ')) {
@@ -120,6 +225,11 @@ export class Stacklink {
     fetchImpl;
     cacheOptions;
     responseCache = new Map();
+    discoveryRequests = new Map();
+    timeoutMs;
+    maxAttempts;
+    bots;
+    approvals;
     webhooks;
     triggers;
     sessions;
@@ -136,6 +246,8 @@ export class Stacklink {
         this.registrationKey = options.registrationKey;
         this.baseUrl = options.baseUrl.endsWith('/') ? options.baseUrl.slice(0, -1) : options.baseUrl;
         this.fetchImpl = options.fetch ?? fetch;
+        this.timeoutMs = positiveSdkInteger(options.timeoutMs ?? 15_000, 'timeoutMs');
+        this.maxAttempts = Math.min(3, positiveSdkInteger(options.maxAttempts ?? 3, 'maxAttempts'));
         this.cacheOptions = {
             enabled: options.cache?.enabled ?? true,
             toolsListTtlMs: options.cache?.toolsListTtlMs ?? 300_000,
@@ -144,6 +256,8 @@ export class Stacklink {
             searchTtlMs: options.cache?.searchTtlMs ?? 120_000,
             maxEntries: options.cache?.maxEntries ?? 500,
         };
+        this.bots = new StacklinkBotsClient(this);
+        this.approvals = new StacklinkApprovalsClient(this);
         this.webhooks = new StacklinkWebhooksClient(this);
         this.triggers = new StacklinkTriggersClient(this);
         this.sessions = new StacklinkSessionsClient(this);
@@ -176,27 +290,24 @@ export class Stacklink {
                 userEmail: input.userEmail,
                 scopes: input.scopes ?? [],
                 toolRouter: input.toolRouter,
-                preset: input.preset,
-                preload: input.preload,
+                modelSurface: input.modelSurface,
                 toolkits: input.toolkits,
                 tools: input.tools,
                 authConfigs: input.authConfigs,
                 connectedAccounts: input.connectedAccounts,
+                providerMutationMode: input.providerMutationMode,
                 multiAccount: input.multiAccount,
                 workbench: input.workbench,
                 knowledgePacks: input.knowledgePacks,
                 memory: input.memory,
-                metaTools: input.metaTools,
                 metadata: input.metadata ?? {},
             },
         });
-        const projection = await this.getSessionMetaTools(response.session.id);
-        return new ToolRouterSession(this, response.session.id, response.session.tenantId, response.session.mcp, projection.contractVersion, projection.tools);
+        return new ToolRouterSession(this, response.session.id, response.session.tenantId, response.session.mcp, response.metaTools.contractVersion, response.metaTools.tools);
     }
     async use(sessionId) {
-        const response = await this.getSession(sessionId);
-        const projection = await this.getSessionMetaTools(sessionId);
-        return new ToolRouterSession(this, response.session.id, response.session.tenantId, response.session.mcp, projection.contractVersion, projection.tools);
+        const response = await this.request(`/v1/sessions/${encodeURIComponent(sessionId)}/bootstrap`);
+        return new ToolRouterSession(this, response.session.id, response.session.tenantId, response.session.mcp, response.metaTools.contractVersion, response.metaTools.tools);
     }
     clearCache(prefix) {
         if (!prefix) {
@@ -262,19 +373,24 @@ export class Stacklink {
             method: 'DELETE',
         });
     }
-    async listProviders() {
-        return this.request('/v1/providers');
+    async listProviders(query = {}) {
+        return this.request('/v1/providers', {
+            query: providerCatalogSdkQuery(query),
+        });
     }
     async listProjectProviders(query = {}) {
         return this.request('/v1/project/providers', {
-            query: { tenantId: query.tenantId },
+            query: providerCatalogSdkQuery(query),
         });
     }
     async listProviderTools(providerKey, input = {}) {
         return this.request(`/v1/providers/${providerKey}/tools`, {
             query: {
+                limit: input.limit,
+                cursor: input.cursor,
+                search: input.search,
+                capability: input.capability,
                 includePlanned: input.includePlanned === true ? 'true' : undefined,
-                responseMode: input.responseMode === 'compact' ? 'compact' : undefined,
             },
         });
     }
@@ -360,6 +476,10 @@ export class Stacklink {
             method: 'POST',
             body: input,
             signal: options.signal,
+            timeoutMs: options.timeoutMs ?? 60_000,
+            idempotencyKey: options.idempotencyKey ?? sdkString(input.idempotencyKey),
+            requestId: options.requestId,
+            traceparent: options.traceparent,
         });
     }
     async executeToolsBatch(input, options = {}) {
@@ -367,6 +487,10 @@ export class Stacklink {
             method: 'POST',
             body: input,
             signal: options.signal,
+            timeoutMs: options.timeoutMs ?? 60_000,
+            idempotencyKey: options.idempotencyKey ?? sdkString(input.idempotencyKey),
+            requestId: options.requestId,
+            traceparent: options.traceparent,
         });
     }
     async getSubscription() {
@@ -611,7 +735,7 @@ export class Stacklink {
         const executionKind = accepted.executionKind === 'workbench_code' || accepted.executionKind === 'workbench_bash'
             ? accepted.executionKind
             : undefined;
-        if (!sessionId || !executionId || !executionKind)
+        if (!sessionId || !executionId || !executionKind || accepted.status === 'waiting_for_approval')
             return accepted;
         while (true) {
             const waited = await this.waitForExecution({
@@ -619,10 +743,9 @@ export class Stacklink {
                 executionKind,
                 executionId,
                 waitTimeoutMs: 10_000,
-                pollIntervalMs: 500,
             }, options);
             const execution = isSdkRecord(waited.execution) ? waited.execution : undefined;
-            if (execution && isTerminalSdkExecution(execution)) {
+            if (execution && (isTerminalSdkExecution(execution) || execution.status === 'waiting_for_approval')) {
                 return materializeStacklinkWorkbenchExecutionResponse(accepted, execution);
             }
         }
@@ -660,15 +783,110 @@ export class Stacklink {
             signal: options.signal,
         });
     }
+    async *streamBotEvents(botId, runId, options = {}) {
+        let cursor = options.after ?? '0';
+        const deadline = Date.now() + positiveSdkInteger(options.totalTimeoutMs ?? 300_000, 'totalTimeoutMs');
+        const terminal = (event) => ['run.completed', 'run.failed', 'run.stopped'].includes(String(event.type));
+        while (!options.signal?.aborted) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new StacklinkApiError('Bot observation timed out. The same run may still be active; resume with the last sequence.', 408, 'sdk_stream_timeout', { runId, after: cursor });
+            try {
+                const response = await this.requestRaw(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/events/stream`, { headers: { accept: 'text/event-stream', 'Last-Event-ID': cursor }, signal: options.signal, timeoutMs: Math.min(options.timeoutMs ?? 30_000, remaining) });
+                for await (const event of this.readJsonEventStream(response)) {
+                    if (!isSdkRecord(event) || typeof event.sequence !== 'string')
+                        continue;
+                    if (event.runId !== runId)
+                        throw new StacklinkApiError('Bot event belongs to a different run.', 502, 'bot_event_invalid');
+                    if (BigInt(event.sequence) <= BigInt(cursor))
+                        continue;
+                    cursor = event.sequence;
+                    yield event;
+                    if (terminal(event))
+                        return;
+                }
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason ?? error;
+                const retryable = error instanceof TypeError || (error instanceof Error && ['AbortError', 'TimeoutError'].includes(error.name))
+                    || (error instanceof StacklinkApiError && [408, 429, 502, 503, 504].includes(error.statusCode) && error.code !== 'bot_event_invalid');
+                if (!retryable)
+                    throw error;
+            }
+            // Fetch the durable tail before considering completion. A status read alone
+            // could miss the final text and terminal event that arrived during a disconnect.
+            const page = await this.bots.events(botId, runId, cursor);
+            for (const event of page.events) {
+                if (BigInt(event.sequence) <= BigInt(cursor))
+                    continue;
+                cursor = event.sequence;
+                yield event;
+                if (terminal(event))
+                    return;
+            }
+            if (page.terminal && page.events.length === 0)
+                return;
+            if (page.events.length < 200)
+                await sdkDelay(Math.min(1000, Math.max(1, deadline - Date.now())), options.signal ?? AbortSignal.timeout(Math.max(1, deadline - Date.now())));
+        }
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+    }
+    async *streamExecutionEvents(input, options = {}) {
+        let afterSequence = input.afterSequence === undefined ? undefined : String(input.afterSequence);
+        while (!options.signal?.aborted) {
+            const response = await this.requestRaw(`/v1/executions/${input.executionKind}/${input.executionId}/events/stream`, {
+                headers: {
+                    accept: 'text/event-stream',
+                    ...(afterSequence === undefined ? {} : { 'Last-Event-ID': afterSequence }),
+                },
+                query: {
+                    sessionId: input.sessionId,
+                    afterSequence,
+                    limit: input.limit,
+                },
+                signal: options.signal,
+                timeoutMs: options.timeoutMs ?? 30_000,
+            });
+            try {
+                for await (const payload of this.readJsonEventStream(response)) {
+                    if (!isSdkRecord(payload))
+                        continue;
+                    const events = Array.isArray(payload.events) ? payload.events : [];
+                    for (const event of events) {
+                        if (isSdkRecord(event) && (typeof event.sequence === 'string' || typeof event.sequence === 'number')) {
+                            afterSequence = String(event.sequence);
+                        }
+                        yield event;
+                    }
+                    if (typeof payload.nextCursor === 'string')
+                        afterSequence = payload.nextCursor;
+                    if (payload.terminal === true)
+                        return;
+                }
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason ?? error;
+                const errorName = error instanceof Error ? error.name : '';
+                if (errorName !== 'AbortError' && errorName !== 'TimeoutError')
+                    throw error;
+                // The per-connection deadline bounds a stream. Reconnect from the durable cursor.
+            }
+        }
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? new Error('Stacklink execution stream was aborted.');
+    }
     async waitForExecution(input, options = {}) {
         return this.request(`/v1/executions/${input.executionKind}/${input.executionId}/wait`, {
             method: 'POST',
             body: {
                 sessionId: input.sessionId,
                 waitTimeoutMs: input.waitTimeoutMs,
-                pollIntervalMs: input.pollIntervalMs,
             },
-            signal: options.signal,
+            ...options,
+            timeoutMs: options.timeoutMs ?? (input.waitTimeoutMs ?? 30_000) + 5_000,
         });
     }
     async cancelExecution(input, options = {}) {
@@ -719,7 +937,7 @@ export class Stacklink {
     async getConnectedAccount(accountId) {
         return this.request(`/v1/connections/${accountId}`);
     }
-    async listConnectedAccountTools(accountId, input = {}) {
+    async listConnectedAccountTools(accountId, input) {
         return this.request(`/v1/connections/${accountId}/tools`, {
             query: {
                 ...(input.includePlanned !== undefined ? { includePlanned: String(input.includePlanned) } : {}),
@@ -985,21 +1203,35 @@ export class Stacklink {
             method: 'DELETE',
         });
     }
-    async mcpRequest(input, options = {}) {
-        return this.mcpRequestAtPath('/v1/mcp', input, options);
-    }
     async mcpSessionRequest(sessionId, input, options = {}) {
         return this.mcpRequestAtPath(`/v1/sessions/${encodeURIComponent(sessionId)}/mcp`, input, options);
     }
     async mcpRequestAtPath(path, input, options = {}) {
-        return this.request(path, {
-            method: 'POST',
-            body: input,
-            signal: options.signal,
-        });
-    }
-    async mcpRequestStream(input, options = {}) {
-        return this.mcpRequestStreamAtPath('/v1/mcp', input, options);
+        if (!Array.isArray(input))
+            return this.mcpRequestStreamAtPath(path, input, {
+                ...options, timeoutMs: options.timeoutMs ?? (mcpRequestIsDiscovery(input) ? this.timeoutMs : 60_000),
+            });
+        const response = await this.requestRaw(path, { method: 'POST', body: input, headers: { accept: 'application/json, text/event-stream' },
+            ...options, timeoutMs: options.timeoutMs ?? 60_000 });
+        if (response.status === 202)
+            return null;
+        const value = await response.json();
+        if (!Array.isArray(value))
+            throw new StacklinkApiError('Expected MCP batch responses.', 502, 'mcp_response_invalid');
+        const expected = input.filter((entry) => entry.id !== undefined && entry.id !== null);
+        if (expected.length !== value.length)
+            throw new StacklinkApiError('MCP batch response count does not match.', 502, 'mcp_response_invalid');
+        const seen = new Set();
+        for (const message of value) {
+            if (!isSdkRecord(message) || seen.has(message.id))
+                throw new StacklinkApiError('Duplicate or invalid MCP response.', 502, 'mcp_response_invalid');
+            const request = expected.find((entry) => entry.id === message.id);
+            if (!request)
+                throw new StacklinkApiError('MCP response belongs to another request.', 502, 'mcp_response_invalid');
+            validateSdkMcpResponse(message, request.id);
+            seen.add(message.id);
+        }
+        return value;
     }
     async mcpSessionRequestStream(sessionId, input, options = {}) {
         return this.mcpRequestStreamAtPath(`/v1/sessions/${encodeURIComponent(sessionId)}/mcp`, input, options);
@@ -1032,49 +1264,40 @@ export class Stacklink {
                 method: 'POST',
                 body: input,
                 signal: options.signal,
+                timeoutMs: options.timeoutMs ?? 60_000,
+                idempotencyKey: options.idempotencyKey,
+                requestId: options.requestId,
+                traceparent: options.traceparent,
                 headers: {
                     accept: 'text/event-stream, application/json',
                 },
             });
             const contentType = response.headers.get('content-type') ?? '';
+            if (response.status === 202 && (input.id === undefined || input.id === null))
+                return null;
             if (!contentType.includes('text/event-stream')) {
-                return await response.json().catch(() => null);
+                const value = await response.json();
+                validateSdkMcpResponse(value, input.id);
+                return value;
             }
-            return await this.readMcpEventStream(response, options.onProgress);
+            return await this.readMcpEventStream(response, input, options.onProgress);
         }
         finally {
             completed = true;
             options.signal?.removeEventListener('abort', cancel);
         }
     }
-    async listMcpTools() {
-        return this.mcpRequest({
-            jsonrpc: '2.0',
-            id: 'tools-list',
-            method: 'tools/list',
-        });
-    }
-    async callMcpTool(name, args) {
-        return this.mcpRequest({
-            jsonrpc: '2.0',
-            id: `${name}-call`,
-            method: 'tools/call',
-            params: {
-                name,
-                arguments: args,
-            },
-        });
-    }
-    async callSessionMcpTool(sessionId, name, args) {
-        return this.mcpSessionRequest(sessionId, {
+    async callSessionMcpTool(sessionId, name, args, options = {}) {
+        return this.mcpSessionRequestStream(sessionId, {
             jsonrpc: '2.0',
-            id: `${name}-call`,
+            id: createSdkRequestId(),
             method: 'tools/call',
             params: {
                 name,
+                ...(options.onProgress ? { _meta: { progressToken: createSdkRequestId() } } : {}),
                 arguments: args,
             },
-        });
+        }, options);
     }
     async listKnowledgePacks() {
         return this.request('/v1/knowledge/packs');
@@ -1221,26 +1444,17 @@ export class Stacklink {
         signal.addEventListener('abort', cancel, { once: true });
     }
     async request(path, init = {}) {
-        const url = new URL(`${this.baseUrl}${path}`);
-        for (const [key, value] of Object.entries(init.query ?? {})) {
-            if (Array.isArray(value)) {
-                for (const entry of value) {
-                    if (entry !== undefined && entry !== null)
-                        url.searchParams.append(key, String(entry));
-                }
+        const response = await this.performRequest(path, init);
+        const responseText = await response.text();
+        let body = null;
+        if (responseText.length > 0) {
+            try {
+                body = JSON.parse(responseText);
             }
-            else if (value !== undefined && value !== null) {
-                url.searchParams.set(key, String(value));
+            catch {
+                body = null;
             }
         }
-        const headers = this.requestHeaders(init.registration === true, init.headers);
-        const response = await this.fetchImpl(url, {
-            method: init.method ?? 'GET',
-            headers,
-            ...(init.signal ? { signal: init.signal } : {}),
-            ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
-        });
-        const body = await response.json().catch(() => null);
         if (!response.ok) {
             const message = body && typeof body === 'object' && 'message' in body
                 ? String(body.message)
@@ -1256,6 +1470,21 @@ export class Stacklink {
         return body;
     }
     async requestRaw(path, init = {}) {
+        const response = await this.performRequest(path, init);
+        if (!response.ok) {
+            const body = await response.text();
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                parsed = null;
+            }
+            throw new StacklinkApiError(isSdkRecord(parsed) && typeof parsed.message === 'string' ? parsed.message : `Stacklink request failed with ${response.status}`, response.status, isSdkRecord(parsed) && typeof parsed.code === 'string' ? parsed.code : undefined, isSdkRecord(parsed) ? parsed.details : undefined);
+        }
+        return response;
+    }
+    async performRequest(path, init) {
         const url = new URL(`${this.baseUrl}${path}`);
         for (const [key, value] of Object.entries(init.query ?? {})) {
             if (Array.isArray(value)) {
@@ -1268,17 +1497,55 @@ export class Stacklink {
                 url.searchParams.set(key, String(value));
             }
         }
-        const response = await this.fetchImpl(url, {
-            method: init.method ?? 'GET',
-            headers: this.requestHeaders(init.registration === true, init.headers),
-            ...(init.signal ? { signal: init.signal } : {}),
-            ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
-        });
-        if (!response.ok) {
-            const body = await response.text().catch(() => '');
-            throw new StacklinkApiError(body || `Stacklink request failed with ${response.status}`, response.status);
+        const method = init.method ?? 'GET';
+        const timeoutMs = positiveSdkInteger(init.timeoutMs ?? this.timeoutMs, 'timeoutMs');
+        const deadlineAt = Date.now() + timeoutMs;
+        const requestId = init.requestId ?? createSdkRequestId();
+        const retrySafe = !path.endsWith('/mcp') && sdkRetrySafe(method, init.idempotencyKey);
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            const remainingMs = deadlineAt - Date.now();
+            if (remainingMs <= 0)
+                throw sdkTimeoutError(timeoutMs, requestId);
+            const deadlineSignal = AbortSignal.timeout(remainingMs);
+            const signal = init.signal ? AbortSignal.any([init.signal, deadlineSignal]) : deadlineSignal;
+            const headers = this.requestHeaders(init.registration === true, {
+                ...init.headers,
+                'X-Stacklink-Client-Request-Id': requestId,
+                'X-Stacklink-Timeout-Ms': String(remainingMs),
+                ...(init.idempotencyKey ? { 'Idempotency-Key': init.idempotencyKey } : {}),
+                ...(init.traceparent ? { traceparent: init.traceparent } : {}),
+            });
+            try {
+                const response = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    signal,
+                    ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+                });
+                if (!retrySafe || attempt >= this.maxAttempts || !sdkRetryableStatus(response.status)) {
+                    return response;
+                }
+                const delayMs = sdkRetryDelayMs(response, attempt);
+                if (delayMs >= deadlineAt - Date.now())
+                    return response;
+                await response.body?.cancel().catch(() => undefined);
+                await sdkDelay(delayMs, signal);
+            }
+            catch (error) {
+                if (init.signal?.aborted)
+                    throw init.signal.reason ?? error;
+                if (deadlineSignal.aborted || Date.now() >= deadlineAt)
+                    throw sdkTimeoutError(timeoutMs, requestId);
+                if (!retrySafe || attempt >= this.maxAttempts)
+                    throw error;
+                const delayMs = sdkRetryDelayMs(undefined, attempt);
+                if (delayMs >= deadlineAt - Date.now())
+                    throw error;
+                await sdkDelay(delayMs, signal);
+            }
         }
-        return response;
     }
     async cachedDiscoveryRequest(cacheKey, ttlMs, control, producer) {
         if (!this.cacheOptions.enabled || control?.cache === 'bypass')
@@ -1287,13 +1554,21 @@ export class Stacklink {
         const existing = this.responseCache.get(cacheKey);
         if (existing && existing.expiresAt > now)
             return existing.value;
-        const value = await producer();
-        this.responseCache.set(cacheKey, {
-            value,
-            expiresAt: now + ttlMs,
+        const active = this.discoveryRequests.get(cacheKey);
+        if (active)
+            return active;
+        const request = producer().then((value) => {
+            this.responseCache.set(cacheKey, {
+                value,
+                expiresAt: Date.now() + ttlMs,
+            });
+            this.trimResponseCache();
+            return value;
+        }).finally(() => {
+            this.discoveryRequests.delete(cacheKey);
         });
-        this.trimResponseCache();
-        return value;
+        this.discoveryRequests.set(cacheKey, request);
+        return request;
     }
     discoveryCacheTtl(kind) {
         if (kind === 'toolsList')
@@ -1313,7 +1588,7 @@ export class Stacklink {
             this.responseCache.delete(firstKey);
         }
     }
-    async readMcpEventStream(response, onProgress) {
+    async readMcpEventStream(response, request, onProgress) {
         if (!response.body)
             throw new Error('Stacklink MCP stream response has no body.');
         const reader = response.body.getReader();
@@ -1321,6 +1596,10 @@ export class Stacklink {
         let buffer = '';
         let dataLines = [];
         let finalResponse;
+        let bytes = 0;
+        const requestParams = isSdkRecord(request.params) ? request.params : {};
+        const meta = isSdkRecord(requestParams._meta) ? requestParams._meta : {};
+        const progressToken = meta.progressToken;
         const handleLine = (line) => {
             if (line.endsWith('\r'))
                 line = line.slice(0, -1);
@@ -1330,10 +1609,24 @@ export class Stacklink {
                     dataLines = [];
                     if (data.length > 0) {
                         const message = JSON.parse(data);
+                        if (!isSdkRecord(message) || message.jsonrpc !== '2.0') {
+                            throw new StacklinkApiError('Stacklink returned an invalid MCP message.', 502, 'mcp_response_invalid');
+                        }
                         if (isSdkRecord(message) && message.method === 'notifications/progress' && isSdkRecord(message.params)) {
-                            onProgress?.(message.params);
+                            if (progressToken !== undefined && message.params.progressToken === progressToken) {
+                                onProgress?.(message.params);
+                            }
+                        }
+                        else if (typeof message.method === 'string' && message.id !== undefined) {
+                            throw new StacklinkApiError('The server requested a capability this SDK did not declare.', 502, 'mcp_capability_not_supported');
                         }
-                        else if (isSdkRecord(message) && ('result' in message || 'error' in message)) {
+                        else if ('result' in message || 'error' in message) {
+                            if (message.id !== request.id)
+                                return;
+                            if (finalResponse !== undefined || ('result' in message) === ('error' in message)) {
+                                throw new StacklinkApiError('Stacklink returned a conflicting MCP result.', 502, 'mcp_response_invalid');
+                            }
+                            validateSdkMcpResponse(message, request.id);
                             finalResponse = message;
                         }
                     }
@@ -1347,25 +1640,92 @@ export class Stacklink {
                 dataLines.push(value);
             }
         };
-        while (true) {
-            const read = await reader.read();
-            if (read.done)
-                break;
-            buffer += decoder.decode(read.value, { stream: true });
-            let index = buffer.indexOf('\n');
-            while (index >= 0) {
-                handleLine(buffer.slice(0, index));
-                buffer = buffer.slice(index + 1);
-                index = buffer.indexOf('\n');
+        try {
+            while (true) {
+                const read = await reader.read();
+                if (read.done)
+                    break;
+                bytes += read.value.byteLength;
+                if (bytes > 8 * 1024 * 1024)
+                    throw new StacklinkApiError('MCP response exceeds 8 MiB.', 502, 'mcp_response_too_large');
+                buffer += decoder.decode(read.value, { stream: true });
+                let index = buffer.indexOf('\n');
+                while (index >= 0) {
+                    handleLine(buffer.slice(0, index));
+                    buffer = buffer.slice(index + 1);
+                    if (finalResponse !== undefined)
+                        return finalResponse;
+                    index = buffer.indexOf('\n');
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer.length > 0)
+                handleLine(buffer);
+            handleLine('');
+            if (finalResponse === undefined)
+                throw new Error('Stacklink MCP stream ended without a final JSON-RPC response.');
+            return finalResponse;
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+    }
+    async *readJsonEventStream(response) {
+        if (!response.body)
+            throw new Error('Stacklink event stream response has no body.');
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let dataLines = [];
+        const payloadForLine = (lineValue) => {
+            let line = lineValue;
+            if (line.endsWith('\r'))
+                line = line.slice(0, -1);
+            if (line === '') {
+                if (dataLines.length === 0)
+                    return undefined;
+                const data = dataLines.join('\n');
+                dataLines = [];
+                return data.length === 0 ? undefined : JSON.parse(data);
             }
+            if (line.startsWith('data:')) {
+                let value = line.slice(5);
+                if (value.startsWith(' '))
+                    value = value.slice(1);
+                dataLines.push(value);
+            }
+            return undefined;
+        };
+        try {
+            while (true) {
+                const read = await reader.read();
+                if (read.done)
+                    break;
+                buffer += decoder.decode(read.value, { stream: true });
+                let index = buffer.indexOf('\n');
+                while (index >= 0) {
+                    const payload = payloadForLine(buffer.slice(0, index));
+                    if (payload !== undefined)
+                        yield payload;
+                    buffer = buffer.slice(index + 1);
+                    index = buffer.indexOf('\n');
+                }
+            }
+            buffer += decoder.decode();
+            if (buffer.length > 0) {
+                const payload = payloadForLine(buffer);
+                if (payload !== undefined)
+                    yield payload;
+            }
+            const finalPayload = payloadForLine('');
+            if (finalPayload !== undefined)
+                yield finalPayload;
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
         }
-        buffer += decoder.decode();
-        if (buffer.length > 0)
-            handleLine(buffer);
-        handleLine('');
-        if (finalResponse === undefined)
-            throw new Error('Stacklink MCP stream ended without a final JSON-RPC response.');
-        return finalResponse;
     }
     requestHeaders(registration, extraHeaders = {}) {
         if (registration) {
@@ -1540,6 +1900,12 @@ export class StacklinkMemoryClient {
             body: input,
         });
     }
+    reviewQuality(memoryId, input) {
+        return this.client.request(`/v1/memory/records/${memoryId}/quality-review`, {
+            method: 'POST',
+            body: input,
+        });
+    }
     forget(memoryId, input) {
         return this.client.request(`/v1/memory/records/${memoryId}/forget`, {
             method: 'POST',
@@ -1629,8 +1995,8 @@ export class StacklinkMemoryClient {
             body: input,
         });
     }
-    deleteSource(bindingId) {
-        return this.client.request(`/v1/memory/sources/${bindingId}`, { method: 'DELETE' });
+    deleteSource(bindingId, input) {
+        return this.client.request(`/v1/memory/sources/${bindingId}`, { method: 'DELETE', body: input });
     }
     replaySourceItem(bindingId, itemId) {
         return this.client.request(`/v1/memory/sources/${bindingId}/items/${itemId}/replay`, {
@@ -1659,6 +2025,55 @@ export class StacklinkMemoryClient {
         return this.client.request(`/v1/memory/legal-holds/${holdId}/release`, { method: 'POST' });
     }
 }
+export class StacklinkApprovalsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Server-only access. Identity comes from the authenticated application session. */
+    getCustomerGrant(sessionId) {
+        return this.client.request('/v1/approvals/customer-grant', { query: { sessionId } });
+    }
+    saveCustomerGrant(sessionId, grant) {
+        return this.client.request('/v1/approvals/customer-grant', { method: 'PUT', query: { sessionId }, body: grant });
+    }
+    removeCustomerGrant(sessionId, revision) {
+        return this.client.request('/v1/approvals/customer-grant', { method: 'DELETE', query: { sessionId }, body: { revision } });
+    }
+    list(input) {
+        return this.client.request('/v1/approvals', { query: { ...input } });
+    }
+    get(id, access) {
+        return this.client.request(`/v1/approvals/${encodeURIComponent(id)}`, { query: { ...access } });
+    }
+    /** Decide only after displaying the exact proposal and checking permissions. Never resubmit the original action. */
+    decide(id, access, decision) {
+        return this.client.request(`/v1/approvals/${encodeURIComponent(id)}/decide`, { method: 'POST', query: { ...access }, body: decision });
+    }
+    change(id, access, change) {
+        return this.client.request(`/v1/approvals/${encodeURIComponent(id)}/change`, { method: 'POST', query: { ...access }, body: change });
+    }
+    events(access, after = '0', options = {}) {
+        return this.client.request('/v1/approvals/events', { ...options, query: { ...access, after } });
+    }
+    /** Durable cursor observation. Save each sequence and pass it as `after` when reconnecting. */
+    async *observe(access, options = {}) {
+        let cursor = options.after ?? '0';
+        const deadline = Date.now() + (options.timeoutMs ?? 300_000);
+        const signal = options.signal ?? AbortSignal.timeout(Math.max(1, deadline - Date.now()));
+        while (!signal.aborted && Date.now() < deadline) {
+            const page = await this.events(access, cursor, { signal, timeoutMs: Math.min(15_000, Math.max(1, deadline - Date.now())) });
+            for (const event of page.events) {
+                if (BigInt(event.sequence) <= BigInt(cursor))
+                    continue;
+                cursor = event.sequence;
+                yield event;
+            }
+            if (page.events.length < 100)
+                await sdkDelay(Math.min(1000, Math.max(1, deadline - Date.now())), signal);
+        }
+    }
+}
 export class StacklinkSessionsClient {
     client;
     constructor(client) {
@@ -1688,8 +2103,10 @@ export class StacklinkSessionsClient {
     metaTools(sessionId) {
         return this.client.getSessionMetaTools(sessionId);
     }
-    toolkits(sessionId) {
-        return this.client.request(`/v1/sessions/${sessionId}/toolkits`);
+    toolkits(sessionId, query = {}) {
+        return this.client.request(`/v1/sessions/${sessionId}/toolkits`, {
+            query: providerCatalogSdkQuery(query),
+        });
     }
     streamEvents(sessionId, input = {}) {
         return this.client.requestRaw(`/v1/sessions/${sessionId}/events/stream`, {
@@ -1700,7 +2117,6 @@ export class StacklinkSessionsClient {
                 after: input.after,
                 eventType: input.eventTypes,
                 limit: input.limit,
-                pollIntervalMs: input.pollIntervalMs,
             },
         });
     }
@@ -1809,7 +2225,7 @@ export class StacklinkConnectedAccountsClient {
     get(accountId) {
         return this.client.getConnectedAccount(accountId);
     }
-    listTools(accountId, input = {}) {
+    listTools(accountId, input) {
         return this.client.listConnectedAccountTools(accountId, input);
     }
     listResources(accountId) {
@@ -1872,14 +2288,14 @@ export class StacklinkToolkitsClient {
     constructor(client) {
         this.client = client;
     }
-    list() {
-        return this.client.listProviders();
+    list(query = {}) {
+        return this.client.listProviders(query);
     }
     listProject(query = {}) {
         return this.client.listProjectProviders(query);
     }
-    listTools(providerKey) {
-        return this.client.listProviderTools(providerKey);
+    listTools(providerKey, query = {}) {
+        return this.client.listProviderTools(providerKey, query);
     }
 }
 export class StacklinkProviderToolsClient {
@@ -1952,12 +2368,6 @@ export class StacklinkSessionMemoryClient {
             ...(reason ? { reason } : {}),
         });
     }
-    restore(memoryId, reason) {
-        return this.memoryClient.restore(memoryId, {
-            sessionId: this.sessionId,
-            ...(reason ? { reason } : {}),
-        });
-    }
 }
 export class StacklinkWorkbenchRun {
     client;
@@ -1972,37 +2382,16 @@ export class StacklinkWorkbenchRun {
         this.executionId = response.executionId;
         this.executionKind = response.executionKind;
     }
-    async *events(input = {}) {
-        let afterSequence;
-        while (true) {
-            const page = await this.client.readExecutionEvents({
-                sessionId: this.platformSessionId,
-                executionKind: this.executionKind,
-                executionId: this.executionId,
-                afterSequence,
-                limit: input.limit ?? 200,
-            });
-            for (const event of page.events) {
-                yield event;
-                if (isSdkRecord(event) && (typeof event.sequence === 'string' || typeof event.sequence === 'number')) {
-                    afterSequence = String(event.sequence);
-                }
-            }
-            if (page.hasMore) {
-                if (!page.nextCursor)
-                    throw new Error('Execution event page reported hasMore without nextCursor.');
-                afterSequence = page.nextCursor;
-                continue;
-            }
-            const state = await this.client.getExecution({
-                sessionId: this.platformSessionId,
-                executionKind: this.executionKind,
-                executionId: this.executionId,
-            });
-            if (isTerminalSdkExecution(state.execution))
-                return;
-            await sleep(input.pollIntervalMs ?? 500);
-        }
+    events(input = {}) {
+        return this.client.streamExecutionEvents({
+            sessionId: this.platformSessionId,
+            executionKind: this.executionKind,
+            executionId: this.executionId,
+            limit: input.limit ?? 200,
+        }, {
+            signal: input.signal,
+            timeoutMs: input.streamTimeoutMs,
+        });
     }
     wait(input = {}) {
         return this.client.waitForExecution({
@@ -2261,8 +2650,8 @@ export class ToolRouterSession {
     async mcpRequestStream(input, options = {}) {
         return this.client.mcpSessionRequestStream(this.id, input, options);
     }
-    async callMcpTool(name, args) {
-        return this.client.callSessionMcpTool(this.id, name, args);
+    async callMcpTool(name, args, options = {}) {
+        return this.client.callSessionMcpTool(this.id, name, args, options);
     }
     mcpConnection() {
         if (!this.mcp) {
@@ -2285,6 +2674,7 @@ export class ToolRouterSession {
         return this.toolDefinitions.map((definition) => ({
             ...definition,
             inputSchema: { ...definition.inputSchema },
+            outputSchema: { ...definition.outputSchema },
         }));
     }
     async close() {
@@ -2305,18 +2695,17 @@ export class ToolRouterSession {
     async workbenchActivity() {
         return this.client.getSessionWorkbench(this.id);
     }
-    async toolkits() {
-        const response = await this.client.cachedDiscoveryRequest(`session:${this.id}:toolkits`, this.client.discoveryCacheTtl('toolkits'), undefined, () => this.client.request(`/v1/sessions/${this.id}/toolkits`));
-        return response.toolkits;
+    async toolkits(query = {}) {
+        return this.client.request(`/v1/sessions/${this.id}/toolkits`, {
+            query: providerCatalogSdkQuery(query),
+        });
     }
-    async authorize(providerKey, input = {}) {
+    async authorize(connectionRef, input = {}) {
         const response = await this.client.request(`/v1/sessions/${this.id}/connections/authorize`, {
             method: 'POST',
             body: {
-                providerKey,
-                callbackUrl: input.callbackUrl,
-                authConfigId: input.authConfigId,
-                authMode: input.authMode,
+                connectionRef,
+                oauthScopeProfile: input.oauthScopeProfile,
                 metadata: input.metadata ?? {},
             },
         });
@@ -2409,70 +2798,19 @@ export class ToolRouterSession {
         this.client.clearCache(`session:${this.id}:`);
         return response;
     }
-    async searchTools(input = {}) {
-        const searchInput = {
-            responseMode: 'compact',
-            includeSchemas: false,
-            includeRelatedTools: false,
-            includeExecutionPlan: false,
-            ...input,
-        };
-        return this.client.cachedDiscoveryRequest(`session:${this.id}:search:${stableSdkStringify(withoutCacheControl(searchInput))}`, this.client.discoveryCacheTtl('search'), searchInput, () => this.client.request(`/v1/sessions/${this.id}/tools/search`, {
+    async search(input) {
+        const searchInput = { queries: input.queries };
+        return this.client.cachedDiscoveryRequest(`session:${this.id}:search:${stableSdkStringify(withoutCacheControl(searchInput))}`, this.client.discoveryCacheTtl('search'), input, () => this.client.request(`/v1/sessions/${this.id}/tools/search`, {
             method: 'POST',
             body: discoveryServerBody(searchInput),
         }));
     }
-    async getToolSchemas(toolKeys, input = {}) {
-        return this.client.cachedDiscoveryRequest(`session:${this.id}:schemas:${stableSdkStringify({
-            toolKeys: [...toolKeys].sort(),
-            includePlanned: input.includePlanned === true,
-        })}`, this.client.discoveryCacheTtl('schemas'), input, () => this.client.request(`/v1/sessions/${this.id}/tools/schemas`, {
+    async getContracts(contractRefs) {
+        return this.client.request(`/v1/sessions/${this.id}/tools/contracts`, {
             method: 'POST',
-            body: {
-                toolKeys,
-                includePlanned: input.includePlanned,
-                ...(input.cache === 'bypass' ? { cache: 'bypass' } : {}),
-            },
-        }));
-    }
-    async prepareRuntimeTools(input = {}) {
-        return this.client.request(`/v1/sessions/${this.id}/tools/runtime-contracts`, {
-            method: 'POST',
-            body: input,
+            body: { contractRefs },
         });
     }
-    async prepareTools(input) {
-        const limitPerIntent = input.limitPerIntent ?? 5;
-        const search = await this.searchTools({
-            cache: input.cache,
-            responseMode: 'compact',
-            includeSchemas: false,
-            includeRelatedTools: false,
-            includeExecutionPlan: false,
-            queries: input.intents.map((intent) => ({
-                query: intent,
-                limit: limitPerIntent,
-                ...(input.toolkitKey ? { toolkitKey: input.toolkitKey } : {}),
-                ...(input.capability ? { capability: input.capability } : {}),
-            })),
-            includePlanned: input.includePlanned === true,
-            model: input.model,
-            limit: Math.max(limitPerIntent, input.intents.length * limitPerIntent),
-        });
-        const toolKeys = uniqueSdkStrings(search.tools.map((tool) => tool.key));
-        const schemaResponse = input.includeSchemas === false || toolKeys.length === 0
-            ? { tools: [] }
-            : await this.getToolSchemas(toolKeys, {
-                cache: input.cache,
-                includePlanned: input.includePlanned,
-            });
-        return {
-            tools: search.tools,
-            schemas: schemaResponse.tools,
-            toolKeys,
-            search,
-        };
-    }
     async searchKnowledge(input = {}) {
         return this.client.searchKnowledge({
             ...input,
@@ -2575,18 +2913,26 @@ export class ToolRouterSession {
             sessionId: this.id,
         });
     }
-    async executeTool(input, options = {}) {
+    async execute(contractRef, input, execution = {}, options = {}) {
+        if (execution.idempotencyKey !== undefined && options.idempotencyKey !== undefined
+            && execution.idempotencyKey !== options.idempotencyKey) {
+            throw new StacklinkApiError('Execution and request idempotency keys must match.', 400, 'idempotency_key_conflict');
+        }
+        const idempotencyKey = execution.idempotencyKey ?? options.idempotencyKey ?? createSdkRequestId();
+        const { idempotencyKey: _childKey, ...item } = execution;
         return this.client.request(`/v1/sessions/${this.id}/tools/execute`, {
             method: 'POST',
-            body: input,
-            ...options,
-        });
-    }
-    async executeToolsBatch(input, options = {}) {
-        return this.client.request(`/v1/sessions/${this.id}/tools/execute-batch`, {
-            method: 'POST',
-            body: input,
+            body: {
+                idempotencyKey,
+                executions: [{
+                        contractRef,
+                        input,
+                        ...item,
+                    }],
+            },
             ...options,
+            timeoutMs: options.timeoutMs ?? 60_000,
+            idempotencyKey,
         });
     }
     async runWorkbench(input, options = {}) {
@@ -2652,7 +2998,6 @@ export class ToolRouterSession {
                 after: input.after,
                 eventType: input.eventTypes,
                 limit: input.limit === undefined ? undefined : String(input.limit),
-                pollIntervalMs: input.pollIntervalMs === undefined ? undefined : String(input.pollIntervalMs),
             },
         });
     }
@@ -2662,7 +3007,8 @@ export class ToolRouterSession {
             {
                 description: definition.description,
                 parameters: definition.inputSchema,
-                execute: async (input) => unwrapMcpToolResult(await this.callMcpTool(definition.name, input)),
+                outputSchema: definition.outputSchema,
+                execute: async (input, execution) => unwrapMcpToolResult(await this.callMcpTool(definition.name, input, { ...(execution?.abortSignal ? { signal: execution.abortSignal } : {}), ...(execution?.onProgress ? { onProgress: execution.onProgress } : {}) })),
             },
         ]));
     }
@@ -2779,4 +3125,55 @@ function isTerminalSdkExecution(value) {
         || status === 'cancelled'
         || status === 'timed_out';
 }
+function validateSdkMcpResponse(value, requestId) {
+    if (!isSdkRecord(value) || value.jsonrpc !== '2.0' || value.id !== requestId || ('result' in value) === ('error' in value)
+        || ('error' in value && (!isSdkRecord(value.error) || typeof value.error.code !== 'number' || typeof value.error.message !== 'string'))) {
+        throw new StacklinkApiError('Stacklink returned an invalid or unrelated MCP response.', 502, 'mcp_response_invalid');
+    }
+}
+/** Hosted bots share durable runs across the API, MCP and dashboard. */
+export class StacklinkBotsClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    apis() { return this.client.request('/v1/bots/apis'); }
+    updateApi(apiId, revision, api) { return this.client.request(`/v1/bots/apis/${encodeURIComponent(apiId)}`, { method: 'PATCH', body: { revision, api } }); }
+    deleteApi(apiId) { return this.client.request(`/v1/bots/apis/${encodeURIComponent(apiId)}`, { method: 'DELETE' }); }
+    webhookSecret(botId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/webhook-secret`, { method: 'POST', body: {} }); }
+    triggerWebhook(botId, triggerId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/triggers/${encodeURIComponent(triggerId)}/webhook`, { method: 'POST', body: {} }); }
+    triggerAdmission(botId, triggerId, admissionId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/triggers/${encodeURIComponent(triggerId)}/admissions/${encodeURIComponent(admissionId)}`); }
+    apiSigningKey(botId, apiId, request = { action: 'read' }) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/apis/${encodeURIComponent(apiId)}/signing-key`, { method: 'POST', body: request }); }
+    models() { return this.client.request('/v1/bots/models'); }
+    setCredential(botId, secret) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/credentials`, { method: 'POST', body: { secret } }); }
+    deliveries(botId, runId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/deliveries`); }
+    retryDelivery(botId, runId, deliveryId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/deliveries/retry`, { method: 'POST', body: { deliveryId } }); }
+    setCustomerCredential(botId, input) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/credentials`, { method: 'POST', body: input }); }
+    delete(botId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}`, { method: 'DELETE' }); }
+    deleteCustomerData(botId, sessionId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/customer-data/delete`, { method: 'POST', body: { sessionId } }); }
+    setState(botId, input) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/state`, { method: 'POST', body: input }); }
+    list() { return this.client.request('/v1/bots'); }
+    create(name) { return this.client.request('/v1/bots', { method: 'POST', body: { name } }); }
+    get(botId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}`); }
+    update(botId, revision, patch) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}`, { method: 'PATCH', body: { revision, patch } }); }
+    publish(botId, revision, channels) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/publish`, { method: 'POST', body: { revision, channels } }); }
+    run(botId, input) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs`, { method: 'POST', body: { ...input, runId: input.runId ?? globalThis.crypto.randomUUID() } }); }
+    getRun(botId, runId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}`); }
+    /** Observe the same durable run. Returns when finished or when a person must act. */
+    async wait(botId, runId, options = {}) {
+        const deadline = Date.now() + positiveSdkInteger(options.totalTimeoutMs ?? 300_000, 'totalTimeoutMs');
+        while (Date.now() < deadline) {
+            if (options.signal?.aborted)
+                throw options.signal.reason;
+            const run = await this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}`, { signal: options.signal, timeoutMs: Math.min(30_000, deadline - Date.now()) });
+            if (['completed', 'failed', 'stopped', 'cancelled', 'waiting_for_approval', 'waiting_for_connection'].includes(run.status))
+                return run;
+            await sdkDelay(Math.min(1000, Math.max(1, deadline - Date.now())), options.signal ?? AbortSignal.timeout(Math.max(1, deadline - Date.now())));
+        }
+        throw new StacklinkApiError('Bot observation timed out. Continue observing the same run.', 408, 'sdk_run_timeout', { botId, runId });
+    }
+    events(botId, runId, after = '0') { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/events`, { query: { after } }); }
+    stream(botId, runId, options = {}) { return this.client.streamBotEvents(botId, runId, options); }
+    cancel(botId, runId) { return this.client.request(`/v1/bots/${encodeURIComponent(botId)}/runs/${encodeURIComponent(runId)}/stop`, { method: 'POST', body: {} }); }
+}
 //# sourceMappingURL=index.js.map