@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/browser-automation/browser-tool.js

@@ -99,12 +99,20 @@ function findMatchingLines(text, query, limit) {
 // ============================================================================
 // Browser Tool
 // ============================================================================
+/** Evidence dir for screenshots/PDFs: env override, else $HOME/.codebuddy — never shared /tmp. */
+export function resolveBrowserEvidenceDir() {
+    const override = process.env.CODEBUDDY_SCREENSHOT_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(os.homedir(), '.codebuddy', 'browser-screenshots');
+}
 export class BrowserTool {
     manager;
-    screenshotDir;
     constructor() {
         this.manager = getBrowserManager();
-        this.screenshotDir = path.join(os.tmpdir(), 'codebuddy-screenshots');
+    }
+    evidenceDir() {
+        return resolveBrowserEvidenceDir();
     }
     /**
      * Execute browser action
@@ -202,6 +210,8 @@ export class BrowserTool {
                     return this.getImages(input);
                 case 'console':
                     return this.consoleHistory(input);
+                case 'network':
+                    return this.networkFailures(input);
                 case 'dialog':
                     return this.dialog(input);
                 // Info
@@ -268,23 +278,17 @@ export class BrowserTool {
         const stopOnError = input.stopOnError !== false; // default true
         const results = [];
         for (const subAction of input.actions) {
-            // SSRF check for navigation actions in batch (Native Engine v2026.3.14)
+            // SSRF check for navigation actions in batch — same fail-closed guard as
+            // single-navigate (blocks file:/data:/about:, private/metadata IPs, and
+            // refuses if the guard module can't load).
             if (subAction.action === 'navigate' && subAction.url) {
-                try {
-                    const { assertSafeUrl } = await import('../security/ssrf-guard.js');
-                    const check = await assertSafeUrl(subAction.url);
-                    if (!check.safe) {
-                        results.push({
-                            action: subAction.action,
-                            success: false,
-                            error: `SSRF blocked: ${check.reason || 'URL not allowed'}`,
-                        });
-                        if (stopOnError)
-                            break;
-                        continue;
-                    }
+                const guard = await this.guardNavigationUrl(subAction.url);
+                if (!guard.ok) {
+                    results.push({ action: subAction.action, success: false, error: guard.error });
+                    if (stopOnError)
+                        break;
+                    continue;
                 }
-                catch { /* SSRF guard unavailable, proceed */ }
             }
             const result = await this.execute(subAction);
             results.push({
@@ -468,28 +472,51 @@ export class BrowserTool {
     // ============================================================================
     // Navigation
     // ============================================================================
+    /**
+     * Gate EVERY navigation target — fail closed. assertSafeUrl already blocks
+     * non-http(s) schemes (`file:`/`data:`/`about:` → would otherwise read local
+     * files, e.g. `file:///home/user/.aws/credentials`, straight into the model
+     * context), private/loopback/metadata IPs, DNS-rebind, and unparseable URLs,
+     * and it never throws. The only remaining failure point is the dynamic import
+     * of the guard module itself; if that fails we REFUSE rather than proceed (the
+     * previous code caught the import error and navigated unchecked — S3). The one
+     * explicit exception is `about:blank`, an inert empty page with no read.
+     */
+    async guardNavigationUrl(url) {
+        if (url.trim().toLowerCase() === 'about:blank')
+            return { ok: true };
+        // Session-registered dev origins (loopback-only by construction — see
+        // security/dev-origins.ts) are the one sanctioned exception: the dev
+        // server the agent itself launched. A miss falls through to the normal
+        // fail-closed SSRF gate below.
+        try {
+            const { isDevOriginAllowed } = await import('../security/dev-origins.js');
+            if (isDevOriginAllowed(url))
+                return { ok: true };
+        }
+        catch {
+            // Registry unavailable → no exception granted; the SSRF gate decides.
+        }
+        try {
+            const { assertSafeUrl } = await import('../security/ssrf-guard.js');
+            const check = await assertSafeUrl(url);
+            if (!check.safe) {
+                return { ok: false, error: `Navigation blocked: ${check.reason || 'URL not allowed'}` };
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { ok: false, error: `Navigation blocked: URL guard unavailable (${msg})` };
+        }
+    }
     async navigate(input) {
         if (!input.url) {
             return { success: false, error: 'URL is required' };
         }
-        // SSRF guard for the network surface only. http/https can be steered at internal
-        // services / cloud metadata, so they're validated (parity with batch-mode :474).
-        // Local schemes (file://, about:, data:) are legitimate navigation targets and are
-        // not a server-side request forgery, so they pass through unchanged.
-        let scheme = '';
-        try {
-            scheme = new URL(input.url).protocol;
-        }
-        catch { /* leave to Playwright */ }
-        if (scheme === 'http:' || scheme === 'https:') {
-            try {
-                const { assertSafeUrl } = await import('../security/ssrf-guard.js');
-                const check = await assertSafeUrl(input.url);
-                if (!check.safe) {
-                    return { success: false, error: `SSRF blocked: ${check.reason || 'URL not allowed'}` };
-                }
-            }
-            catch { /* SSRF guard unavailable, proceed */ }
+        const guard = await this.guardNavigationUrl(input.url);
+        if (!guard.ok) {
+            return { success: false, error: guard.error };
         }
         await this.manager.navigate({
             url: input.url,
@@ -603,7 +630,8 @@ export class BrowserTool {
     // Media
     // ============================================================================
     async screenshot(input) {
-        await fs.mkdir(this.screenshotDir, { recursive: true });
+        const evidenceDir = this.evidenceDir();
+        await fs.mkdir(evidenceDir, { recursive: true });
         const buffer = await this.manager.screenshot({
             fullPage: input.fullPage,
             element: input.element,
@@ -611,7 +639,7 @@ export class BrowserTool {
             quality: input.quality,
         });
         const filename = input.outputPath ||
-            path.join(this.screenshotDir, `screenshot-${Date.now()}.${input.format || 'png'}`);
+            path.join(evidenceDir, `screenshot-${Date.now()}.${input.format || 'png'}`);
         await fs.writeFile(filename, buffer);
         return {
             success: true,
@@ -620,10 +648,11 @@ export class BrowserTool {
         };
     }
     async pdf(input) {
-        await fs.mkdir(this.screenshotDir, { recursive: true });
+        const evidenceDir = this.evidenceDir();
+        await fs.mkdir(evidenceDir, { recursive: true });
         const buffer = await this.manager.pdf({});
         const filename = input.outputPath ||
-            path.join(this.screenshotDir, `page-${Date.now()}.pdf`);
+            path.join(evidenceDir, `page-${Date.now()}.pdf`);
         await fs.writeFile(filename, buffer);
         return {
             success: true,
@@ -844,6 +873,39 @@ export class BrowserTool {
             data: { entries },
         };
     }
+    async networkFailures(input) {
+        const networkAction = input.networkAction ?? 'list';
+        if (networkAction === 'clear') {
+            this.manager.clearNetworkFailures();
+            return {
+                success: true,
+                output: 'Browser network failure history cleared.',
+                data: { failures: [] },
+            };
+        }
+        if (networkAction !== 'list') {
+            return { success: false, error: `Unknown network action: ${networkAction}` };
+        }
+        const failures = this.manager.getNetworkFailures(input.limit);
+        if (failures.length === 0) {
+            return {
+                success: true,
+                output: 'No browser network failures.',
+                data: { failures },
+            };
+        }
+        return {
+            success: true,
+            output: failures.map((failure) => {
+                const when = failure.timestamp instanceof Date ? failure.timestamp.toISOString() : String(failure.timestamp);
+                const detail = failure.kind === 'httperror'
+                    ? `HTTP ${failure.status}`
+                    : (failure.errorText || 'request failed');
+                return `[${when}] ${failure.method} ${failure.url} → ${detail}`;
+            }).join('\n'),
+            data: { failures },
+        };
+    }
     async extract(input) {
         const result = await this.manager.evaluate({
             expression: `(() => {

package/dist/browser-automation/internet-scout-plan.d.ts

@@ -9,6 +9,7 @@ export interface InternetScoutPlanOptions {
     sourceUrl?: string;
     intent?: InternetScoutIntent;
     requiresInteraction?: boolean;
+    interactionInstruction?: string;
     expectedText?: string;
     persistWhenProven?: boolean;
     maxPages?: number;

package/dist/browser-automation/internet-scout-plan.js

@@ -17,6 +17,7 @@ export function buildInternetScoutPlan(options) {
     const query = normalizeText(options.query) || goal;
     const sourceUrl = normalizeText(options.sourceUrl);
     const expectedText = normalizeText(options.expectedText);
+    const interactionInstruction = normalizeText(options.interactionInstruction) || goal;
     const intent = normalizeIntent(options.intent);
     const maxPages = normalizeMaxPages(options.maxPages);
     const allowLoginPages = options.allowLoginPages === true;
@@ -70,6 +71,21 @@ export function buildInternetScoutPlan(options) {
             reason: 'Use LLM-assisted observation to resolve a visible selector before any click, typing, or form fill.',
             inputs: { target: query, requiresVisibleRef: true },
         });
+        steps.push({
+            id: 'reviewed-interaction',
+            title: 'Perform the exact reviewed interaction',
+            tool: 'browser',
+            stage: 'interact',
+            evidence: 'user-action',
+            required: true,
+            action: 'act',
+            reason: 'Execute one visible browser action tied to the exact operator-reviewed instruction; the executor asks for confirmation again immediately before acting.',
+            inputs: {
+                instruction: interactionInstruction,
+                exactReviewedGoal: true,
+                maxActions: 1,
+            },
+        });
     }
     steps.push({
         id: 'extract',
@@ -207,6 +223,7 @@ function buildSafetyRules() {
         'Use public web pages or user-authorized pages only.',
         'Prefer web_fetch before browser automation to reduce page load and side effects.',
         'Observe before clicking or typing, and use visible refs rather than blind selectors.',
+        'Interactive plans may execute only the exact reviewed action and require a second confirmation immediately before it runs.',
         'Do not bypass captcha, bot checks, paywalls, access controls, or robots/rate-limit signals.',
         'Do not infer or persist identity for unknown people without explicit permission and evidence.',
         'Persist only compact facts with source evidence; avoid storing raw page dumps or private data.',

package/dist/browser-automation/profile-manager.js

@@ -8,6 +8,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { homedir } from 'os';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 // ============================================================================
 // Profile Manager
 // ============================================================================
@@ -29,7 +30,7 @@ export class BrowserProfileManager {
             savedAt: new Date(),
         };
         const filePath = this.getProfilePath(name);
-        await fs.writeFile(filePath, JSON.stringify(profile, null, 2), 'utf-8');
+        await writeJsonAtomic(filePath, profile, { mode: 0o600 });
         logger.info(`Browser profile saved: ${name}`, { path: filePath });
     }
     /**
@@ -38,8 +39,9 @@ export class BrowserProfileManager {
     async load(name) {
         try {
             const filePath = this.getProfilePath(name);
-            const raw = await fs.readFile(filePath, 'utf-8');
-            const profile = JSON.parse(raw);
+            const profile = await readJsonAtomic(filePath, null);
+            if (!profile)
+                return null;
             profile.savedAt = new Date(profile.savedAt);
             return profile;
         }

package/dist/browser-automation/types.d.ts

@@ -304,6 +304,31 @@ export interface NetworkResponse {
     mimeType: string;
     timestamp: number;
 }
+/**
+ * A failed network exchange captured on the active page — either a request
+ * that never completed (`requestfailed`: connection refused, DNS failure,
+ * aborted, CORS-blocked, …) or an HTTP response with a client/server error
+ * status (>= 400). This is the network face of a bug: a UI that renders but
+ * whose API calls fail.
+ */
+export interface NetworkFailure {
+    /** 'requestfailed' = the request never completed; 'httperror' = a >= 400 HTTP response. */
+    kind: 'requestfailed' | 'httperror';
+    /** Request URL */
+    url: string;
+    /** HTTP method (GET, POST, …) */
+    method: string;
+    /** HTTP status for kind='httperror' */
+    status?: number;
+    /** Playwright request.failure() errorText for kind='requestfailed' (e.g. net::ERR_CONNECTION_REFUSED) */
+    errorText?: string;
+    /** Resource type (document, fetch, xhr, script, …) when available */
+    resourceType?: string;
+    /** When the failure was captured */
+    timestamp: Date;
+    /** Browser page that produced the entry */
+    pageId?: string;
+}
 export interface EvaluateOptions {
     /** JavaScript code to execute */
     expression: string;

package/dist/cache/advanced-lru-cache.js

@@ -30,6 +30,7 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import * as zlib from 'zlib';
 import { promisify } from 'util';
+import { readJsonAtomic, writeFileAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 const gzip = promisify(zlib.gzip);
 const gunzip = promisify(zlib.gunzip);
 // ============================================================================
@@ -424,7 +425,7 @@ export class AdvancedLRUCache extends EventEmitter {
             data = Buffer.from(serialized, 'utf-8');
             compressedSize = data.length;
         }
-        await fs.writeFile(filePath, data);
+        await writeFileAtomic(filePath, data);
         const now = Date.now();
         const entry = {
             key,
@@ -498,8 +499,7 @@ export class AdvancedLRUCache extends EventEmitter {
     async loadDiskIndex() {
         try {
             if (existsSync(this.indexPath)) {
-                const content = await fs.readFile(this.indexPath, 'utf-8');
-                const data = JSON.parse(content);
+                const data = await readJsonAtomic(this.indexPath, { entries: [] });
                 if (Array.isArray(data.entries)) {
                     const now = Date.now();
                     for (const entry of data.entries) {
@@ -518,7 +518,7 @@ export class AdvancedLRUCache extends EventEmitter {
     async saveDiskIndex() {
         try {
             const entries = Array.from(this.diskIndex.values());
-            await fs.writeFile(this.indexPath, JSON.stringify({ entries, savedAt: Date.now() }), 'utf-8');
+            await writeJsonAtomic(this.indexPath, { entries, savedAt: Date.now() });
         }
         catch {
             // Failed to save index

package/dist/cache/cache-manager.js

@@ -19,6 +19,7 @@ import { getEmbeddingCache } from './embedding-cache.js';
 import { getSearchResultsCache } from './search-results-cache.js';
 import { getCacheConfig } from './cache-config.js';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -786,7 +787,6 @@ export class CacheManager extends EventEmitter {
      * Persist all cache state to disk for long sessions
      */
     async persistToDisk(basePath = '.codebuddy/cache') {
-        const fs = await import('fs/promises');
         const path = await import('path');
         const { existsSync, mkdirSync } = await import('fs');
         // Ensure directory exists
@@ -798,13 +798,13 @@ export class CacheManager extends EventEmitter {
             const state = await this.exportCacheState();
             // Write state file
             const statePath = path.join(basePath, 'cache-manager-state.json');
-            await fs.writeFile(statePath, JSON.stringify(state, null, 2));
+            await writeJsonAtomic(statePath, state);
             // Write metrics history
             const metricsPath = path.join(basePath, 'metrics-history.json');
-            await fs.writeFile(metricsPath, JSON.stringify({
+            await writeJsonAtomic(metricsPath, {
                 history: this.metricsHistory,
                 savedAt: Date.now(),
-            }, null, 2));
+            });
             logger.debug(`Cache state persisted to ${basePath}`);
             this.emit('persist:complete', { path: basePath });
         }
@@ -817,7 +817,6 @@ export class CacheManager extends EventEmitter {
      * Restore cache state from disk
      */
     async restoreFromDisk(basePath = '.codebuddy/cache') {
-        const fs = await import('fs/promises');
         const path = await import('path');
         const { existsSync } = await import('fs');
         const statePath = path.join(basePath, 'cache-manager-state.json');
@@ -827,8 +826,9 @@ export class CacheManager extends EventEmitter {
         }
         try {
             // Read state file
-            const stateContent = await fs.readFile(statePath, 'utf-8');
-            const state = JSON.parse(stateContent);
+            const state = await readJsonAtomic(statePath, null);
+            if (!state)
+                return false;
             // Check if state is too old (more than 24 hours)
             const maxAge = 24 * 60 * 60 * 1000;
             if (Date.now() - state.timestamp > maxAge) {
@@ -840,11 +840,10 @@ export class CacheManager extends EventEmitter {
             // Try to restore metrics history
             const metricsPath = path.join(basePath, 'metrics-history.json');
             if (existsSync(metricsPath)) {
-                const metricsContent = await fs.readFile(metricsPath, 'utf-8');
-                const metricsData = JSON.parse(metricsContent);
+                const metricsData = await readJsonAtomic(metricsPath, null);
                 // Only restore recent metrics (last hour)
                 const oneHourAgo = Date.now() - 60 * 60 * 1000;
-                this.metricsHistory = (metricsData.history || []).filter((m) => m.timestamp > oneHourAgo);
+                this.metricsHistory = (metricsData?.history || []).filter((m) => m.timestamp > oneHourAgo);
             }
             logger.debug(`Cache state restored from ${basePath}`);
             this.emit('restore:complete', { path: basePath });

package/dist/cache/embedding-cache.js

@@ -12,10 +12,10 @@
  */
 import { EventEmitter } from 'events';
 import * as crypto from 'crypto';
-import * as fs from 'fs/promises';
 import { existsSync, mkdirSync } from 'fs';
 import * as path from 'path';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -314,13 +314,13 @@ export class EmbeddingCache extends EventEmitter {
                 // Optionally compress embeddings further for storage
                 embedding: e.embedding,
             }));
-            await fs.writeFile(this.config.cachePath, JSON.stringify({
+            await writeJsonAtomic(this.config.cachePath, {
                 version: 1,
                 dimension: this.config.dimension,
                 model: this.config.modelName,
                 entries: entries.slice(0, this.config.maxEntries),
                 stats: this.stats,
-            }));
+            });
             this.pendingSave = [];
             logger.debug(`Saved ${entries.length} embeddings to cache`);
         }
@@ -336,8 +336,9 @@ export class EmbeddingCache extends EventEmitter {
             return;
         (async () => {
             try {
-                const content = await fs.readFile(this.config.cachePath, 'utf-8');
-                const data = JSON.parse(content);
+                const data = await readJsonAtomic(this.config.cachePath, null);
+                if (!data)
+                    return;
                 // Validate version and dimension
                 if (data.version !== 1 || data.dimension !== this.config.dimension) {
                     logger.debug('Embedding cache version or dimension mismatch, starting fresh');

package/dist/cache/llm-response-cache.js

@@ -12,10 +12,10 @@
  */
 import { EventEmitter } from 'events';
 import * as crypto from 'crypto';
-import * as fs from 'fs/promises';
 import { existsSync, mkdirSync } from 'fs';
 import * as path from 'path';
 import { logger } from '../utils/logger.js';
+import { readJsonAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
 // ============================================================================
 // Default Configuration
 // ============================================================================
@@ -410,7 +410,7 @@ export class LLMResponseCache extends EventEmitter {
             const entries = Array.from(this.cache.values())
                 .filter(e => !this.isExpired(e))
                 .slice(0, this.config.maxEntries);
-            await fs.writeFile(this.config.cachePath, JSON.stringify({ entries, stats: this.stats }, null, 2));
+            await writeJsonAtomic(this.config.cachePath, { entries, stats: this.stats });
         }
         catch (error) {
             logger.debug('Failed to save LLM cache', { error });
@@ -424,8 +424,7 @@ export class LLMResponseCache extends EventEmitter {
             return;
         (async () => {
             try {
-                const content = await fs.readFile(this.config.cachePath, 'utf-8');
-                const data = JSON.parse(content);
+                const data = await readJsonAtomic(this.config.cachePath, { entries: [] });
                 if (Array.isArray(data.entries)) {
                     const now = Date.now();
                     for (const entry of data.entries) {

package/dist/capture/screen-recorder.d.ts

@@ -73,8 +73,10 @@ export declare function buildRecordArgs(output: string, opts?: RecordOptions, pl
 export declare class ScreenRecorder {
     private proc;
     private readonly doSpawn;
+    private readonly platform;
     constructor(opts?: {
         spawnImpl?: SpawnLike;
+        platform?: NodeJS.Platform;
     });
     /** Capture one frame; resolves to the output path. */
     captureFrame(output: string, target?: CaptureTarget): Promise<string>;

package/dist/capture/screen-recorder.js

@@ -91,15 +91,17 @@ export function buildRecordArgs(output, opts = {}, platform = process.platform)
 export class ScreenRecorder {
     proc = null;
     doSpawn;
+    platform;
     constructor(opts = {}) {
         this.doSpawn = opts.spawnImpl ?? spawn;
+        this.platform = opts.platform ?? process.platform;
     }
     /** Capture one frame; resolves to the output path. */
     captureFrame(output, target = {}) {
-        if (process.platform === 'linux' && isWaylandSession()) {
+        if (this.platform === 'linux' && isWaylandSession()) {
             return Promise.reject(new Error('Wayland session: x11grab cannot capture. Use a portal/wf-recorder backend.'));
         }
-        const { cmd, args } = buildFrameArgs(output, target);
+        const { cmd, args } = buildFrameArgs(output, target, this.platform);
         return new Promise((resolve, reject) => {
             const p = this.doSpawn(cmd, args, { stdio: 'ignore' });
             p.on('error', reject);
@@ -110,11 +112,11 @@ export class ScreenRecorder {
     start(output, opts = {}) {
         if (this.proc)
             throw new Error('already recording');
-        if (process.platform === 'linux' && isWaylandSession()) {
+        if (this.platform === 'linux' && isWaylandSession()) {
             throw new Error('Wayland session: x11grab cannot record. Use a portal/wf-recorder backend.');
         }
         fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
-        const { cmd, args } = buildRecordArgs(output, opts);
+        const { cmd, args } = buildRecordArgs(output, opts, this.platform);
         this.proc = this.doSpawn(cmd, args, { stdio: 'ignore' });
         return output;
     }

package/dist/capture/screen-watcher.d.ts

@@ -17,11 +17,12 @@ export interface ScreenWatcherOptions {
     /** Capture a frame to `output`, resolve to the path. Injectable for tests. */
     capture?: (output: string) => Promise<string>;
     /**
-     * Fingerprint a frame for dedup. Default: sha1 of file bytes. May be async —
-     * e.g. the codebuddy-captured Rust daemon's perceptual hash, which dedups
-     * near-identical frames (robust to lossy re-encode), unlike a byte sha1.
+     * Fingerprint a frame for dedup. Default: Sharp dHash + colour signature,
+     * falling back to an exact SHA-256 when the optional image stack is absent.
      */
     fingerprint?: (framePath: string) => string | Promise<string>;
+    /** Maximum differing bits for perceptual hashes to still count as idle. Default: 6. */
+    perceptualHashThreshold?: number;
     /** OCR a frame to text. Default: `tesseract <frame> stdout`. */
     ocrImpl?: (framePath: string) => Promise<string>;
     /** Redact secrets/PII from text. Default: privacy-lint. */
@@ -38,6 +39,8 @@ export declare function redactSecrets(text: string): {
     text: string;
     redacted: boolean;
 };
+/** Hamming + coarse colour distance for dHash fingerprints, or null for other formats. */
+export declare function perceptualHashDistance(left: string, right: string): number | null;
 export declare class ScreenWatcher {
     private readonly opts;
     private timer;