newmark-agent 0.6.4 → 0.6.8

package/dist/tools/computerUsePowerShellHost.js

@@ -35,48 +35,90 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runPersistentPowerShell = runPersistentPowerShell;
 exports.computerUsePowerShellLaneReady = computerUsePowerShellLaneReady;
+exports.prepareComputerUsePowerShellLane = prepareComputerUsePowerShellLane;
+exports.stopComputerUsePowerShellLane = stopComputerUsePowerShellLane;
 exports.stopComputerUsePowerShellHost = stopComputerUsePowerShellHost;
 const child_process_1 = require("child_process");
 const crypto = __importStar(require("crypto"));
 const readline = __importStar(require("readline"));
-const HOST_SCRIPT = [
-    '[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)',
-    '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)',
-    '$OutputEncoding = [System.Text.UTF8Encoding]::new($false)',
-    'Add-Type -AssemblyName System.Windows.Forms',
-    'Add-Type -AssemblyName System.Drawing',
-    'Add-Type -AssemblyName UIAutomationClient',
-    'Add-Type -AssemblyName UIAutomationTypes',
-    `if (-not ("NewmarkComputerUseNative" -as [type])) { Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class NewmarkComputerUseNative { [DllImport("user32.dll")] public static extern bool SetCursorPos(int X, int Y); [DllImport("user32.dll")] public static extern void mouse_event(uint dwFlags, int dx, int dy, int dwData, UIntPtr dwExtraInfo); [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd); [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow); [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow(); }' }`,
-    'while (($line = [Console]::In.ReadLine()) -ne $null) {',
-    '  $id = ""',
-    '  $timer = [System.Diagnostics.Stopwatch]::StartNew()',
-    '  try {',
-    '    $request = $line | ConvertFrom-Json',
-    '    $id = [string]$request.id',
-    '    $source = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String([string]$request.script))',
-    '    $previousPreference = $ErrorActionPreference',
-    '    $ErrorActionPreference = "Stop"',
-    '    try { $output = (& ([scriptblock]::Create($source)) 2>&1 | Out-String -Width 1048576).Trim() } finally { $ErrorActionPreference = $previousPreference }',
-    '    $response = @{ id=$id; ok=$true; output=$output; elapsed_ms=[int]$timer.ElapsedMilliseconds }',
-    '  } catch {',
-    '    $response = @{ id=$id; ok=$false; output=[string]$_; elapsed_ms=[int]$timer.ElapsedMilliseconds }',
-    '  }',
-    '  [Console]::Out.WriteLine(($response | ConvertTo-Json -Compress -Depth 6))',
-    '  [Console]::Out.Flush()',
-    '}',
-].join('; ');
+function createHostScript(includeUiAutomation) {
+    return [
+        '[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)',
+        '[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)',
+        '$OutputEncoding = [System.Text.UTF8Encoding]::new($false)',
+        'Add-Type -AssemblyName System.Windows.Forms',
+        'Add-Type -AssemblyName System.Drawing',
+        ...(includeUiAutomation ? ['Add-Type -AssemblyName UIAutomationClient', 'Add-Type -AssemblyName UIAutomationTypes'] : []),
+        ...(includeUiAutomation ? [`if (-not ("NewmarkComputerUseNative" -as [type])) { Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class NewmarkComputerUseNative { [DllImport("user32.dll")] public static extern bool SetCursorPos(int X, int Y); [DllImport("user32.dll")] public static extern void mouse_event(uint dwFlags, int dx, int dy, int dwData, UIntPtr dwExtraInfo); [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd); [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow); [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow(); }' }`] : []),
+        ...(!includeUiAutomation ? [`if (-not ("NewmarkSparseCapture" -as [type])) { Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class NewmarkSparseCapture { [StructLayout(LayoutKind.Sequential)] struct BitmapInfoHeader { public uint Size; public int Width; public int Height; public ushort Planes; public ushort BitCount; public uint Compression; public uint SizeImage; public int XPelsPerMeter; public int YPelsPerMeter; public uint ColorsUsed; public uint ColorsImportant; } [StructLayout(LayoutKind.Sequential)] struct BitmapInfo { public BitmapInfoHeader Header; public uint Colors; } [DllImport("user32.dll")] static extern IntPtr GetDC(IntPtr hWnd); [DllImport("user32.dll")] static extern int ReleaseDC(IntPtr hWnd, IntPtr hdc); [DllImport("gdi32.dll")] static extern IntPtr CreateCompatibleDC(IntPtr hdc); [DllImport("gdi32.dll")] static extern bool DeleteDC(IntPtr hdc); [DllImport("gdi32.dll")] static extern IntPtr CreateDIBSection(IntPtr hdc, ref BitmapInfo info, uint usage, out IntPtr bits, IntPtr section, uint offset); [DllImport("gdi32.dll")] static extern IntPtr SelectObject(IntPtr hdc, IntPtr obj); [DllImport("gdi32.dll")] static extern bool DeleteObject(IntPtr obj); [DllImport("gdi32.dll")] static extern int SetStretchBltMode(IntPtr hdc, int mode); [DllImport("gdi32.dll")] static extern bool SetBrushOrgEx(IntPtr hdc, int x, int y, IntPtr oldOrigin); [DllImport("gdi32.dll", SetLastError=true)] static extern bool StretchBlt(IntPtr dst, int dx, int dy, int dw, int dh, IntPtr src, int sx, int sy, int sw, int sh, int operation); [DllImport("gdi32.dll")] static extern bool GdiFlush(); public sealed class Capture : IDisposable { private int width; private byte[] pixels; internal Capture(int w, byte[] p) { width=w; pixels=p; } public byte GetLuma(int x, int y) { int offset=(y*width+x)*4; return (byte)Math.Round((pixels[offset+2]*0.299)+(pixels[offset+1]*0.587)+(pixels[offset]*0.114)); } public void Dispose() { pixels=null; } } public static Capture CaptureScaled(int x, int y, int width, int height, int targetWidth, int targetHeight) { IntPtr screen=GetDC(IntPtr.Zero); if (screen == IntPtr.Zero) throw new InvalidOperationException("Could not read desktop DC."); IntPtr memory=IntPtr.Zero; IntPtr bitmap=IntPtr.Zero; IntPtr previous=IntPtr.Zero; IntPtr bits=IntPtr.Zero; try { memory=CreateCompatibleDC(screen); BitmapInfo info=new BitmapInfo(); info.Header.Size=(uint)System.Runtime.InteropServices.Marshal.SizeOf(typeof(BitmapInfoHeader)); info.Header.Width=targetWidth; info.Header.Height=-targetHeight; info.Header.Planes=1; info.Header.BitCount=32; info.Header.Compression=0; info.Header.SizeImage=(uint)(targetWidth*targetHeight*4); bitmap=CreateDIBSection(screen,ref info,0,out bits,IntPtr.Zero,0); if (memory == IntPtr.Zero || bitmap == IntPtr.Zero || bits == IntPtr.Zero) throw new InvalidOperationException("Could not allocate sparse DIB section."); previous=SelectObject(memory,bitmap); if (previous == IntPtr.Zero) throw new InvalidOperationException("Could not select sparse DIB section."); if (SetStretchBltMode(memory,4)==0 || !SetBrushOrgEx(memory,0,0,IntPtr.Zero)) throw new InvalidOperationException("Could not configure sparse capture scaling."); if (!StretchBlt(memory,0,0,targetWidth,targetHeight,screen,x,y,width,height,0x00CC0020)) throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error()); if (!GdiFlush()) throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error()); byte[] pixels=new byte[targetWidth*targetHeight*4]; Marshal.Copy(bits,pixels,0,pixels.Length); return new Capture(targetWidth,pixels); } finally { if (memory != IntPtr.Zero && previous != IntPtr.Zero) SelectObject(memory,previous); if (bitmap != IntPtr.Zero) DeleteObject(bitmap); if (memory != IntPtr.Zero) DeleteDC(memory); ReleaseDC(IntPtr.Zero,screen); } } }' }`] : []),
+        '$hostReady = @{ id="__newmark_ready__"; ready=$true }; [Console]::Out.WriteLine(($hostReady | ConvertTo-Json -Compress)); [Console]::Out.Flush()',
+        'while (($line = [Console]::In.ReadLine()) -ne $null) {',
+        '  $id = ""',
+        '  $timer = [System.Diagnostics.Stopwatch]::StartNew()',
+        '  try {',
+        '    $request = $line | ConvertFrom-Json',
+        '    $id = [string]$request.id',
+        '    $source = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String([string]$request.script))',
+        '    $previousPreference = $ErrorActionPreference',
+        '    $ErrorActionPreference = "Stop"',
+        '    try { $output = (& ([scriptblock]::Create($source)) 2>&1 | Out-String -Width 1048576).Trim() } finally { $ErrorActionPreference = $previousPreference }',
+        '    $response = @{ id=$id; ok=$true; output=$output; elapsed_ms=[int]$timer.ElapsedMilliseconds }',
+        '  } catch {',
+        '    $response = @{ id=$id; ok=$false; output=[string]$_; elapsed_ms=[int]$timer.ElapsedMilliseconds }',
+        '  }',
+        '  [Console]::Out.WriteLine(($response | ConvertTo-Json -Compress -Depth 6))',
+        '  [Console]::Out.Flush()',
+        '}',
+    ].join('; ');
+}
+const HOST_SCRIPT = createHostScript(true);
+const SPARSE_HOST_SCRIPT = createHostScript(false);
 class PowerShellWorker {
     lane;
     child = null;
+    readyChild = null;
     pending = new Map();
+    readinessWaiters = new Set();
     restarting = false;
     unavailableUntil = 0;
     constructor(lane) {
         this.lane = lane;
     }
     ready() {
-        return Date.now() >= this.unavailableUntil && !!this.child && !this.child.killed && this.child.exitCode === null;
+        return Date.now() >= this.unavailableUntil
+            && !!this.child
+            && !this.child.killed
+            && this.child.exitCode === null
+            && this.readyChild === this.child;
+    }
+    async prepare(timeoutMs) {
+        const startedAt = Date.now();
+        if (Date.now() < this.unavailableUntil)
+            return { ready: false, elapsedMs: 0 };
+        const child = this.ensureChild();
+        if (this.readyChild === child)
+            return { ready: true, elapsedMs: Date.now() - startedAt };
+        const ready = await new Promise(resolve => {
+            let settled = false;
+            let waiter;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(waiter.timer);
+                this.readinessWaiters.delete(waiter);
+                resolve(value);
+            };
+            waiter = {
+                child,
+                resolve: finish,
+                timer: setTimeout(() => finish(false), Math.max(0, Math.floor(timeoutMs))),
+            };
+            this.readinessWaiters.add(waiter);
+            if (this.readyChild === child)
+                finish(true);
+        });
+        return { ready, elapsedMs: Date.now() - startedAt };
     }
     async run(script, timeoutMs) {
         const startedAt = Date.now();
@@ -114,6 +156,9 @@ class PowerShellWorker {
     stop() {
         const child = this.child;
         this.child = null;
+        this.readyChild = null;
+        if (child)
+            this.resolveReadiness(child, false);
         if (child && !child.killed)
             child.kill();
         this.rejectPending(`Computer Use ${this.lane} helper stopped.`);
@@ -154,14 +199,14 @@ class PowerShellWorker {
             '-ExecutionPolicy',
             'Bypass',
             '-Command',
-            HOST_SCRIPT,
+            this.lane === 'sparse' ? SPARSE_HOST_SCRIPT : HOST_SCRIPT,
         ], {
             windowsHide: true,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         child.stdin.setDefaultEncoding('utf8');
         const lines = readline.createInterface({ input: child.stdout });
-        lines.on('line', line => this.handleLine(line));
+        lines.on('line', line => this.handleLine(line, child));
         let stderr = '';
         child.stderr.on('data', chunk => {
             stderr = `${stderr}${String(chunk)}`.slice(-8192);
@@ -170,6 +215,8 @@ class PowerShellWorker {
             if (this.child !== child)
                 return;
             this.child = null;
+            this.readyChild = null;
+            this.resolveReadiness(child, false);
             this.rejectPending(error.message);
         });
         child.once('exit', (code, signal) => {
@@ -177,12 +224,14 @@ class PowerShellWorker {
             if (this.child !== child)
                 return;
             this.child = null;
+            this.readyChild = null;
+            this.resolveReadiness(child, false);
             this.rejectPending(`Computer Use ${this.lane} helper exited (${code ?? signal ?? 'unknown'}).${stderr ? ` ${stderr.trim()}` : ''}`);
         });
         this.child = child;
         return child;
     }
-    handleLine(line) {
+    handleLine(line, child) {
         let parsed;
         try {
             parsed = JSON.parse(line);
@@ -190,6 +239,13 @@ class PowerShellWorker {
         catch {
             return;
         }
+        if (String(parsed.id || '') === '__newmark_ready__' && parsed.ready === true) {
+            if (this.child === child) {
+                this.readyChild = child;
+                this.resolveReadiness(child, true);
+            }
+            return;
+        }
         const id = String(parsed.id || '');
         const pending = this.pending.get(id);
         if (!pending)
@@ -209,6 +265,12 @@ class PowerShellWorker {
         }
         this.pending.clear();
     }
+    resolveReadiness(child, ready) {
+        for (const waiter of [...this.readinessWaiters]) {
+            if (waiter.child === child)
+                waiter.resolve(ready);
+        }
+    }
 }
 const workers = {
     action: new PowerShellWorker('action'),
@@ -216,6 +278,7 @@ const workers = {
     windows: new PowerShellWorker('windows'),
     uia_advisory: new PowerShellWorker('uia_advisory'),
     windows_advisory: new PowerShellWorker('windows_advisory'),
+    sparse: new PowerShellWorker('sparse'),
 };
 let cleanupRegistered = false;
 function registerCleanup() {
@@ -228,6 +291,7 @@ function registerCleanup() {
         workers.windows.stop();
         workers.uia_advisory.stop();
         workers.windows_advisory.stop();
+        workers.sparse.stop();
     };
     process.once('exit', stop);
 }
@@ -241,11 +305,21 @@ async function runPersistentPowerShell(script, timeoutMs = 30000, lane = 'action
 function computerUsePowerShellLaneReady(lane) {
     return process.platform === 'win32' && workers[lane].ready();
 }
+async function prepareComputerUsePowerShellLane(lane, timeoutMs) {
+    if (process.platform !== 'win32')
+        return { ready: false, elapsedMs: 0 };
+    registerCleanup();
+    return await workers[lane].prepare(timeoutMs);
+}
+function stopComputerUsePowerShellLane(lane) {
+    workers[lane].stop();
+}
 function stopComputerUsePowerShellHost() {
     workers.action.stop();
     workers.uia.stop();
     workers.windows.stop();
     workers.uia_advisory.stop();
     workers.windows_advisory.stop();
+    workers.sparse.stop();
 }
 //# sourceMappingURL=computerUsePowerShellHost.js.map

package/dist/tools/index.d.ts

@@ -16,6 +16,7 @@ export interface ToolExecutionContext {
     actorId?: string;
     workspaceId?: string;
     runtimeKey?: string;
+    runId?: string;
     backend?: string;
     invocation?: 'agent' | 'cli';
     signal?: AbortSignal;
@@ -42,6 +43,7 @@ export declare class ToolExecutor {
     private readonly localOcr;
     private readonly argumentValidators;
     private readonly searchMcpPool;
+    private readonly fileWriteObservationGate;
     private hostProfile;
     constructor(root: string, config: ConfigManager, ssh?: SshManager | undefined, workspace?: WorkspaceManager | undefined);
     webSearch(query: string, signal?: AbortSignal): Promise<string>;
@@ -72,16 +74,13 @@ export declare class ToolExecutor {
     private decorateBrowserUseReceipt;
     private sshWorkspace;
     private checkWorkspaceAccess;
+    private fileWriteObservationScope;
     private checkBashWorkspaceAccess;
     private extractCommandPathRefs;
     private looksLikePath;
     private isReadonlyShellCommand;
     private resolveBashTimeout;
     private bash;
-    private fread;
-    private fwrite;
-    private fedit;
-    private fdelete;
     private glob;
     private grep;
     private createProxyAgent;

package/dist/tools/index.js

@@ -64,6 +64,7 @@ const localOcr_1 = require("../core/localOcr");
 const visualTextFallback_1 = require("../core/visualTextFallback");
 const computerUseSession_1 = require("../core/computerUseSession");
 const searchMcpPool_1 = require("../core/searchMcpPool");
+const fileWriteObservation_1 = require("../core/fileWriteObservation");
 function normalizeComputerUseAction(action) {
     return String(action || '').trim().toLowerCase();
 }
@@ -279,6 +280,7 @@ class ToolExecutor {
     localOcr;
     argumentValidators = new toolArgumentValidator_1.ToolArgumentValidatorRegistry();
     searchMcpPool;
+    fileWriteObservationGate = new fileWriteObservation_1.FileWriteObservationGate();
     hostProfile = {
         kind: 'desktop',
         platform: process.platform,
@@ -351,15 +353,15 @@ class ToolExecutor {
         const tools = [
             t('bash', `${shellDescription} Optional timeout_ms lets the Agent choose this command timeout in milliseconds; 0 requests no limit, but a nonzero terminal.interrupt_timeout_ms setting is the upper cap.`, { command: { type: 'string' }, timeout_ms: { type: 'number', description: 'Per-command timeout in milliseconds. 0 means no requested limit unless capped by settings.' } }, ['command']),
             t('pwd', 'Print working directory (current folder path)', {}, []),
-            t('read', 'Read file contents. Use ABSOLUTE paths. The working directory is given in system prompt.', { path: { type: 'string' } }, ['path']),
-            t('write', 'Write/create a file. Use ABSOLUTE paths.', { path: { type: 'string' }, content: { type: 'string' } }, ['path', 'content']),
-            t('edit', 'Edit file with find-and-replace. Use ABSOLUTE paths.', { path: { type: 'string' }, old_str: { type: 'string' }, new_str: { type: 'string' } }, ['path', 'old_str', 'new_str']),
-            t('delete_file', 'Delete ONE file under Agent supervision. Use ABSOLUTE paths. This tool refuses directory deletion and wildcard paths; delete files one by one. Never use bash rm/del/Remove-Item for batch (recursive/wildcard/loop/pipe/multi-target) deletion — the runtime hard-blocks such commands.', { path: { type: 'string' } }, ['path']),
+            t('read', 'Read file contents. Use ABSOLUTE paths. A complete read or explicit line range records a short-lived, conversation/workspace/run-scoped observation for write/edit/delete_file. Read an exact target path before changing it. Large files can be read with start_line/end_line; overwrite/delete requires full line coverage, while edit requires the exact old_str lines.', { path: { type: 'string' }, start_line: { type: 'integer', minimum: 1, description: 'Optional inclusive first line for a bounded read. Provide together with end_line.' }, end_line: { type: 'integer', minimum: 1, description: 'Optional inclusive last line for a bounded read. Provide together with start_line.' } }, ['path']),
+            t('write', 'Write/create a file only after the exact target path has been read in this conversation, workspace, actor, and Build run. Existing files require a complete read; new files require an exact-path absence observation. Changed targets are refused until read again.', { path: { type: 'string' }, content: { type: 'string' } }, ['path', 'content']),
+            t('edit', 'Edit a file with find-and-replace only after reading the exact target lines in this conversation, workspace, actor, and Build run. The old_str must have appeared in a successful read range; stale or ambiguous matches are refused.', { path: { type: 'string' }, old_str: { type: 'string' }, new_str: { type: 'string' } }, ['path', 'old_str', 'new_str']),
+            t('delete_file', 'Delete ONE file only after reading its complete contents at the exact target path in this conversation, workspace, actor, and Build run. This tool refuses directory deletion and wildcard paths; delete files one by one. Never use bash rm/del/Remove-Item for batch (recursive/wildcard/loop/pipe/multi-target) deletion — the runtime hard-blocks such commands.', { path: { type: 'string' } }, ['path']),
             t('glob', 'Find files by glob pattern (e.g. **/*.ts, src/**/*.html)', { pattern: { type: 'string' } }, ['pattern']),
             t('grep', 'Search file content with regex', { pattern: { type: 'string' }, path: { type: 'string' } }, ['pattern', 'path']),
             t('web_search', 'Search the web', { query: { type: 'string' } }, ['query']),
             t('web_fetch', 'Fetch and extract URL content', { url: { type: 'string' } }, ['url']),
-            t('web_catch', 'Download a public web resource, save a webpage, or capture one page component into an exact workspace destination. Advanced Build/Goal tool; unavailable in Plan and Chat. This writes only the requested local output and never changes the remote page.', {
+            t('web_catch', 'Download a public web resource, save a webpage, or capture one page component into an exact workspace destination. Read the exact destination first; existing files require a complete read and new files require an exact-path absence observation. Advanced Build/Goal tool; unavailable in Plan and Chat. This writes only the requested local output and never changes the remote page.', {
                 action: { type: 'string', enum: ['download', 'save_page', 'capture_component'], description: 'download saves response bytes; save_page stores the HTML response; capture_component selects one CSS element and saves its src/href asset, or its outer HTML when no asset attribute exists.' },
                 url: { type: 'string', description: 'Public http:// or https:// URL.' },
                 destination: { type: 'string', description: 'Exact output file path. Relative paths resolve inside the active workspace.' },
@@ -405,22 +407,25 @@ class ToolExecutor {
                 capture_max_height: { type: 'number', minimum: 240, maximum: 2048, description: 'Maximum ephemeral screenshot height; defaults to 960. Aspect ratio is preserved and the source is never enlarged.' },
                 max_chars: { type: 'number', minimum: 1000, maximum: 100000, description: 'Maximum returned semantic UI text characters.' },
             }, []),
-            t('computer_use', 'Native Windows desktop control with persistent observation/action helpers. Use observe/app_observe before acting. sequence may perform up to three stable low-risk move/click/scroll/wait/app_activate steps and stops when focus, window, menu, dialog, scene, or risk changes. Vision screenshots remain one-time inputs and are deleted immediately.', {
-                action: { type: 'string', enum: ['observe', 'app_list', 'app_observe', 'sequence', 'takeover_start', 'takeover_stop', 'move', 'click', 'scroll', 'type', 'key', 'wait', 'app_activate', 'app_click', 'app_scroll', 'app_type', 'app_key'] },
+            t('computer_use', 'Native Windows desktop control with persistent observation/action helpers. Use observe/app_observe before acting. Set include_ui_tree=false for a fast screenshot-only observation; the default includes a bounded UI Automation tree for semantic targets. wait_for polls one visible app window for text, a target_id from the latest observation, or window availability. A match refreshes the semantic target cache; inspect the returned element before acting. For passive observe, sparse_wait_ms can wait up to 5 seconds on a coarse local pixel-change signal without a local perception model; after a signal or timeout it captures a fresh screenshot and the requested UI Automation data. This low-resolution signal can miss small or brief changes and does not prove that no change occurred. sequence may perform up to three stable low-risk move/click/scroll/wait/app_activate steps and stops when focus, window, menu, dialog, scene, or risk changes. Vision screenshots remain one-time inputs and are deleted immediately.', {
+                action: { type: 'string', enum: ['observe', 'app_list', 'app_observe', 'wait_for', 'sequence', 'takeover_start', 'takeover_stop', 'move', 'click', 'scroll', 'type', 'key', 'wait', 'app_activate', 'app_click', 'app_scroll', 'app_type', 'app_key'] },
                 capture_max_width: { type: 'number', minimum: 320, maximum: 2048, description: 'For observe/app_observe only. Maximum ephemeral screenshot width; defaults to 1280. Aspect ratio is preserved and the source is never enlarged.' },
                 capture_max_height: { type: 'number', minimum: 240, maximum: 2048, description: 'For observe/app_observe only. Maximum ephemeral screenshot height; defaults to 960. Aspect ratio is preserved and the source is never enlarged.' },
+                include_ui_tree: { type: 'boolean', description: 'For observe/app_observe only. Defaults to true. Set false to skip UI Automation traversal and return a screenshot-only observation; prior semantic target IDs are invalidated.' },
+                sparse_wait_ms: { type: 'integer', minimum: 0, maximum: 5000, description: 'Optional for action=observe only; defaults to 0 (immediate capture). Wait this many milliseconds for a coarse 32×18 grayscale change signal with no local neural model, then capture a fresh screenshot and the UI Automation tree when include_ui_tree=true, whether signaled or timed out. Small/transient changes can be missed.' },
                 x: { type: 'number' },
                 y: { type: 'number' },
-                target_id: { type: 'string', description: 'Stable id from the latest observe perception.objects entry. Preferred over raw coordinates when available.' },
+                target_id: { type: 'string', description: 'Stable id from the latest observe perception.objects entry. Preferred over raw coordinates when available; for wait_for it must come from the latest semantic observation.' },
                 app_target: { type: 'string', description: 'Application title, process name, or process id for app-scoped observation and actions.' },
                 window_handle: { type: 'string', description: 'Native window handle from app_list/app_observe for exact app-scoped actions.' },
                 max_chars: { type: 'number', minimum: 1000, maximum: 100000, description: 'Maximum returned text characters for observation and application listings.' },
                 scroll_x: { type: 'number', description: 'Horizontal scroll delta for action=scroll.' },
                 scroll_y: { type: 'number', description: 'Vertical scroll delta for action=scroll. Positive scrolls down.' },
                 button: { type: 'string', enum: ['left', 'right'] },
-                text: { type: 'string' },
+                text: { type: 'string', description: 'Text to type, or for wait_for a case-insensitive substring of a visible UI Automation Name or AutomationId.' },
                 key: { type: 'string' },
                 duration_ms: { type: 'number' },
+                timeout_ms: { type: 'integer', minimum: 250, maximum: 30000, description: 'For wait_for only. Polling budget in milliseconds; defaults to 5000 and is capped at 30000. A UI Automation call already in flight can add bounded completion latency.' },
                 dry_run: { type: 'boolean' },
                 include_raw_ui: { type: 'boolean', description: 'Debug only. Include the raw UI Automation element list; normal observation returns compact semantic objects.' },
                 steps: {
@@ -650,14 +655,18 @@ class ToolExecutor {
             if (tool.function?.name !== 'computer_use')
                 return tool;
             const copy = JSON.parse(JSON.stringify(tool));
-            copy.function.description = 'Plan read-only desktop: observe, app_list, app_observe only.';
+            copy.function.description = 'Plan read-only desktop: observe, app_list, app_observe, wait_for only.';
             copy.function.parameters.properties = {
                 action: { type: 'string', enum: [...toolPolicy_1.PLAN_COMPUTER_USE_ACTIONS] },
                 app_target: copy.function.parameters.properties.app_target,
                 window_handle: copy.function.parameters.properties.window_handle,
+                target_id: copy.function.parameters.properties.target_id,
+                text: copy.function.parameters.properties.text,
                 max_chars: copy.function.parameters.properties.max_chars,
                 capture_max_width: copy.function.parameters.properties.capture_max_width,
                 capture_max_height: copy.function.parameters.properties.capture_max_height,
+                include_ui_tree: copy.function.parameters.properties.include_ui_tree,
+                timeout_ms: copy.function.parameters.properties.timeout_ms,
                 include_raw_ui: copy.function.parameters.properties.include_raw_ui,
             };
             return copy;
@@ -787,15 +796,99 @@ class ToolExecutor {
             switch (tool) {
                 case 'bash': return await this.bash(g('command'), wsPath, args.timeout_ms, context.signal);
                 case 'pwd': return `Current directory: ${wsPath}`;
-                case 'read': return this.fread(resolve(g('path')));
-                case 'write': return this.fwrite(resolve(g('path')), g('content'));
-                case 'edit': return this.fedit(resolve(g('path')), g('old_str'), g('new_str'));
-                case 'delete_file': return this.fdelete(resolve(g('path')));
+                case 'read':
+                    return await this.fileWriteObservationGate.read(resolve(g('path')), this.fileWriteObservationScope(context, wsPath), {
+                        startLine: args.start_line === undefined ? undefined : Number(args.start_line),
+                        endLine: args.end_line === undefined ? undefined : Number(args.end_line),
+                    });
+                case 'write': {
+                    const target = resolve(g('path'));
+                    const mutation = await this.fileWriteObservationGate.mutate(target, this.fileWriteObservationScope(context, wsPath), { kind: 'full' }, gate => {
+                        const denied = this.checkWorkspaceAccess('write', gate.canonicalPath, context.workspacePath || wsPath);
+                        if (denied)
+                            return { value: denied, committed: false };
+                        if (gate.exists) {
+                            gate.assertBeforeCommit();
+                            fs.writeFileSync(target, g('content'), 'utf-8');
+                        }
+                        else {
+                            fs.mkdirSync(path.dirname(target), { recursive: true });
+                            gate.assertBeforeCommit();
+                            fs.writeFileSync(target, g('content'), { encoding: 'utf-8', flag: 'wx' });
+                        }
+                        return { value: '[write] OK: ' + target, committed: true };
+                    });
+                    return mutation.ok ? mutation.value : mutation.error;
+                }
+                case 'edit': {
+                    const target = resolve(g('path'));
+                    const oldText = g('old_str');
+                    const replacement = g('new_str');
+                    const mutation = await this.fileWriteObservationGate.mutate(target, this.fileWriteObservationScope(context, wsPath), { kind: 'edit', oldText }, gate => {
+                        const denied = this.checkWorkspaceAccess('edit', gate.canonicalPath, context.workspacePath || wsPath);
+                        if (denied)
+                            return { value: denied, committed: false };
+                        if (!gate.exists || gate.text === undefined)
+                            return { value: '[edit] Target file does not exist: ' + target, committed: false };
+                        const first = gate.text.indexOf(oldText);
+                        if (first < 0)
+                            return { value: '[edit] String not found in ' + target + '.', committed: false };
+                        if (gate.text.indexOf(oldText, first + oldText.length) >= 0) {
+                            return { value: '[edit] Refused: old_str matches more than one position in ' + target + '; read a more specific context and retry.', committed: false };
+                        }
+                        gate.assertBeforeCommit();
+                        const updated = gate.text.slice(0, first) + replacement + gate.text.slice(first + oldText.length);
+                        fs.writeFileSync(target, updated, 'utf-8');
+                        return { value: '[edit] OK: ' + target, committed: true };
+                    });
+                    return mutation.ok ? mutation.value : mutation.error;
+                }
+                case 'delete_file': {
+                    const target = resolve(g('path'));
+                    if (/[*?]/.test(target))
+                        return '[delete_file] Refused: wildcard paths are not allowed. Delete one file per call.';
+                    try {
+                        if (fs.lstatSync(target).isDirectory()) {
+                            return '[delete_file] Refused: deleting a directory is not allowed. Delete files one by one under Agent supervision.';
+                        }
+                    }
+                    catch (error) {
+                        if (error?.code !== 'ENOENT') {
+                            return '[delete_file] ' + (error instanceof Error ? error.message : String(error));
+                        }
+                    }
+                    const mutation = await this.fileWriteObservationGate.mutate(target, this.fileWriteObservationScope(context, wsPath), { kind: 'full' }, gate => {
+                        const denied = this.checkWorkspaceAccess('delete_file', gate.canonicalPath, context.workspacePath || wsPath);
+                        if (denied)
+                            return { value: denied, committed: false };
+                        if (!gate.exists)
+                            return { value: '[delete_file] Target does not exist: ' + target, committed: false };
+                        gate.assertBeforeCommit();
+                        fs.unlinkSync(target);
+                        return { value: '[delete_file] OK: ' + target, committed: true };
+                    });
+                    return mutation.ok ? mutation.value : mutation.error;
+                }
                 case 'glob': return this.glob(g('pattern'), wsPath);
                 case 'grep': return this.grep(g('pattern'), resolve(g('path')));
                 case 'web_search': return await this.wsearch(g('query'), context.signal);
                 case 'web_fetch': return await this.wfetch(g('url'), context.signal);
-                case 'web_catch': return await this.wcatch(args, resolve(g('destination')), context.signal);
+                case 'web_catch': {
+                    const destination = resolve(g('destination'));
+                    const mutation = await this.fileWriteObservationGate.mutate(destination, this.fileWriteObservationScope(context, wsPath), { kind: 'full' }, async (gate) => {
+                        const denied = this.checkWorkspaceAccess('web_catch', gate.canonicalPath, context.workspacePath || wsPath);
+                        if (denied)
+                            return { value: denied, committed: false };
+                        const value = await this.wcatch(args, destination, context.signal, () => gate.assertBeforeCommit());
+                        let committed = false;
+                        try {
+                            committed = JSON.parse(value).ok === true;
+                        }
+                        catch { }
+                        return { value, committed };
+                    });
+                    return mutation.ok ? mutation.value : mutation.error;
+                }
                 case 'browser_open': return await this.browserRun({ action: 'open', url: g('url') }, context.signal, context, wsPath);
                 case 'browser_snapshot': return await this.browserRun({ action: 'snapshot', maxChars: Number(args.max_chars || 12000) }, context.signal, context, wsPath);
                 case 'browser_click': return await this.browserRun({ action: 'click', selector: g('selector') }, context.signal, context, wsPath);
@@ -999,6 +1092,14 @@ class ToolExecutor {
                 }
                 case 'computer_use': {
                     const action = normalizeComputerUseAction(g('action'));
+                    if (process.env.NEWMARK_TEST_CU_OBSERVE_ONLY === '1'
+                        && !['observe', 'app_observe', 'app_list', 'wait_for'].includes(action)) {
+                        return JSON.stringify({
+                            ok: false,
+                            action,
+                            error: '[computer_use test guard] The live-model smoke only permits read-only desktop observation.',
+                        });
+                    }
                     const owner = `${computerUseOwner(context, wsPath)}:${String(context.actorId || 'root')}`;
                     const lockGuard = action === 'takeover_stop'
                         ? assertComputerUseLockOwner(action, owner, context, wsPath)
@@ -1063,6 +1164,10 @@ class ToolExecutor {
                         allowEphemeralVisionImage: context.allowEphemeralVisionImage === true,
                         captureMaxWidth: Number(args.capture_max_width),
                         captureMaxHeight: Number(args.capture_max_height),
+                        sparseWaitMs: Number(args.sparse_wait_ms),
+                        includeUiTree: args.include_ui_tree !== false,
+                        timeoutMs: Number(args.timeout_ms),
+                        signal: context.signal,
                         gradientColors: Array.isArray(args.gradient_colors) ? args.gradient_colors : undefined,
                         gradientSpeed: args.gradient_speed !== undefined ? Number(args.gradient_speed) : undefined,
                         gradientWidth: args.gradient_width !== undefined ? Number(args.gradient_width) : undefined,
@@ -1299,6 +1404,18 @@ class ToolExecutor {
         const action = policy === 'ask_user' ? 'User approval required' : 'Denied';
         return `[permission] ${action}: ${tool} cannot access outside workspace (${target}).`;
     }
+    fileWriteObservationScope(context, wsPath) {
+        const workspacePath = path.resolve(context.workspacePath || wsPath || this.root);
+        return JSON.stringify({
+            runtimeKey: String(context.runtimeKey || process.env.NEWMARK_RUNTIME_KEY || ''),
+            runId: String(context.runId || ''),
+            workspaceId: String(context.workspaceId || workspacePath),
+            workspacePath,
+            conversationId: String(context.conversationId || 'default'),
+            actorId: String(context.actorId || terminalTakeover_1.ROOT_TERMINAL_ACTOR_ID),
+            backend: String(context.backend || (process.env.NEWMARK_WSL_DISTRO ? 'wsl' : process.platform)),
+        });
+    }
     checkBashWorkspaceAccess(command, wsPath) {
         const perm = this.config.getStr('workspace', 'access_permission');
         if (perm === 'full_access')
@@ -1386,54 +1503,6 @@ class ToolExecutor {
             return `[bash] ${e instanceof Error ? e.message : String(e)}`;
         }
     }
-    fread(p) {
-        try {
-            const c = fs.readFileSync(p, 'utf-8');
-            return c.length > 30000 ? c.slice(0, 30000) + '...\n[truncated]' : c;
-        }
-        catch (e) {
-            return `[read] ${e}`;
-        }
-    }
-    fwrite(p, content) {
-        try {
-            fs.mkdirSync(path.dirname(p), { recursive: true });
-            fs.writeFileSync(p, content, 'utf-8');
-            return `[write] OK: ${p}`;
-        }
-        catch (e) {
-            return `[write] ${e}`;
-        }
-    }
-    fedit(p, oldStr, newStr) {
-        try {
-            const c = fs.readFileSync(p, 'utf-8');
-            if (!c.includes(oldStr))
-                return `[edit] String not found in ${p}.`;
-            const updated = c.replace(oldStr, newStr);
-            fs.writeFileSync(p, updated, 'utf-8');
-            return `[edit] OK: ${p}`;
-        }
-        catch (e) {
-            return `[edit] ${e}`;
-        }
-    }
-    fdelete(p) {
-        try {
-            if (/[*?]/.test(p))
-                return '[delete_file] Refused: wildcard paths are not allowed. Delete one file per call.';
-            const resolved = path.resolve(p);
-            const stat = fs.lstatSync(resolved);
-            if (stat.isDirectory()) {
-                return '[delete_file] Refused: deleting a directory is not allowed. Delete files one by one under Agent supervision.';
-            }
-            fs.unlinkSync(resolved);
-            return `[delete_file] OK: ${resolved}`;
-        }
-        catch (e) {
-            return `[delete_file] ${e instanceof Error ? e.message : String(e)}`;
-        }
-    }
     glob(pattern, ws) {
         try {
             const results = globSync(pattern, {
@@ -1885,7 +1954,7 @@ class ToolExecutor {
             guard.dispose();
         }
     }
-    async wcatch(args, destination, signal) {
+    async wcatch(args, destination, signal, beforeCommit) {
         const action = String(args.action || 'download');
         const maxBytes = Math.max(1, Math.min(100 * 1024 * 1024, Number(args.max_bytes || 50 * 1024 * 1024)));
         const sourceUrl = this.checkedPublicWebUrl(String(args.url || ''));
@@ -1929,9 +1998,20 @@ class ToolExecutor {
         const backup = destinationExists ? `${destination}.newmark-${crypto.randomUUID()}.bak` : '';
         try {
             fs.writeFileSync(temp, bytes, { flag: 'wx' });
-            if (destinationExists)
+            beforeCommit?.();
+            const currentDestinationExists = fs.existsSync(destination);
+            if (currentDestinationExists !== destinationExists)
+                throw new Error('Destination changed during download; read it again and retry.');
+            if (currentDestinationExists && !fs.statSync(destination).isFile())
+                throw new Error('Destination changed to a non-file during download.');
+            if (destinationExists) {
                 fs.renameSync(destination, backup);
-            fs.renameSync(temp, destination);
+                fs.renameSync(temp, destination);
+            }
+            else {
+                fs.linkSync(temp, destination);
+                fs.unlinkSync(temp);
+            }
             if (backup)
                 fs.unlinkSync(backup);
         }