@modelprofile.com/flexharness 10.17.1 → 10.19.0

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_tools/readme.md

@@ -11,6 +11,16 @@ pnpm add @modelprofile.com/flexharness
 See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
 for composition examples and the SmartAI/SmartAgent migration map.
 
+## Filesystem tools
+
+`createFilesystemTools(context, options)` exposes `read_file`, `write_file`, `list_directory` and, unless `includeDelete: false`, `delete_file` over the context's `fs`. `write_file` and `delete_file` ask `context.requestPermission` (`write`, `delete`) before they change anything.
+
+`includeEdit: true` adds `edit_file { path, find, replace, replaceAll? }`. It replaces one exact occurrence of `find`, or every occurrence with `replaceAll`, and refuses a `find` that does not occur or, without `replaceAll`, occurs more than once. The replacement text is literal. It asks for `write` permission before it reads the file, so an edit made while the request waits is kept. It is off by default, so the tools an existing agent sees do not change.
+
+```typescript
+const tools = createFilesystemTools(context, { includeEdit: true });
+```
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).

package/ts_tools/tool.filesystem.ts

@@ -7,6 +7,8 @@ import {
 export interface ICreateFilesystemToolsOptions {
   /** Include delete_file. Default: true. */
   includeDelete?: boolean;
+  /** Include edit_file, which replaces an exact snippet of a file. Default: false. */
+  includeEdit?: boolean;
   /** Maximum output lines before truncating. */
   maxLines?: number;
   /** Maximum output bytes before truncating. */
@@ -110,6 +112,59 @@ export function createFilesystemTools(context: IToolExecutionContext, options: I
     }),
   };
 
+  if (options.includeEdit === true) {
+    tools.edit_file = plugins.tool({
+      description:
+        'Replace an exact snippet of a UTF-8 file in the active workspace. `find` must occur exactly once unless `replaceAll` is set; include enough surrounding text to make it unique. Requires host permission when configured.',
+      inputSchema: plugins.z.object({
+        path: plugins.z.string().describe('File path'),
+        find: plugins.z.string().min(1).describe('Exact text to replace, copied from the current file'),
+        replace: plugins.z.string().describe('The text to put in its place'),
+        replaceAll: plugins.z
+          .boolean()
+          .optional()
+          .describe('Replace every occurrence instead of exactly one. Default: false'),
+      }),
+      execute: async (
+        {
+          path: filePath,
+          find,
+          replace,
+          replaceAll,
+        }: { path: string; find: string; replace: string; replaceAll?: boolean },
+        invocationOptions?: plugins.ToolExecutionOptions<unknown>,
+      ) => {
+        if (!context.fs) {
+          throw new Error('Filesystem tools are not available in this execution context.');
+        }
+        const abortSignal = invocationOptions?.abortSignal ?? context.abortSignal;
+        const invocation = { toolCallId: invocationOptions?.toolCallId, abortSignal };
+        // asked before the file is read: an edit made while the request waits is kept, not overwritten
+        await context.requestPermission?.({
+          type: 'write',
+          title: 'Edit file',
+          metadata: { path: filePath },
+          toolCallId: invocationOptions?.toolCallId,
+          abortSignal,
+        });
+        const content = await context.fs.readFile(filePath, undefined, invocation);
+        const occurrences = content.split(find).length - 1;
+        if (occurrences === 0) {
+          throw new Error(`The text to replace does not occur in ${filePath}.`);
+        }
+        if (occurrences > 1 && replaceAll !== true) {
+          throw new Error(
+            `The text to replace occurs ${occurrences} times in ${filePath}; include more surrounding text or set replaceAll.`,
+          );
+        }
+        const updated = replaceAll === true ? content.split(find).join(replace) : content.replace(find, () => replace);
+        await context.fs.writeFile(filePath, updated, invocation);
+        const replaced = replaceAll === true ? occurrences : 1;
+        return truncate(`Replaced ${replaced} occurrence${replaced === 1 ? '' : 's'} in ${filePath}`);
+      },
+    });
+  }
+
   if (options.includeDelete !== false) {
     tools.delete_file = plugins.tool({
       description: 'Delete a file or empty directory in the active workspace. Requires host permission when configured.',

package/ts_tools_node/classes.workspacereversion.ts

@@ -0,0 +1,255 @@
+import * as plugins from './plugins.js';
+import type { IToolFileChange, IToolFileChangeObserver } from './tool.context.js';
+import {
+  fileImageBytes,
+  fileImagesEqual,
+  missingAncestors,
+  readFileImage,
+  removeEmptyDirectories,
+  writeFileImage,
+  type TFileImage,
+} from './functions.fileimages.js';
+
+export interface IInMemoryWorkspaceReversionOptions {
+  /** The workspace a revertible turn names in the session's reversion info. */
+  workspace: plugins.IFlexAffectedWorkspace;
+  /**
+   * The bytes of file images one turn may hold. A turn that changes more is recorded as
+   * nonrevertible (`capture-too-large`) and its images are dropped. Default: 64 MiB.
+   */
+  maxCaptureBytes?: number;
+}
+
+/** One file a turn changed: what it held before the turn's first change and after the turn. */
+interface IFileRecord {
+  before: TFileImage;
+  after?: TFileImage;
+  /** directories the turn's first write created, deepest first */
+  createdDirectories: string[];
+}
+
+interface ICapture {
+  captureId: string;
+  runId: string;
+  state: 'prepared' | 'finalized';
+  files: Map<string, IFileRecord>;
+  bytes: number;
+  nonrevertibleReason?: string;
+  outcome?: plugins.TFlexTurnReversionFinalizedOutcome;
+  appliedOperations: Set<string>;
+  /** apply operations that failed after a partial change could not be rolled back */
+  uncertainOperations: Set<string>;
+}
+
+interface ICaptureReference {
+  captureId: string;
+}
+
+const DEFAULT_MAX_CAPTURE_BYTES = 64 * 1024 * 1024;
+
+const isCaptureReference = (valueArg: plugins.TJsonValue): valueArg is plugins.TJsonValue & ICaptureReference =>
+  !!valueArg
+  && typeof valueArg === 'object'
+  && !Array.isArray(valueArg)
+  && typeof valueArg.captureId === 'string';
+
+/**
+ * Turn reversion for the local filesystem tools, held in memory: FlexHarness `/undo` and `/redo`
+ * move a turn's file changes together with its transcript.
+ *
+ * Give each run's `createLocalToolExecutionContext` the observer `observerFor(context.runId)`. The
+ * first change of a file in a turn records what the file held before; `finalize` records what it
+ * holds after. Undo puts the before images back and redo the after images, each only while every
+ * file still holds what the other direction left, so a later edit of the user is never overwritten.
+ * A turn that ran a shell command is nonrevertible, since the command may have changed files no
+ * observer saw.
+ *
+ * Captures live as long as the process. A capture FlexHarness asks about after a restart is
+ * `missing`, and undoing past it fails without changing anything. Only root-session runs are
+ * captured; a change of a run without a prepared capture is refused.
+ */
+export class InMemoryWorkspaceReversion<TScope = unknown> implements plugins.IFlexTurnReversionProviderV2<TScope> {
+  public readonly protocolVersion = 2;
+
+  private readonly workspace: plugins.IFlexAffectedWorkspace;
+  private readonly maxCaptureBytes: number;
+  private readonly captures = new Map<string, ICapture>();
+  private readonly captureIdsByRun = new Map<string, string>();
+
+  constructor(optionsArg: IInMemoryWorkspaceReversionOptions) {
+    this.workspace = { id: optionsArg.workspace.id, label: optionsArg.workspace.label };
+    this.maxCaptureBytes = optionsArg.maxCaptureBytes ?? DEFAULT_MAX_CAPTURE_BYTES;
+    if (!Number.isSafeInteger(this.maxCaptureBytes) || this.maxCaptureBytes <= 0) {
+      throw new Error('maxCaptureBytes must be a positive integer.');
+    }
+  }
+
+  /** The observer of one run's file changes and shell commands. */
+  public observerFor(runIdArg: string): IToolFileChangeObserver {
+    return {
+      beforeFileChange: (changeArg) => this.recordChange(runIdArg, changeArg),
+      beforeShellCommand: () => {
+        this.markNonrevertible(this.requirePreparedCapture(runIdArg), 'shell-command');
+      },
+    };
+  }
+
+  public prepare(contextArg: plugins.IFlexTurnReversionBaseContext<TScope>): void {
+    contextArg.signal.throwIfAborted();
+    if (this.captures.has(contextArg.captureId)) return;
+    this.captures.set(contextArg.captureId, {
+      captureId: contextArg.captureId,
+      runId: contextArg.runId,
+      state: 'prepared',
+      files: new Map(),
+      bytes: 0,
+      appliedOperations: new Set(),
+      uncertainOperations: new Set(),
+    });
+    this.captureIdsByRun.set(contextArg.runId, contextArg.captureId);
+  }
+
+  public inspectCapture(
+    contextArg: plugins.IFlexTurnReversionBaseContext<TScope>,
+  ): plugins.TFlexTurnReversionCaptureInspectionV2 {
+    const capture = this.captures.get(contextArg.captureId);
+    if (!capture) return { status: 'missing' };
+    return capture.outcome ? { status: 'finalized', outcome: capture.outcome } : { status: 'prepared' };
+  }
+
+  public async finalize(
+    contextArg: plugins.IFlexTurnReversionBaseContext<TScope>,
+  ): Promise<plugins.TFlexTurnReversionFinalizedOutcome> {
+    contextArg.signal.throwIfAborted();
+    const capture = this.requireCapture(contextArg.captureId);
+    if (capture.outcome) return capture.outcome;
+    const reference: ICaptureReference = { captureId: capture.captureId };
+    if (!capture.nonrevertibleReason) {
+      for (const [filePath, record] of capture.files) {
+        record.after = await readFileImage(filePath);
+        if (fileImagesEqual(record.before, record.after)) capture.files.delete(filePath);
+      }
+    }
+    capture.state = 'finalized';
+    if (capture.nonrevertibleReason) {
+      capture.outcome = {
+        disposition: 'nonrevertible',
+        reference: { ...reference },
+        reasonCode: capture.nonrevertibleReason,
+        affectedWorkspaces: [this.workspace],
+      };
+    } else if (capture.files.size === 0) {
+      capture.outcome = { disposition: 'no-change', reference: { ...reference } };
+    } else {
+      capture.outcome = { disposition: 'revertible', reference: { ...reference }, affectedWorkspaces: [this.workspace] };
+    }
+    this.captureIdsByRun.delete(capture.runId);
+    return capture.outcome;
+  }
+
+  public async apply(contextArg: plugins.IFlexTurnReversionApplyContext<TScope>): Promise<void> {
+    contextArg.signal.throwIfAborted();
+    const capture = this.captureOf(contextArg.reference);
+    if (capture.outcome?.disposition !== 'revertible') {
+      throw new Error('This turn has no revertible workspace changes.');
+    }
+    const records = [...capture.files.entries()];
+    const expected = (recordArg: IFileRecord) => (contextArg.direction === 'undo' ? recordArg.after! : recordArg.before);
+    const target = (recordArg: IFileRecord) => (contextArg.direction === 'undo' ? recordArg.before : recordArg.after!);
+    for (const [filePath, record] of records) {
+      if (!fileImagesEqual(await readFileImage(filePath), expected(record))) {
+        throw new Error(`"${filePath}" changed after the turn; its changes were not ${contextArg.direction === 'undo' ? 'undone' : 'redone'}.`);
+      }
+    }
+    const written: Array<[string, IFileRecord]> = [];
+    try {
+      for (const entry of records) {
+        await writeFileImage(entry[0], target(entry[1]));
+        written.push(entry);
+      }
+    } catch (error) {
+      await this.rollBack(written, expected, contextArg.operationId, capture);
+      throw error;
+    }
+    if (contextArg.direction === 'undo') {
+      for (const [, record] of records) await removeEmptyDirectories(record.createdDirectories);
+    }
+    capture.appliedOperations.add(contextArg.operationId);
+  }
+
+  public inspectApply(
+    contextArg: plugins.IFlexTurnReversionApplyContext<TScope>,
+  ): plugins.IFlexTurnReversionApplyInspection {
+    const capture = this.captures.get(isCaptureReference(contextArg.reference) ? contextArg.reference.captureId : '');
+    if (!capture) return { status: 'not-applied' };
+    if (capture.appliedOperations.has(contextArg.operationId)) return { status: 'applied' };
+    if (capture.uncertainOperations.has(contextArg.operationId)) return { status: 'unknown' };
+    return { status: 'not-applied' };
+  }
+
+  public release(contextArg: plugins.IFlexTurnReversionReleaseContext<TScope>): void {
+    const captureId = isCaptureReference(contextArg.reference) ? contextArg.reference.captureId : contextArg.captureId;
+    const capture = this.captures.get(captureId);
+    if (!capture) return;
+    this.captures.delete(captureId);
+    if (this.captureIdsByRun.get(capture.runId) === captureId) this.captureIdsByRun.delete(capture.runId);
+  }
+
+  private async recordChange(runIdArg: string, changeArg: IToolFileChange): Promise<void> {
+    const capture = this.requirePreparedCapture(runIdArg);
+    if (capture.nonrevertibleReason || capture.files.has(changeArg.path)) return;
+    const before = await readFileImage(changeArg.path);
+    const createdDirectories = before.kind === 'absent' && changeArg.kind === 'write'
+      ? await missingAncestors(changeArg.path)
+      : [];
+    if (capture.files.has(changeArg.path)) return;
+    capture.bytes += fileImageBytes(before);
+    if (capture.bytes > this.maxCaptureBytes) {
+      this.markNonrevertible(capture, 'capture-too-large');
+      return;
+    }
+    capture.files.set(changeArg.path, { before, createdDirectories });
+  }
+
+  private markNonrevertible(captureArg: ICapture, reasonArg: string): void {
+    captureArg.nonrevertibleReason ??= reasonArg;
+    captureArg.files.clear();
+    captureArg.bytes = 0;
+  }
+
+  private async rollBack(
+    writtenArg: Array<[string, IFileRecord]>,
+    expectedArg: (recordArg: IFileRecord) => TFileImage,
+    operationIdArg: string,
+    captureArg: ICapture,
+  ): Promise<void> {
+    try {
+      for (const [filePath, record] of writtenArg.reverse()) await writeFileImage(filePath, expectedArg(record));
+    } catch {
+      // the workspace holds part of the change; FlexHarness learns that the outcome is unknown
+      captureArg.uncertainOperations.add(operationIdArg);
+    }
+  }
+
+  private requirePreparedCapture(runIdArg: string): ICapture {
+    const captureId = this.captureIdsByRun.get(runIdArg);
+    const capture = captureId ? this.captures.get(captureId) : undefined;
+    if (!capture || capture.state !== 'prepared') {
+      throw new Error(`No workspace capture is open for run "${runIdArg}"; the change was refused.`);
+    }
+    return capture;
+  }
+
+  private requireCapture(captureIdArg: string): ICapture {
+    const capture = this.captures.get(captureIdArg);
+    if (!capture) throw new Error(`The workspace capture "${captureIdArg}" is not held.`);
+    return capture;
+  }
+
+  private captureOf(referenceArg: plugins.TJsonValue): ICapture {
+    if (!isCaptureReference(referenceArg)) throw new Error('The workspace capture reference is malformed.');
+    const capture = this.captures.get(referenceArg.captureId);
+    if (!capture) throw new Error('The workspace changes of this turn are no longer held in memory.');
+    return capture;
+  }
+}

package/ts_tools_node/functions.fileimages.ts

@@ -0,0 +1,89 @@
+import * as plugins from './plugins.js';
+
+/** What one path holds at a moment: nothing, a regular file, or a symbolic link. */
+export type TFileImage =
+  | { kind: 'absent' }
+  | { kind: 'file'; bytes: Buffer; mode: number }
+  | { kind: 'symlink'; target: string };
+
+const isMissing = (error: unknown): boolean => {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+};
+
+/** Reads what the path holds, without following a final symbolic link. */
+export const readFileImage = async (pathArg: string): Promise<TFileImage> => {
+  let stats: plugins.fs.Stats;
+  try {
+    stats = await plugins.fs.promises.lstat(pathArg);
+  } catch (error) {
+    if (isMissing(error)) return { kind: 'absent' };
+    throw error;
+  }
+  if (stats.isSymbolicLink()) return { kind: 'symlink', target: await plugins.fs.promises.readlink(pathArg) };
+  if (stats.isFile()) return { kind: 'file', bytes: await plugins.fs.promises.readFile(pathArg), mode: stats.mode & 0o7777 };
+  throw new Error(`"${pathArg}" is neither a file nor a symbolic link.`);
+};
+
+/** The bytes an image keeps in memory. */
+export const fileImageBytes = (imageArg: TFileImage): number =>
+  imageArg.kind === 'file'
+    ? imageArg.bytes.byteLength
+    : imageArg.kind === 'symlink'
+      ? Buffer.byteLength(imageArg.target)
+      : 0;
+
+export const fileImagesEqual = (leftArg: TFileImage, rightArg: TFileImage): boolean => {
+  if (leftArg.kind === 'absent' || rightArg.kind === 'absent') return leftArg.kind === rightArg.kind;
+  if (leftArg.kind === 'symlink' || rightArg.kind === 'symlink') {
+    return leftArg.kind === 'symlink' && rightArg.kind === 'symlink' && leftArg.target === rightArg.target;
+  }
+  return leftArg.bytes.equals(rightArg.bytes);
+};
+
+/** Puts the image at the path, creating parent directories as needed. */
+export const writeFileImage = async (pathArg: string, imageArg: TFileImage): Promise<void> => {
+  if (imageArg.kind === 'absent') {
+    await plugins.fs.promises.rm(pathArg, { force: true });
+    return;
+  }
+  await plugins.fs.promises.mkdir(plugins.path.dirname(pathArg), { recursive: true });
+  if (imageArg.kind === 'symlink') {
+    await plugins.fs.promises.rm(pathArg, { force: true });
+    await plugins.fs.promises.symlink(imageArg.target, pathArg);
+    return;
+  }
+  if ((await readFileImage(pathArg)).kind === 'symlink') await plugins.fs.promises.rm(pathArg);
+  await plugins.fs.promises.writeFile(pathArg, imageArg.bytes);
+  await plugins.fs.promises.chmod(pathArg, imageArg.mode);
+};
+
+/** The ancestors of the path that do not exist yet, deepest first: a write would create them. */
+export const missingAncestors = async (pathArg: string): Promise<string[]> => {
+  const missing: string[] = [];
+  let current = plugins.path.dirname(pathArg);
+  while (current !== plugins.path.dirname(current)) {
+    try {
+      await plugins.fs.promises.lstat(current);
+      break;
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+      missing.push(current);
+      current = plugins.path.dirname(current);
+    }
+  }
+  return missing;
+};
+
+/** Removes the directories, deepest first, as far as they are empty. */
+export const removeEmptyDirectories = async (directoriesArg: readonly string[]): Promise<void> => {
+  for (const directory of directoriesArg) {
+    try {
+      await plugins.fs.promises.rmdir(directory);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOTEMPTY' || code === 'EEXIST') return;
+      if (!isMissing(error)) throw error;
+    }
+  }
+};

package/ts_tools_node/index.ts

@@ -1,5 +1,11 @@
 export { createLocalToolExecutionContext } from './tool.context.js';
-export type { ILocalToolExecutionContextOptions } from './tool.context.js';
+export type {
+  ILocalToolExecutionContextOptions,
+  IToolFileChange,
+  IToolFileChangeObserver,
+} from './tool.context.js';
+export { InMemoryWorkspaceReversion } from './classes.workspacereversion.js';
+export type { IInMemoryWorkspaceReversionOptions } from './classes.workspacereversion.js';
 export { FileToolJobStore } from './tool.persistence.js';
 export type { IFileToolJobStoreOptions } from './tool.persistence.js';
 export * from './tools.local.js';