@dokebi/mcp 0.0.0-stage → 0.1.0

package/dist/runner.js

@@ -0,0 +1,740 @@
+import { performance } from 'node:perf_hooks';
+import { isDokebiError } from '@dokebi/core';
+import { diagnostics } from '@dokebi/core/libraries';
+import { imageBytes, isEnvelope } from './envelope.js';
+import { McpError } from './errors.js';
+import { isPlainObject } from './jsonrpc.js';
+import { INTERNAL_ERROR, INVALID_PARAMS, RESOURCE_NOT_FOUND } from './protocol.js';
+const INTERNAL_MESSAGE = 'The call failed unexpectedly';
+const INTERNAL_HINT = 'Try again later; if it keeps failing, tell the person who runs this server.';
+/** The body of a tool error (D-0074 shape plus `next`): code, message, hint, next, data. */
+export function errorBody(error) {
+    const data = error.data;
+    const next = data?.next;
+    const rest = data === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'next'));
+    return {
+        code: error.code,
+        message: error.message,
+        ...(error.hint === undefined ? {} : { hint: error.hint }),
+        ...(typeof next === 'string' || Array.isArray(next) ? { next } : {}),
+        ...(rest && Object.keys(rest).length ? { data: rest } : {}),
+    };
+}
+/** A tool result with `isError`: the error object as structuredContent and as JSON text. */
+export function toolError(body) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(body) }],
+        structuredContent: body,
+        isError: true,
+    };
+}
+function internalBody() {
+    return { code: 'INTERNAL', message: INTERNAL_MESSAGE, hint: INTERNAL_HINT };
+}
+function coded(code, message, hint, data) {
+    return { code, message, hint, ...(data ? { data } : {}) };
+}
+export class McpRunner {
+    #s;
+    #repeats;
+    constructor(settings) {
+        this.#s = settings;
+        this.#repeats = new diagnostics.Repeats({
+            logger: settings.logger,
+            intervalMs: settings.logRepeatWindowMs ?? 10_000,
+        });
+    }
+    /**
+     * D-0154: reloaded limits of the next call (the tool deadline, the result size, the picture
+     * limits); a call in progress keeps the ones it started with.
+     */
+    update(next) {
+        this.#s = { ...this.#s, ...next };
+    }
+    /** Writes the counted repeats of error logs (at close). */
+    flush() {
+        this.#repeats.flush();
+    }
+    #hookContext(signal, request) {
+        return Object.freeze({ ...this.#s.hookContext, signal, request });
+    }
+    #context(call, signal, fields, rateLimit) {
+        return {
+            grant: call.grant,
+            userId: call.grant.userId,
+            logger: this.#s.logger.child({ ...fields, grant: call.grant.id }),
+            signal,
+            request: call.request,
+            version: call.version,
+            rateLimit,
+        };
+    }
+    /**
+     * The budget of one call: one deadline and one signal for its hooks and its handler. The client's
+     * and the app's signals abort it through one listener each, removed by `release` when the call
+     * answered. Not AbortSignal.any: with the app signal, which lives as long as the app and never
+     * aborts before the stop, each composite stayed among that signal's dependants (about 340 bytes
+     * per call on Node 24.15, never freed: R5-MCP-1).
+     */
+    #budget(call) {
+        const controller = new AbortController();
+        const links = [];
+        for (const source of [call.signal, this.#s.appSignal]) {
+            if (source === undefined)
+                continue;
+            if (source.aborted) {
+                controller.abort(source.reason);
+                break;
+            }
+            const onAbort = () => controller.abort(source.reason);
+            source.addEventListener('abort', onAbort, { once: true });
+            links.push([source, onAbort]);
+        }
+        return {
+            controller,
+            signal: controller.signal,
+            deadline: performance.now() + this.#s.timeoutMs,
+            release: () => {
+                for (const [source, onAbort] of links)
+                    source.removeEventListener('abort', onAbort);
+                links.length = 0;
+            },
+        };
+    }
+    /**
+     * Runs one step (a hook or the handler) within what is left of the call's budget. Nothing runs
+     * once the signal is aborted (the client left, the budget ended, the app stops); a step that
+     * outlives its answer is observed and its end logged, never lost.
+     */
+    async #within(budget, work, fields) {
+        const signal = budget.signal;
+        if (signal.aborted)
+            return { kind: 'cancelled' };
+        const remaining = budget.deadline - performance.now();
+        if (remaining <= 0) {
+            budget.controller.abort(this.#timeout());
+            return { kind: 'timeout' };
+        }
+        let timer;
+        let onAbort;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ kind: 'timeout' }), remaining);
+        });
+        const stopped = new Promise((resolve) => {
+            onAbort = () => resolve({ kind: 'cancelled' });
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+        let running;
+        try {
+            running = Promise.resolve(work(signal));
+        }
+        catch (error) {
+            running = Promise.reject(error);
+        }
+        const settled = running.then((value) => ({ kind: 'done', value }), (error) => ({ kind: 'failed', error }));
+        const outcome = await Promise.race([settled, expired, stopped]);
+        clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener('abort', onAbort);
+        if (outcome.kind === 'timeout' || outcome.kind === 'cancelled') {
+            if (outcome.kind === 'timeout')
+                budget.controller.abort(this.#timeout());
+            // The step keeps running until it notices the signal: its end is logged. The signal is
+            // aborted by now (the budget or the client ended it), so a late rejection is told apart by
+            // what it is: the step stopping on the abort is debug, any other failure is an error.
+            void settled.then((late) => {
+                if (late.kind === 'failed' && !endedByAbort(late.error, signal))
+                    this.#repeats.log('error', 'MCP handler failed after its answer', 'MCP_LATE_FAILURE', late.error, fields, String(fields.name));
+                else
+                    diagnostics.logDebug(this.#s.logger, 'MCP handler ended after its answer', () => ({
+                        ...fields,
+                        outcome: late.kind,
+                        ...(late.kind === 'failed' ? { error: diagnostics.describeError(late.error) } : {}),
+                    }));
+            });
+        }
+        return outcome;
+    }
+    #timeout() {
+        return new McpError('TOOL_TIMEOUT', `The call ran longer than ${this.#s.timeoutMs} ms`);
+    }
+    /** The DokebiError for a thrown value: itself, a translation (D-0093), or undefined. */
+    #known(error, call, fields) {
+        if (isDokebiError(error)) {
+            if ((error.status ?? 0) >= 500)
+                this.#repeats.log('error', 'MCP call failed with a server error', 'MCP_CALL_FAILED', error, fields, `${fields.name} ${error.code}`);
+            else
+                diagnostics.logDebug(this.#s.logger, 'MCP call refused', () => ({
+                    ...fields,
+                    errorCode: error.code,
+                    ...(error.fix === undefined ? {} : { fix: error.fix }),
+                }));
+            return error;
+        }
+        for (const { plugin, value } of this.#s.translators) {
+            let translated;
+            try {
+                translated = value.translate(error, call.request);
+            }
+            catch (failure) {
+                this.#repeats.log('error', 'MCP error translator failed', 'MCP_ERROR_TRANSLATOR_FAILED', failure, { ...fields, translator: plugin }, plugin);
+                continue;
+            }
+            if (translated === undefined)
+                continue;
+            if (!isDokebiError(translated)) {
+                this.#repeats.log('error', 'MCP error translator failed', 'MCP_ERROR_TRANSLATOR_FAILED', new McpError('INVALID_HOOK_RESULT', 'An error translator returned something other than a Dokebi error or undefined', { data: { translator: plugin } }), { ...fields, translator: plugin }, plugin);
+                continue;
+            }
+            this.#repeats.log('error', 'MCP call error translated', 'MCP_ERROR_TRANSLATED', translated, { ...fields, translator: plugin, errorCode: translated.code }, `${fields.name} ${translated.code}`);
+            return translated;
+        }
+        return undefined;
+    }
+    #failed(error, fields) {
+        this.#repeats.log('error', 'MCP call failed', 'MCP_CALL_FAILED', error, fields, String(fields.name));
+    }
+    #hookFailed(hook, error, fields) {
+        this.#repeats.log('error', 'MCP hook failed', 'MCP_HOOK_FAILED', error, { ...fields, hook }, hook);
+    }
+    #log(call, fields, started, bytes, code, envelope) {
+        this.report(call, fields.method, String(fields.name), Math.round(performance.now() - started), bytes, code, envelope);
+    }
+    /**
+     * The end of one call: its MCP_CALL info line and, when the request records them, its frozen
+     * `onCall` entry with the same values (D-0134). The route's own refusals (the scope, an unknown
+     * name) come here too, so the log and the hook see the same calls.
+     */
+    report(call, method, name, ms, bytes, code, envelope) {
+        const images = envelope?.images;
+        this.#s.logger.log('info', 'MCP call', {
+            code: 'MCP_CALL',
+            method,
+            name,
+            grant: call.grant.id,
+            client: call.grant.clientId,
+            ms,
+            bytes,
+            result: code,
+            // D-0143: how many pictures went and their bytes; never the bytes themselves.
+            ...(images ? { images: images.length, imageBytes: total(images) } : {}),
+        });
+        if (call.record)
+            call.record(Object.freeze({
+                method,
+                name,
+                grant: call.grant.id,
+                client: call.grant.clientId,
+                userId: call.grant.userId,
+                ms,
+                bytes,
+                result: code,
+                ...(envelope === undefined ? {} : { envelope }),
+            }));
+    }
+    /**
+     * One token of the grant's bucket. An allowed call keeps the decision (D-0131): the handler reads
+     * it as `context.rateLimit`, what is left after this call's token, without another round trip.
+     */
+    async #limit(bucket, grant) {
+        const limiter = this.#s.limiters.get(bucket);
+        if (!limiter)
+            return { kind: 'none' };
+        let decision;
+        try {
+            decision = await limiter.consume(`${bucket}:${grant.id}`);
+        }
+        catch (error) {
+            // A store failure of the limiter (UNAVAILABLE, CAPACITY): answered with its code.
+            return { kind: 'failed', error };
+        }
+        if (!decision.allowed)
+            return { kind: 'refused', seconds: Math.max(1, Math.ceil(decision.retryAfterMs / 1000)) };
+        return {
+            kind: 'allowed',
+            rateLimit: Object.freeze({
+                bucket,
+                limit: decision.limit,
+                remaining: decision.remaining,
+                resetAfterMs: decision.resetAfterMs,
+            }),
+        };
+    }
+    /** `checkGrant` when the extension has it, within the budget. */
+    async #checkGrant(target, call, budget, fields) {
+        if (!this.#s.hooks || !this.#s.overridden.has('checkGrant'))
+            return undefined;
+        const hooks = this.#s.hooks;
+        const outcome = await this.#within(budget, (signal) => hooks.checkGrant(call.grant, target, this.#hookContext(signal, call.request)), { ...fields, hook: 'checkGrant' });
+        if (outcome.kind === 'timeout' || outcome.kind === 'cancelled')
+            return { stopped: outcome.kind };
+        if (outcome.kind === 'failed') {
+            if (isDokebiError(outcome.error))
+                return { error: outcome.error };
+            this.#hookFailed('checkGrant', outcome.error, fields);
+            return { error: new McpError('INTERNAL', INTERNAL_MESSAGE, { cause: outcome.error }) };
+        }
+        if (outcome.value === true)
+            return undefined;
+        if (outcome.value === false) {
+            diagnostics.logDebug(this.#s.logger, 'MCP grant refused by checkGrant', () => fields);
+            return { refused: true };
+        }
+        this.#hookFailed('checkGrant', new McpError('INVALID_HOOK_RESULT', 'checkGrant() must return a boolean', {
+            data: { hook: 'checkGrant' },
+        }), fields);
+        return { error: new McpError('INTERNAL', INTERNAL_MESSAGE) };
+    }
+    /** One `tools/call`, after the scope check. */
+    async callTool(compiled, args, call) {
+        const budget = this.#budget(call);
+        try {
+            return await this.#callTool(compiled, args, call, budget);
+        }
+        finally {
+            budget.release();
+        }
+    }
+    async #callTool(compiled, args, call, budget) {
+        const started = performance.now();
+        const fields = {
+            method: 'tools/call',
+            name: compiled.name,
+            grant: call.grant.id,
+            client: call.grant.clientId,
+        };
+        const done = (result, code, bytes, envelope) => {
+            this.#log(call, fields, started, bytes, code, envelope);
+            return { result, code };
+        };
+        const refuse = (body) => {
+            const result = toolError(body);
+            return done(result, String(body.code), Buffer.byteLength(result.content[0]?.text ?? ''));
+        };
+        const fromError = (error) => {
+            const known = this.#known(error, call, fields);
+            if (known)
+                return refuse(errorBody(known));
+            this.#failed(error, fields);
+            return refuse(internalBody());
+        };
+        const stopped = (kind) => {
+            if (kind === 'cancelled')
+                return refuse(coded('CANCELLED', 'The call was cancelled', 'Call the tool again if you still need it.'));
+            this.#s.logger.log('warn', 'MCP call ran out of time', {
+                code: 'MCP_TOOL_TIMEOUT',
+                ...fields,
+                timeoutMs: this.#s.timeoutMs,
+            });
+            return refuse(coded('TOOL_TIMEOUT', `The tool ran longer than ${Math.round(this.#s.timeoutMs / 1000)} seconds`, 'Ask for less (a smaller page or a narrower filter), or try again later.'));
+        };
+        // 1. The limit of this grant and bucket (every attempt takes a token).
+        const limited = await this.#limit(compiled.bucket, call.grant);
+        if (limited.kind === 'failed')
+            return fromError(limited.error);
+        if (limited.kind === 'refused')
+            return refuse({
+                code: 'LIMIT_EXCEEDED',
+                message: `This connection used its ${compiled.bucket} limit`,
+                hint: `Wait ${limited.seconds} seconds, then call the tool again.`,
+                next: `Wait ${limited.seconds} seconds before calling ${compiled.name} again.`,
+                retry_after: limited.seconds,
+            });
+        if (budget.signal.aborted)
+            return stopped('cancelled');
+        // 2. The grant may still reach this (the binding's project, the membership).
+        const grantCheck = await this.#checkGrant({
+            kind: 'tool',
+            name: compiled.name,
+            scope: compiled.scope,
+            scopes: compiled.scopes,
+            matched: matchedScope(call.grant.scopes, compiled.scopes),
+            value: compiled.tool,
+        }, call, budget, fields);
+        if (grantCheck && 'stopped' in grantCheck)
+            return stopped(grantCheck.stopped);
+        if (grantCheck && 'refused' in grantCheck)
+            return refuse(coded('GRANT_REFUSED', 'This connection may not use this any more', 'Ask the user to check the connection in the application, or to connect again.'));
+        if (grantCheck)
+            return fromError(grantCheck.error);
+        // 3. The input (any failure of the check is an answer, never an HTTP 500).
+        const input = args === undefined ? {} : args;
+        if (!isPlainObject(input))
+            return refuse(coded('INVALID_INPUT', `The arguments of ${compiled.name} must be an object`, 'Send the arguments as one JSON object, as the input schema says.'));
+        let problems;
+        try {
+            problems = compiled.input.validate(input);
+        }
+        catch (error) {
+            this.#failed(new McpError('INVALID_INPUT', `The input check of ${compiled.name} failed`, {
+                cause: error,
+            }), fields);
+            return refuse(internalBody());
+        }
+        if (problems.length)
+            return refuse(coded('INVALID_INPUT', `The arguments do not match the input schema of ${compiled.name}`, 'Correct the listed arguments and call the tool again.', { problems }));
+        // 4. The handler, within the budget.
+        const outcome = await this.#within(budget, (signal) => {
+            const context = Object.freeze({
+                ...this.#context(call, signal, { tool: compiled.name }, limited.kind === 'allowed' ? limited.rateLimit : undefined),
+                resultMaxChars: this.#s.resultMaxChars,
+                images: this.#s.images,
+            });
+            return compiled.tool.handle(input, context);
+        }, fields);
+        if (outcome.kind === 'timeout' || outcome.kind === 'cancelled')
+            return stopped(outcome.kind);
+        if (outcome.kind === 'failed')
+            return fromError(outcome.error);
+        // 5. The envelope, then the hook that may change it once (within the budget too).
+        let result = outcome.value;
+        if (!isEnvelope(result)) {
+            this.#failed(new McpError('INVALID_RESULT', `${compiled.name}.handle() returned something other than envelope()`, {
+                fix: `Return envelope({ content, note, … }) from ${compiled.name}.handle() (import { envelope } from '@dokebi/mcp').`,
+            }), fields);
+            return refuse(internalBody());
+        }
+        if (this.#s.hooks && this.#s.overridden.has('transformResult')) {
+            const hooks = this.#s.hooks;
+            const original = result;
+            const changed = await this.#within(budget, (signal) => hooks.transformResult(original, { tool: compiled.tool, grant: call.grant }, this.#hookContext(signal, call.request)), { ...fields, hook: 'transformResult' });
+            if (changed.kind === 'timeout' || changed.kind === 'cancelled')
+                return stopped(changed.kind);
+            if (changed.kind === 'failed') {
+                if (isDokebiError(changed.error))
+                    return fromError(changed.error);
+                this.#hookFailed('transformResult', changed.error, fields);
+                return refuse(internalBody());
+            }
+            result = changed.value;
+            if (!isEnvelope(result)) {
+                this.#hookFailed('transformResult', new McpError('INVALID_HOOK_RESULT', 'transformResult() must return an envelope (amend(result, …))', { data: { hook: 'transformResult' } }), fields);
+                return refuse(internalBody());
+            }
+        }
+        // 6. The pictures (D-0143): their own limits, apart from resultMaxChars.
+        const images = result.images ?? [];
+        if (images.length) {
+            const refused = this.#imageLimits(images, fields);
+            if (refused)
+                return refuse(refused);
+        }
+        // 7. The size, never cut silently.
+        let text;
+        try {
+            text = JSON.stringify(result);
+        }
+        catch (error) {
+            this.#failed(new McpError('INVALID_RESULT', `The result of ${compiled.name} cannot be written as JSON`, {
+                cause: error,
+            }), fields);
+            return refuse(internalBody());
+        }
+        if (text.length > this.#s.resultMaxChars)
+            return refuse(coded('RESULT_TOO_LARGE', `The result has ${text.length} characters; the limit is ${this.#s.resultMaxChars}`, 'Ask for less: a smaller page (cursor) or a narrower filter.', {
+                chars: text.length,
+                max: this.#s.resultMaxChars,
+            }));
+        // The text block first, then one MCP image block per picture (every protocol version has
+        // `{ type: 'image', data, mimeType }`; no annotations, so 2025-03-26 clients read it too).
+        const content = [{ type: 'text', text }];
+        for (const image of images) {
+            // Every placeholder of an envelope() has its bytes (isEnvelope above).
+            const bytes = imageBytes(image);
+            content.push({
+                type: 'image',
+                data: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64'),
+                mimeType: image.mimeType,
+            });
+        }
+        return done({ content, structuredContent: result }, 'ok', Buffer.byteLength(text), result);
+    }
+    /** The image limits of one result: undefined when they hold, else the tool error's body. */
+    #imageLimits(images, fields) {
+        const limits = this.#s.images;
+        const bytes = total(images);
+        const refuse = (body) => {
+            diagnostics.logDebug(this.#s.logger, 'MCP images refused', () => ({
+                ...fields,
+                errorCode: body.code,
+                images: images.length,
+                imageBytes: bytes,
+                ...limits,
+            }));
+            return body;
+        };
+        if (images.length > limits.maxImages)
+            return refuse(coded('TOO_MANY_IMAGES', `The result has ${images.length} pictures; the limit is ${limits.maxImages}`, 'Ask for fewer pictures (a narrower filter or a smaller page).', { count: images.length, max: limits.maxImages }));
+        for (const image of images)
+            if (image.bytes > limits.imageMaxBytes)
+                return refuse(coded('IMAGE_TOO_LARGE', `Picture ${image.index} has ${image.bytes} bytes; the limit is ${limits.imageMaxBytes}`, 'Ask for a smaller picture, or describe it in words instead.', { index: image.index, bytes: image.bytes, max: limits.imageMaxBytes }));
+        if (bytes > limits.imageTotalMaxBytes)
+            return refuse(coded('IMAGE_TOTAL_TOO_LARGE', `The pictures have ${bytes} bytes together; the limit is ${limits.imageTotalMaxBytes}`, 'Ask for fewer or smaller pictures.', { bytes, max: limits.imageTotalMaxBytes }));
+        diagnostics.logDebug(this.#s.logger, 'MCP images attached', () => ({
+            ...fields,
+            images: images.length,
+            imageBytes: bytes,
+            sizes: images.map((image) => image.bytes),
+            mimeTypes: images.map((image) => image.mimeType),
+        }));
+        return undefined;
+    }
+    /** The JSON-RPC error of a thrown value (prompts, resources). */
+    #rpcFailure(error, call, fields) {
+        const known = this.#known(error, call, fields);
+        if (known)
+            return {
+                kind: 'error',
+                // A 5xx is the server's state (a storage that is stopping, a store that is down): -32603,
+                // with the code and its retryAfterMs; an application refusal is the request's: -32602.
+                error: (known.status ?? 0) >= 500 ? INTERNAL_ERROR : INVALID_PARAMS,
+                message: known.message,
+                data: errorBody(known),
+                code: known.code,
+            };
+        this.#failed(error, fields);
+        return {
+            kind: 'error',
+            error: INTERNAL_ERROR,
+            message: INTERNAL_MESSAGE,
+            data: internalBody(),
+            code: 'INTERNAL',
+        };
+    }
+    /** The size limit of a prompt or resource answer (its JSON). */
+    #sized(result, what) {
+        const size = JSON.stringify(result).length;
+        if (size <= this.#s.resultMaxChars)
+            return { kind: 'result', result, code: 'ok' };
+        const message = `The ${what} has ${size} characters; the limit is ${this.#s.resultMaxChars}`;
+        return {
+            kind: 'error',
+            error: INVALID_PARAMS,
+            message,
+            data: coded('RESULT_TOO_LARGE', message, `Ask for a smaller ${what}.`, {
+                chars: size,
+                max: this.#s.resultMaxChars,
+            }),
+            code: 'RESULT_TOO_LARGE',
+        };
+    }
+    /** Prompts and resources: the `read` limit, checkGrant and the step, all within the budget. */
+    async #guarded(target, call, fields, run, shape) {
+        const budget = this.#budget(call);
+        try {
+            return await this.#guardedIn(budget, target, call, fields, run, shape);
+        }
+        finally {
+            budget.release();
+        }
+    }
+    async #guardedIn(budget, target, call, fields, run, shape) {
+        const started = performance.now();
+        const finish = (outcome) => {
+            const bytes = outcome.kind === 'result' ? Buffer.byteLength(JSON.stringify(outcome.result)) : 0;
+            this.#log(call, fields, started, bytes, outcome.code);
+            return outcome;
+        };
+        const failure = (error, code, message, hint, data) => ({
+            kind: 'error',
+            error,
+            message,
+            data: coded(code, message, hint, data),
+            code,
+        });
+        const stopped = (kind) => {
+            if (kind === 'cancelled')
+                return failure(INTERNAL_ERROR, 'CANCELLED', 'The call was cancelled', 'Call again if you still need it.');
+            this.#s.logger.log('warn', 'MCP call ran out of time', {
+                code: 'MCP_TOOL_TIMEOUT',
+                ...fields,
+                timeoutMs: this.#s.timeoutMs,
+            });
+            return failure(INTERNAL_ERROR, 'TOOL_TIMEOUT', `The call ran longer than ${Math.round(this.#s.timeoutMs / 1000)} seconds`, 'Try again later.');
+        };
+        // Prompts and resources take tokens of the `read` bucket (a batch is no way around it).
+        const limited = await this.#limit('read', call.grant);
+        if (limited.kind === 'failed')
+            return finish(this.#rpcFailure(limited.error, call, fields));
+        if (limited.kind === 'refused')
+            return finish({
+                kind: 'error',
+                error: INVALID_PARAMS,
+                message: 'This connection used its read limit',
+                data: {
+                    code: 'LIMIT_EXCEEDED',
+                    message: 'This connection used its read limit',
+                    hint: `Wait ${limited.seconds} seconds, then call again.`,
+                    retry_after: limited.seconds,
+                },
+                code: 'LIMIT_EXCEEDED',
+            });
+        if (budget.signal.aborted)
+            return finish(stopped('cancelled'));
+        const grantCheck = await this.#checkGrant(target, call, budget, fields);
+        if (grantCheck && 'stopped' in grantCheck)
+            return finish(stopped(grantCheck.stopped));
+        if (grantCheck && 'refused' in grantCheck)
+            return finish(failure(INVALID_PARAMS, 'GRANT_REFUSED', 'This connection may not use this any more', 'Ask the user to check the connection in the application, or to connect again.'));
+        if (grantCheck)
+            return finish(this.#rpcFailure(grantCheck.error, call, fields));
+        const rateLimit = limited.kind === 'allowed' ? limited.rateLimit : undefined;
+        const outcome = await this.#within(budget, (signal) => run(signal, rateLimit), fields);
+        if (outcome.kind === 'timeout' || outcome.kind === 'cancelled')
+            return finish(stopped(outcome.kind));
+        if (outcome.kind === 'failed')
+            return finish(this.#rpcFailure(outcome.error, call, fields));
+        return finish(shape(outcome.value));
+    }
+    /** One `prompts/get` (arguments already checked against the declaration). */
+    async getPrompt(compiled, args, call) {
+        const fields = {
+            method: 'prompts/get',
+            name: compiled.name,
+            grant: call.grant.id,
+            client: call.grant.clientId,
+        };
+        return this.#guarded({
+            kind: 'prompt',
+            name: compiled.name,
+            scope: compiled.scope,
+            scopes: compiled.scopes,
+            matched: matchedScope(call.grant.scopes, compiled.scopes),
+            value: compiled.prompt,
+        }, call, fields, (signal, rateLimit) => compiled.prompt.handle(args, Object.freeze(this.#context(call, signal, { prompt: compiled.name }, rateLimit))), (value) => {
+            const shaped = promptResult(value);
+            if (shaped)
+                return this.#sized(shaped, 'prompt');
+            this.#failed(new McpError('INVALID_RESULT', `${compiled.name}.handle() must return a string, a list of { role, text } or { description, messages }`), fields);
+            return {
+                kind: 'error',
+                error: INTERNAL_ERROR,
+                message: INTERNAL_MESSAGE,
+                data: internalBody(),
+                code: 'INTERNAL',
+            };
+        });
+    }
+    /** One `resources/read` of a matched resource. */
+    async readResource(compiled, params, uri, call) {
+        const fields = {
+            method: 'resources/read',
+            name: compiled.name,
+            grant: call.grant.id,
+            client: call.grant.clientId,
+        };
+        return this.#guarded({
+            kind: 'resource',
+            name: compiled.name,
+            scope: compiled.scope,
+            scopes: compiled.scopes,
+            matched: matchedScope(call.grant.scopes, compiled.scopes),
+            value: compiled.resource,
+        }, call, fields, (signal, rateLimit) => compiled.resource.read(params, Object.freeze({
+            ...this.#context(call, signal, { resource: compiled.name }, rateLimit),
+            uri,
+        })), (value) => {
+            if (value === undefined)
+                return {
+                    kind: 'error',
+                    error: RESOURCE_NOT_FOUND,
+                    message: 'There is no such resource',
+                    data: { uri, code: 'NOT_FOUND' },
+                    code: 'NOT_FOUND',
+                };
+            let entry;
+            if (typeof value === 'string')
+                entry = { uri, mimeType: compiled.mimeType ?? 'text/plain', text: value };
+            else if (value instanceof Uint8Array)
+                entry = {
+                    uri,
+                    mimeType: compiled.mimeType ?? 'application/octet-stream',
+                    blob: Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('base64'),
+                };
+            else {
+                let text;
+                try {
+                    text = JSON.stringify(value);
+                    // No throw, no text either (a function, a symbol, a toJSON answering undefined): the
+                    // INTERNAL answer below gets its error record all the same (D-0047, R5-MCP-2).
+                    if (text === undefined)
+                        this.#failed(new McpError('INVALID_RESULT', `${compiled.name}.read() returned a value JSON cannot write`), fields);
+                }
+                catch (error) {
+                    this.#failed(new McpError('INVALID_RESULT', `${compiled.name}.read() returned a value that is not JSON`, { cause: error }), fields);
+                }
+                if (text === undefined)
+                    return {
+                        kind: 'error',
+                        error: INTERNAL_ERROR,
+                        message: INTERNAL_MESSAGE,
+                        data: internalBody(),
+                        code: 'INTERNAL',
+                    };
+                entry = { uri, mimeType: compiled.mimeType ?? 'application/json', text };
+            }
+            return this.#sized({ contents: [entry] }, 'resource');
+        });
+    }
+}
+/**
+ * Whether a step's late rejection is its reaction to the abort: the signal's own reason (what
+ * an aborted `fetch` rejects with on Node 24) or an AbortError (what `timers/promises` rejects
+ * with, its cause the reason), never a failure of its own.
+ */
+function endedByAbort(error, signal) {
+    if (signal.aborted && error === signal.reason)
+        return true;
+    return error?.name === 'AbortError';
+}
+/** The bytes of a result's pictures together. */
+function total(images) {
+    let bytes = 0;
+    for (const image of images)
+        bytes += image.bytes;
+    return bytes;
+}
+/** A prompt's return value as `GetPromptResult`, or undefined when it has the wrong shape. */
+function promptResult(value) {
+    const message = (one) => {
+        const entry = one;
+        if (!entry ||
+            (entry.role !== 'user' && entry.role !== 'assistant') ||
+            typeof entry.text !== 'string')
+            return undefined;
+        return { role: entry.role, content: { type: 'text', text: entry.text } };
+    };
+    const list = (items) => {
+        if (!Array.isArray(items) || items.length === 0)
+            return undefined;
+        const messages = items.map(message);
+        return messages.every((one) => one !== undefined) ? messages : undefined;
+    };
+    if (typeof value === 'string')
+        return { messages: [{ role: 'user', content: { type: 'text', text: value } }] };
+    if (Array.isArray(value)) {
+        const messages = list(value);
+        return messages && { messages };
+    }
+    if (isPlainObject(value)) {
+        const messages = list(value.messages);
+        if (!messages)
+            return undefined;
+        if (value.description !== undefined && typeof value.description !== 'string')
+            return undefined;
+        return {
+            ...(value.description === undefined ? {} : { description: value.description }),
+            messages,
+        };
+    }
+    return undefined;
+}
+/**
+ * The first of `scopes` the grant holds: the one that let the call through (the scope check ran
+ * before, so one is held; the first of the list otherwise).
+ */
+function matchedScope(granted, scopes) {
+    return scopes.find((scope) => granted.includes(scope)) ?? scopes[0];
+}