@modelprofile.com/flexharness 8.4.0 → 9.0.0

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts_document/index.d.ts

@@ -1,3 +1,4 @@
+import * as plugins from './plugins.js';
 import type { ModelMessage } from 'ai';
 import type { TSmartAiLanguageModel, TSmartAiProviderOptions } from '@modelprofile.com/flexharness-models';
 /** Options every document request accepts in addition to its model and messages. */
@@ -5,16 +6,28 @@ export interface IDocumentRequestOptions {
     /** Passed to the model call unchanged, for example `{ openai: { store: false } }`. */
     providerOptions?: TSmartAiProviderOptions;
     /**
-     * Checked before each document is rendered and before the model call, and passed to the model
-     * call. SmartPDF cannot stop a document it is rendering, so that render finishes first.
+     * Checked before each document is rendered and before the model call, and passed to both the
+     * render and the model call: an abort stops a document that is rendering. The request rejects
+     * with the signal's reason.
      */
     abortSignal?: AbortSignal;
     /**
-     * The most rendered pages one request may send to the model. A request with more pages rejects
-     * with `DocumentPageLimitError` before the model is called; documents after the one that
-     * exceeded the limit are not rendered.
+     * The most rendered pages one request may send to the model, counted over all its documents. A
+     * request with more pages rejects with `DocumentPageLimitError` before the model is called. Each
+     * document is rendered only when its page count fits the pages the request has left, so the
+     * document that exceeds the limit and every document after it are not rendered. The exception is
+     * a one-page document that comes after the request's pages are used up: it renders and is then
+     * refused.
      */
     maxPages?: number;
+    /**
+     * Called once for every model call of the request, as soon as its usage is known, whatever the
+     * request's outcome: `reported` with the provider's usage, or `unreported` with the reason when
+     * the call failed, was aborted or its response carried no usage. A retried attempt is a call of
+     * its own. Nothing is reported for a request that ends before its model is called. When a request
+     * returns, its reported calls sum to its `usage`. Must not throw.
+     */
+    onUsage?: plugins.TAgentModelCallUsageReporter;
 }
 export interface IDocumentOptions extends IDocumentRequestOptions {
     model: TSmartAiLanguageModel;
@@ -44,17 +57,28 @@ export interface IDocumentAnalysisResult {
     pageCount: number;
 }
 export interface IDocumentPageLimitErrorDetails {
+    /** The pages of the documents up to and including the one that exceeded the limit. */
     renderedPages: number;
     maxPages: number;
     documentCount: number;
+    /** Zero-based position, in the request's documents, of the document that exceeded the limit. */
+    documentIndex: number;
+    /** Whether the pages of every document of the request were counted. */
     allDocumentsRendered: boolean;
 }
-/** A request whose documents render to more pages than its `maxPages`; the model was not called. */
+/** A request whose documents have more pages than its `maxPages`; the model was not called. */
 export declare class DocumentPageLimitError extends Error {
-    /** Pages rendered before the request stopped; with several documents, later documents are not counted. */
+    /**
+     * The pages of the documents up to and including the one that exceeded the limit. That document's
+     * pages are counted but not rendered, except a one-page document that came after the request's
+     * pages were used up, which rendered and was then refused. Documents after it are neither counted
+     * nor rendered.
+     */
     readonly renderedPages: number;
     readonly maxPages: number;
-    constructor(details: IDocumentPageLimitErrorDetails);
+    /** Zero-based position, in the request's documents, of the document that exceeded the limit. */
+    readonly documentIndex: number;
+    constructor(details: IDocumentPageLimitErrorDetails, options?: ErrorOptions);
 }
 /** The model-based PDF OCR recipe formerly provided by SmartOCR. */
 export declare function extractTextFromPdf(pdfDocument: Uint8Array, options: IPdfTextExtractionOptions): Promise<string>;

package/dist_ts_document/index.js

@@ -14,21 +14,29 @@ function ensureSmartpdf() {
     }
     return smartpdfStart;
 }
-/** A request whose documents render to more pages than its `maxPages`; the model was not called. */
+/** A request whose documents have more pages than its `maxPages`; the model was not called. */
 export class DocumentPageLimitError extends Error {
-    /** Pages rendered before the request stopped; with several documents, later documents are not counted. */
+    /**
+     * The pages of the documents up to and including the one that exceeded the limit. That document's
+     * pages are counted but not rendered, except a one-page document that came after the request's
+     * pages were used up, which rendered and was then refused. Documents after it are neither counted
+     * nor rendered.
+     */
     renderedPages;
     maxPages;
-    constructor(details) {
+    /** Zero-based position, in the request's documents, of the document that exceeded the limit. */
+    documentIndex;
+    constructor(details, options) {
         const subject = details.documentCount === 1
             ? `The document has ${details.renderedPages} pages`
             : details.allDocumentsRendered
                 ? `The documents have ${details.renderedPages} pages`
                 : `The documents have at least ${details.renderedPages} pages`;
-        super(`${subject}, more than the ${details.maxPages} allowed.`);
+        super(`${subject}, more than the ${details.maxPages} allowed.`, options);
         this.name = 'DocumentPageLimitError';
         this.renderedPages = details.renderedPages;
         this.maxPages = details.maxPages;
+        this.documentIndex = details.documentIndex;
     }
 }
 const DEFAULT_OCR_SYSTEM_MESSAGE = 'You are a precise OCR engine. Extract text faithfully and do not summarize.';
@@ -48,6 +56,7 @@ export async function extractTextFromPdfWithUsage(pdfDocument, options) {
         providerOptions: options.providerOptions,
         abortSignal: options.abortSignal,
         maxPages: options.maxPages,
+        onUsage: options.onUsage,
     });
 }
 export async function analyzeDocuments(options) {
@@ -65,40 +74,92 @@ export async function analyzeDocumentsWithUsage(options) {
     for (const [index, doc] of options.pdfDocuments.entries()) {
         const pdf = await ensureSmartpdf();
         abortSignal?.throwIfAborted();
-        const pages = await pdf.convertPDFToPngBytes(doc);
+        const limitDetails = (renderedPages, limit) => ({
+            renderedPages,
+            maxPages: limit,
+            documentCount: options.pdfDocuments.length,
+            documentIndex: index,
+            allDocumentsRendered: index === options.pdfDocuments.length - 1,
+        });
+        // SmartPDF limits one document, so each render gets the pages the request has left. It takes
+        // no limit of zero: when the earlier documents used up the request's pages, the smallest limit
+        // lets the document's page count be known, and a document of one page renders and is refused below.
+        const renderMaxPages = maxPages === undefined ? undefined : Math.max(maxPages - imagePages.length, 1);
+        let pages;
+        try {
+            pages = await pdf.convertPDFToPngBytes(doc, { signal: abortSignal, maxPages: renderMaxPages });
+        }
+        catch (error) {
+            if (maxPages !== undefined && error instanceof plugins.smartpdf.SmartPdfPageLimitError) {
+                throw new DocumentPageLimitError(limitDetails(imagePages.length + error.pageCount, maxPages), { cause: error });
+            }
+            throw error;
+        }
         abortSignal?.throwIfAborted();
         imagePages.push(...pages);
         if (maxPages !== undefined && imagePages.length > maxPages) {
-            throw new DocumentPageLimitError({
-                renderedPages: imagePages.length,
-                maxPages,
-                documentCount: options.pdfDocuments.length,
-                allDocumentsRendered: index === options.pdfDocuments.length - 1,
-            });
+            throw new DocumentPageLimitError(limitDetails(imagePages.length, maxPages));
         }
     }
     // Filter out empty buffers
     const validPages = imagePages.filter(page => page && page.length > 0);
-    const result = await plugins.generateText({
-        model: options.model,
-        instructions: options.systemMessage,
-        messages: [
-            ...(options.messageHistory ?? []),
-            {
-                role: 'user',
-                content: [
-                    { type: 'text', text: options.userMessage },
-                    ...validPages.map(page => ({
-                        type: 'file',
-                        data: page,
-                        mediaType: 'image/png',
-                    })),
-                ],
+    const onUsage = options.onUsage;
+    const modelCalls = onUsage ? new plugins.AgentModelCallUsageRecorder(options.model, onUsage) : null;
+    // Each attempt, retries included, is one model call: it starts in the middleware, which also
+    // settles an attempt that throws; a call whose response arrives ends in onLanguageModelCallEnd.
+    const model = modelCalls
+        ? plugins.wrapLanguageModel({
+            model: options.model,
+            middleware: {
+                wrapGenerate: async ({ doGenerate, params }) => {
+                    modelCalls.start();
+                    try {
+                        return await doGenerate();
+                    }
+                    catch (error) {
+                        modelCalls.settle(params.abortSignal?.aborted ? 'aborted' : 'failed');
+                        throw error;
+                    }
+                },
             },
-        ],
-        providerOptions: options.providerOptions,
-        abortSignal,
-    });
+        })
+        : options.model;
+    const messages = [
+        ...(options.messageHistory ?? []),
+        {
+            role: 'user',
+            content: [
+                { type: 'text', text: options.userMessage },
+                ...validPages.map(page => ({
+                    type: 'file',
+                    data: page,
+                    mediaType: 'image/png',
+                })),
+            ],
+        },
+    ];
+    let result;
+    try {
+        result = await plugins.generateText({
+            model,
+            instructions: options.systemMessage,
+            messages,
+            providerOptions: options.providerOptions,
+            abortSignal,
+            ...(modelCalls
+                ? {
+                    onLanguageModelCallEnd: ({ modelId, usage: callUsage }) => {
+                        modelCalls.end(modelId, callUsage);
+                    },
+                }
+                : {}),
+        });
+        modelCalls?.settle('missing');
+    }
+    catch (error) {
+        modelCalls?.settle(abortSignal?.aborted ? 'aborted' : 'failed');
+        throw error;
+    }
     const usage = result.totalUsage;
     const inputTokens = usage.inputTokens ?? 0;
     const outputTokens = usage.outputTokens ?? 0;
@@ -132,4 +193,4 @@ export async function stopSmartpdf() {
     }
     await instance.stop();
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19kb2N1bWVudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQU14QywrR0FBK0c7QUFDL0csSUFBSSxhQUFhLEdBQThCLElBQUksQ0FBQztBQUVwRCxTQUFTLGNBQWM7SUFDckIsSUFBSSxDQUFDLGFBQWEsRUFBRSxDQUFDO1FBQ25CLE1BQU0sUUFBUSxHQUFHLElBQUksT0FBTyxDQUFDLFFBQVEsQ0FBQyxRQUFRLEVBQUUsQ0FBQztRQUNqRCxNQUFNLEtBQUssR0FBRyxRQUFRLENBQUMsS0FBSyxFQUFFLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ3BELGFBQWEsR0FBRyxLQUFLLENBQUM7UUFDdEIsS0FBSyxDQUFDLEtBQUssQ0FBQyxHQUFHLEVBQUU7WUFDZixJQUFJLGFBQWEsS0FBSyxLQUFLLEVBQUUsQ0FBQztnQkFDNUIsYUFBYSxHQUFHLElBQUksQ0FBQztZQUN2QixDQUFDO1FBQ0gsQ0FBQyxDQUFDLENBQUM7SUFDTCxDQUFDO0lBQ0QsT0FBTyxhQUFhLENBQUM7QUFDdkIsQ0FBQztBQXlERCxvR0FBb0c7QUFDcEcsTUFBTSxPQUFPLHNCQUF1QixTQUFRLEtBQUs7SUFDL0MsMEdBQTBHO0lBQzFGLGFBQWEsQ0FBUztJQUN0QixRQUFRLENBQVM7SUFFakMsWUFBWSxPQUF1QztRQUNqRCxNQUFNLE9BQU8sR0FBRyxPQUFPLENBQUMsYUFBYSxLQUFLLENBQUM7WUFDekMsQ0FBQyxDQUFDLG9CQUFvQixPQUFPLENBQUMsYUFBYSxRQUFRO1lBQ25ELENBQUMsQ0FBQyxPQUFPLENBQUMsb0JBQW9CO2dCQUM1QixDQUFDLENBQUMsc0JBQXNCLE9BQU8sQ0FBQyxhQUFhLFFBQVE7Z0JBQ3JELENBQUMsQ0FBQywrQkFBK0IsT0FBTyxDQUFDLGFBQWEsUUFBUSxDQUFD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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19kb2N1bWVudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQU14QywrR0FBK0c7QUFDL0csSUFBSSxhQUFhLEdBQThCLElBQUksQ0FBQztBQUVwRCxTQUFTLGNBQWM7SUFDckIsSUFBSSxDQUFDLGFBQWEsRUFBRSxDQUFDO1FBQ25CLE1BQU0sUUFBUSxHQUFHLElBQUksT0FBTyxDQUFDLFFBQVEsQ0FBQyxRQUFRLEVBQUUsQ0FBQztRQUNqRCxNQUFNLEtBQUssR0FBRyxRQUFRLENBQUMsS0FBSyxFQUFFLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ3BELGFBQWEsR0FBRyxLQUFLLENBQUM7UUFDdEIsS0FBSyxDQUFDLEtBQUssQ0FBQyxHQUFHLEVBQUU7WUFDZixJQUFJLGFBQWEsS0FBSyxLQUFLLEVBQUUsQ0FBQztnQkFDNUIsYUFBYSxHQUFHLElBQUksQ0FBQztZQUN2QixDQUFDO1FBQ0gsQ0FBQyxDQUFDLENBQUM7SUFDTCxDQUFDO0lBQ0QsT0FBTyxhQUFhLENBQUM7QUFDdkIsQ0FBQztBQXlFRCwrRkFBK0Y7QUFDL0YsTUFBTSxPQUFPLHNCQUF1QixTQUFRLEtBQUs7SUFDL0M7Ozs7O09BS0c7SUFDYSxhQUFhLENBQVM7SUFDdEIsUUFBUSxDQUFTO0lBQ2pDLGdHQUFnRztJQUNoRixhQUFhLENBQVM7SUFFdEMsWUFBWSxPQUF1QyxFQUFFLE9BQXNCO1FBQ3pFLE1BQU0sT0FBTyxHQUFHLE9BQU8sQ0FBQyxhQUFhLEtBQUssQ0FBQztZQUN6QyxDQUFDLENBQUMsb0JBQW9CLE9BQU8sQ0FBQyxhQUFhLFFBQVE7WUFDbkQsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxvQkFBb0I7Z0JBQzVCLENBQUMsQ0FBQyxzQkFBc0IsT0FBTyxDQUFDLGFBQWEsUUFBUTtnQkFDckQs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

package/dist_ts_document/plugins.d.ts

@@ -1,3 +1,5 @@
-import { generateText } from 'ai';
+import { generateText, wrapLanguageModel } from 'ai';
 import * as smartpdf from '@push.rocks/smartpdf';
-export { generateText, smartpdf };
+import { AgentModelCallUsageRecorder } from '@modelprofile.com/flexharness-agent';
+export { generateText, wrapLanguageModel, smartpdf, AgentModelCallUsageRecorder };
+export type { TAgentModelCallUsageReporter } from '@modelprofile.com/flexharness-agent';

package/dist_ts_document/plugins.js

@@ -1,4 +1,5 @@
-import { generateText } from 'ai';
+import { generateText, wrapLanguageModel } from 'ai';
 import * as smartpdf from '@push.rocks/smartpdf';
-export { generateText, smartpdf };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2RvY3VtZW50L3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLElBQUksQ0FBQztBQUNsQyxPQUFPLEtBQUssUUFBUSxNQUFNLHNCQUFzQixDQUFDO0FBQ2pELE9BQU8sRUFBRSxZQUFZLEVBQUUsUUFBUSxFQUFFLENBQUMifQ==
+import { AgentModelCallUsageRecorder } from '@modelprofile.com/flexharness-agent';
+export { generateText, wrapLanguageModel, smartpdf, AgentModelCallUsageRecorder };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX2RvY3VtZW50L3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFlBQVksRUFBRSxpQkFBaUIsRUFBRSxNQUFNLElBQUksQ0FBQztBQUNyRCxPQUFPLEtBQUssUUFBUSxNQUFNLHNCQUFzQixDQUFDO0FBQ2pELE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLHFDQUFxQyxDQUFDO0FBQ2xGLE9BQU8sRUFBRSxZQUFZLEVBQUUsaUJBQWlCLEVBQUUsUUFBUSxFQUFFLDJCQUEyQixFQUFFLENBQUMifQ==

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "8.4.0",
+  "version": "9.0.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",
@@ -62,15 +62,15 @@
     }
   },
   "dependencies": {
-    "@modelprofile.com/flexharness-agent": "8.4.0",
-    "@modelprofile.com/flexharness-models": "8.4.0",
+    "@modelprofile.com/flexharness-agent": "9.0.0",
+    "@modelprofile.com/flexharness-models": "9.0.0",
     "@push.rocks/smartrequest": "^5.0.1",
     "ai": "^7.0.79",
     "zod": "^4.4.1"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@push.rocks/smartpdf": "^5.0.1",
+    "@push.rocks/smartpdf": "^6.0.0",
     "puppeteer": "^24.42.0",
     "ink": "^6.8.0",
     "ink-text-input": "^6.0.0",

package/ts/00_commitinfo_data.ts

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

package/ts_document/index.ts

@@ -26,16 +26,28 @@ export interface IDocumentRequestOptions {
   /** Passed to the model call unchanged, for example `{ openai: { store: false } }`. */
   providerOptions?: TSmartAiProviderOptions;
   /**
-   * Checked before each document is rendered and before the model call, and passed to the model
-   * call. SmartPDF cannot stop a document it is rendering, so that render finishes first.
+   * Checked before each document is rendered and before the model call, and passed to both the
+   * render and the model call: an abort stops a document that is rendering. The request rejects
+   * with the signal's reason.
    */
   abortSignal?: AbortSignal;
   /**
-   * The most rendered pages one request may send to the model. A request with more pages rejects
-   * with `DocumentPageLimitError` before the model is called; documents after the one that
-   * exceeded the limit are not rendered.
+   * The most rendered pages one request may send to the model, counted over all its documents. A
+   * request with more pages rejects with `DocumentPageLimitError` before the model is called. Each
+   * document is rendered only when its page count fits the pages the request has left, so the
+   * document that exceeds the limit and every document after it are not rendered. The exception is
+   * a one-page document that comes after the request's pages are used up: it renders and is then
+   * refused.
    */
   maxPages?: number;
+  /**
+   * Called once for every model call of the request, as soon as its usage is known, whatever the
+   * request's outcome: `reported` with the provider's usage, or `unreported` with the reason when
+   * the call failed, was aborted or its response carried no usage. A retried attempt is a call of
+   * its own. Nothing is reported for a request that ends before its model is called. When a request
+   * returns, its reported calls sum to its `usage`. Must not throw.
+   */
+  onUsage?: plugins.TAgentModelCallUsageReporter;
 }
 
 export interface IDocumentOptions extends IDocumentRequestOptions {
@@ -70,28 +82,40 @@ export interface IDocumentAnalysisResult {
 }
 
 export interface IDocumentPageLimitErrorDetails {
+  /** The pages of the documents up to and including the one that exceeded the limit. */
   renderedPages: number;
   maxPages: number;
   documentCount: number;
+  /** Zero-based position, in the request's documents, of the document that exceeded the limit. */
+  documentIndex: number;
+  /** Whether the pages of every document of the request were counted. */
   allDocumentsRendered: boolean;
 }
 
-/** A request whose documents render to more pages than its `maxPages`; the model was not called. */
+/** A request whose documents have more pages than its `maxPages`; the model was not called. */
 export class DocumentPageLimitError extends Error {
-  /** Pages rendered before the request stopped; with several documents, later documents are not counted. */
+  /**
+   * The pages of the documents up to and including the one that exceeded the limit. That document's
+   * pages are counted but not rendered, except a one-page document that came after the request's
+   * pages were used up, which rendered and was then refused. Documents after it are neither counted
+   * nor rendered.
+   */
   public readonly renderedPages: number;
   public readonly maxPages: number;
+  /** Zero-based position, in the request's documents, of the document that exceeded the limit. */
+  public readonly documentIndex: number;
 
-  constructor(details: IDocumentPageLimitErrorDetails) {
+  constructor(details: IDocumentPageLimitErrorDetails, options?: ErrorOptions) {
     const subject = details.documentCount === 1
       ? `The document has ${details.renderedPages} pages`
       : details.allDocumentsRendered
         ? `The documents have ${details.renderedPages} pages`
         : `The documents have at least ${details.renderedPages} pages`;
-    super(`${subject}, more than the ${details.maxPages} allowed.`);
+    super(`${subject}, more than the ${details.maxPages} allowed.`, options);
     this.name = 'DocumentPageLimitError';
     this.renderedPages = details.renderedPages;
     this.maxPages = details.maxPages;
+    this.documentIndex = details.documentIndex;
   }
 }
 
@@ -120,6 +144,7 @@ export async function extractTextFromPdfWithUsage(
     providerOptions: options.providerOptions,
     abortSignal: options.abortSignal,
     maxPages: options.maxPages,
+    onUsage: options.onUsage,
   });
 }
 
@@ -140,42 +165,91 @@ export async function analyzeDocumentsWithUsage(options: IDocumentOptions): Prom
   for (const [index, doc] of options.pdfDocuments.entries()) {
     const pdf = await ensureSmartpdf();
     abortSignal?.throwIfAborted();
-    const pages = await pdf.convertPDFToPngBytes(doc);
+    const limitDetails = (renderedPages: number, limit: number): IDocumentPageLimitErrorDetails => ({
+      renderedPages,
+      maxPages: limit,
+      documentCount: options.pdfDocuments.length,
+      documentIndex: index,
+      allDocumentsRendered: index === options.pdfDocuments.length - 1,
+    });
+    // SmartPDF limits one document, so each render gets the pages the request has left. It takes
+    // no limit of zero: when the earlier documents used up the request's pages, the smallest limit
+    // lets the document's page count be known, and a document of one page renders and is refused below.
+    const renderMaxPages = maxPages === undefined ? undefined : Math.max(maxPages - imagePages.length, 1);
+    let pages: Uint8Array[];
+    try {
+      pages = await pdf.convertPDFToPngBytes(doc, { signal: abortSignal, maxPages: renderMaxPages });
+    } catch (error) {
+      if (maxPages !== undefined && error instanceof plugins.smartpdf.SmartPdfPageLimitError) {
+        throw new DocumentPageLimitError(limitDetails(imagePages.length + error.pageCount, maxPages), { cause: error });
+      }
+      throw error;
+    }
     abortSignal?.throwIfAborted();
     imagePages.push(...pages);
     if (maxPages !== undefined && imagePages.length > maxPages) {
-      throw new DocumentPageLimitError({
-        renderedPages: imagePages.length,
-        maxPages,
-        documentCount: options.pdfDocuments.length,
-        allDocumentsRendered: index === options.pdfDocuments.length - 1,
-      });
+      throw new DocumentPageLimitError(limitDetails(imagePages.length, maxPages));
     }
   }
 
   // Filter out empty buffers
   const validPages = imagePages.filter(page => page && page.length > 0);
 
-  const result = await plugins.generateText({
-    model: options.model,
-    instructions: options.systemMessage,
-    messages: [
-      ...(options.messageHistory ?? []),
-      {
-        role: 'user',
-        content: [
-          { type: 'text', text: options.userMessage },
-          ...validPages.map(page => ({
-            type: 'file' as const,
-            data: page,
-            mediaType: 'image/png' as const,
-          })),
-        ],
-      },
-    ],
-    providerOptions: options.providerOptions,
-    abortSignal,
-  });
+  const onUsage = options.onUsage;
+  const modelCalls = onUsage ? new plugins.AgentModelCallUsageRecorder(options.model, onUsage) : null;
+  // Each attempt, retries included, is one model call: it starts in the middleware, which also
+  // settles an attempt that throws; a call whose response arrives ends in onLanguageModelCallEnd.
+  const model = modelCalls
+    ? plugins.wrapLanguageModel({
+        model: options.model,
+        middleware: {
+          wrapGenerate: async ({ doGenerate, params }) => {
+            modelCalls.start();
+            try {
+              return await doGenerate();
+            } catch (error) {
+              modelCalls.settle(params.abortSignal?.aborted ? 'aborted' : 'failed');
+              throw error;
+            }
+          },
+        },
+      })
+    : options.model;
+  const messages: ModelMessage[] = [
+    ...(options.messageHistory ?? []),
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: options.userMessage },
+        ...validPages.map(page => ({
+          type: 'file' as const,
+          data: page,
+          mediaType: 'image/png' as const,
+        })),
+      ],
+    },
+  ];
+  let result: Awaited<ReturnType<typeof plugins.generateText>>;
+  try {
+    result = await plugins.generateText({
+      model,
+      instructions: options.systemMessage,
+      messages,
+      providerOptions: options.providerOptions,
+      abortSignal,
+      ...(modelCalls
+        ? {
+            onLanguageModelCallEnd: ({ modelId, usage: callUsage }) => {
+              modelCalls.end(modelId, callUsage);
+            },
+          }
+        : {}),
+    });
+    modelCalls?.settle('missing');
+  } catch (error) {
+    modelCalls?.settle(abortSignal?.aborted ? 'aborted' : 'failed');
+    throw error;
+  }
   const usage = result.totalUsage;
   const inputTokens = usage.inputTokens ?? 0;
   const outputTokens = usage.outputTokens ?? 0;

package/ts_document/plugins.ts

@@ -1,3 +1,5 @@
-import { generateText } from 'ai';
+import { generateText, wrapLanguageModel } from 'ai';
 import * as smartpdf from '@push.rocks/smartpdf';
-export { generateText, smartpdf };
+import { AgentModelCallUsageRecorder } from '@modelprofile.com/flexharness-agent';
+export { generateText, wrapLanguageModel, smartpdf, AgentModelCallUsageRecorder };
+export type { TAgentModelCallUsageReporter } from '@modelprofile.com/flexharness-agent';

package/ts_document/readme.md

@@ -23,11 +23,12 @@ Supply a model from your selected FlexHarness provider. `extractTextFromPdf` rep
 
 `analyzeDocuments({ model, userMessage, pdfDocuments, systemMessage?, messageHistory? })` supports general analysis across multiple PDFs. This component owns a shared SmartPDF instance; call `stopSmartpdf()` when all document work has finished. Image-only OCR is available independently in `flexharness/ocr`.
 
-Both functions accept three request options:
+Both functions accept four request options:
 
 - `providerOptions` is passed to the model call unchanged, for example `{ openai: { store: false } }` so the provider does not keep the request as application state.
-- `abortSignal` is checked before each document is rendered and before the model call, and is passed to the model call. SmartPDF cannot stop a document it is already rendering, so that render finishes first.
-- `maxPages` is the most rendered pages one request may send to the model. A request with more pages rejects with `DocumentPageLimitError` (`renderedPages`, `maxPages`) before the model is called, and documents after the one that exceeded the limit are not rendered.
+- `abortSignal` is checked before each document is rendered and before the model call, and is passed to both the render and the model call, so an abort also stops a document that is rendering. The request rejects with the signal's reason.
+- `maxPages` is the most rendered pages one request may send to the model, counted over all its documents. A request with more pages rejects with `DocumentPageLimitError` before the model is called. Each document is rendered only when its page count fits the pages the request has left, so the document that exceeds the limit and every document after it are not rendered; SmartPDF counts that document's pages without rendering them. The exception is a one-page document that comes after the request's pages are used up: SmartPDF takes no limit of zero pages, so that document renders and is then refused. The error carries `renderedPages` (the pages of the documents up to and including the one that exceeded the limit), `maxPages` and `documentIndex` (the zero-based position of that document), and SmartPDF's `SmartPdfPageLimitError` as its `cause` when SmartPDF refused the document.
+- `onUsage` receives the usage of each model call of the request, also of a request that fails or is aborted; see [Usage of a request that fails or is aborted](#usage-of-a-request-that-fails-or-is-aborted).
 
 `extractTextFromPdfWithUsage` and `analyzeDocumentsWithUsage` take the same arguments and return `{ text, usage, pageCount }`. `usage` has the shape of an agent run's usage (`inputTokens`, `outputTokens`, `totalTokens`, `cacheReadTokens`, `cacheWriteTokens`), summed over the request's model steps, with usage the provider leaves out counted as zero; `pageCount` is the number of rendered pages sent to the model.
 
@@ -49,6 +50,28 @@ try {
 }
 ```
 
+### Usage of a request that fails or is aborted
+
+A request that throws returns no `usage`. `onUsage` reports each model call of a request once, as soon as its usage is known, whatever the outcome, with the events of `AgentModelCallUsageRecorder` (the type is `TFlexModelCallUsage` from `@modelprofile.com/flexharness`):
+
+```typescript
+import type { TFlexModelCallUsage } from '@modelprofile.com/flexharness';
+
+const calls: TFlexModelCallUsage[] = [];
+try {
+  await extractTextFromPdfWithUsage(pdfBytes, { model, abortSignal, onUsage: (call) => calls.push(call) });
+} finally {
+  const reported = calls.filter((call) => call.status === 'reported');
+  const complete = reported.length === calls.length; // an unreported call used an unknown number of tokens
+}
+```
+
+- `status: 'reported'`: the provider reported the call's `usage`; `requestedModelId` is the model's id and `responseModelId` the id the response named.
+- `status: 'unreported'`: the call `failed`, was `aborted`, or its response carried no usage (`missing`). The provider may still have consumed tokens for it.
+- Every attempt is a call of its own: a call retried after a failure reports the failed attempt and the retry.
+- A request that ends before its model is called (an abort during rendering, `DocumentPageLimitError`) reports nothing.
+- When a request returns, its reported calls sum to its `usage`; count one or the other. `onUsage` must not throw.
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).