@modelprofile.com/flexharness 10.18.0 → 10.20.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@modelprofile.com/flexharness',
-    version: '10.18.0',
+    version: '10.20.0',
     description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSwrQkFBK0I7SUFDckMsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLDBFQUEwRTtDQUN4RixDQUFBIn0=

package/dist_ts_ocr/ocr.mistral.d.ts

@@ -5,6 +5,12 @@ export interface ISmartAiOcrImageInput {
     dataBase64: string;
     mimeType: TSmartAiOcrImageMimeType;
 }
+/** Mistral OCR reads PDF, PPTX, DOCX and other document formats. */
+export type TSmartAiOcrDocumentMimeType = 'application/pdf' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | string;
+export interface ISmartAiOcrDocumentInput {
+    dataBase64: string;
+    mimeType: TSmartAiOcrDocumentMimeType;
+}
 export interface ISmartAiOcrPageResult {
     index: number;
     text: string;
@@ -19,6 +25,10 @@ export interface ISmartAiOcrResult<TRaw = unknown> {
 export interface ISmartAiOcrEngine {
     recognizeImage: (input: ISmartAiOcrImageInput, options?: ISmartAiMistralOcrRecognizeOptions) => Promise<ISmartAiOcrResult<IMistralOcrResponse>>;
 }
+/** The Mistral OCR engine also reads whole documents, such as a PDF with all its pages. */
+export interface ISmartAiMistralOcrEngine extends ISmartAiOcrEngine {
+    recognizeDocument: (input: ISmartAiOcrDocumentInput, options?: ISmartAiMistralOcrRecognizeOptions) => Promise<ISmartAiOcrResult<IMistralOcrResponse>>;
+}
 export interface IMistralOcrPageConfidenceScores {
     average_page_confidence_score?: number;
     averagePageConfidenceScore?: number;
@@ -51,8 +61,17 @@ export interface IMistralOcrRequest {
     extract_footer?: boolean;
     confidence_scores_granularity?: TSmartAiMistralOcrConfidenceScoresGranularity;
 }
+/** A document (PDF, PPTX, DOCX and other formats) as a URL or a base64 data URL; the other fields are those of an image request. */
+export interface IMistralOcrDocumentRequest extends Omit<IMistralOcrRequest, 'document'> {
+    document: {
+        type: 'document_url';
+        document_url: string;
+    };
+}
 export interface ISmartAiMistralOcrTransport {
     process: (request: IMistralOcrRequest) => Promise<IMistralOcrResponse>;
+    /** Reads documents. A transport without it reads images only, and `recognizeDocument` refuses documents. */
+    processDocument?: (request: IMistralOcrDocumentRequest) => Promise<IMistralOcrResponse>;
 }
 export interface ISmartAiMistralOcrOptions {
     apiKey?: string;
@@ -72,4 +91,4 @@ export interface ISmartAiMistralOcrRecognizeOptions {
     extractFooter?: boolean;
     confidenceScoresGranularity?: TSmartAiMistralOcrConfidenceScoresGranularity;
 }
-export declare const createMistralOcrEngine: (options?: ISmartAiMistralOcrOptions) => ISmartAiOcrEngine;
+export declare const createMistralOcrEngine: (options?: ISmartAiMistralOcrOptions) => ISmartAiMistralOcrEngine;

package/dist_ts_ocr/ocr.mistral.js

@@ -1,32 +1,50 @@
 const defaultMistralOcrModel = 'mistral-ocr-latest';
 const defaultMistralOcrEndpointUrl = 'https://api.mistral.ai/v1/ocr';
 const createMistralOcrHttpTransport = (options) => {
-    return {
-        process: async (request) => {
-            if (!options.apiKey) {
-                throw new Error('Mistral OCR requires an apiKey when no custom transport is provided.');
-            }
-            const response = await fetch(options.endpointUrl ?? defaultMistralOcrEndpointUrl, {
-                method: 'POST',
-                headers: {
-                    Authorization: `Bearer ${options.apiKey}`,
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify(request),
-            });
-            if (!response.ok) {
-                const errorBody = await response.text();
-                throw new Error(`Mistral OCR request failed with status ${response.status}: ${errorBody}`);
-            }
-            return (await response.json());
-        },
+    const post = async (request) => {
+        if (!options.apiKey) {
+            throw new Error('Mistral OCR requires an apiKey when no custom transport is provided.');
+        }
+        const response = await fetch(options.endpointUrl ?? defaultMistralOcrEndpointUrl, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${options.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`Mistral OCR request failed with status ${response.status}: ${errorBody}`);
+        }
+        return (await response.json());
     };
+    return { process: post, processDocument: post };
 };
 const getPageConfidence = (page) => {
     const confidenceScores = page.confidence_scores ?? page.confidenceScores;
     return (confidenceScores?.average_page_confidence_score ??
         confidenceScores?.averagePageConfidenceScore);
 };
+const toOcrResult = (response) => {
+    const pages = response.pages.map((page) => ({
+        index: page.index,
+        text: page.markdown,
+        confidence: getPageConfidence(page),
+    }));
+    const pageConfidences = pages
+        .map((page) => page.confidence)
+        .filter((confidence) => typeof confidence === 'number');
+    const confidence = pageConfidences.length
+        ? pageConfidences.reduce((sum, value) => sum + value, 0) / pageConfidences.length
+        : undefined;
+    return {
+        text: pages.map((page) => page.text).join('\n\n').trim(),
+        confidence,
+        pages,
+        raw: response,
+    };
+};
 export const createMistralOcrEngine = (options = {}) => {
     const transport = options.transport ??
         createMistralOcrHttpTransport({
@@ -34,6 +52,13 @@ export const createMistralOcrEngine = (options = {}) => {
             endpointUrl: options.endpointUrl,
         });
     const model = options.model ?? defaultMistralOcrModel;
+    const settingsOf = (recognizeOptions) => ({
+        include_image_base64: recognizeOptions.includeImageBase64 ?? options.includeImageBase64 ?? false,
+        table_format: recognizeOptions.tableFormat ?? options.tableFormat,
+        extract_header: recognizeOptions.extractHeader ?? options.extractHeader,
+        extract_footer: recognizeOptions.extractFooter ?? options.extractFooter,
+        confidence_scores_granularity: recognizeOptions.confidenceScoresGranularity ?? options.confidenceScoresGranularity,
+    });
     return {
         recognizeImage: async (input, recognizeOptions = {}) => {
             if (!input.dataBase64) {
@@ -42,36 +67,34 @@ export const createMistralOcrEngine = (options = {}) => {
             if (!input.mimeType) {
                 throw new Error('Mistral OCR image input requires mimeType.');
             }
-            const response = await transport.process({
+            return toOcrResult(await transport.process({
                 model,
                 document: {
                     type: 'image_url',
                     image_url: `data:${input.mimeType};base64,${input.dataBase64}`,
                 },
-                include_image_base64: recognizeOptions.includeImageBase64 ?? options.includeImageBase64 ?? false,
-                table_format: recognizeOptions.tableFormat ?? options.tableFormat,
-                extract_header: recognizeOptions.extractHeader ?? options.extractHeader,
-                extract_footer: recognizeOptions.extractFooter ?? options.extractFooter,
-                confidence_scores_granularity: recognizeOptions.confidenceScoresGranularity ?? options.confidenceScoresGranularity,
-            });
-            const pages = response.pages.map((page) => ({
-                index: page.index,
-                text: page.markdown,
-                confidence: getPageConfidence(page),
+                ...settingsOf(recognizeOptions),
+            }));
+        },
+        recognizeDocument: async (input, recognizeOptions = {}) => {
+            if (!transport.processDocument) {
+                throw new Error('This Mistral OCR transport reads images only: it has no processDocument, so it cannot read documents.');
+            }
+            if (!input.dataBase64) {
+                throw new Error('Mistral OCR document input requires dataBase64.');
+            }
+            if (!input.mimeType) {
+                throw new Error('Mistral OCR document input requires mimeType.');
+            }
+            return toOcrResult(await transport.processDocument({
+                model,
+                document: {
+                    type: 'document_url',
+                    document_url: `data:${input.mimeType};base64,${input.dataBase64}`,
+                },
+                ...settingsOf(recognizeOptions),
             }));
-            const pageConfidences = pages
-                .map((page) => page.confidence)
-                .filter((confidence) => typeof confidence === 'number');
-            const confidence = pageConfidences.length
-                ? pageConfidences.reduce((sum, value) => sum + value, 0) / pageConfidences.length
-                : undefined;
-            return {
-                text: pages.map((page) => page.text).join('\n\n').trim(),
-                confidence,
-                pages,
-                raw: response,
-            };
         },
     };
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib2NyLm1pc3RyYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19vY3Ivb2NyLm1pc3RyYWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBZ0dBLE1BQU0sc0JBQXNCLEdBQUcsb0JBQW9CLENBQUM7QUFDcEQsTUFBTSw0QkFBNEIsR0FBRywrQkFBK0IsQ0FBQztBQUVyRSxNQUFNLDZCQUE2QixHQUFHLENBQUMsT0FHdEMsRUFBK0IsRUFBRTtJQUNoQyxPQUFPO1FBQ0wsT0FBTyxFQUFFLEtBQUssRUFBRSxPQUFPLEVBQUUsRUFBRTtZQUN6QixJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU0sRUFBRSxDQUFDO2dCQUNwQixNQUFNLElBQUksS0FBSyxDQUFDLHNFQUFzRSxDQUFDLENBQUM7WUFDMUYsQ0FBQztZQUVELE1BQU0sUUFBUSxHQUFHLE1BQU0sS0FBSyxDQUFDLE9BQU8sQ0FBQyxXQUFXLElBQUksNEJBQTRCLEVBQUU7Z0JBQ2hGLE1BQU0sRUFBRSxNQUFNO2dCQUNkLE9BQU8sRUFBRTtvQkFDUCxhQUFhLEVBQUUsVUFBVSxPQUFPLENBQUMsTUFBTSxFQUFFO29CQUN6QyxjQUFjLEVBQUUsa0JBQWtCO2lCQUNuQztnQkFDRCxJQUFJLEVBQUUsSUFBSSxDQUFDLFNBQVMsQ0FBQyxPQUFPLENBQUM7YUFDOUIsQ0FBQyxDQUFDO1lBRUgsSUFBSSxDQUFDLFFBQVEsQ0FBQyxFQUFFLEVBQUUsQ0FBQztnQkFDakIsTUFBTSxTQUFTLEdBQUcsTUFBTSxRQUFRLENBQUMsSUFBSSxFQUFFLENBQUM7Z0JBQ3hDLE1BQU0sSUFBSSxLQUFLLENBQUMsMENBQTBDLFFBQVEsQ0FBQyxNQUFNLEtBQUssU0FBUyxFQUFFLENBQUMsQ0FBQztZQUM3RixDQUFDO1lBRUQsT0FBTyxDQUFDLE1BQU0sUUFBUSxDQUFDLElBQUksRUFBRSxDQUF3QixDQUFDO1FBQ3hELENBQUM7S0FDRixDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUYsTUFBTSxpQkFBaUIsR0FB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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoib2NyLm1pc3RyYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19vY3Ivb2NyLm1pc3RyYWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBOEhBLE1BQU0sc0JBQXNCLEdBQUcsb0JBQW9CLENBQUM7QUFDcEQsTUFBTSw0QkFBNEIsR0FBRywrQkFBK0IsQ0FBQztBQUVyRSxNQUFNLDZCQUE2QixHQUFHLENBQUMsT0FHdEMsRUFBK0IsRUFBRTtJQUNoQyxNQUFNLElBQUksR0FBRyxLQUFLLEVBQUUsT0FBd0QsRUFBZ0MsRUFBRTtRQUM1RyxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU0sRUFBRSxDQUFDO1lBQ3BCLE1BQU0sSUFBSSxLQUFLLENBQUMsc0VBQXNFLENBQUMsQ0FBQztRQUMxRixDQUFDO1FBRUQsTUFBTSxRQUFRLEdBQUcsTUFBTSxLQUFLLENBQUMsT0FBTyxDQUFDLFdBQVcsSUFBSSw0QkFBNEIsRUFBRTtZQUNoRixNQUFNLEVBQUUsTUFBTTtZQUNkLE9BQU8sRUFBRTtnQkFDUCxhQUFhLEVBQUUsVUFBVSxPQUFPLENBQUMsTUFBTSxFQUFFO2dCQUN6QyxjQUFjLEVBQUUsa0JBQWtCO2FBQ25DO1lBQ0QsSUFBSSxFQUFFLElBQUksQ0FBQyxTQUFTLENBQUMsT0FBTyxDQUFDO1NBQzlCLENBQUMsQ0FBQztRQUVILElBQUksQ0FBQyxRQUFRLENBQUMsRUFBRSxFQUFFLENBQUM7WUFDakIsTUFBTSxTQUFTLEdBQUcsTUFBTSxRQUFRLENBQUMsSUFBSSxFQUFFLENBQUM7WUFDeEMsTUFBTSxJQUFJLEtBQUssQ0FBQywwQ0FBMEMsUUFBUSxDQUFDLE1BQU0sS0FBSyxTQUFTLEVBQUUsQ0FBQyxDQUFDO1FBQzdGLENBQUM7UUFFRCxPQUFPLENBQUMsTUFBTSxRQUFRLENBQUMsSUFBSSxFQUFFLENBQXdCLENBQUM7SUFDeEQsQ0FBQyxDQUFDO0lBQ0YsT0FBTyxFQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsZUFBZSxFQUFFLElBQUks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

package/dist_ts_typedrequest/catalog.d.ts

@@ -23,6 +23,8 @@ export declare class FlexTypedRequestError extends Error {
  * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
  * its path, declared as its contract writes it and validated against its schema, and runs through
  * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
- * properties `request` fills. A refusal rejects with `FlexTypedRequestError`.
+ * properties `request` fills and its result what `response` makes of the answer. A refusal rejects
+ * with `FlexTypedRequestError`. A method `readOnly` marks is declared read-only and not gated by
+ * `onCall`.
  */
 export declare function catalogFromTypedRequests<TScope = unknown>(surface: IFlexTypedRequestSurface, options: IFlexTypedRequestCatalogOptions<TScope>): IFlexToolCatalog<TScope>;

package/dist_ts_typedrequest/catalog.js

@@ -25,7 +25,9 @@ export class FlexTypedRequestError extends Error {
  * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
  * its path, declared as its contract writes it and validated against its schema, and runs through
  * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
- * properties `request` fills. A refusal rejects with `FlexTypedRequestError`.
+ * properties `request` fills and its result what `response` makes of the answer. A refusal rejects
+ * with `FlexTypedRequestError`. A method `readOnly` marks is declared read-only and not gated by
+ * `onCall`.
  */
 export function catalogFromTypedRequests(surface, options) {
     if (typeof options?.router?.routeAndAddResponse !== 'function') {
@@ -41,6 +43,7 @@ export function catalogFromTypedRequests(surface, options) {
         throw new plugins.FlexHarnessValidationError(`The surface leaves ${surface.omit.join(', ')} out of every request; the options' request() must fill them.`);
     }
     const include = options.include ?? ((method) => !method.deprecated);
+    const readOnly = options.readOnly ?? (() => false);
     const { router } = options;
     const call = async (method, params, context) => {
         const filled = options.request ? await options.request(method, context) : {};
@@ -55,7 +58,9 @@ export function catalogFromTypedRequests(surface, options) {
             throw new FlexTypedRequestError(method.method, 'The router answered nothing.');
         if (answer.error)
             throw new FlexTypedRequestError(method.method, answer.error.text, answer.error.data);
-        return answer.response;
+        return options.response
+            ? await options.response(method, answer.response, context)
+            : answer.response;
     };
     return {
         methods: surface.methods.filter((method) => include(method)).map((method) => ({
@@ -67,13 +72,15 @@ export function catalogFromTypedRequests(surface, options) {
             outputSchema: method.outputSchema,
             declaration: method.declaration,
             run: (params, context) => call(method, params, context),
-            ...(options.onCall
-                ? { onCall: (params, context) => options.onCall(method, params, context) }
-                : {}),
+            ...(readOnly(method)
+                ? { readOnly: true }
+                : options.onCall
+                    ? { onCall: (params, context) => options.onCall(method, params, context) }
+                    : {}),
         })),
         types: surface.types,
         ...(options.vocabulary ? { vocabulary: options.vocabulary } : {}),
         ...(options.onProposals ? { onProposals: options.onProposals } : {}),
     };
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2F0YWxvZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3R5cGVkcmVxdWVzdC9jYXRhbG9nLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBUXhDOzs7R0FHRztBQUNILE1BQU0sT0FBTyxxQkFBc0IsU0FBUSxLQUFLO0lBRzVCO0lBRUE7SUFFQTtJQU5sQjtJQUNFLHNDQUFzQztJQUN0QixNQUFjO0lBQzlCLGtFQUFrRTtJQUNsRCxJQUFZO0lBQzVCLHdCQUF3QjtJQUNSLElBQWM7UUFFOUIsS0FBSyxDQUFDLEdBQUcsTUFBTSxpQkFBaUIsSUFBSSxFQUFFLENBQUMsQ0FBQztRQU54QixXQUFNLEdBQU4sTUFBTSxDQUFRO1FBRWQsU0FBSSxHQUFKLElBQUksQ0FBUTtRQUVaLFNBQUksR0FBSixJQUFJLENBQVU7UUFHOUIsSUFBSSxDQUFDLElBQUksR0FBRyx1QkFBdUIsQ0FBQztJQUN0QyxDQUFDO0NBQ0Y7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sVUFBVSx3QkFBd0IsQ0FDdEMsT0FBaUMsRUFDakMsT0FBZ0Q7SUFFaEQsSUFBSSxPQUFPLE9BQU8sRUFBRSxNQUFNLEVBQUUsbUJBQW1CLEtBQUssVUFBVSxFQUFFLENBQUM7UUFDL0QsTUFBTSxJQUFJLE9BQU8sQ0FBQywwQkFBMEIsQ0FBQyxxRUFBcUUsQ0FBQyxDQUFDO0lBQ3RILENBQUM7SUFDRCxNQUFNLE9BQU8sR0FBRyxPQUFPLENBQUMsT0FBTyxJQUFJLEVBQUUsQ0FBQztJQUN0QyxNQUFNLEtBQUssR0FBRyxJQUFJLEdBQUcsQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sRUFBRSxFQUFFLENBQUMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUM7SUFDdEUsTUFBTSxPQUFPLEdBQUcsTUFBTSxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FB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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2F0YWxvZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3R5cGVkcmVxdWVzdC9jYXRhbG9nLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBUXhDOzs7R0FHRztBQUNILE1BQU0sT0FBTyxxQkFBc0IsU0FBUSxLQUFLO0lBRzVCO0lBRUE7SUFFQTtJQU5sQjtJQUNFLHNDQUFzQztJQUN0QixNQUFjO0lBQzlCLGtFQUFrRTtJQUNsRCxJQUFZO0lBQzVCLHdCQUF3QjtJQUNSLElBQWM7UUFFOUIsS0FBSyxDQUFDLEdBQUcsTUFBTSxpQkFBaUIsSUFBSSxFQUFFLENBQUMsQ0FBQztRQU54QixXQUFNLEdBQU4sTUFBTSxDQUFRO1FBRWQsU0FBSSxHQUFKLElBQUksQ0FBUTtRQUVaLFNBQUksR0FBSixJQUFJLENBQVU7UUFHOUIsSUFBSSxDQUFDLElBQUksR0FBRyx1QkFBdUIsQ0FBQztJQUN0QyxDQUFDO0NBQ0Y7QUFFRDs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxVQUFVLHdCQUF3QixDQUN0QyxPQUFpQyxFQUNqQyxPQUFnRDtJQUVoRCxJQUFJLE9BQU8sT0FBTyxFQUFFLE1BQU0sRUFBRSxtQkFBbUIsS0FBSyxVQUFVLEVBQUUsQ0FBQztRQUMvRCxNQUFNLElBQUksT0FBTyxDQUFDLDBCQUEwQixDQUFDLHFFQUFxRSxDQUFDLENBQUM7SUFDdEgsQ0FBQztJQUNELE1BQU0sT0FBTyxHQUFHLE9BQU8sQ0FBQyxPQUFPLElBQUksRUFBRSxDQUFDO0lBQ3RDLE1BQU0sS0FBSyxHQUFHLElBQUksR0FBRyxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQztJQUN0RSxNQUFNLE9BQU8sR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLE1BQU0sRUFBRSxFQUFFLENBQUMsQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUM7SUFDNUUsSUFBSSxPQUFPLENBQUMsTUFBTSxHQUFHLENBQUMsRUFBRSxDQUFDO1FBQ3ZCLE1BQU0sSUFBSSxPQUFPLENBQUMsMEJBQTBCLENBQUMsNkJBQTZCLE9BQU8sQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLG1CQUFtQixDQUFDLENBQUM7SUFDbkgsQ0FBQztJQUNELElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxNQUFNLEdBQUcsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLE9BQU8sRUFBRSxDQUFDO1FBQ2hELE1BQU0sSUFBSSxPQUFPLENBQUMsMEJBQTBCLENBQzFDLHNCQUFzQixPQUFPLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsK0RBQStELENBQzdHLENBQUM7SUFDSixDQUFDO0lBQ0QsTUFBTSxPQUFPLEdBQUcsT0FBTyxDQUFDLE9BQU8sSUFBSSxDQUFDLENBQUMsTUFBK0IsRUFBRSxFQUFFLENBQUMsQ0FBQyxNQUFNLENBQUMsVUFBVSxDQUFDLENBQUM7SUFDN0YsTUFBTSxRQUFRLEdBQUcsT0FBTyxDQUFDLFFBQVEsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ25ELE1BQU0sRUFBRSxNQUFNLEVBQUUsR0FBRyxPQUFPLENBQUM7SUFDM0IsTUFBTSxJQUFJLEdBQUcsS0FBSyxFQUNoQixNQUErQixFQUMvQixNQUErQixFQUMvQixPQUF1QyxFQUNyQixFQUFFO1FBQ3BCLE1BQU0sTUFBTSxHQUFHLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FBQyxDQUFDLE1BQU0sT0FBTyxDQUFDLE9BQU8sQ0FBQyxNQUFNLEVBQUUsT0FBTyxDQUFDLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQztRQUM3RSxNQUFNLFNBQVMsR0FBRyxPQUFPLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxNQUFNLE9BQU8sQ0FBQyxTQUFTLENBQUMsTUFBTSxFQUFFLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUM7UUFDM0YsTUFBTSxNQUFNLEdBQUcsTUFBTSxNQUFNLENBQUMsbUJBQW1CLENBQzdDO1lBQ0UsTUFBTSxFQUFFLE1BQU0sQ0FBQyxNQUFNO1lBQ3JCLE9BQU8sRUFBRSxFQUFFLEdBQUcsTUFBTSxFQUFFLEdBQUcsTUFBTSxFQUFFO1lBQ2pDLFFBQVEsRUFBRSxFQUFFO1lBQ1osV0FBVyxFQUFFLEVBQUUsRUFBRSxFQUFFLE9BQU8sQ0FBQyxNQUFNLENBQUMsVUFBVSxFQUFFLEVBQUUsS0FBSyxFQUFFLFNBQVMsRUFBRTtTQUNuRSxFQUNELEVBQUUsR0FBRyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxnQkFBZ0IsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLEVBQUUsa0JBQWtCLEVBQUUsT0FBTyxDQUFDLFdBQVcsRUFBRSxDQUNuRyxDQUFDO1FBQ0YsSUFBSSxDQUFDLE1BQU07WUFBRSxNQUFNLElBQUkscUJBQXFCLENBQUMsTUFBTSxDQUFDLE1BQU0sRUFBRSw4QkFBOEIsQ0FBQyxDQUFDO1FBQzVGLElBQUksTUFBTSxDQUFDLEtBQUs7WUFBRSxNQUFNLElBQUkscUJBQXFCLENBQUMsTUFBTSxDQUFDLE1BQU0sRUFBRSxNQUFNLENBQUMsS0FBSyxDQUFDLElBQUksRUFBRSxNQUFNLENBQUMsS0FBSyxDQUFDLElBQUksQ0FBQyxDQUFDO1FBQ3ZHLE9BQU8sT0FBTyxDQUFDLFFBQVE7WUFDckIsQ0FBQyxDQUFDLE1BQU0sT0FBTyxDQUFDLFFBQVEsQ0FBQyxNQUFNLEVBQUUsTUFBTSxDQUFDLFFBQW1DLEVBQUUsT0FBTyxDQUFDO1lBQ3JGLENBQUMsQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDO0lBQ3RCLENBQUMsQ0FBQztJQUNGLE9BQU87UUFDTCxPQUFPLEVBQUUsT0FBTyxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLE1BQU0sRUFBOEIsRUFBRSxDQUFDLENBQUM7WUFDeEcsTUFBTSxFQUFFLE1BQU0sQ0FBQyxJQUFJO1lBQ25CLE9BQU8sRUFBRSxNQUFNLENBQUMsT0FBTztZQUN2QixHQUFHLENBQUMsTUFBTSxDQUFDLFdBQVcsQ0FBQyxDQUFDLENBQUMsRUFBRSxXQUFXLEVBQUUsTUFBTSxDQUFDLFdBQVcsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7WUFDbEUsR0FBRyxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxDQUFDLEVBQUUsT0FBTyxFQUFFLE9BQU8sQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO1lBQ3RFLFdBQVcsRUFBRSxNQUFNLENBQUMsV0FBVztZQUMvQixZQUFZLEVBQUUsTUFBTSxDQUFDLFlBQVk7WUFDakMsV0FBVyxFQUFFLE1BQU0sQ0FBQyxXQUFXO1lBQy9CLEdBQUcsRUFBRSxDQUFDLE1BQStCLEVBQUUsT0FBTyxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLENBQUM7WUFDaEYsR0FBRyxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUM7Z0JBQ2xCLENBQUMsQ0FBQyxFQUFFLFFBQVEsRUFBRSxJQUFJLEVBQUU7Z0JBQ3BCLENBQUMsQ0FBQyxPQUFPLENBQUMsTUFBTTtvQkFDZCxDQUFDLENBQUMsRUFBRSxNQUFNLEVBQUUsQ0FBQyxNQUErQixFQUFFLE9BQXVDLEVBQUUsRUFBRSxDQUFDLE9BQU8sQ0FBQyxNQUFPLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLENBQUMsRUFBRTtvQkFDcEksQ0FBQyxDQUFDLEVBQUUsQ0FBQztTQUNWLENBQUMsQ0FBQztRQUNILEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSztRQUNwQixHQUFHLENBQUMsT0FBTyxDQUFDLFVBQVUsQ0FBQyxDQUFDLENBQUMsRUFBRSxVQUFVLEVBQUUsT0FBTyxDQUFDLFVBQVUsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUM7UUFDakUsR0FBRyxDQUFDLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLEVBQUUsV0FBVyxFQUFFLE9BQU8sQ0FBQyxXQUFXLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO0tBQ3JFLENBQUM7QUFDSixDQUFDIn0=

package/dist_ts_typedrequest/interfaces.d.ts

@@ -96,11 +96,27 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
     localData?(method: IFlexTypedRequestMethod, context: IFlexCatalogRunContext<TScope>): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
     /** The methods the model may use. Default: every method that is not deprecated. */
     include?(method: IFlexTypedRequestMethod): boolean;
+    /**
+     * The methods that only read: a call has no effect but its result. Such a method is declared
+     * `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may
+     * start while the model still streams its response, and a turn answers identical ones once; see
+     * `IFlexCatalogMethod.readOnly`. Default: none.
+     */
+    readOnly?(method: IFlexTypedRequestMethod): boolean;
+    /**
+     * What the model sees of a method's answered response, such as the response without a
+     * credential's secret. Default: the response. A refusal does not reach it, and the method's
+     * declaration still shows the contract's response.
+     */
+    response?(method: IFlexTypedRequestMethod, response: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>): unknown;
     /** Other names of methods, by typed method: `{ getVoucher: ['Beleg abrufen'] }`. */
     aliases?: Readonly<Record<string, readonly string[]>>;
     /** The words the API's users say for its own words; see `IFlexToolCatalog.vocabulary`. */
     vocabulary?: IFlexToolCatalog['vocabulary'];
-    /** Decides each validated call before it runs; see `IFlexCatalogMethod.onCall`. */
+    /**
+     * Decides each validated call of a method `readOnly` does not mark before it runs; see
+     * `IFlexCatalogMethod.onCall`.
+     */
     onCall?(method: IFlexTypedRequestMethod, params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>): TFlexCatalogCallDecision | PromiseLike<TFlexCatalogCallDecision>;
     /** Receives the calls `onCall` proposed; see `IFlexToolCatalog.onProposals`. */
     onProposals?: IFlexToolCatalog<TScope>['onProposals'];

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "10.18.0",
+  "version": "10.20.0",
   "type": "module",
   "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
   "main": "./dist_ts/index.js",
@@ -87,8 +87,8 @@
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@modelprofile.com/flexharness-agent": "10.18.0",
-    "@modelprofile.com/flexharness-models": "10.18.0",
+    "@modelprofile.com/flexharness-agent": "10.20.0",
+    "@modelprofile.com/flexharness-models": "10.20.0",
     "@push.rocks/smartrequest": "^5.5.1",
     "ai": "^7.0.111",
     "zod": "^4.6.5"

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '10.18.0',
+  version: '10.20.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

package/ts_ocr/ocr.mistral.ts

@@ -14,6 +14,18 @@ export interface ISmartAiOcrImageInput {
   mimeType: TSmartAiOcrImageMimeType;
 }
 
+/** Mistral OCR reads PDF, PPTX, DOCX and other document formats. */
+export type TSmartAiOcrDocumentMimeType =
+  | 'application/pdf'
+  | 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
+  | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+  | string;
+
+export interface ISmartAiOcrDocumentInput {
+  dataBase64: string;
+  mimeType: TSmartAiOcrDocumentMimeType;
+}
+
 export interface ISmartAiOcrPageResult {
   index: number;
   text: string;
@@ -34,6 +46,14 @@ export interface ISmartAiOcrEngine {
   ) => Promise<ISmartAiOcrResult<IMistralOcrResponse>>;
 }
 
+/** The Mistral OCR engine also reads whole documents, such as a PDF with all its pages. */
+export interface ISmartAiMistralOcrEngine extends ISmartAiOcrEngine {
+  recognizeDocument: (
+    input: ISmartAiOcrDocumentInput,
+    options?: ISmartAiMistralOcrRecognizeOptions
+  ) => Promise<ISmartAiOcrResult<IMistralOcrResponse>>;
+}
+
 export interface IMistralOcrPageConfidenceScores {
   average_page_confidence_score?: number;
   averagePageConfidenceScore?: number;
@@ -70,8 +90,18 @@ export interface IMistralOcrRequest {
   confidence_scores_granularity?: TSmartAiMistralOcrConfidenceScoresGranularity;
 }
 
+/** A document (PDF, PPTX, DOCX and other formats) as a URL or a base64 data URL; the other fields are those of an image request. */
+export interface IMistralOcrDocumentRequest extends Omit<IMistralOcrRequest, 'document'> {
+  document: {
+    type: 'document_url';
+    document_url: string;
+  };
+}
+
 export interface ISmartAiMistralOcrTransport {
   process: (request: IMistralOcrRequest) => Promise<IMistralOcrResponse>;
+  /** Reads documents. A transport without it reads images only, and `recognizeDocument` refuses documents. */
+  processDocument?: (request: IMistralOcrDocumentRequest) => Promise<IMistralOcrResponse>;
 }
 
 export interface ISmartAiMistralOcrOptions {
@@ -101,29 +131,28 @@ const createMistralOcrHttpTransport = (options: {
   apiKey?: string;
   endpointUrl?: string;
 }): ISmartAiMistralOcrTransport => {
-  return {
-    process: async (request) => {
-      if (!options.apiKey) {
-        throw new Error('Mistral OCR requires an apiKey when no custom transport is provided.');
-      }
-
-      const response = await fetch(options.endpointUrl ?? defaultMistralOcrEndpointUrl, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${options.apiKey}`,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(request),
-      });
+  const post = async (request: IMistralOcrRequest | IMistralOcrDocumentRequest): Promise<IMistralOcrResponse> => {
+    if (!options.apiKey) {
+      throw new Error('Mistral OCR requires an apiKey when no custom transport is provided.');
+    }
+
+    const response = await fetch(options.endpointUrl ?? defaultMistralOcrEndpointUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${options.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(request),
+    });
 
-      if (!response.ok) {
-        const errorBody = await response.text();
-        throw new Error(`Mistral OCR request failed with status ${response.status}: ${errorBody}`);
-      }
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new Error(`Mistral OCR request failed with status ${response.status}: ${errorBody}`);
+    }
 
-      return (await response.json()) as IMistralOcrResponse;
-    },
+    return (await response.json()) as IMistralOcrResponse;
   };
+  return { process: post, processDocument: post };
 };
 
 const getPageConfidence = (page: IMistralOcrPageResponse): number | undefined => {
@@ -134,9 +163,30 @@ const getPageConfidence = (page: IMistralOcrPageResponse): number | undefined =>
   );
 };
 
+const toOcrResult = (response: IMistralOcrResponse): ISmartAiOcrResult<IMistralOcrResponse> => {
+  const pages = response.pages.map((page) => ({
+    index: page.index,
+    text: page.markdown,
+    confidence: getPageConfidence(page),
+  }));
+  const pageConfidences = pages
+    .map((page) => page.confidence)
+    .filter((confidence): confidence is number => typeof confidence === 'number');
+  const confidence = pageConfidences.length
+    ? pageConfidences.reduce((sum, value) => sum + value, 0) / pageConfidences.length
+    : undefined;
+
+  return {
+    text: pages.map((page) => page.text).join('\n\n').trim(),
+    confidence,
+    pages,
+    raw: response,
+  };
+};
+
 export const createMistralOcrEngine = (
   options: ISmartAiMistralOcrOptions = {}
-): ISmartAiOcrEngine => {
+): ISmartAiMistralOcrEngine => {
   const transport =
     options.transport ??
     createMistralOcrHttpTransport({
@@ -145,6 +195,16 @@ export const createMistralOcrEngine = (
     });
   const model = options.model ?? defaultMistralOcrModel;
 
+  const settingsOf = (recognizeOptions: ISmartAiMistralOcrRecognizeOptions) => ({
+    include_image_base64:
+      recognizeOptions.includeImageBase64 ?? options.includeImageBase64 ?? false,
+    table_format: recognizeOptions.tableFormat ?? options.tableFormat,
+    extract_header: recognizeOptions.extractHeader ?? options.extractHeader,
+    extract_footer: recognizeOptions.extractFooter ?? options.extractFooter,
+    confidence_scores_granularity:
+      recognizeOptions.confidenceScoresGranularity ?? options.confidenceScoresGranularity,
+  });
+
   return {
     recognizeImage: async (input, recognizeOptions = {}) => {
       if (!input.dataBase64) {
@@ -153,40 +213,33 @@ export const createMistralOcrEngine = (
       if (!input.mimeType) {
         throw new Error('Mistral OCR image input requires mimeType.');
       }
-
-      const response = await transport.process({
+      return toOcrResult(await transport.process({
         model,
         document: {
           type: 'image_url',
           image_url: `data:${input.mimeType};base64,${input.dataBase64}`,
         },
-        include_image_base64:
-          recognizeOptions.includeImageBase64 ?? options.includeImageBase64 ?? false,
-        table_format: recognizeOptions.tableFormat ?? options.tableFormat,
-        extract_header: recognizeOptions.extractHeader ?? options.extractHeader,
-        extract_footer: recognizeOptions.extractFooter ?? options.extractFooter,
-        confidence_scores_granularity:
-          recognizeOptions.confidenceScoresGranularity ?? options.confidenceScoresGranularity,
-      });
-
-      const pages = response.pages.map((page) => ({
-        index: page.index,
-        text: page.markdown,
-        confidence: getPageConfidence(page),
+        ...settingsOf(recognizeOptions),
+      }));
+    },
+    recognizeDocument: async (input, recognizeOptions = {}) => {
+      if (!transport.processDocument) {
+        throw new Error('This Mistral OCR transport reads images only: it has no processDocument, so it cannot read documents.');
+      }
+      if (!input.dataBase64) {
+        throw new Error('Mistral OCR document input requires dataBase64.');
+      }
+      if (!input.mimeType) {
+        throw new Error('Mistral OCR document input requires mimeType.');
+      }
+      return toOcrResult(await transport.processDocument({
+        model,
+        document: {
+          type: 'document_url',
+          document_url: `data:${input.mimeType};base64,${input.dataBase64}`,
+        },
+        ...settingsOf(recognizeOptions),
       }));
-      const pageConfidences = pages
-        .map((page) => page.confidence)
-        .filter((confidence): confidence is number => typeof confidence === 'number');
-      const confidence = pageConfidences.length
-        ? pageConfidences.reduce((sum, value) => sum + value, 0) / pageConfidences.length
-        : undefined;
-
-      return {
-        text: pages.map((page) => page.text).join('\n\n').trim(),
-        confidence,
-        pages,
-        raw: response,
-      };
     },
   };
 };

package/ts_ocr/readme.md

@@ -1,4 +1,4 @@
-Image OCR with Mistral or an injected recognition engine. This subpath imports no runtime dependencies and works with Node buffers and browser byte arrays.
+Image OCR with Mistral or an injected recognition engine, and document OCR with Mistral. This subpath imports no runtime dependencies and works with Node buffers and browser byte arrays.
 
 Part of the [FlexHarness toolbox](https://code.foss.global/modelprofile.com/flexharness).
 Install the components your project uses. Provider adapters are registered explicitly;
@@ -20,6 +20,17 @@ console.log(result.text);
 
 Constructor and call options accept `engine` or `mistralOptions`. A per-call engine takes precedence over the constructor engine. Otherwise Mistral settings merge, with per-call settings taking precedence. `recognizeOptions` controls each request. `recognizeImage` accepts an existing `{ dataBase64, mimeType }` image; `createMistralOcrEngine` remains available for lower-level integrations.
 
+`createMistralOcrEngine()` also reads whole documents: `recognizeDocument({ dataBase64, mimeType: 'application/pdf' })` sends the document as a `document_url` data URL, as Mistral's OCR API takes PDF, PPTX, DOCX and other document formats, and returns every page. Mistral accepts documents of up to 50 MB and 1,000 pages.
+
+A custom `transport` receives image requests (`IMistralOcrRequest`) through `process`, as before. It reads documents only when it also implements the optional `processDocument`, which receives an `IMistralOcrDocumentRequest`, whose `document` is a `document_url`; for a transport without it, `recognizeDocument` fails with "This Mistral OCR transport reads images only". The built-in transport implements both.
+
+```typescript
+import { createMistralOcrEngine } from '@modelprofile.com/flexharness/ocr';
+
+const engine = createMistralOcrEngine({ apiKey: process.env.MISTRAL_API_KEY });
+const { text, pages } = await engine.recognizeDocument({ dataBase64: pdfBase64, mimeType: 'application/pdf' });
+```
+
 Model-based PDF text extraction lives in `@modelprofile.com/flexharness/documents`. Native `ocrmypdf` processing remains in `@push.rocks/smartocr`.
 
 ## Issue Reporting and Security

package/ts_typedrequest/catalog.ts

@@ -28,7 +28,9 @@ export class FlexTypedRequestError extends Error {
  * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
  * its path, declared as its contract writes it and validated against its schema, and runs through
  * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
- * properties `request` fills. A refusal rejects with `FlexTypedRequestError`.
+ * properties `request` fills and its result what `response` makes of the answer. A refusal rejects
+ * with `FlexTypedRequestError`. A method `readOnly` marks is declared read-only and not gated by
+ * `onCall`.
  */
 export function catalogFromTypedRequests<TScope = unknown>(
   surface: IFlexTypedRequestSurface,
@@ -49,6 +51,7 @@ export function catalogFromTypedRequests<TScope = unknown>(
     );
   }
   const include = options.include ?? ((method: IFlexTypedRequestMethod) => !method.deprecated);
+  const readOnly = options.readOnly ?? (() => false);
   const { router } = options;
   const call = async (
     method: IFlexTypedRequestMethod,
@@ -68,7 +71,9 @@ export function catalogFromTypedRequests<TScope = unknown>(
     );
     if (!answer) throw new FlexTypedRequestError(method.method, 'The router answered nothing.');
     if (answer.error) throw new FlexTypedRequestError(method.method, answer.error.text, answer.error.data);
-    return answer.response;
+    return options.response
+      ? await options.response(method, answer.response as Record<string, unknown>, context)
+      : answer.response;
   };
   return {
     methods: surface.methods.filter((method) => include(method)).map((method): IFlexCatalogMethod<TScope> => ({
@@ -80,9 +85,11 @@ export function catalogFromTypedRequests<TScope = unknown>(
       outputSchema: method.outputSchema,
       declaration: method.declaration,
       run: (params: Record<string, unknown>, context) => call(method, params, context),
-      ...(options.onCall
-        ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
-        : {}),
+      ...(readOnly(method)
+        ? { readOnly: true }
+        : options.onCall
+          ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
+          : {}),
     })),
     types: surface.types,
     ...(options.vocabulary ? { vocabulary: options.vocabulary } : {}),

package/ts_typedrequest/interfaces.ts

@@ -109,11 +109,31 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
   ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
   /** The methods the model may use. Default: every method that is not deprecated. */
   include?(method: IFlexTypedRequestMethod): boolean;
+  /**
+   * The methods that only read: a call has no effect but its result. Such a method is declared
+   * `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may
+   * start while the model still streams its response, and a turn answers identical ones once; see
+   * `IFlexCatalogMethod.readOnly`. Default: none.
+   */
+  readOnly?(method: IFlexTypedRequestMethod): boolean;
+  /**
+   * What the model sees of a method's answered response, such as the response without a
+   * credential's secret. Default: the response. A refusal does not reach it, and the method's
+   * declaration still shows the contract's response.
+   */
+  response?(
+    method: IFlexTypedRequestMethod,
+    response: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): unknown;
   /** Other names of methods, by typed method: `{ getVoucher: ['Beleg abrufen'] }`. */
   aliases?: Readonly<Record<string, readonly string[]>>;
   /** The words the API's users say for its own words; see `IFlexToolCatalog.vocabulary`. */
   vocabulary?: IFlexToolCatalog['vocabulary'];
-  /** Decides each validated call before it runs; see `IFlexCatalogMethod.onCall`. */
+  /**
+   * Decides each validated call of a method `readOnly` does not mark before it runs; see
+   * `IFlexCatalogMethod.onCall`.
+   */
   onCall?(
     method: IFlexTypedRequestMethod,
     params: Record<string, unknown>,

package/ts_typedrequest/readme.md

@@ -19,7 +19,8 @@ const surface = await describeTypedRequests({
 const catalog = catalogFromTypedRequests<IAppScope>(surface, {
   router: server.typedrouter,
   request: (method, context) => ({ identity: identityOf(context.provider.scope) }),
-  onCall: (method) => (method.method.startsWith('get') || method.method.startsWith('list') ? 'run' : 'propose'),
+  readOnly: (method) => method.method.startsWith('get') || method.method.startsWith('list'),
+  onCall: () => 'propose',
 });
 ```
 
@@ -38,6 +39,8 @@ The surface is plain JSON, so a build step can write it next to the server and t
 - `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters and what `request` returns for the omitted properties, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
 - A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
 - `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
+- `readOnly` marks the methods that only read. A marked method is declared `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may start while the model still streams, and a turn answers identical ones once; every other method's calls, gated by `onCall` or not, run in the order the model made them. Mark nothing that asks for permission.
+- `response` decides what the model sees of an answered response, such as the response without a credential's secret; by default the response itself. A refusal does not reach it, and the method's declaration still shows the contract's response.
 - A surface that omits properties needs `request`; an alias for a method the surface lacks is refused.
 
 ## Issue Reporting and Security