@modelprofile.com/flexharness 9.7.0 → 9.9.0

package/ts/interfaces.ts

@@ -532,9 +532,24 @@ export interface IFlexPermissionRequest
   sessionId: string;
   runId: string;
   createdAt: string;
+  /** A bound policy requires an explicit response and disallows remembered approval. */
+  requiresExplicitResponse?: true;
 }
 
 export type TFlexPermissionDecision = 'once' | 'always' | 'reject';
+export type TFlexSessionPermissionPolicyDecision = 'inherit' | 'allow' | 'ask' | 'deny';
+
+export interface IFlexSessionPermissionPolicyContext<TScope> extends IFlexSessionGeneration {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+  readonly runId: string;
+  readonly configurationRef: string;
+  readonly agent?: string;
+  readonly request: Readonly<IFlexPermissionRequest>;
+  readonly signal: AbortSignal;
+}
 
 export interface IFlexToolProviderContext<TScope> extends IFlexSessionGeneration {
   scopeId: string;
@@ -753,6 +768,12 @@ export interface IFlexSessionConfigurationResolverContext<TScope> extends IFlexS
 export interface IFlexResolvedSessionConfiguration<TScope> {
   subagents?: readonly IFlexSubagentDefinition[];
   slashCommands?: readonly TFlexSlashCommandRegistration<TScope>[];
+  /** Exact model-facing names permitted for this bound session; omitted means unrestricted. */
+  allowedTools?: readonly string[];
+  /** Evaluated for each request before a remembered grant can be reused. */
+  permissionPolicy?: (
+    context: IFlexSessionPermissionPolicyContext<TScope>,
+  ) => TFlexSessionPermissionPolicyDecision | Promise<TFlexSessionPermissionPolicyDecision>;
 }
 
 export interface IFlexSessionConfigurationResolver<TScope> {
@@ -1138,6 +1159,7 @@ export interface IFlexRedoSessionResult {
 export type TFlexExternalErrorSource =
   | 'modelResolver'
   | 'sessionConfigurationResolver'
+  | 'permissionPolicy'
   | 'toolProvider'
   | 'delegatedRunAdmissionProvider'
   | 'toolExecution'
@@ -1268,6 +1290,8 @@ export interface IFlexSubagentDefinition {
   modelHint?: string;
   system?: string;
   maxSteps?: number;
+  /** Exact model-facing names permitted for this agent; omitted means unrestricted. */
+  allowedTools?: readonly string[];
 }
 
 export interface IFlexProjectManagementBuiltInToolsOptions {
@@ -1420,6 +1444,8 @@ export interface IFlexPermissionResolvedEvent extends IFlexEventBase {
   readonly runId: string;
   readonly request: IFlexPermissionRequest;
   readonly decision: TFlexPermissionDecision;
+  /** Present when a bound policy resolved the request without making it pending. */
+  readonly origin?: 'policy';
 }
 
 export interface IFlexRunFinishedEvent extends IFlexEventBase {

package/ts/readme.md

@@ -62,7 +62,7 @@ or provider SDKs.
 | `/chat/cli` | Ink/React terminal chat | `ink ink-text-input react`; TypeScript: `@types/react` |
 | `/chat/web` | Lit `flexchat-window`, `flexchat-message`, `flexchat-input` | `lit` |
 | `/kvm` | Browser control, terminal framing and OCR observation | `puppeteer` |
-| `/documents` | PDF processing and `extractTextFromPdf` | `@push.rocks/smartpdf` |
+| `/documents` | PDF and image documents, `extractTextFromPdf` | `@push.rocks/smartpdf`; for image documents `sharp` |
 | `/mcp` | MCP clients and AI SDK tool conversion | `@modelcontextprotocol/sdk` |
 | `/migration` | Existing versioned harness migrations | None |
 

package/ts/utils.harnessoptions.ts

@@ -54,12 +54,39 @@ export const maxSubagentNameBytes = 128;
 const maxSubagentDescriptionBytes = 2048;
 const maxSubagentModelHintBytes = 512;
 const maxSubagentSystemBytes = 64 * 1024;
+const maxAllowedToolNames = 128;
+const maxAllowedToolNameBytes = 512;
+const toolNameControlPattern = /[\u0000-\u001f\u007f-\u009f]/u;
+const toolNameUnpairedSurrogatePattern = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
 const maxSlashCommandRegistrations = 128;
 const maxSlashCommandDescriptionBytes = 2048;
 const maxSlashCommandTemplateBytes = FLEX_SLASH_COMMAND_MAX_INPUT_BYTES;
 const defaultReversionMaintenanceTimeoutMs = 30_000;
 const maximumReversionMaintenanceTimeoutMs = 30 * 60 * 1000;
 
+export function normalizeAllowedTools(
+  names: readonly string[] | undefined,
+  label = 'allowedTools',
+): readonly string[] | undefined {
+  if (names === undefined) return undefined;
+  if (!Array.isArray(names) || names.length > maxAllowedToolNames) {
+    throw new FlexHarnessValidationError(`${label} must be an array with at most ${maxAllowedToolNames} names.`);
+  }
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (let index = 0; index < names.length; index++) {
+    const name = names[index];
+    validateUtf8String(name, `${label}[${index}]`, maxAllowedToolNameBytes, true);
+    if (toolNameControlPattern.test(name) || toolNameUnpairedSurrogatePattern.test(name)) {
+      throw new FlexHarnessValidationError(`${label}[${index}] must be a well-formed name without control characters.`);
+    }
+    if (seen.has(name)) throw new FlexHarnessValidationError(`${label} contains duplicate name "${name}".`);
+    seen.add(name);
+    normalized.push(name);
+  }
+  return Object.freeze(normalized);
+}
+
 export function normalizeSubagents(
   definitions: readonly IFlexSubagentDefinition[] | undefined,
 ): ReadonlyMap<string, Readonly<IFlexSubagentDefinition>> {
@@ -81,7 +108,7 @@ export function normalizeSubagents(
       throw new FlexHarnessValidationError(`subagents[${index}] must be a plain object.`);
     }
     const unsupported = Object.keys(definition).find(
-      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps'].includes(key),
+      (key) => !['name', 'description', 'modelHint', 'system', 'maxSteps', 'allowedTools'].includes(key),
     );
     if (unsupported) {
       throw new FlexHarnessValidationError(`subagents[${index}] does not support "${unsupported}".`);
@@ -121,6 +148,9 @@ export function normalizeSubagents(
       ...(definition.modelHint === undefined ? {} : { modelHint: definition.modelHint }),
       ...(definition.system === undefined ? {} : { system: definition.system }),
       ...(definition.maxSteps === undefined ? {} : { maxSteps: definition.maxSteps }),
+      ...(definition.allowedTools === undefined ? {} : {
+        allowedTools: normalizeAllowedTools(definition.allowedTools, `subagents[${index}].allowedTools`),
+      }),
     }));
   }
   return Object.freeze(normalized);

package/ts_document/index.ts

@@ -38,6 +38,11 @@ export interface IDocumentRequestOptions {
    * refused.
    */
   maxPages?: number;
+  /**
+   * The longest edge, in pixels, of an image document as it is sent to the model; a larger image is
+   * scaled down to it. Defaults to `DEFAULT_MAX_IMAGE_EDGE`.
+   */
+  maxImageEdge?: 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
@@ -52,7 +57,19 @@ export interface IDocumentOptions extends IDocumentRequestOptions {
   model: plugins.TSmartAiLanguageModel;
   systemMessage?: string;
   userMessage: string;
-  pdfDocuments: Uint8Array[];
+  /** PDFs, rendered page by page. The model sees their pages first, in the order given. */
+  pdfDocuments?: Uint8Array[];
+  /**
+   * Images, after the PDFs' pages, in the order given: JPEG, PNG, WebP, GIF, TIFF (every page) and
+   * AVIF. A JPEG, PNG or WebP within `maxImageEdge` and `MAX_IMAGE_BYTES` that needs no turning is
+   * sent as it is. Any other is turned upright by its EXIF orientation, scaled down to fit
+   * `maxImageEdge` and sent as JPEG (from a JPEG or AVIF, transparency on white) or PNG, for this
+   * request only. Each image and each TIFF page is a page of the request. Refused with
+   * `DocumentFormatError` before the model is called: an image that cannot be read, a format outside
+   * these, HEIC (not decodable here), a GIF or WebP of more than one frame, an AVIF of more than one
+   * image, and an image or TIFF page of more than `MAX_IMAGE_PIXELS`. Needs the optional peer dependency `sharp`.
+   */
+  imageDocuments?: Uint8Array[];
   messageHistory?: plugins.ModelMessage[];
 }
 
@@ -75,7 +92,10 @@ export interface IDocumentUsage {
 export interface IDocumentAnalysisResult {
   text: string;
   usage: IDocumentUsage;
-  /** Rendered pages sent to the model. A page that renders to an empty image is not sent. */
+  /**
+   * Pages sent to the model: the PDFs' rendered pages and the images' pages. A PDF page that renders
+   * to an empty image is not sent.
+   */
   pageCount: number;
 }
 
@@ -117,6 +137,251 @@ export class DocumentPageLimitError extends Error {
   }
 }
 
+/*
+ * The image limits below stay within what the providers publish (read 2026-09-28):
+ * - Anthropic, https://platform.claude.com/docs/en/build-with-claude/vision: at most 8000x8000 px per
+ *   image; in a request with more than 20 images at most 2000 px per side; at most 10 MB per image
+ *   (base64) on the Claude API and 5 MB (base64) on Amazon Bedrock and Google Cloud; JPEG, PNG, GIF
+ *   and WebP, of an animation only the first frame.
+ * - OpenAI, https://developers.openai.com/api/docs/guides/images-vision: PNG, JPEG, WebP and
+ *   non-animated GIF; up to 512 MB payload and 1500 images per request; the page names no size per
+ *   image. Images are scaled down on the provider's side.
+ */
+
+/**
+ * The longest edge, in pixels, of an image sent to the model when a request names none: Anthropic's
+ * 2000 pixels per side for a request with more than 20 images, the tightest of the limits above.
+ */
+export const DEFAULT_MAX_IMAGE_EDGE = 2000;
+
+/**
+ * The most bytes of one image sent to the model: 5 000 000 characters once base64-encoded, within
+ * Anthropic's 5 MB per image on Amazon Bedrock and Google Cloud, the smallest of the limits above.
+ */
+export const MAX_IMAGE_BYTES = 3_750_000;
+
+/**
+ * The most pixels (width times height) of one image or TIFF page that is decoded: an A3 page scanned
+ * at 600 dpi has about 70 million. The images come from mail and uploads, so a larger one is refused
+ * from its header, before it is decoded, instead of being given sharp's own limit of about 268 million.
+ */
+export const MAX_IMAGE_PIXELS = 100_000_000;
+
+/** Why an image document is refused. */
+export type TDocumentFormatRefusal =
+  /** it could not be read at all */
+  | 'unreadable'
+  /** it is a format this component does not read */
+  | 'unsupported'
+  /** it is HEIC, which the prebuilt sharp cannot decode */
+  | 'heic'
+  /** it is a GIF or WebP of more than one frame: frames are no pages, and none is dropped */
+  | 'animated'
+  /** it is an AVIF container of more than one image: which of them is the document is not known, and none is dropped */
+  | 'multiple_images'
+  /** it has more pixels than `MAX_IMAGE_PIXELS` */
+  | 'too_many_pixels'
+  /** it stays larger than `MAX_IMAGE_BYTES` after scaling */
+  | 'too_large';
+
+/** An image document this component does not read; the model was not called. */
+export class DocumentFormatError extends Error {
+  /** Zero-based position, in the request's documents (the PDFs first, then the images), of the image. */
+  public readonly documentIndex: number;
+  /** The format the image was read as, or null when it could not be read at all. */
+  public readonly format: string | null;
+  public readonly reason: TDocumentFormatRefusal;
+
+  constructor(
+    message: string,
+    details: { documentIndex: number; format: string | null; reason: TDocumentFormatRefusal },
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = 'DocumentFormatError';
+    this.documentIndex = details.documentIndex;
+    this.format = details.format;
+    this.reason = details.reason;
+  }
+}
+
+/** A page as it is sent to the model. */
+interface IModelPage {
+  data: Uint8Array;
+  mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
+}
+
+/** The formats sent as they are when they need no scaling and no turning. */
+const AS_IS_MEDIA_TYPES: ReadonlyMap<string, IModelPage['mediaType']> = new Map([
+  ['jpeg', 'image/jpeg'],
+  ['png', 'image/png'],
+  ['webp', 'image/webp'],
+]);
+
+/** The formats read at all: sharp's names, HEIF only with AV1 compression (AVIF). */
+const READABLE_IMAGE_FORMATS: ReadonlySet<string> = new Set(['jpeg', 'png', 'webp', 'gif', 'tiff', 'heif']);
+
+/** The formats whose further pages are frames of an animation, not pages of a document. */
+const ANIMATED_FORMATS: ReadonlySet<string> = new Set(['gif', 'webp']);
+
+/** The one load of the optional peer dependency sharp; a failed load is forgotten. */
+let sharpLoad: Promise<plugins.TImageReader> | null = null;
+
+function loadSharp(): Promise<plugins.TImageReader> {
+  if (!sharpLoad) {
+    const load = plugins.importSharp().catch((error: unknown) => {
+      if (sharpLoad === load) {
+        sharpLoad = null;
+      }
+      throw new Error('Image documents need the optional peer dependency sharp.', { cause: error });
+    });
+    sharpLoad = load;
+  }
+  return sharpLoad;
+}
+
+/** Refuses a page with more pixels than `MAX_IMAGE_PIXELS`, from what its header says. */
+function checkPixels(metadata: plugins.IImageMetadata, documentIndex: number, format: string): void {
+  const pixels = (metadata.width ?? 0) * (metadata.height ?? 0);
+  if (pixels > MAX_IMAGE_PIXELS) {
+    throw new DocumentFormatError(
+      `The image has ${metadata.width}x${metadata.height} pixels, more than the ${MAX_IMAGE_PIXELS} read here.`,
+      { documentIndex, format, reason: 'too_many_pixels' },
+    );
+  }
+}
+
+/** What an image document is, read from its header without decoding it. */
+async function readImage(
+  sharp: plugins.TImageReader,
+  image: Uint8Array,
+  documentIndex: number,
+): Promise<{ metadata: plugins.IImageMetadata; pageCount: number }> {
+  let metadata: plugins.IImageMetadata;
+  try {
+    metadata = await sharp(image).metadata();
+  } catch (error) {
+    throw new DocumentFormatError('The image could not be read.', { documentIndex, format: null, reason: 'unreadable' }, { cause: error });
+  }
+  const format = metadata.format ?? null;
+  if (format === 'heif' && metadata.compression !== 'av1') {
+    throw new DocumentFormatError(
+      'The image is HEIC, which cannot be decoded here; send it as JPEG.',
+      { documentIndex, format, reason: 'heic' },
+    );
+  }
+  if (!format || !READABLE_IMAGE_FORMATS.has(format)) {
+    throw new DocumentFormatError(
+      `The image is ${format ?? 'of an unknown format'}; images are read as JPEG, PNG, WebP, GIF, TIFF or AVIF.`,
+      { documentIndex, format, reason: 'unsupported' },
+    );
+  }
+  const pages = Math.max(metadata.pages ?? 1, 1);
+  if (ANIMATED_FORMATS.has(format) && pages > 1) {
+    throw new DocumentFormatError(
+      `The image is an animated ${format === 'gif' ? 'GIF' : 'WebP'} of ${pages} frames; its frames are no pages, so it is not read.`,
+      { documentIndex, format, reason: 'animated' },
+    );
+  }
+  // sharp reports the top-level images of a HEIF container as its pages (libvips heifload, n-pages);
+  // only a TIFF's pages are pages of a document
+  if (format !== 'tiff' && pages > 1) {
+    throw new DocumentFormatError(
+      `The image is an AVIF holding ${pages} images; which of them is the document is not known, so it is not read.`,
+      { documentIndex, format, reason: 'multiple_images' },
+    );
+  }
+  checkPixels(metadata, documentIndex, format);
+  return { metadata, pageCount: format === 'tiff' ? pages : 1 };
+}
+
+/** One page of an image document, upright, scaled down and encoded; a page that cannot be decoded is refused. */
+async function imagePage(
+  sharp: plugins.TImageReader,
+  image: Uint8Array,
+  page: number,
+  format: string,
+  photo: boolean,
+  maxEdge: number,
+  documentIndex: number,
+): Promise<IModelPage> {
+  const pipeline = () => sharp(image, { page, limitInputPixels: MAX_IMAGE_PIXELS })
+    .autoOrient()
+    .resize({ width: maxEdge, height: maxEdge, fit: 'inside', withoutEnlargement: true });
+  // JPEG has no transparency: a transparent background becomes white, not black
+  const jpeg = async (quality: number): Promise<IModelPage> => ({
+    data: await pipeline().flatten({ background: '#ffffff' }).jpeg({ quality }).toBuffer(),
+    mediaType: 'image/jpeg',
+  });
+  let encoded: IModelPage;
+  try {
+    if (page > 0) {
+      // each TIFF page has its own size; the first was checked with the document
+      checkPixels(await sharp(image, { page }).metadata(), documentIndex, format);
+    }
+    encoded = photo ? await jpeg(90) : { data: await pipeline().png().toBuffer(), mediaType: 'image/png' };
+    // too large: a photo tries a lower quality, any other a JPEG at the higher one first
+    for (const quality of photo ? [75] : [90, 75]) {
+      if (encoded.data.byteLength <= MAX_IMAGE_BYTES) {
+        break;
+      }
+      encoded = await jpeg(quality);
+    }
+  } catch (error) {
+    if (error instanceof DocumentFormatError) {
+      throw error;
+    }
+    throw new DocumentFormatError(
+      pageLabel(page, 'could not be decoded.'),
+      { documentIndex, format, reason: 'unreadable' },
+      { cause: error },
+    );
+  }
+  if (encoded.data.byteLength > MAX_IMAGE_BYTES) {
+    throw new DocumentFormatError(
+      pageLabel(page, `stays larger than ${MAX_IMAGE_BYTES} bytes after scaling to ${maxEdge} pixels.`),
+      { documentIndex, format, reason: 'too_large' },
+    );
+  }
+  // a Buffer is a Uint8Array view of a pooled ArrayBuffer; send exactly its bytes
+  return { data: new Uint8Array(encoded.data), mediaType: encoded.mediaType };
+}
+
+/** "The image …" for a one-page image, "Page n of the image …" for a TIFF page after the first. */
+const pageLabel = (page: number, predicate: string): string =>
+  page === 0 ? `The image ${predicate}` : `Page ${page + 1} of the image ${predicate}`;
+
+/** An image document's pages as they are sent: as they are where that fits, else upright and scaled down. */
+async function imagePages(
+  sharp: plugins.TImageReader,
+  image: Uint8Array,
+  metadata: plugins.IImageMetadata,
+  pageCount: number,
+  maxEdge: number,
+  documentIndex: number,
+  abortSignal: AbortSignal | undefined,
+): Promise<IModelPage[]> {
+  const format = metadata.format!;
+  const asIs = AS_IS_MEDIA_TYPES.get(format);
+  if (
+    asIs
+    && pageCount === 1
+    && (metadata.orientation ?? 1) === 1
+    && (metadata.width ?? Infinity) <= maxEdge
+    && (metadata.height ?? Infinity) <= maxEdge
+    && image.byteLength <= MAX_IMAGE_BYTES
+  ) {
+    return [{ data: image, mediaType: asIs }];
+  }
+  const photo = format === 'jpeg' || format === 'heif';
+  const pages: IModelPage[] = [];
+  for (let page = 0; page < pageCount; page++) {
+    abortSignal?.throwIfAborted();
+    pages.push(await imagePage(sharp, image, page, format, photo, maxEdge, documentIndex));
+  }
+  return pages;
+}
+
 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.';
 
@@ -156,42 +421,65 @@ export async function analyzeDocumentsWithUsage(options: IDocumentOptions): Prom
   if (maxPages !== undefined && (!Number.isSafeInteger(maxPages) || maxPages < 1)) {
     throw new RangeError('maxPages must be a positive whole number.');
   }
+  const maxImageEdge = options.maxImageEdge ?? DEFAULT_MAX_IMAGE_EDGE;
+  if (!Number.isSafeInteger(maxImageEdge) || maxImageEdge < 1) {
+    throw new RangeError('maxImageEdge must be a positive whole number.');
+  }
   const abortSignal = options.abortSignal;
   abortSignal?.throwIfAborted();
 
-  const imagePages: Uint8Array[] = [];
-  for (const [index, doc] of options.pdfDocuments.entries()) {
+  const pdfDocuments = options.pdfDocuments ?? [];
+  const imageDocuments = options.imageDocuments ?? [];
+  const documentCount = pdfDocuments.length + imageDocuments.length;
+  const limitDetails = (index: number, renderedPages: number, limit: number): IDocumentPageLimitErrorDetails => ({
+    renderedPages,
+    maxPages: limit,
+    documentCount,
+    documentIndex: index,
+    allDocumentsRendered: index === documentCount - 1,
+  });
+  const modelPages: IModelPage[] = [];
+  // every rendered page counts against maxPages, also a PDF page that renders empty and is not sent
+  let countedPages = 0;
+  for (const [index, doc] of pdfDocuments.entries()) {
     const pdf = await ensureSmartpdf();
     abortSignal?.throwIfAborted();
-    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);
+    const renderMaxPages = maxPages === undefined ? undefined : Math.max(maxPages - countedPages, 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 new DocumentPageLimitError(limitDetails(index, countedPages + error.pageCount, maxPages), { cause: error });
       }
       throw error;
     }
     abortSignal?.throwIfAborted();
-    imagePages.push(...pages);
-    if (maxPages !== undefined && imagePages.length > maxPages) {
-      throw new DocumentPageLimitError(limitDetails(imagePages.length, maxPages));
+    countedPages += pages.length;
+    modelPages.push(...pages.filter((page) => page && page.length > 0).map((page) => ({ data: page, mediaType: 'image/png' as const })));
+    if (maxPages !== undefined && countedPages > maxPages) {
+      throw new DocumentPageLimitError(limitDetails(index, countedPages, maxPages));
     }
   }
 
-  // Filter out empty buffers
-  const validPages = imagePages.filter(page => page && page.length > 0);
+  if (imageDocuments.length) {
+    const sharp = await loadSharp();
+    for (const [imageIndex, image] of imageDocuments.entries()) {
+      abortSignal?.throwIfAborted();
+      const index = pdfDocuments.length + imageIndex;
+      const { metadata, pageCount } = await readImage(sharp, image, index);
+      // an image's pages are known from its header, so an image over the limit is not decoded
+      if (maxPages !== undefined && countedPages + pageCount > maxPages) {
+        throw new DocumentPageLimitError(limitDetails(index, countedPages + pageCount, maxPages));
+      }
+      countedPages += pageCount;
+      modelPages.push(...await imagePages(sharp, image, metadata, pageCount, maxImageEdge, index, abortSignal));
+    }
+    abortSignal?.throwIfAborted();
+  }
 
   const onUsage = options.onUsage;
   const modelCalls = onUsage ? new plugins.AgentModelCallUsageRecorder(options.model, onUsage) : null;
@@ -219,10 +507,10 @@ export async function analyzeDocumentsWithUsage(options: IDocumentOptions): Prom
       role: 'user',
       content: [
         { type: 'text', text: options.userMessage },
-        ...validPages.map(page => ({
+        ...modelPages.map(page => ({
           type: 'file' as const,
-          data: page,
-          mediaType: 'image/png' as const,
+          data: page.data,
+          mediaType: page.mediaType,
         })),
       ],
     },
@@ -260,7 +548,7 @@ export async function analyzeDocumentsWithUsage(options: IDocumentOptions): Prom
       cacheReadTokens: usage.inputTokenDetails.cacheReadTokens ?? 0,
       cacheWriteTokens: usage.inputTokenDetails.cacheWriteTokens ?? 0,
     },
-    pageCount: validPages.length,
+    pageCount: modelPages.length,
   };
 }
 

package/ts_document/plugins.ts

@@ -5,3 +5,38 @@ export { generateText, wrapLanguageModel, smartpdf, AgentModelCallUsageRecorder
 export type { ModelMessage } from 'ai';
 export type { TSmartAiLanguageModel, TSmartAiProviderOptions } from '@modelprofile.com/flexharness-models';
 export type { TAgentModelCallUsageReporter } from '@modelprofile.com/flexharness-agent';
+
+// sharp is an optional peer dependency: it is loaded when a request carries its first image
+// document, so a project that sends only PDFs does not install it. What of it this component uses is
+// typed here, structurally, so that no declaration of /documents names sharp: a project without it
+// type-checks /documents all the same.
+
+/** What sharp reads from an image's header (`sharp.Metadata`, the fields used here). */
+export interface IImageMetadata {
+  format?: string;
+  compression?: string;
+  pages?: number;
+  orientation?: number;
+  width?: number;
+  height?: number;
+}
+
+/** A sharp pipeline, the operations used here. */
+export interface IImagePipeline {
+  metadata(): Promise<IImageMetadata>;
+  autoOrient(): IImagePipeline;
+  resize(options: { width: number; height: number; fit: 'inside'; withoutEnlargement: boolean }): IImagePipeline;
+  flatten(options: { background: string }): IImagePipeline;
+  jpeg(options: { quality: number }): IImagePipeline;
+  png(): IImagePipeline;
+  toBuffer(): Promise<Uint8Array>;
+}
+
+/** Opens an image (a page of it) as a pipeline, as `sharp(input, options)` does. */
+export type TImageReader = (input: Uint8Array, options?: { page?: number; limitInputPixels?: number }) => IImagePipeline;
+
+/** Loads sharp and hands out its reader. */
+export const importSharp = async (): Promise<TImageReader> => {
+  const sharp = (await import('sharp')).default;
+  return (input, options) => sharp(input, options);
+};

package/ts_document/readme.md

@@ -1,4 +1,4 @@
-PDF processing and language-model document recipes.
+PDF and image processing and language-model document recipes.
 
 Part of the [FlexHarness toolbox](https://code.foss.global/modelprofile.com/flexharness).
 Install the components your project uses. Provider adapters are registered explicitly;
@@ -6,6 +6,8 @@ the agent and harness do not install or register vendor SDKs.
 
 ```sh
 pnpm add @modelprofile.com/flexharness @push.rocks/smartpdf
+# for image documents as well
+pnpm add sharp
 ```
 
 ```typescript
@@ -23,11 +25,46 @@ 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 four request options:
+`analyzeDocuments` also takes `imageDocuments`, sent after the PDFs' pages in the order given. They need the optional peer dependency `sharp`, loaded with the first image:
+
+- JPEG, PNG and WebP that fit `maxImageEdge` and `MAX_IMAGE_BYTES` and need no turning go to the model as they are.
+- Any other image is turned upright by its EXIF orientation, scaled down to fit `maxImageEdge` and sent as JPEG (from a JPEG or AVIF) or PNG (from PNG, WebP, GIF or TIFF), for this request only; nothing is stored. A PNG that stays larger than `MAX_IMAGE_BYTES` is sent as JPEG. A transparent background becomes white in a JPEG.
+- Each image and each TIFF page is a page of the request. Their count is read from the header, so an image over `maxPages` is refused with `DocumentPageLimitError` before it is decoded.
+- A TIFF that stores a pyramid, its lower resolutions as further pages, sends every level as a page: sharp's metadata does not tell such levels from the pages of a document, and none is dropped.
+- Refused with `DocumentFormatError` before the model is called, its `reason` saying why:
+  - `unreadable`: the image cannot be read, or a page of it cannot be decoded;
+  - `unsupported`: none of JPEG, PNG, WebP, GIF, TIFF and AVIF;
+  - `heic`: the prebuilt sharp decodes AVIF but has no HEVC decoder;
+  - `animated`: a GIF or WebP of more than one frame, since frames are no pages and none is dropped;
+  - `multiple_images`: an AVIF container of more than one top-level image, since which of them is the document is not known and none is dropped;
+  - `too_many_pixels`: an image or TIFF page of more than `MAX_IMAGE_PIXELS` (100 000 000, an A3 page at 600 dpi has about 70 million), refused from its header before anything is decoded;
+  - `too_large`: an image that stays larger than `MAX_IMAGE_BYTES` after scaling.
+
+The limits stay within what the providers publish (read 2026-09-28):
+
+- Anthropic, <https://platform.claude.com/docs/en/build-with-claude/vision>: at most 8000x8000 px per image, at most 2000 px per side in a request with more than 20 images, at most 10 MB per image (base64) on the Claude API and 5 MB (base64) on Amazon Bedrock and Google Cloud.
+- OpenAI, <https://developers.openai.com/api/docs/guides/images-vision>: PNG, JPEG, WebP and non-animated GIF, up to 512 MB payload and 1500 images per request; the page names no limit per image.
+- `DEFAULT_MAX_IMAGE_EDGE` (2000 pixels) is Anthropic's limit for a request with more than 20 images, the tightest; `MAX_IMAGE_BYTES` (3 750 000 bytes, 5 000 000 characters once base64-encoded) is within Anthropic's 5 MB on Amazon Bedrock and Google Cloud.
+
+```typescript
+import { analyzeDocumentsWithUsage, DocumentFormatError } from '@modelprofile.com/flexharness/documents';
+
+const { text, pageCount } = await analyzeDocumentsWithUsage({
+  model,
+  userMessage: 'Read the invoice: supplier, date, number, net, VAT and gross amounts.',
+  imageDocuments: [photoBytes],
+  maxPages: 20,
+});
+```
+
+The request options below apply to image documents as they do to PDFs: an abort is checked before each document and each TIFF page, and before the model call.
+
+Both functions accept these 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 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.
+- `maxImageEdge` is the longest edge, in pixels, of an image document as it is sent; see above.
 - `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.