@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/tools/remote.js

@@ -1,13 +1,23 @@
 import { errorKind } from '../../guardrails/error.js';
-import { lexiconText } from '../../guardrails/lexicon.js';
+import { labelText } from '../../guardrails/labels.js';
 import { fetchGuarded } from '../../guardrails/network.js';
+import { retryTransient } from '../../providers/shared/retry.js';
 import { refreshOAuthToken, tokenAudienceCovers } from '../auth/oauth.js';
 import { mapStrings } from '../engine/tree.js';
-import { guardToolTarget, messageOf, networkBlocked, networkBlockedEvent, requestChecks, startToolExecution, toolEvent, toolNetworkPolicy, } from './events.js';
+import { dispatchToolBody, guardToolTarget, messageOf, networkBlocked, networkBlockedEvent, requestChecks, startToolExecution, toolEvent, toolNetworkPolicy, } from './events.js';
+import { answeredIn, takeLimitPlace } from './http-limit.js';
 import { createMcpSessionCache, isMcpSessionId, mcpSessionKey, } from './mcp-sessions.js';
-import { checkPermission } from './permission.js';
+import { checkPermission, gateDetails } from './permission.js';
 import { assertFixedEndpointOrigin } from './schema.js';
 import { runPreToolPipeline } from './stage-run.js';
+/** `url` with the credential set in its query parameter; `url` itself is left as it was. */
+export function withCredentialQuery(url, query) {
+    if (!query)
+        return url;
+    const signed = new URL(url);
+    signed.searchParams.set(query.name, query.value);
+    return signed;
+}
 function authHeaderPair(authConfig, value, defaults) {
     const headerName = authConfig.headerName ?? defaults.headerName;
     const headerPrefix = authConfig.headerPrefix ?? defaults.headerPrefix;
@@ -30,31 +40,41 @@ function buildAuthGate(toolName, authConfig, message, extras) {
 }
 function unauthenticatedResult(toolName, authConfig, message, policy, extras) {
     if (policy === 'gate') {
-        // The caller emits the gate through emitGateSettlement, so `pre_tool` runs first.
+        // why: The caller emits the gate through emitGateSettlement, so `pre_tool` runs first.
         const gate = buildAuthGate(toolName, authConfig, message, extras);
         return { headers: {}, unauthenticated: true, gate };
     }
+    if (policy === 'fail')
+        return { headers: {}, unauthenticated: true, failureMessage: message };
     return { headers: {}, unauthenticated: true, modelMessage: message };
 }
-function resolveStaticCredential(credential, authConfig) {
+/**
+ * Where a token or API key goes on a tool's requests: the query parameter the tool names, or a
+ * header, `Authorization: Bearer …` for a token and `Authorization: …` for a key unless the tool
+ * or the key names another.
+ */
+export function credentialPlacement(authConfig, credential) {
+    const value = credential.type === 'bearer' ? credential.token : credential.key;
+    if (authConfig.queryParam !== undefined) {
+        return { headers: {}, query: { name: authConfig.queryParam, value } };
+    }
     if (credential.type === 'bearer') {
         return {
-            headers: authHeaderPair(authConfig, credential.token, {
+            headers: authHeaderPair(authConfig, value, {
                 headerName: 'Authorization',
                 headerPrefix: 'Bearer ',
             }),
-            secret: credential.token,
         };
     }
-    if (credential.type === 'api_key') {
-        const headerName = credential.headerName ?? authConfig.headerName ?? 'Authorization';
-        const headerPrefix = credential.headerPrefix ?? authConfig.headerPrefix ?? '';
-        return {
-            headers: { [headerName]: `${headerPrefix}${credential.key}` },
-            secret: credential.key,
-        };
-    }
-    return undefined;
+    const headerName = credential.headerName ?? authConfig.headerName ?? 'Authorization';
+    const headerPrefix = credential.headerPrefix ?? authConfig.headerPrefix ?? '';
+    return { headers: { [headerName]: `${headerPrefix}${value}` } };
+}
+function resolveStaticCredential(credential, authConfig) {
+    if (credential.type !== 'bearer' && credential.type !== 'api_key')
+        return undefined;
+    const secret = credential.type === 'bearer' ? credential.token : credential.key;
+    return { ...credentialPlacement(authConfig, credential), secret };
 }
 /**
  * Refreshes in flight, by grant. Calls that find the same expired token share
@@ -85,10 +105,10 @@ function refreshOnce(credential, refreshToken, transport, clientSecret) {
 async function* resolveOAuth2Credential(toolName, authConfig, credential, source, ctx, base, policy) {
     const slot = authConfig.slot;
     const bound = { issuer: credential.issuer, resource: credential.resource };
-    // A token goes only to the resource it was issued for; one that names none
+    // invariant: A token goes only to the resource it was issued for; one that names none
     // has nowhere it may go, so the user signs in again.
     if (typeof credential.resource !== 'string' || credential.resource.length === 0) {
-        const message = `OAuth credential for '${toolName}' (slot: '${slot}') does not name the resource it was issued for.`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const message = `OAuth credential for '${toolName}' (slot: '${slot}') does not name the resource it was issued for.`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         return unauthenticatedResult(toolName, authConfig, message, policy, bound);
     }
     let active = credential;
@@ -98,7 +118,7 @@ async function* resolveOAuth2Credential(toolName, authConfig, credential, source
             active = await refreshOnce(credential, credential.refreshToken, { network: toolNetworkPolicy(ctx), resolveHost: ctx.resolveHost }, await source.clientSecret?.(credential.clientId));
         }
         catch (err) {
-            // The server's own words are untrusted text: they go to the host as
+            // invariant: The server's own words are untrusted text: they go to the host as
             // `errorInternal`, never to the model or the client.
             yield {
                 ...toolEvent(base, {
@@ -107,10 +127,10 @@ async function* resolveOAuth2Credential(toolName, authConfig, credential, source
                 }),
                 errorInternal: messageOf(err),
             };
-            const message = `Failed to refresh OAuth token for '${toolName}' (slot: '${slot}').`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            const message = `Failed to refresh OAuth token for '${toolName}' (slot: '${slot}').`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             return unauthenticatedResult(toolName, authConfig, message, policy, bound);
         }
-        // The host persists the refreshed credential before the call goes on; the
+        // why: The host persists the refreshed credential before the call goes on; the
         // event only names the slot, so no token rides the stream.
         await source.set(slot, active);
         yield toolEvent(base, {
@@ -119,7 +139,7 @@ async function* resolveOAuth2Credential(toolName, authConfig, credential, source
         });
     }
     else if (isExpired) {
-        const message = `OAuth token expired for '${toolName}' (slot: '${slot}') and no refresh token is available.`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const message = `OAuth token expired for '${toolName}' (slot: '${slot}') and no refresh token is available.`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         return unauthenticatedResult(toolName, authConfig, message, policy, bound);
     }
     return {
@@ -131,6 +151,7 @@ async function* resolveOAuth2Credential(toolName, authConfig, credential, source
         audience: credential.resource,
     };
 }
+/** Finds the auth headers for a call from the host's credential for the tool's slot, refreshing an OAuth token when needed; with no usable credential it returns a gate or a message for the model, per the tool's `onUnauthenticated`. */
 export async function* resolveToolAuth(toolName, authConfig, ctx, base) {
     if (!authConfig) {
         return { headers: {} };
@@ -139,7 +160,7 @@ export async function* resolveToolAuth(toolName, authConfig, ctx, base) {
     const credential = source ? await source.get(authConfig.slot) : undefined;
     const policy = authConfig.onUnauthenticated ?? 'gate';
     if (!source || !credential) {
-        const message = `Authentication required for '${toolName}' (auth slot: '${authConfig.slot}').`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        const message = `Authentication required for '${toolName}' (auth slot: '${authConfig.slot}').`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         return unauthenticatedResult(toolName, authConfig, message, policy);
     }
     const staticResolved = resolveStaticCredential(credential, authConfig);
@@ -157,10 +178,11 @@ export async function* resolveToolAuth(toolName, authConfig, ctx, base) {
  */
 function pathSegment(param, value) {
     if (value === '.' || value === '..') {
-        throw new Error(`Path parameter "${param}" cannot be "${value}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`Path parameter "${param}" cannot be "${value}"`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return encodeURIComponent(value);
 }
+/** The URL and, for anything but GET, the JSON body of an HTTP tool call: path parameters fill the endpoint, query parameters go on the URL, and the rest of the input (or `bodyParam`) is the body; throws when a path parameter is missing. */
 export function buildHttpToolTarget(endpoint, method, input, mapping) {
     assertFixedEndpointOrigin(endpoint);
     let urlStr = endpoint;
@@ -223,7 +245,7 @@ export function parseToolOutput(schema, responseData) {
             }
         }
         catch {
-            // Not JSON: the schema's first result stands.
+            // why: Not JSON: the schema's first result stands.
         }
     }
     return checked;
@@ -251,25 +273,19 @@ async function* runRemotePreBodyStages(args) {
     }
     return { ...failureOutcome(pre.failure, true), ...(pre.denied ? { denied: true } : {}) };
 }
-async function* remoteParseAndPermit(tool, rawInput, ctx, base) {
-    const started = yield* startToolExecution(tool, rawInput, ctx, base);
+function remoteParseAndPermit(tool, rawInput, ctx) {
+    const started = startToolExecution(tool, rawInput, ctx);
     if (!started.ok) {
-        return {
-            ok: false,
-            outcome: failureOutcome({
-                code: 'invalid_input',
-                kind: 'bad_response',
-                message: lexiconText('tool.input_invalid', {}, ctx.profile.lexicon),
-            }, true),
-        };
+        return { ok: false, outcome: failureOutcome(started.failure, true) };
     }
-    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume);
+    const permissionGate = checkPermission(tool.name, tool.permission, ctx.sessionPermissions, ctx.resume, gateDetails(tool, started.data));
     if (permissionGate) {
         return { ok: false, outcome: { kind: 'gated', gate: permissionGate } };
     }
     return { ok: true, input: started.data };
 }
-export function outcomeFromUnauth(authRes) {
+/** `sent`: the service refused a request the call already sent, so the call has started. */
+export function outcomeFromUnauth(authRes, sent = false) {
     if (!authRes.unauthenticated)
         return undefined;
     if (authRes.gate)
@@ -281,8 +297,10 @@ export function outcomeFromUnauth(authRes) {
             outputRaw: { unauthenticated: true, message: authRes.modelMessage },
         };
     }
-    return failureOutcome({ code: 'not_authorized', kind: 'auth', message: 'Tool authentication required' }, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    true);
+    if (authRes.failureMessage === undefined) {
+        throw new Error('An unauthenticated call carries a gate, a model message or a failure'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return failureOutcome({ code: 'not_authorized', kind: 'auth', message: authRes.failureMessage }, !sent);
 }
 export function credentialRefusal(response) {
     return response.status === 401 || response.status === 403
@@ -307,16 +325,17 @@ export function refusalAsksForSignIn(refusal) {
  * the person signs in again. A 403 `insufficient_scope` asks for more access: a
  * sign-in can grant scopes the tool declares, and nothing else, so a request
  * outside them fails with `sign_in.out_of_scope` and the trace records what was
- * asked against what is declared. Any other refusal is the call's failure.
+ * asked against what is declared. Any other refusal is the call's failure. `carried` says the
+ * request went with a credential, in a header or in the URL.
  */
-export function* refusedCredentialOutcome(tool, refusal, authHeaders, ctx, base) {
+export function* refusedCredentialOutcome(tool, refusal, carried, ctx, base) {
     const auth = tool.auth;
-    if (!auth || !refusal || Object.keys(authHeaders).length === 0)
+    if (!auth || !refusal || !carried)
         return undefined;
     const policy = auth.onUnauthenticated ?? 'gate';
     if (refusal.status === 401) {
-        const message = `The credential for '${tool.name}' (slot: '${auth.slot}') was refused.`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        return outcomeFromUnauth(unauthenticatedResult(tool.name, auth, message, policy));
+        const message = `The credential for '${tool.name}' (slot: '${auth.slot}') was refused.`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return outcomeFromUnauth(unauthenticatedResult(tool.name, auth, message, policy), true);
     }
     const challenge = bearerChallenge(refusal.challenge);
     if (challenge.error !== 'insufficient_scope')
@@ -324,8 +343,8 @@ export function* refusedCredentialOutcome(tool, refusal, authHeaders, ctx, base)
     const declared = auth.scopes ?? [];
     const requested = challenge.scopes;
     if (requested.length > 0 && requested.every((scope) => declared.includes(scope))) {
-        const message = `'${tool.name}' needs scopes its credential (slot: '${auth.slot}') does not carry.`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        return outcomeFromUnauth(unauthenticatedResult(tool.name, auth, message, policy));
+        const message = `'${tool.name}' needs scopes its credential (slot: '${auth.slot}') does not carry.`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return outcomeFromUnauth(unauthenticatedResult(tool.name, auth, message, policy), true);
     }
     const refused = {
         kind: 'auth_scope_refused',
@@ -337,7 +356,7 @@ export function* refusedCredentialOutcome(tool, refusal, authHeaders, ctx, base)
     return failureOutcome({
         code: 'out_of_scope',
         kind: 'auth',
-        message: lexiconText('sign_in.out_of_scope', { service: auth.service }, ctx.profile.lexicon),
+        message: labelText('sign_in.out_of_scope', { service: auth.service }, ctx.profile.labels),
     }, false);
 }
 async function* remoteAuthAndPreBody(args) {
@@ -358,6 +377,7 @@ async function* remoteAuthAndPreBody(args) {
         ok: true,
         input: preBody.input,
         authHeaders: authRes.headers ?? {},
+        ...(authRes.query ? { query: authRes.query } : {}),
         ...(authRes.secret ? { secret: authRes.secret } : {}),
         ...(authRes.audience ? { audience: authRes.audience } : {}),
     };
@@ -375,19 +395,20 @@ const OMIT_CREDENTIAL = '[omitted - credential]';
 export const MAX_TOOL_RESPONSE_BYTES = 4 * 1024 * 1024;
 /** The most of an error or unparseable body quoted back in a failure message. */
 const MAX_QUOTED_BODY_CHARS = 2000;
-/** A body, read up to `maxBytes`; `undefined` when it runs past, with the rest left unread. */
-async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
+/** A body's text as it arrives, up to `maxBytes`; returns `false` when it runs past, with the rest left unread. */
+async function* cappedPieces(response, maxBytes) {
     const declared = Number(response.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
         await response.body?.cancel().catch(() => { });
-        return undefined;
+        return false;
+    }
+    if (!response.body) {
+        yield await response.text();
+        return true;
     }
-    if (!response.body)
-        return await response.text();
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let bytes = 0;
-    let text = '';
     for (;;) {
         const { done, value } = await reader.read();
         if (done)
@@ -395,11 +416,56 @@ async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
         bytes += value.byteLength;
         if (bytes > maxBytes) {
             await reader.cancel().catch(() => { });
-            return undefined;
+            return false;
+        }
+        const piece = decoder.decode(value, { stream: true });
+        if (piece)
+            yield piece;
+    }
+    const rest = decoder.decode();
+    if (rest)
+        yield rest;
+    return true;
+}
+/** A body, read up to `maxBytes`; `undefined` when it runs past, with the rest left unread. */
+async function readCappedText(response, maxBytes = MAX_TOOL_RESPONSE_BYTES) {
+    const pieces = cappedPieces(response, maxBytes);
+    let text = '';
+    for (;;) {
+        const next = await pieces.next();
+        if (next.done)
+            return next.value ? text : undefined;
+        text += next.value;
+    }
+}
+/**
+ * A body read as `readCappedText` reads it, shown as drafts while it arrives. The credential never
+ * shows: the last `secret.length - 1` characters wait for the next piece, so one split across
+ * pieces is whole when it is replaced. Drafts that ran before the body ran past its cap stay sent.
+ */
+async function* readCappedTextShowing(response, shown, secret) {
+    const pieces = cappedPieces(response, MAX_TOOL_RESPONSE_BYTES);
+    const hold = secret ? secret.length - 1 : 0;
+    let text = '';
+    let pending = '';
+    for (;;) {
+        const next = await pieces.next();
+        if (next.done) {
+            if (!next.value)
+                return undefined;
+            if (pending)
+                yield* shown.show({ kind: 'draft', text: pending });
+            yield* shown.end();
+            return text;
         }
-        text += decoder.decode(value, { stream: true });
+        text += next.value;
+        pending = secret ? omitSecretText(pending + next.value, secret) : pending + next.value;
+        const cut = pending.length - hold;
+        if (cut <= 0)
+            continue;
+        yield* shown.show({ kind: 'draft', text: pending.slice(0, cut) });
+        pending = pending.slice(cut);
     }
-    return text + decoder.decode();
 }
 /** A body quoted in a failure message, cut short when long. */
 function quotedBody(text) {
@@ -410,7 +476,7 @@ function tooLargeFailure(host) {
     return {
         code: 'response_too_large',
         kind: 'bad_response',
-        message: `Response from ${host} is larger than ${MAX_TOOL_RESPONSE_BYTES} bytes`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        message: `Response from ${host} is larger than ${MAX_TOOL_RESPONSE_BYTES} bytes`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     };
 }
 /** The text with the credential replaced. */
@@ -429,7 +495,7 @@ export function failureWithoutSecret(failure, secret) {
         ...(failure.details === undefined ? {} : { details: omitSecret(failure.details, secret) }),
     };
 }
-/** An echo endpoint or debug page can repeat the credential; it must never reach the model, trace or client. */
+/** An echo endpoint or debug page can repeat the credential; it must never reach the model, trace, or client. */
 function withoutSecret(outcome, secret) {
     if (!secret)
         return outcome;
@@ -450,19 +516,25 @@ function withoutSecret(outcome, secret) {
 export function audienceMismatch(audience, url) {
     if (!audience || tokenAudienceCovers(audience, url))
         return undefined;
-    return `The OAuth token for "${audience}" cannot be sent to "${url.origin}${url.pathname}"`; // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return `The OAuth token for "${audience}" cannot be sent to "${url.origin}${url.pathname}"`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
 }
-/** An OAuth token goes only to the resource it was issued for (RFC 8707); any other target gets no request. */
+/**
+ * An OAuth token goes only to the resource it was issued for (RFC 8707); any other target gets no
+ * request. `send` gets the URL with any key the tool puts in the query, after the target's checks.
+ */
 async function* sendWithCredential(prepared, url, send) {
     const mismatch = audienceMismatch(prepared.audience, url);
     if (mismatch) {
         return failureOutcome({ code: 'credential_audience_mismatch', kind: 'config', message: mismatch }, true);
     }
-    return withoutSecret(yield* send(), prepared.secret);
+    return withoutSecret(yield* send(withCredentialQuery(url, prepared.query)), prepared.secret);
 }
-/** Order: schema → permission → auth → preTool/host stages → body. */
-export async function* executeHttpTool(tool, rawInput, ctx, base, stages) {
-    const parsed = yield* remoteParseAndPermit(tool, rawInput, ctx, base);
+/**
+ * Order: schema → permission → auth → preTool/host stages → body. `shown` takes the body while it
+ * arrives, as a function tool's drafts.
+ */
+export async function* executeHttpTool(tool, rawInput, ctx, base, stages, beginBody, shown) {
+    const parsed = remoteParseAndPermit(tool, rawInput, ctx);
     if (!parsed.ok)
         return parsed.outcome;
     let input = parsed.input;
@@ -485,27 +557,51 @@ export async function* executeHttpTool(tool, rawInput, ctx, base, stages) {
     const guarded = yield* guardToolTarget(target.url, ctx, stages?.span);
     if (!guarded.ok)
         return failureOutcome(guarded.failure, true);
-    return yield* sendWithCredential(prepared, guarded.url, () => sendHttpRequest(tool, guarded.url, target.body, prepared.authHeaders, ctx, base, stages?.span));
+    yield* dispatchToolBody(tool, input, ctx, base, beginBody);
+    return yield* sendWithCredential(prepared, guarded.url, (url) => sendHttpRequest(tool, url, target.body, prepared, ctx, base, stages?.span, shown));
+}
+/** A body that is text, read so far: what a successful call's drafts show. */
+function isDraftable(response) {
+    if (!response.ok)
+        return false;
+    const type = response.headers.get('content-type') ?? '';
+    return type === '' || type.startsWith('text/') || /[/+]json\b/.test(type);
 }
-async function* sendHttpRequest(tool, targetUrl, body, authHeaders, ctx, base, span) {
+/** An HTTP tool's body; a successful text body shows as drafts while it arrives, any other reads whole. */
+async function* readHttpBody(response, shown, secret) {
+    if (!shown || !isDraftable(response))
+        return await readCappedText(response);
+    return yield* readCappedTextShowing(response, shown, secret);
+}
+async function* sendHttpRequest(tool, targetUrl, body, { authHeaders, secret }, ctx, base, span, shown) {
     const checks = requestChecks(span);
     const headers = { Accept: 'application/json' };
     if (tool.method !== 'GET') {
         headers['Content-Type'] = 'application/json';
     }
+    let timedOut;
     try {
-        const response = await fetchGuarded(targetUrl.href, { method: tool.method, headers, body, signal: ctx.signal }, {
+        const place = tool.limit ? await takeLimitPlace(tool, tool.limit, ctx.signal) : undefined;
+        if (place && 'full' in place)
+            return failureOutcome(limitFullFailure(tool, place), false);
+        // why: the timeout starts at send, so a call's wait for a place is not counted against it.
+        timedOut = tool.timeoutMs === undefined ? undefined : AbortSignal.timeout(tool.timeoutMs);
+        const signal = timedOut && ctx.signal ? AbortSignal.any([ctx.signal, timedOut]) : (timedOut ?? ctx.signal);
+        const response = await answeredIn(place, fetchGuarded(targetUrl.href, { method: tool.method, headers, body, signal }, {
             policy: toolNetworkPolicy(ctx),
             followRedirects: true,
+            // why: a read changes nothing, so a busy or briefly down service is asked again, as a
+            // model call is; a write is never sent twice.
+            ...(tool.access === 'read-only' ? { fetchFn: retryTransient(fetch) } : {}),
             originBoundHeaders: { ...tool.headers, ...authHeaders },
             resolveHost: ctx.resolveHost,
             onCheck: checks.onCheck,
-        });
-        const text = await readCappedText(response);
+        }));
+        const text = yield* readHttpBody(response, shown, secret);
         if (text === undefined)
             return failureOutcome(tooLargeFailure(targetUrl.hostname), false);
         if (!response.ok) {
-            const refused = yield* refusedCredentialOutcome(tool, credentialRefusal(response), authHeaders, ctx, base);
+            const refused = yield* refusedCredentialOutcome(tool, credentialRefusal(response), secret !== undefined, ctx, base);
             if (refused)
                 return refused;
             const failure = {
@@ -521,7 +617,7 @@ async function* sendHttpRequest(tool, targetUrl, body, authHeaders, ctx, base, s
             const failure = {
                 code: 'invalid_output',
                 kind: 'bad_response',
-                message: 'HTTP response did not match tool output schema', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                message: 'HTTP response did not match tool output schema', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 details: checked.error.flatten(),
             };
             return failureOutcome(failure, false);
@@ -533,12 +629,23 @@ async function* sendHttpRequest(tool, targetUrl, body, authHeaders, ctx, base, s
         };
     }
     catch (err) {
+        if (tool.timeoutMs !== undefined && timedOut?.aborted && !ctx.signal?.aborted) {
+            return failureOutcome(timeoutFailure(targetUrl.hostname, tool.timeoutMs), false);
+        }
         return yield* thrownOutcome(err, checks);
     }
     finally {
         checks.record();
     }
 }
+/** The service did not answer within the tool's `timeoutMs`. */
+function timeoutFailure(hostname, timeoutMs) {
+    return {
+        code: 'timeout',
+        kind: 'timeout',
+        message: `${hostname} did not answer within ${timeoutMs} ms`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    };
+}
 /** Preferred first. */
 export const MCP_PROTOCOL_VERSIONS = [
     '2026-07-28',
@@ -563,7 +670,7 @@ export function parseMcpRpcResponse(text) {
             messages.push(JSON.parse(payload));
         }
         catch {
-            // Pings and other non-JSON payloads.
+            // why: Pings and other non-JSON payloads.
         }
     }
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -573,16 +680,17 @@ export function parseMcpRpcResponse(text) {
     }
     const last = messages.at(-1);
     if (!last) {
-        throw new Error(`MCP server returned non-JSON response: ${text}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new Error(`MCP server returned non-JSON response: ${text}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return last;
 }
+/** True when an MCP error says the server does not accept the protocol version sent. */
 export function isUnsupportedMcpProtocolError(error) {
     if (!error)
         return false;
     const message = error.message.toLowerCase();
-    return (message.includes('unsupported protocol version') || // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        message.includes('inconsistent mcp protocol version') // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return (message.includes('unsupported protocol version') || // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        message.includes('inconsistent mcp protocol version') // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     );
 }
 function unsupportedProtocolFromHttpBody(text) {
@@ -593,9 +701,9 @@ function unsupportedProtocolFromHttpBody(text) {
         }
     }
     catch {
-        // A non-JSON error page falls through to the raw-text check.
+        // why: A non-JSON error page falls through to the raw-text check.
     }
-    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     if (text.toLowerCase().includes('unsupported protocol version')) {
         return { code: -32600, message: text };
     }
@@ -609,7 +717,7 @@ async function fetchMcpProtocolAttempt(transport, rpcId, mcpToolName, input, pro
         params: {
             name: mcpToolName,
             arguments: input,
-            // Stateless servers read the client's capabilities from each call, not from an initialize.
+            // why: Stateless servers read the client's capabilities from each call, not from an initialize.
             _meta: {
                 'io.modelcontextprotocol/protocolVersion': protocolVersion,
                 'io.modelcontextprotocol/clientCapabilities': {},
@@ -659,7 +767,7 @@ async function fetchMcpProtocolAttempt(transport, rpcId, mcpToolName, input, pro
             failure: {
                 code: `mcp_http_${response.status}`,
                 kind: kindOfToolHttpStatus(response.status),
-                message: `MCP server error HTTP ${response.status}: ${quotedBody(text)}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                message: `MCP server error HTTP ${response.status}: ${quotedBody(text)}`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             },
         };
     }
@@ -676,7 +784,7 @@ async function fetchMcpProtocolAttempt(transport, rpcId, mcpToolName, input, pro
             failure: {
                 code: 'invalid_response',
                 kind: 'bad_response',
-                message: `MCP server returned non-JSON response: ${quotedBody(text)}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                message: `MCP server returned non-JSON response: ${quotedBody(text)}`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             },
         };
     }
@@ -792,7 +900,7 @@ async function negotiateInSession(transport, rpcId, mcpToolName, input, sessions
         if (outcome.kind === 'rpc')
             return { rpc: outcome.response };
         if (outcome.kind === 'failure') {
-            // A server can echo the session ID in its error; it goes no further than the server.
+            // why: A server can echo the session ID in its error; it goes no further than the server.
             const failure = {
                 ...outcome.failure,
                 message: outcome.failure.message.replaceAll(session.id, '[session]'),
@@ -807,12 +915,30 @@ async function negotiateInSession(transport, rpcId, mcpToolName, input, sessions
         failure: {
             code: 'mcp_session_expired',
             kind: 'failed',
-            message: 'MCP server ended the session again right after it was reopened', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            message: 'MCP server ended the session again right after it was reopened', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         },
     };
 }
+/** A limited tool with no place in its window within the wait budget: nothing was sent. */
+function limitFullFailure(tool, full) {
+    const { requests, windowMs } = full.limit;
+    // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    const opens = full.opensInMs === undefined
+        ? 'every one is still unanswered'
+        : `the next place opens in ${Math.ceil(full.opensInMs)} ms`;
+    return {
+        code: 'rate_limit_window',
+        kind: 'rate_limit',
+        message: `${tool.name} is at its limit of ${requests} requests per ${windowMs} ms; ${opens}`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    };
+}
+/** The failure kind for a tool server's HTTP status: 401, 402 and 403 are `auth`, as a provider's are; 429 `rate_limit`; the rest `failed`. */
 function kindOfToolHttpStatus(status) {
-    return status === 401 || status === 403 ? 'auth' : 'failed';
+    if (status === 401 || status === 402 || status === 403)
+        return 'auth';
+    if (status === 429)
+        return 'rate_limit';
+    return 'failed';
 }
 /** A content block as text: its text, an embedded resource's text, or a linked resource's URI. */
 function mcpContentText(block) {
@@ -870,7 +996,7 @@ function structuredMismatch(issues) {
     return {
         code: 'mcp_structured_mismatch',
         severity: 'warning',
-        message: `structuredContent does not match the output schema, so the text content was used. ${shown.join('; ')}${more}`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        message: `structuredContent does not match the output schema, so the text content was used. ${shown.join('; ')}${more}`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     };
 }
 function mcpResultFailure(rpcResponse) {
@@ -887,7 +1013,7 @@ function mcpResultFailure(rpcResponse) {
         return {
             code: 'mcp_tool_execution_failed',
             kind: 'failed',
-            message: result.content?.map((c) => c.text ?? '').join('\n') ?? 'MCP Tool execution error', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            message: result.content?.map((c) => c.text ?? '').join('\n') ?? 'MCP Tool execution error', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         };
     }
     return undefined;
@@ -903,7 +1029,7 @@ function interpretMcpRpc(tool, negotiated) {
             failure: {
                 code: 'mcp_protocol_error',
                 kind: 'failed',
-                message: negotiated.lastProtocolError?.message ?? 'MCP protocol negotiation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                message: negotiated.lastProtocolError?.message ?? 'MCP protocol negotiation failed', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 details: negotiated.lastProtocolError?.data,
             },
         };
@@ -920,7 +1046,7 @@ function interpretMcpRpc(tool, negotiated) {
             failure: {
                 code: 'invalid_output',
                 kind: 'bad_response',
-                message: 'MCP output schema validation failed', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                message: 'MCP output schema validation failed', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
                 details: checked.error.flatten(),
             },
             ...withWarning,
@@ -931,8 +1057,8 @@ function interpretMcpRpc(tool, negotiated) {
 /** Streamable HTTP, spec revision 2026-07-28. Order: schema → permission → auth → preTool/host stages → body. */
 export async function* executeMcpTool(tool, rawInput, ctx, base, stages, 
 /** The scope's sessions; without them a session lasts one call. */
-sessions = createMcpSessionCache()) {
-    const permitted = yield* remoteParseAndPermit(tool, rawInput, ctx, base);
+sessions = createMcpSessionCache(), beginBody) {
+    const permitted = remoteParseAndPermit(tool, rawInput, ctx);
     if (!permitted.ok)
         return permitted.outcome;
     const guarded = yield* guardToolTarget(tool.serverUrl, ctx, stages?.span);
@@ -941,9 +1067,10 @@ sessions = createMcpSessionCache()) {
     const prepared = yield* remoteAuthAndPreBody({ tool, input: permitted.input, ctx, base, stages });
     if (!('ok' in prepared))
         return prepared;
-    return yield* sendWithCredential(prepared, guarded.url, () => sendMcpRequest(tool, guarded.url, prepared.input, prepared.authHeaders, ctx, base, stages?.span, sessions));
+    yield* dispatchToolBody(tool, prepared.input, ctx, base, beginBody);
+    return yield* sendWithCredential(prepared, guarded.url, (url) => sendMcpRequest(tool, url, prepared.input, prepared, ctx, base, stages?.span, sessions));
 }
-async function* sendMcpRequest(tool, url, input, authHeaders, ctx, base, span, sessions) {
+async function* sendMcpRequest(tool, url, input, { authHeaders, secret }, ctx, base, span, sessions) {
     const checks = requestChecks(span);
     try {
         const transport = {
@@ -973,7 +1100,7 @@ async function* sendMcpRequest(tool, url, input, authHeaders, ctx, base, span, s
                 key,
             })
             : first;
-        const refused = yield* refusedCredentialOutcome(tool, negotiated.refusal, authHeaders, ctx, base);
+        const refused = yield* refusedCredentialOutcome(tool, negotiated.refusal, secret !== undefined, ctx, base);
         if (refused)
             return refused;
         const interpreted = interpretMcpRpc(tool, negotiated);