@modelprofile.com/flexharness 10.17.1 → 10.19.0

package/ts_tools_node/plugins.ts

@@ -41,3 +41,14 @@ export type {
   TToolJobEvent,
   TToolJobEventListener,
 } from '@modelprofile.com/flexharness-agent';
+export type {
+  IFlexAffectedWorkspace,
+  IFlexTurnReversionApplyContext,
+  IFlexTurnReversionApplyInspection,
+  IFlexTurnReversionBaseContext,
+  IFlexTurnReversionProviderV2,
+  IFlexTurnReversionReleaseContext,
+  TFlexTurnReversionCaptureInspectionV2,
+  TFlexTurnReversionFinalizedOutcome,
+  TJsonValue,
+} from '@modelprofile.com/flexharness';

package/ts_tools_node/readme.md

@@ -11,6 +11,33 @@ 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.
 
+## Turn reversion for local files
+
+`InMemoryWorkspaceReversion` is a FlexHarness `turnReversionProvider` that undoes and redoes a turn's changes of the local filesystem tools together with its transcript, held in memory for the process's lifetime.
+
+```typescript
+const reversion = new InMemoryWorkspaceReversion({ workspace: { id: rootDir, label: 'project' } });
+const harness = new FlexHarness({
+  scopeResolver,
+  modelResolver,
+  turnReversionProvider: reversion,
+  reversionPolicy: 'workspace-required',
+  toolProvider: {
+    provideTools: (context) => {
+      const execution = createLocalToolExecutionContext({
+        rootDir,
+        cwd: rootDir,
+        fileChangeObserver: reversion.observerFor(context.runId),
+        requestPermission: createFlexToolPermissionRequester(context, { policy: { write: 'allow' } }),
+      });
+      return { tools: { ...createFilesystemTools(execution, { includeEdit: true }), ...createShellTools(execution) } };
+    },
+  },
+});
+```
+
+The `fileChangeObserver` of `createLocalToolExecutionContext` sees every write and delete by its canonical path (a write follows a symbolic link to its target, a delete removes the link itself) after the root checks and before the change, and every shell command before it starts; a rejection refuses the operation. The first change of a file in a turn records its bytes, mode or link target, and the directories a new file's write creates. Undo puts the before images back and removes those directories while empty; redo puts the after images back. Either direction applies only while every file still holds what the other direction left, so a later edit is never overwritten: the undo fails without a change and can be retried. A turn that ran a shell command is nonrevertible (`shell-command`), as is one whose images exceed `maxCaptureBytes` (64 MiB by default; `capture-too-large`). Only root-session runs are captured: a change of a run without a capture is refused. Captures do not survive a restart; FlexHarness then finds them `missing`.
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).

package/ts_tools_node/tool.context.ts

@@ -1,6 +1,26 @@
 import * as plugins from './plugins.js';
 import type { IToolJobStore, IToolPermissionRequest, IToolInvocationOptions, IToolRunOptions, IToolShellResult, IShellCommand, IToolShellContext, IToolJobRequest, IShellStartedResult, IShellFinishedResult, IToolJobState, IToolJobHandle, IToolJobEvent, IToolJobOutputEvent, TToolJobEvent, TToolJobEventListener, IToolJobContext, IToolFilesystemReadOptions, IToolFilesystemListOptions, IToolFilesystemContext, IToolBrowserRunOptions, TBrowserToolAction, IBrowserToolInput, IToolBrowserContext, IToolExecutionContext } from './plugins.js';
 
+/** A file a tool is about to change, named by its canonical path. */
+export interface IToolFileChange {
+  kind: 'write' | 'delete';
+  /**
+   * The canonical absolute path the operation changes. A write follows a symlink to its target; a
+   * delete removes the link itself, so its path is the link's.
+   */
+  path: string;
+}
+
+/**
+ * Sees every change the local filesystem tools make, after the path checks and before the change,
+ * and every shell command before it starts. A rejection refuses the operation.
+ */
+export interface IToolFileChangeObserver {
+  beforeFileChange(change: IToolFileChange): Promise<void> | void;
+  /** A shell command or background job may change files the observer does not see. */
+  beforeShellCommand(): Promise<void> | void;
+}
+
 export interface ILocalToolExecutionContextOptions {
   cwd?: string;
   rootDir?: string;
@@ -9,6 +29,8 @@ export interface ILocalToolExecutionContextOptions {
   abortSignal?: AbortSignal;
   /** Guards each local filesystem operation or shell side effect. */
   beforeOperation?: () => Promise<void> | void;
+  /** Observes every file change and shell command, for example to capture a turn for undo. */
+  fileChangeObserver?: IToolFileChangeObserver;
   /** Hard combined stdout/stderr capture limit for each local shell command. Default: 1 MiB. */
   maxShellOutputBytes?: number;
   /** Number of terminal background job snapshots retained for get/list. Default: 100. */
@@ -58,6 +80,13 @@ export const createLocalToolExecutionContext = (options: ILocalToolExecutionCont
   if (!Number.isSafeInteger(jobStoreOperationTimeoutMs) || jobStoreOperationTimeoutMs <= 0) {
     throw new Error('jobStoreOperationTimeoutMs must be a positive integer.');
   }
+  const fileChangeObserver = options.fileChangeObserver;
+  const beforeShellOperation: ILocalToolExecutionContextOptions['beforeOperation'] = fileChangeObserver
+    ? async () => {
+        await options.beforeOperation?.();
+        await fileChangeObserver.beforeShellCommand();
+      }
+    : options.beforeOperation;
   const jobs = createLocalToolJobContext({
     cwd,
     rootDir,
@@ -67,7 +96,7 @@ export const createLocalToolExecutionContext = (options: ILocalToolExecutionCont
     outputListenerTimeoutMs,
     jobStoreOperationTimeoutMs,
     settleOrphanedJob: options.settleOrphanedJob,
-    beforeOperation: options.beforeOperation,
+    beforeOperation: beforeShellOperation,
     abortSignal: options.abortSignal,
   });
   return {
@@ -84,7 +113,7 @@ export const createLocalToolExecutionContext = (options: ILocalToolExecutionCont
         onOutput: runOptions?.onOutput,
         outputListenerTimeoutMs,
         maxOutputBytes: maxShellOutputBytes,
-        beforeOperation: options.beforeOperation,
+        beforeOperation: beforeShellOperation,
       }),
       runStructured: (command, runOptions) => runLocalStructuredCommand(command, {
         cwd: resolveLocalPath(runOptions?.cwd ?? cwd, rootDir),
@@ -93,7 +122,7 @@ export const createLocalToolExecutionContext = (options: ILocalToolExecutionCont
         onOutput: runOptions?.onOutput,
         outputListenerTimeoutMs,
         maxOutputBytes: maxShellOutputBytes,
-        beforeOperation: options.beforeOperation,
+        beforeOperation: beforeShellOperation,
       }),
     },
     jobs,
@@ -147,6 +176,13 @@ export const createLocalToolExecutionContext = (options: ILocalToolExecutionCont
             canonicalBoundary.rootDir,
           );
         }
+        if (fileChangeObserver) {
+          await fileChangeObserver.beforeFileChange({
+            kind: 'write',
+            path: await resolveCanonicalProspectivePath(resolved),
+          });
+          throwIfAborted(abortSignal);
+        }
         await runBeforeLocalOperation(options.beforeOperation, abortSignal);
         await plugins.fs.promises.mkdir(parentPath, { recursive: true });
         throwIfAborted(abortSignal);
@@ -193,6 +229,16 @@ export const createLocalToolExecutionContext = (options: ILocalToolExecutionCont
         if (rootDir) {
           await resolveCanonicalExistingLocalPath(resolved, targetPath, rootDir);
         }
+        if (fileChangeObserver) {
+          await fileChangeObserver.beforeFileChange({
+            kind: 'delete',
+            path: plugins.path.join(
+              await resolveCanonicalProspectivePath(plugins.path.dirname(resolved)),
+              plugins.path.basename(resolved),
+            ),
+          });
+          throwIfAborted(abortSignal);
+        }
         await runBeforeLocalOperation(options.beforeOperation, abortSignal);
         await plugins.fs.promises.rm(resolved, { recursive: false, force: false });
         throwIfAborted(abortSignal);