@modelprofile.com/flexharness 8.1.0 → 8.2.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@modelprofile.com/flexharness',
-    version: '8.1.0',
+    version: '8.2.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,19 +1,66 @@
 import type { ModelMessage } from 'ai';
-import type { TSmartAiLanguageModel } from '@modelprofile.com/flexharness-models';
-export interface IDocumentOptions {
+import type { TSmartAiLanguageModel, TSmartAiProviderOptions } from '@modelprofile.com/flexharness-models';
+/** Options every document request accepts in addition to its model and messages. */
+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.
+     */
+    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.
+     */
+    maxPages?: number;
+}
+export interface IDocumentOptions extends IDocumentRequestOptions {
     model: TSmartAiLanguageModel;
     systemMessage?: string;
     userMessage: string;
     pdfDocuments: Uint8Array[];
     messageHistory?: ModelMessage[];
 }
-export interface IPdfTextExtractionOptions {
+export interface IPdfTextExtractionOptions extends IDocumentRequestOptions {
     model: TSmartAiLanguageModel;
     systemMessage?: string;
     userMessage?: string;
     messageHistory?: ModelMessage[];
 }
+/** Token usage of a document request, summed over its model steps; usage a provider leaves out counts as zero. */
+export interface IDocumentUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+export interface IDocumentAnalysisResult {
+    text: string;
+    usage: IDocumentUsage;
+    /** Rendered pages sent to the model. A page that renders to an empty image is not sent. */
+    pageCount: number;
+}
+export interface IDocumentPageLimitErrorDetails {
+    renderedPages: number;
+    maxPages: number;
+    documentCount: number;
+    allDocumentsRendered: boolean;
+}
+/** A request whose documents render to 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. */
+    readonly renderedPages: number;
+    readonly maxPages: number;
+    constructor(details: IDocumentPageLimitErrorDetails);
+}
 /** The model-based PDF OCR recipe formerly provided by SmartOCR. */
 export declare function extractTextFromPdf(pdfDocument: Uint8Array, options: IPdfTextExtractionOptions): Promise<string>;
+/** `extractTextFromPdf` that also returns the request's token usage and the pages sent. */
+export declare function extractTextFromPdfWithUsage(pdfDocument: Uint8Array, options: IPdfTextExtractionOptions): Promise<IDocumentAnalysisResult>;
 export declare function analyzeDocuments(options: IDocumentOptions): Promise<string>;
+/** `analyzeDocuments` that also returns the request's token usage and the pages sent. */
+export declare function analyzeDocumentsWithUsage(options: IDocumentOptions): Promise<IDocumentAnalysisResult>;
 export declare function stopSmartpdf(): Promise<void>;

package/dist_ts_document/index.js

@@ -1,28 +1,81 @@
 import * as plugins from './plugins.js';
-let smartpdfInstance = null;
-async function ensureSmartpdf() {
-    if (!smartpdfInstance) {
-        smartpdfInstance = new plugins.smartpdf.SmartPdf();
-        await smartpdfInstance.start();
+/** The one start of the shared SmartPDF instance; every request awaits it, and a failed start is forgotten. */
+let smartpdfStart = null;
+function ensureSmartpdf() {
+    if (!smartpdfStart) {
+        const instance = new plugins.smartpdf.SmartPdf();
+        const start = instance.start().then(() => instance);
+        smartpdfStart = start;
+        start.catch(() => {
+            if (smartpdfStart === start) {
+                smartpdfStart = null;
+            }
+        });
     }
-    return smartpdfInstance;
+    return smartpdfStart;
 }
+/** A request whose documents render to 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. */
+    renderedPages;
+    maxPages;
+    constructor(details) {
+        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.`);
+        this.name = 'DocumentPageLimitError';
+        this.renderedPages = details.renderedPages;
+        this.maxPages = details.maxPages;
+    }
+}
+const DEFAULT_OCR_SYSTEM_MESSAGE = 'You are a precise OCR engine. Extract text faithfully and do not summarize.';
+const DEFAULT_OCR_USER_MESSAGE = 'Extract all readable text from this PDF. Preserve page order, line breaks, table structure, and obvious headings. Return only the extracted text.';
 /** The model-based PDF OCR recipe formerly provided by SmartOCR. */
 export async function extractTextFromPdf(pdfDocument, options) {
-    return analyzeDocuments({
+    return (await extractTextFromPdfWithUsage(pdfDocument, options)).text;
+}
+/** `extractTextFromPdf` that also returns the request's token usage and the pages sent. */
+export async function extractTextFromPdfWithUsage(pdfDocument, options) {
+    return analyzeDocumentsWithUsage({
         model: options.model,
-        systemMessage: options.systemMessage ?? 'You are a precise OCR engine. Extract text faithfully and do not summarize.',
-        userMessage: options.userMessage ?? 'Extract all readable text from this PDF. Preserve page order, line breaks, table structure, and obvious headings. Return only the extracted text.',
+        systemMessage: options.systemMessage ?? DEFAULT_OCR_SYSTEM_MESSAGE,
+        userMessage: options.userMessage ?? DEFAULT_OCR_USER_MESSAGE,
         pdfDocuments: [pdfDocument],
         messageHistory: options.messageHistory,
+        providerOptions: options.providerOptions,
+        abortSignal: options.abortSignal,
+        maxPages: options.maxPages,
     });
 }
 export async function analyzeDocuments(options) {
-    const pdf = await ensureSmartpdf();
+    return (await analyzeDocumentsWithUsage(options)).text;
+}
+/** `analyzeDocuments` that also returns the request's token usage and the pages sent. */
+export async function analyzeDocumentsWithUsage(options) {
+    const maxPages = options.maxPages;
+    if (maxPages !== undefined && (!Number.isSafeInteger(maxPages) || maxPages < 1)) {
+        throw new RangeError('maxPages must be a positive whole number.');
+    }
+    const abortSignal = options.abortSignal;
+    abortSignal?.throwIfAborted();
     const imagePages = [];
-    for (const doc of options.pdfDocuments) {
+    for (const [index, doc] of options.pdfDocuments.entries()) {
+        const pdf = await ensureSmartpdf();
+        abortSignal?.throwIfAborted();
         const pages = await pdf.convertPDFToPngBytes(doc);
+        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,
+            });
+        }
     }
     // Filter out empty buffers
     const validPages = imagePages.filter(page => page && page.length > 0);
@@ -43,13 +96,40 @@ export async function analyzeDocuments(options) {
                 ],
             },
         ],
+        providerOptions: options.providerOptions,
+        abortSignal,
     });
-    return result.text;
+    const usage = result.totalUsage;
+    const inputTokens = usage.inputTokens ?? 0;
+    const outputTokens = usage.outputTokens ?? 0;
+    return {
+        text: result.text,
+        usage: {
+            inputTokens,
+            outputTokens,
+            totalTokens: inputTokens + outputTokens,
+            cacheReadTokens: usage.inputTokenDetails.cacheReadTokens ?? 0,
+            cacheWriteTokens: usage.inputTokenDetails.cacheWriteTokens ?? 0,
+        },
+        pageCount: validPages.length,
+    };
 }
 export async function stopSmartpdf() {
-    if (smartpdfInstance) {
-        await smartpdfInstance.stop();
-        smartpdfInstance = null;
+    const start = smartpdfStart;
+    if (!start) {
+        return;
+    }
+    // forget the instance before waiting on anything, so a request made from now on starts a fresh one
+    // instead of receiving the instance that is being stopped
+    smartpdfStart = null;
+    let instance;
+    try {
+        instance = await start;
+    }
+    catch {
+        // a failed start left no started instance that could be stopped
+        return;
     }
+    await instance.stop();
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19kb2N1bWVudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUl4QyxJQUFJLGdCQUFnQixHQUEwRCxJQUFJLENBQUM7QUFFbkYsS0FBSyxVQUFVLGNBQWM7SUFDM0IsSUFBSSxDQUFDLGdCQUFnQixFQUFFLENBQUM7UUFDdEIsZ0JBQWdCLEdBQUcsSUFBSSxPQUFPLENBQUMsUUFBUSxDQUFDLFFBQVEsRUFBRSxDQUFDO1FBQ25ELE1BQU0sZ0JBQWdCLENBQUMsS0FBSyxFQUFFLENBQUM7SUFDakMsQ0FBQztJQUNELE9BQU8sZ0JBQWdCLENBQUM7QUFDMUIsQ0FBQztBQWlCRCxvRUFBb0U7QUFDcEUsTUFBTSxDQUFDLEtBQUssVUFBVSxrQkFBa0IsQ0FDdEMsV0FBdUIsRUFDdkIsT0FBa0M7SUFFbEMsT0FBTyxnQkFBZ0IsQ0FBQztRQUN0QixLQUFLLEVBQUUsT0FBTyxDQUFDLEtBQUs7UUFDcEIsYUFBYSxFQUFFLE9BQU8sQ0FBQyxhQUFhLElBQUksNkVBQTZFO1FBQ3JILFdBQVcsRUFBRSxPQUFPLENBQUMsV0FBVyxJQUFJLG1KQUFtSjtRQUN2TCxZQUFZLEVBQUUsQ0FBQyxXQUFXLENBQUM7UUFDM0IsY0FBYyxFQUFFLE9BQU8sQ0FBQyxjQUFjO0tBQ3ZDLENBQUMsQ0FBQztBQUNMLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLGdCQUFnQixDQUFDLE9BQXlCO0lBQzlELE1BQU0sR0FBRyxHQUFHLE1BQU0sY0FBYyxFQUFFLENBQUM7SUFFbkMsTUFBTSxVQUFVLEdBQWlCLEVBQUUsQ0FBQztJQUNwQyxLQUFLLE1BQU0sR0FBRyxJQUFJLE9BQU8sQ0FBQyxZQUFZLEVBQUUsQ0FBQztRQUN2QyxNQUFNLEtBQUssR0FBRyxNQUFNLEdBQUcsQ0FBQyxvQkFBb0IsQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUNsRCxVQUFVLENBQUMsSUFBSSxDQUFDLEdBQUcsS0FBSyxDQUFDLENBQUM7SUFDNUIsQ0FBQztJQUVELDJCQUEyQjtJQUMzQixNQUFNLFVBQVUsR0FBRyxVQUFVLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsSUFBSSxJQUFJLElBQUksQ0FBQyxNQUFNLEdBQUcsQ0FBQyxDQUFDLENBQUM7SUFFdEUsTUFBTSxNQUFNLEdBQUcsTUFBTSxPQUFPLENBQUMsWUFBWSxDQUFDO1FBQ3hDLEtBQUssRUFBRSxPQUFPLENBQUMsS0FBSztRQUNwQixZQUFZLEVBQUUsT0FBTyxDQUFDLGFBQWE7UUFDbkMsUUFBUSxFQUFFO1lBQ1IsR0FBRyxDQUFDLE9BQU8sQ0FBQyxjQUFjLElBQUksRUFBRSxDQUFDO1lBQ2pDO2dCQUNFLElBQUksRUFBRSxNQUFNO2dCQUNaLE9BQU8sRUFBRTtvQkFDUCxFQUFFLElBQUksRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLE9BQU8sQ0FBQyxXQUFXLEVBQUU7b0JBQzNDLEdBQUcsVUFBVSxDQUFDLEdBQUcsQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDLENBQUM7d0JBQ3pCLElBQUksRUFBRSxNQUFlO3dCQUNyQixJQUFJLEVBQUUsSUFBSTt3QkFDVixTQUFTLEVBQUUsV0FBb0I7cUJBQ2hDLENBQUMsQ0FBQztpQkFDSjthQUNGO1NBQ0Y7S0FDRixDQUFDLENBQUM7SUFDSCxPQUFPLE1BQU0sQ0FBQyxJQUFJLENBQUM7QUFDckIsQ0FBQztBQUVELE1BQU0sQ0FBQyxLQUFLLFVBQVUsWUFBWTtJQUNoQyxJQUFJLGdCQUFnQixFQUFFLENBQUM7UUFDckIsTUFBTSxnQkFBZ0IsQ0FBQyxJQUFJLEVBQUUsQ0FBQztRQUM5QixnQkFBZ0IsR0FBRyxJQUFJLENBQUM7SUFDMUIsQ0FBQztBQUNILENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19kb2N1bWVudC9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQU14QywrR0FBK0c7QUFDL0csSUFBSSxhQUFhLEdBQThCLElBQUksQ0FBQztBQUVwRCxTQUFTLGNBQWM7SUFDckIsSUFBSSxDQUFDLGFBQWEsRUFBRSxDQUFDO1FBQ25CLE1BQU0sUUFBUSxHQUFHLElBQUksT0FBTyxDQUFDLFFBQVEsQ0FBQyxRQUFRLEVBQUUsQ0FBQztRQUNqRCxNQUFNLEtBQUssR0FBRyxRQUFRLENBQUMsS0FBSyxFQUFFLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQ3BELGFBQWEsR0FBRyxLQUFLLENBQUM7UUFDdEIsS0FBSyxDQUFDLEtBQUssQ0FBQyxHQUFHLEVBQUU7WUFDZixJQUFJLGFBQWEsS0FBSyxLQUFLLEVBQUUsQ0FBQztnQkFDNUIsYUFBYSxHQUFHLElBQUksQ0FBQztZQUN2QixDQUFDO1FBQ0gsQ0FBQyxDQUFDLENBQUM7SUFDTCxDQUFDO0lBQ0QsT0FBTyxhQUFhLENBQUM7QUFDdkIsQ0FBQztBQXlERCxvR0FBb0c7QUFDcEcsTUFBTSxPQUFPLHNCQUF1QixTQUFRLEtBQUs7SUFDL0MsMEdBQTBHO0lBQzFGLGFBQWEsQ0FBUztJQUN0QixRQUFRLENBQVM7SUFFakMsWUFBWSxPQUF1QztRQUNqRCxNQUFNLE9BQU8sR0FBRyxPQUFPLENBQUMsYUFBYSxLQUFLLENBQUM7WUFDekMsQ0FBQyxDQUFDLG9CQUFvQixPQUFPLENBQUMsYUFBYSxRQUFRO1lBQ25ELENBQUMsQ0FBQyxPQUFPLENBQUMsb0JBQW9CO2dCQUM1QixDQUFDLENBQUMsc0JBQXNCLE9BQU8sQ0FBQyxhQUFhLFFBQVE7Z0JBQ3JELENBQUMsQ0FBQywrQkFBK0IsT0FBTyxDQUFDLGFBQWEsUUFBUSxDQUFD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

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "8.1.0",
+  "version": "8.2.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,8 +62,8 @@
     }
   },
   "dependencies": {
-    "@modelprofile.com/flexharness-agent": "8.1.0",
-    "@modelprofile.com/flexharness-models": "8.1.0",
+    "@modelprofile.com/flexharness-agent": "8.2.0",
+    "@modelprofile.com/flexharness-models": "8.2.0",
     "@push.rocks/smartrequest": "^5.0.1",
     "ai": "^7.0.79",
     "zod": "^4.4.1"

package/ts/00_commitinfo_data.ts

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

package/ts_document/index.ts

@@ -1,18 +1,44 @@
 import * as plugins from './plugins.js';
 import type { ModelMessage } from 'ai';
-import type { TSmartAiLanguageModel } from '@modelprofile.com/flexharness-models';
+import type { TSmartAiLanguageModel, TSmartAiProviderOptions } from '@modelprofile.com/flexharness-models';
 
-let smartpdfInstance: InstanceType<typeof plugins.smartpdf.SmartPdf> | null = null;
+type TSmartPdf = InstanceType<typeof plugins.smartpdf.SmartPdf>;
 
-async function ensureSmartpdf(): Promise<InstanceType<typeof plugins.smartpdf.SmartPdf>> {
-  if (!smartpdfInstance) {
-    smartpdfInstance = new plugins.smartpdf.SmartPdf();
-    await smartpdfInstance.start();
+/** The one start of the shared SmartPDF instance; every request awaits it, and a failed start is forgotten. */
+let smartpdfStart: Promise<TSmartPdf> | null = null;
+
+function ensureSmartpdf(): Promise<TSmartPdf> {
+  if (!smartpdfStart) {
+    const instance = new plugins.smartpdf.SmartPdf();
+    const start = instance.start().then(() => instance);
+    smartpdfStart = start;
+    start.catch(() => {
+      if (smartpdfStart === start) {
+        smartpdfStart = null;
+      }
+    });
   }
-  return smartpdfInstance;
+  return smartpdfStart;
+}
+
+/** Options every document request accepts in addition to its model and messages. */
+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.
+   */
+  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.
+   */
+  maxPages?: number;
 }
 
-export interface IDocumentOptions {
+export interface IDocumentOptions extends IDocumentRequestOptions {
   model: TSmartAiLanguageModel;
   systemMessage?: string;
   userMessage: string;
@@ -20,34 +46,111 @@ export interface IDocumentOptions {
   messageHistory?: ModelMessage[];
 }
 
-export interface IPdfTextExtractionOptions {
+export interface IPdfTextExtractionOptions extends IDocumentRequestOptions {
   model: TSmartAiLanguageModel;
   systemMessage?: string;
   userMessage?: string;
   messageHistory?: ModelMessage[];
 }
 
+/** Token usage of a document request, summed over its model steps; usage a provider leaves out counts as zero. */
+export interface IDocumentUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+export interface IDocumentAnalysisResult {
+  text: string;
+  usage: IDocumentUsage;
+  /** Rendered pages sent to the model. A page that renders to an empty image is not sent. */
+  pageCount: number;
+}
+
+export interface IDocumentPageLimitErrorDetails {
+  renderedPages: number;
+  maxPages: number;
+  documentCount: number;
+  allDocumentsRendered: boolean;
+}
+
+/** A request whose documents render to 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. */
+  public readonly renderedPages: number;
+  public readonly maxPages: number;
+
+  constructor(details: IDocumentPageLimitErrorDetails) {
+    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.`);
+    this.name = 'DocumentPageLimitError';
+    this.renderedPages = details.renderedPages;
+    this.maxPages = details.maxPages;
+  }
+}
+
+const DEFAULT_OCR_SYSTEM_MESSAGE = 'You are a precise OCR engine. Extract text faithfully and do not summarize.';
+const DEFAULT_OCR_USER_MESSAGE = 'Extract all readable text from this PDF. Preserve page order, line breaks, table structure, and obvious headings. Return only the extracted text.';
+
 /** The model-based PDF OCR recipe formerly provided by SmartOCR. */
 export async function extractTextFromPdf(
   pdfDocument: Uint8Array,
   options: IPdfTextExtractionOptions,
 ): Promise<string> {
-  return analyzeDocuments({
+  return (await extractTextFromPdfWithUsage(pdfDocument, options)).text;
+}
+
+/** `extractTextFromPdf` that also returns the request's token usage and the pages sent. */
+export async function extractTextFromPdfWithUsage(
+  pdfDocument: Uint8Array,
+  options: IPdfTextExtractionOptions,
+): Promise<IDocumentAnalysisResult> {
+  return analyzeDocumentsWithUsage({
     model: options.model,
-    systemMessage: options.systemMessage ?? 'You are a precise OCR engine. Extract text faithfully and do not summarize.',
-    userMessage: options.userMessage ?? 'Extract all readable text from this PDF. Preserve page order, line breaks, table structure, and obvious headings. Return only the extracted text.',
+    systemMessage: options.systemMessage ?? DEFAULT_OCR_SYSTEM_MESSAGE,
+    userMessage: options.userMessage ?? DEFAULT_OCR_USER_MESSAGE,
     pdfDocuments: [pdfDocument],
     messageHistory: options.messageHistory,
+    providerOptions: options.providerOptions,
+    abortSignal: options.abortSignal,
+    maxPages: options.maxPages,
   });
 }
 
 export async function analyzeDocuments(options: IDocumentOptions): Promise<string> {
-  const pdf = await ensureSmartpdf();
+  return (await analyzeDocumentsWithUsage(options)).text;
+}
+
+/** `analyzeDocuments` that also returns the request's token usage and the pages sent. */
+export async function analyzeDocumentsWithUsage(options: IDocumentOptions): Promise<IDocumentAnalysisResult> {
+  const maxPages = options.maxPages;
+  if (maxPages !== undefined && (!Number.isSafeInteger(maxPages) || maxPages < 1)) {
+    throw new RangeError('maxPages must be a positive whole number.');
+  }
+  const abortSignal = options.abortSignal;
+  abortSignal?.throwIfAborted();
 
   const imagePages: Uint8Array[] = [];
-  for (const doc of options.pdfDocuments) {
+  for (const [index, doc] of options.pdfDocuments.entries()) {
+    const pdf = await ensureSmartpdf();
+    abortSignal?.throwIfAborted();
     const pages = await pdf.convertPDFToPngBytes(doc);
+    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,
+      });
+    }
   }
 
   // Filter out empty buffers
@@ -70,13 +173,39 @@ export async function analyzeDocuments(options: IDocumentOptions): Promise<strin
         ],
       },
     ],
+    providerOptions: options.providerOptions,
+    abortSignal,
   });
-  return result.text;
+  const usage = result.totalUsage;
+  const inputTokens = usage.inputTokens ?? 0;
+  const outputTokens = usage.outputTokens ?? 0;
+  return {
+    text: result.text,
+    usage: {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      cacheReadTokens: usage.inputTokenDetails.cacheReadTokens ?? 0,
+      cacheWriteTokens: usage.inputTokenDetails.cacheWriteTokens ?? 0,
+    },
+    pageCount: validPages.length,
+  };
 }
 
 export async function stopSmartpdf(): Promise<void> {
-  if (smartpdfInstance) {
-    await smartpdfInstance.stop();
-    smartpdfInstance = null;
+  const start = smartpdfStart;
+  if (!start) {
+    return;
+  }
+  // forget the instance before waiting on anything, so a request made from now on starts a fresh one
+  // instead of receiving the instance that is being stopped
+  smartpdfStart = null;
+  let instance: TSmartPdf;
+  try {
+    instance = await start;
+  } catch {
+    // a failed start left no started instance that could be stopped
+    return;
   }
+  await instance.stop();
 }

package/ts_document/readme.md

@@ -23,6 +23,32 @@ 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:
+
+- `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.
+
+`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.
+
+```typescript
+import { extractTextFromPdfWithUsage, DocumentPageLimitError } from '@modelprofile.com/flexharness/documents';
+
+try {
+  const { text, usage, pageCount } = await extractTextFromPdfWithUsage(pdfBytes, {
+    model,
+    providerOptions: { openai: { store: false } },
+    abortSignal,
+    maxPages: 20,
+  });
+} catch (error) {
+  if (error instanceof DocumentPageLimitError) {
+    console.log(`${error.renderedPages} pages, at most ${error.maxPages}`);
+  }
+  throw error;
+}
+```
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).