newmark-agent 0.6.4 → 0.6.8

package/dist/core/conversationStateDocument.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readConversationStateDocument = readConversationStateDocument;
+exports.readConversationIndexText = readConversationIndexText;
+/**
+ * Workspace conversation state on disk is an **index** document
+ * (`conversations/state.json`) plus one heavy payload shard per conversation
+ * (`conversations/shards/<key>.<hash>.json`).
+ *
+ * Product code reads through `Agent.readStoredConversationState`, which
+ * hydrates shards lazily. Fixtures, diagnostics and archive tooling that read
+ * the raw file need the same view: reading only the index makes every
+ * conversation look empty. These helpers are the single shard-aware reader for
+ * such callers.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function parseJson(text) {
+    try {
+        const parsed = JSON.parse(text.replace(/^\uFEFF/, ''));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Read a workspace conversation index and hydrate every conversation shard. */
+function readConversationStateDocument(workspacePath) {
+    const indexPath = path.join(workspacePath, 'conversations', 'state.json');
+    const indexText = fs.existsSync(indexPath) ? fs.readFileSync(indexPath, 'utf-8') : '{}';
+    const index = parseJson(indexText);
+    const shardDir = path.join(path.dirname(indexPath), 'shards');
+    const conversations = {};
+    for (const [key, rawEntry] of Object.entries((index.conversations || {}))) {
+        const entry = rawEntry || {};
+        const shardFile = typeof entry.shard === 'string' && entry.shard ? path.join(shardDir, entry.shard) : '';
+        if (shardFile && fs.existsSync(shardFile)) {
+            conversations[key] = { ...entry, ...parseJson(fs.readFileSync(shardFile, 'utf-8')) };
+            continue;
+        }
+        conversations[key] = { ...entry };
+    }
+    return {
+        path: indexPath,
+        index,
+        conversations,
+        indexText,
+        hydratedText: JSON.stringify({ ...index, conversations }, null, 2),
+    };
+}
+/** Index-only text, for assertions about what the index itself must not contain. */
+function readConversationIndexText(workspacePath) {
+    return readConversationStateDocument(workspacePath).indexText;
+}
+//# sourceMappingURL=conversationStateDocument.js.map

package/dist/core/conversationVisualBudget.d.ts

@@ -0,0 +1,74 @@
+/**
+ * dev-0.6.6: per-conversation memory budget for ComputerUse / BrowserControl
+ * visual material.
+ *
+ * Field evidence: a long conversation that repeatedly drove computer_use /
+ * browser_control grew the utility host until V8 aborted with
+ * `OOM error in V8: CALL_AND_RETRY_LAST Allocation failed` at ~3017 MB heap.
+ * Every historic screenshot is stored as a file reference and materialized into
+ * a base64 data URL for the provider request, so a late-stage conversation
+ * builds a request whose visual payload grows with the number of observations.
+ *
+ * The budget is derived from the machine's *available* memory (not just its
+ * total), so an 8 GB machine that is already busy reclaims much earlier than an
+ * idle 32 GB one. Reclaiming only ever drops visual detail that was already
+ * sent in an earlier provider round; it never truncates text, tool results,
+ * plans or the conversation transcript.
+ */
+export type VisualMemoryPressure = 'roomy' | 'tight' | 'critical' | 'severe';
+export interface VisualMemorySample {
+    /** Physical RAM installed. Defaults to `os.totalmem()`. */
+    totalBytes?: number;
+    /** Free physical RAM right now. Defaults to `os.freemem()`. */
+    freeBytes?: number;
+    /** Resident set size of the process that owns the conversation, if known. */
+    rssBytes?: number;
+}
+export interface ConversationVisualBudget {
+    pressure: VisualMemoryPressure;
+    reason: string;
+    /** Largest single screenshot accepted into a provider request. */
+    maxSingleImageBytes: number;
+    /** Total visual bytes one provider request may materialize for the conversation. */
+    maxRequestImageBytes: number;
+    /** How many historic screenshots may stay in context. */
+    maxRetainedImages: number;
+    /** Retained visual bytes for the conversation (history plus live captures). */
+    maxConversationVisualBytes: number;
+    /** Idle hosts above this RSS are recycled instead of being reused. */
+    recycleRssBytes: number;
+}
+/** Pressure tier from available memory, with a total-RAM floor so 4 GB hosts never get a roomy budget. */
+export declare function visualMemoryPressure(sample?: VisualMemorySample): {
+    pressure: VisualMemoryPressure;
+    reason: string;
+};
+export declare function conversationVisualBudget(sample?: VisualMemorySample): ConversationVisualBudget;
+/**
+ * Heap cost of a data URL: the base64 payload length. This is what the provider
+ * request actually holds (a JS string of that many characters), and it matches
+ * the historical `dataUrl.length` cap this budget replaces.
+ */
+export declare function visualDataUrlBytes(value: string): number;
+export interface VisualRetentionEntry {
+    key: string;
+    bytes: number;
+}
+/**
+ * Choose which visual entries stay materialized, newest first.
+ *
+ * `entries` must be ordered oldest → newest (the order they appear in the
+ * conversation); the plan keeps the newest ones within both the byte budget and
+ * the retained-image count, and reports how much was released.
+ */
+export declare function planVisualRetention(entries: VisualRetentionEntry[], budget: ConversationVisualBudget): {
+    keep: Set<string>;
+    released: string[];
+    releasedBytes: number;
+    retainedBytes: number;
+};
+/** Should an idle host be recycled instead of reused? */
+export declare function shouldRecycleIdleHost(rssBytes: number, budget: ConversationVisualBudget): boolean;
+/** Short human-readable summary used in work-status lines. */
+export declare function describeVisualBudget(budget: ConversationVisualBudget): string;
+//# sourceMappingURL=conversationVisualBudget.d.ts.map

package/dist/core/conversationVisualBudget.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visualMemoryPressure = visualMemoryPressure;
+exports.conversationVisualBudget = conversationVisualBudget;
+exports.visualDataUrlBytes = visualDataUrlBytes;
+exports.planVisualRetention = planVisualRetention;
+exports.shouldRecycleIdleHost = shouldRecycleIdleHost;
+exports.describeVisualBudget = describeVisualBudget;
+const node_os_1 = require("node:os");
+const MIB = 1024 ** 2;
+const GIB = 1024 ** 3;
+const TIERS = {
+    roomy: {
+        maxSingleImageBytes: 2 * MIB,
+        maxRequestImageBytes: 48 * MIB,
+        maxRetainedImages: 12,
+        maxConversationVisualBytes: 192 * MIB,
+        recycleRssBytes: 1536 * MIB,
+    },
+    tight: {
+        maxSingleImageBytes: 768 * 1024,
+        maxRequestImageBytes: 16 * MIB,
+        maxRetainedImages: 6,
+        maxConversationVisualBytes: 64 * MIB,
+        recycleRssBytes: 1024 * MIB,
+    },
+    critical: {
+        maxSingleImageBytes: 320 * 1024,
+        maxRequestImageBytes: 6 * MIB,
+        maxRetainedImages: 3,
+        maxConversationVisualBytes: 24 * MIB,
+        recycleRssBytes: 640 * MIB,
+    },
+    severe: {
+        maxSingleImageBytes: 160 * 1024,
+        maxRequestImageBytes: 2 * MIB,
+        maxRetainedImages: 1,
+        maxConversationVisualBytes: 8 * MIB,
+        recycleRssBytes: 384 * MIB,
+    },
+};
+/** Pressure tier from available memory, with a total-RAM floor so 4 GB hosts never get a roomy budget. */
+function visualMemoryPressure(sample = {}) {
+    const totalBytes = Number.isFinite(sample.totalBytes) ? Number(sample.totalBytes) : (0, node_os_1.totalmem)();
+    const freeBytes = Number.isFinite(sample.freeBytes) ? Number(sample.freeBytes) : (0, node_os_1.freemem)();
+    if (Number.isFinite(sample.freeBytes) && Number(sample.freeBytes) <= 0) {
+        return { pressure: 'critical', reason: 'available memory is unknown' };
+    }
+    const available = Math.max(0, freeBytes);
+    if (available < 1.2 * GIB)
+        return { pressure: 'severe', reason: `only ${(available / MIB).toFixed(0)} MiB available` };
+    if (available < 3 * GIB)
+        return { pressure: 'critical', reason: `${(available / GIB).toFixed(1)} GiB available` };
+    if (available < 6 * GIB)
+        return { pressure: 'tight', reason: `${(available / GIB).toFixed(1)} GiB available` };
+    // A small machine rarely has 6 GiB free for long; never hand it the roomy caps.
+    if (Number.isFinite(totalBytes) && totalBytes > 0 && totalBytes < 8 * GIB) {
+        return { pressure: 'tight', reason: `installed RAM is only ${(totalBytes / GIB).toFixed(1)} GiB` };
+    }
+    return { pressure: 'roomy', reason: `${(available / GIB).toFixed(1)} GiB available` };
+}
+function conversationVisualBudget(sample = {}) {
+    const totalBytes = Number.isFinite(sample.totalBytes) ? Number(sample.totalBytes) : (0, node_os_1.totalmem)();
+    const base = visualMemoryPressure(sample);
+    const rssBytes = Math.max(0, Number(sample.rssBytes) || 0);
+    // V8 aborts on the process's own heap, not on the machine's free memory: the
+    // real host died at ~3017 MB while the machine still had memory available. So
+    // a process that already approaches its recycle watermark escalates one tier
+    // even when the machine looks roomy.
+    const escalate = {
+        roomy: 'tight',
+        tight: 'critical',
+        critical: 'severe',
+        severe: 'severe',
+    };
+    const approachingProcessLimit = rssBytes > 0 && rssBytes >= TIERS[base.pressure].recycleRssBytes * 0.6;
+    const pressure = approachingProcessLimit ? escalate[base.pressure] : base.pressure;
+    const reason = approachingProcessLimit
+        ? `${base.reason}; this host already uses ${Math.round(rssBytes / MIB)} MiB`
+        : base.reason;
+    const tier = TIERS[pressure];
+    // Clamp by installed RAM as well: an idle 4 GB machine must not accept a
+    // budget sized for a workstation.
+    const totalClamp = (fraction, floorBytes) => Number.isFinite(totalBytes) && totalBytes > 0 ? Math.max(floorBytes, Math.floor(totalBytes * fraction)) : Number.POSITIVE_INFINITY;
+    return {
+        pressure,
+        reason,
+        maxSingleImageBytes: tier.maxSingleImageBytes,
+        maxRequestImageBytes: Math.min(tier.maxRequestImageBytes, totalClamp(1 / 64, 2 * MIB)),
+        maxRetainedImages: tier.maxRetainedImages,
+        maxConversationVisualBytes: Math.min(tier.maxConversationVisualBytes, totalClamp(1 / 16, 8 * MIB)),
+        recycleRssBytes: Math.min(tier.recycleRssBytes, totalClamp(1 / 8, 256 * MIB)),
+    };
+}
+/**
+ * Heap cost of a data URL: the base64 payload length. This is what the provider
+ * request actually holds (a JS string of that many characters), and it matches
+ * the historical `dataUrl.length` cap this budget replaces.
+ */
+function visualDataUrlBytes(value) {
+    const text = String(value || '');
+    const comma = text.indexOf(',');
+    if (!text.startsWith('data:') || comma < 0)
+        return text.length;
+    return text.length - comma - 1;
+}
+/**
+ * Choose which visual entries stay materialized, newest first.
+ *
+ * `entries` must be ordered oldest → newest (the order they appear in the
+ * conversation); the plan keeps the newest ones within both the byte budget and
+ * the retained-image count, and reports how much was released.
+ */
+function planVisualRetention(entries, budget) {
+    const keep = new Set();
+    const released = [];
+    let releasedBytes = 0;
+    let retainedBytes = 0;
+    let retainedCount = 0;
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        const bytes = Math.max(0, Number(entry.bytes) || 0);
+        const fitsCount = retainedCount < Math.max(1, budget.maxRetainedImages);
+        const fitsBytes = retainedBytes + bytes <= budget.maxRequestImageBytes;
+        // The newest observation is always kept while it fits the single-image cap:
+        // dropping every screenshot would blind the agent, and the per-image cap
+        // already bounds what that one picture can cost.
+        const newestWithinSingleCap = index === entries.length - 1 && bytes <= Math.max(1, budget.maxSingleImageBytes);
+        if (newestWithinSingleCap || (fitsCount && fitsBytes)) {
+            keep.add(entry.key);
+            retainedBytes += bytes;
+            retainedCount += 1;
+            continue;
+        }
+        released.push(entry.key);
+        releasedBytes += bytes;
+    }
+    return { keep, released, releasedBytes, retainedBytes };
+}
+/** Should an idle host be recycled instead of reused? */
+function shouldRecycleIdleHost(rssBytes, budget) {
+    const value = Number(rssBytes);
+    if (!Number.isFinite(value) || value <= 0)
+        return false;
+    return value >= budget.recycleRssBytes;
+}
+/** Short human-readable summary used in work-status lines. */
+function describeVisualBudget(budget) {
+    return `${budget.pressure} (${budget.reason}; single image ≤ ${Math.round(budget.maxSingleImageBytes / 1024)} KiB, `
+        + `request visual ≤ ${Math.round(budget.maxRequestImageBytes / MIB)} MiB, keep ≤ ${budget.maxRetainedImages} screenshots, `
+        + `recycle host at ${Math.round(budget.recycleRssBytes / MIB)} MiB RSS)`;
+}
+//# sourceMappingURL=conversationVisualBudget.js.map

package/dist/core/electronUtilityAgentClient.d.ts

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import { NormalizedConversationTarget } from './conversationTarget';
 import { AgentMode, AgentWorkEvent, ConversationInputEnvelope, GuideReceipt } from './types';
 import { ConversationQueueAction, ConversationQueueActionInput } from './conversationKernel';
-import { UtilityAgentPromptResult, UtilityAutoRouteRatingResult, UtilityAgentSnapshotResult, UtilityAgentStopResult, UtilityConversationRewindResult, UtilityHostToolRequest, UtilityPromptRequest } from './utilityAgentProtocol';
+import { UtilityAgentPromptResult, UtilityAgentSnapshotResult, UtilityAgentStopResult, UtilityConversationRewindResult, UtilityHostToolRequest, UtilityPromptRequest } from './utilityAgentProtocol';
 type WindowsProcessTreeHelperRuntime = {
     kind: 'precompiled' | 'runtime_compile';
     path: string;
@@ -95,6 +95,8 @@ export declare class ElectronUtilityAgentClient {
     snapshot(options?: {
         window?: number;
         before?: number;
+        transcript?: 'auto' | 'force';
+        transcriptRevision?: string;
     }): Promise<UtilityAgentSnapshotResult>;
     rewind(messageIndex: number): Promise<UtilityConversationRewindResult>;
     requestStop(runId?: string): Promise<UtilityAgentStopResult>;
@@ -105,7 +107,6 @@ export declare class ElectronUtilityAgentClient {
         keepRecent?: number;
         force?: boolean;
     }): Promise<Record<string, unknown>>;
-    rateAutoRoute(score: number, routeId?: string): Promise<UtilityAutoRouteRatingResult>;
     setWorkRunExpanded(runId: string, expanded: boolean): Promise<boolean>;
     setMode(mode: AgentMode): Promise<AgentMode>;
     setModel(model: string): Promise<string>;

package/dist/core/electronUtilityAgentClient.js

@@ -52,6 +52,23 @@ const child_process_1 = require("child_process");
 const runtimeDiagnostics_1 = require("./runtimeDiagnostics");
 const runtimeLifecycle_1 = require("./runtimeLifecycle");
 const conversationTarget_1 = require("./conversationTarget");
+/**
+ * Explicit heap ceiling for one conversation host: half of what the machine has
+ * free right now, clamped to a range that is useful on an 8 GB laptop and still
+ * generous on a workstation. Reclamation (idle recycle + the snapshot/visual
+ * budgets) is what keeps the host below this; the ceiling only makes the failure
+ * mode predictable instead of a silent ~3 GB V8 abort.
+ */
+function hostHeapLimitMiB() {
+    let freeMiB = 0;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const os = require('node:os');
+        freeMiB = Math.floor(os.freemem() / 1024 ** 2);
+    }
+    catch { /* fall back to the lower bound */ }
+    return Math.max(1024, Math.min(4096, Math.floor(freeMiB / 2) || 1024));
+}
 // PowerShell startup can be slow on a cold or busy Windows host even though
 // the precompiled Toolhelp helper itself is healthy.
 const WINDOWS_TREE_SNAPSHOT_TIMEOUT_MS = 12_000;
@@ -943,6 +960,21 @@ class ElectronUtilityAgentClient {
     async startNewChild() {
         const child = electron_1.utilityProcess.fork(this.hostScript, [], {
             cwd: this.root,
+            /**
+             * dev-0.6.6 long-run stability: give the per-conversation Agent host an
+             * explicit heap ceiling derived from the machine's available memory
+             * instead of relying on the process default (the field crash aborted at
+             * ~3017 MB with no ceiling policy at all). Recycling an idle host that is
+             * over its budget is handled by the pool.
+             *
+             * `NEWMARK_HOST_HEAP_SNAPSHOT=1` additionally enables
+             * `--heapsnapshot-near-heap-limit` for diagnosis; it is off by default so
+             * no snapshot capability is active in normal runs.
+             */
+            execArgv: [
+                `--max-old-space-size=${hostHeapLimitMiB()}`,
+                ...(process.env.NEWMARK_HOST_HEAP_SNAPSHOT === '1' ? ['--heapsnapshot-near-heap-limit=1'] : []),
+            ],
             env: {
                 ...process.env,
                 NEWMARK_RUNTIME_ROOT: this.root,
@@ -1043,14 +1075,6 @@ class ElectronUtilityAgentClient {
         await this.start();
         return await this.request('context_compress', { target: this.target, options }, 120_000);
     }
-    async rateAutoRoute(score, routeId = '') {
-        await this.start();
-        return await this.request('rate_auto_route', {
-            target: this.target,
-            score,
-            routeId: String(routeId || ''),
-        }, 5_000);
-    }
     async setWorkRunExpanded(runId, expanded) {
         await this.start();
         return !!await this.request('set_work_run_expanded', { target: this.target, runId, expanded }, 5_000);

package/dist/core/electronUtilityRuntimePool.d.ts

@@ -1,8 +1,9 @@
+import { type ConversationVisualBudget } from './conversationVisualBudget';
 import { AgentMode, AgentWorkEvent, ConversationInputEnvelope, GuideReceipt } from './types';
 import { ConversationQueueAction, ConversationQueueActionInput } from './conversationKernel';
 import { ConversationRuntimeTarget, NormalizedConversationTarget } from './conversationTarget';
 import { UtilityHostToolHandler } from './electronUtilityAgentClient';
-import { UtilityAgentPromptResult, UtilityAutoRouteRatingResult, UtilityConversationRewindResult, UtilityAgentSnapshotResult, UtilityAgentStopResult, UtilityPromptRequest } from './utilityAgentProtocol';
+import { UtilityAgentPromptResult, UtilityConversationRewindResult, UtilityAgentSnapshotResult, UtilityAgentStopResult, UtilityPromptRequest } from './utilityAgentProtocol';
 export interface ElectronTargetRuntimeClient {
     subscribe(listener: (event: AgentWorkEvent) => void): () => void;
     setHostToolHandler(handler: UtilityHostToolHandler | null): void;
@@ -10,6 +11,8 @@ export interface ElectronTargetRuntimeClient {
     snapshot(options?: {
         window?: number;
         before?: number;
+        transcript?: 'auto' | 'force';
+        transcriptRevision?: string;
     }): Promise<UtilityAgentSnapshotResult>;
     rewind(messageIndex: number): Promise<UtilityConversationRewindResult>;
     requestStop(runId?: string): Promise<UtilityAgentStopResult>;
@@ -20,7 +23,6 @@ export interface ElectronTargetRuntimeClient {
         keepRecent?: number;
         force?: boolean;
     }): Promise<Record<string, unknown>>;
-    rateAutoRoute?(score: number, routeId?: string): Promise<UtilityAutoRouteRatingResult>;
     setWorkRunExpanded(runId: string, expanded: boolean): Promise<boolean>;
     setMode?(mode: AgentMode): Promise<AgentMode>;
     setModel?(model: string): Promise<string>;
@@ -52,6 +54,15 @@ export interface ElectronUtilityRuntimePoolOptions {
     stopRequestTimeoutMs?: number;
     forceStopAckTimeoutMs?: number;
     maxResidentRuntimes?: number;
+    /** Resident bytes of a host process, supplied by the Electron main process. */
+    sampleProcessMemoryBytes?: (pid: number) => number;
+    /**
+     * dev-0.6.6: per-conversation visual budget. Hosts that exceed its RSS
+     * watermark are recycled when idle instead of being reused, so a conversation
+     * that flooded memory through ComputerUse/BrowserControl observations starts
+     * from a clean process next time.
+     */
+    visualBudget?: () => ConversationVisualBudget;
 }
 /** One real Electron utilityProcess per active ConversationTarget. */
 export declare class ElectronUtilityRuntimePool {
@@ -72,9 +83,18 @@ export declare class ElectronUtilityRuntimePool {
     subscribe(listener: (event: AgentWorkEvent) => void): () => void;
     setHostToolHandler(handler: UtilityHostToolHandler | null): void;
     prompt(params: UtilityPromptRequest): Promise<UtilityAgentPromptResult>;
+    /**
+     * Stop an idle host whose resident memory is still above the machine-derived
+     * watermark after its turn settled. Safe by construction: it only runs after
+     * `release()` and skips anything that is busy, stopping, restarting or
+     * disposing, and the runtime pool rebuilds a fresh host on the next request.
+     */
+    private recycleAfterSettlementIfOverBudget;
     snapshot(target: ConversationRuntimeTarget, options?: {
         window?: number;
         before?: number;
+        transcript?: 'auto' | 'force';
+        transcriptRevision?: string;
     }): Promise<UtilityAgentSnapshotResult>;
     rewind(target: ConversationRuntimeTarget, messageIndex: number): Promise<UtilityConversationRewindResult>;
     requestStop(target: ConversationRuntimeTarget, runId?: string): Promise<ElectronPoolStopResult>;
@@ -85,7 +105,6 @@ export declare class ElectronUtilityRuntimePool {
         keepRecent?: number;
         force?: boolean;
     }): Promise<Record<string, unknown>>;
-    rateAutoRoute(target: ConversationRuntimeTarget, score: number, routeId?: string): Promise<UtilityAutoRouteRatingResult>;
     setWorkRunExpanded(target: ConversationRuntimeTarget, runId: string, expanded: boolean): Promise<boolean>;
     setInputMode(target: ConversationRuntimeTarget, mode: string): Promise<'guide' | 'next' | null>;
     setMode(target: ConversationRuntimeTarget, mode: AgentMode): Promise<AgentMode | null>;
@@ -130,6 +149,12 @@ export declare class ElectronUtilityRuntimePool {
     private evictLeastRecentlyUsedIdle;
     private scheduleIdle;
     private evictIfIdle;
+    /**
+     * Recycle every idle host whose resident memory is over the machine's visual
+     * budget. Returns the runtime keys that were recycled.
+     */
+    reclaimIdleHostsOverMemory(): Promise<string[]>;
+    private hostOverMemoryBudget;
     private findEntry;
     private gracefulSupervisorResult;
     private forceTerminateEntry;

package/dist/core/electronUtilityRuntimePool.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ElectronUtilityRuntimePool = void 0;
+const runtimeMemoryBudget_1 = require("./runtimeMemoryBudget");
+const conversationVisualBudget_1 = require("./conversationVisualBudget");
 const conversationTarget_1 = require("./conversationTarget");
 const electronUtilityAgentClient_1 = require("./electronUtilityAgentClient");
 const runtimePoolCapacity_1 = require("./runtimePoolCapacity");
@@ -48,10 +50,48 @@ class ElectronUtilityRuntimePool {
         }
         finally {
             this.release(entry, true);
+            // dev-0.6.6: a long turn can leave the host far above its budget even
+            // after it settles. Recycling right after settlement (never mid-turn — the
+            // promise has already resolved here) gives the next turn a clean process
+            // instead of waiting for the idle TTL.
+            void this.recycleAfterSettlementIfOverBudget(entry);
         }
     }
+    /**
+     * Stop an idle host whose resident memory is still above the machine-derived
+     * watermark after its turn settled. Safe by construction: it only runs after
+     * `release()` and skips anything that is busy, stopping, restarting or
+     * disposing, and the runtime pool rebuilds a fresh host on the next request.
+     */
+    async recycleAfterSettlementIfOverBudget(entry) {
+        const runtimeKey = entry.target.runtimeKey;
+        if (this.entries.get(runtimeKey) !== entry)
+            return;
+        if (entry.activeOperations > 0 || entry.stopIntent || this.restarting.has(runtimeKey) || this.disposing.has(runtimeKey))
+            return;
+        if (!this.hostOverMemoryBudget(entry))
+            return;
+        try {
+            await this.stopEntry(entry);
+        }
+        catch { /* a host that refuses to stop is left to the idle sweep */ }
+    }
     async snapshot(target, options = {}) {
-        const entry = await this.acquire((0, conversationTarget_1.normalizeConversationTarget)(target));
+        const normalized = (0, conversationTarget_1.normalizeConversationTarget)(target);
+        const wantsDefaultWindow = options.before == null && (options.window == null || options.window === 200);
+        // A read must survive the runtime's own teardown. Clients poll this on a
+        // timer (the paired mobile client polls conversation-ui-state every second)
+        // and an archive deliberately force-stops the target for several seconds;
+        // answering 500 for that window makes the remote UI drop the conversation
+        // it is looking at. Earlier pages really are unavailable mid-teardown, so
+        // only the default window is served from the supervisor's cached view.
+        if (wantsDefaultWindow) {
+            const pending = this.entries.get(normalized.runtimeKey);
+            if (pending && (this.disposing.has(normalized.runtimeKey) || this.restarting.has(normalized.runtimeKey))) {
+                return this.supervisorSnapshot(pending);
+            }
+        }
+        const entry = await this.acquire(normalized);
         let scheduleIdle = false;
         try {
             const customWindow = options.before != null || (options.window != null && options.window !== 200);
@@ -234,19 +274,6 @@ class ElectronUtilityRuntimePool {
             this.release(entry, true);
         }
     }
-    async rateAutoRoute(target, score, routeId = '') {
-        const normalized = (0, conversationTarget_1.normalizeConversationTarget)(target);
-        const entry = await this.acquireExisting(normalized);
-        if (!entry || !entry.client.rateAutoRoute) {
-            return { ok: false, reason: 'no_active_auto_route' };
-        }
-        try {
-            return await entry.client.rateAutoRoute(score, routeId);
-        }
-        finally {
-            this.release(entry, true);
-        }
-    }
     async setWorkRunExpanded(target, runId, expanded) {
         const entry = await this.acquire((0, conversationTarget_1.normalizeConversationTarget)(target));
         try {
@@ -607,13 +634,9 @@ class ElectronUtilityRuntimePool {
         return this.accessSequence;
     }
     maxResidentRuntimes() {
-        // The pool hosts one utility runtime per active conversation target.
-        // A small default (2) silently blocked users from running more than two
-        // conversations at once with "utility runtime pool capacity reached".
-        // Idle runtimes are still evicted on LRU after the idle TTL, so a higher
-        // default bounds memory by activity, not by an arbitrary conversation cap.
-        const configured = Number(this.options.maxResidentRuntimes ?? 8);
-        return Number.isFinite(configured) ? Math.max(1, Math.floor(configured)) : 8;
+        const fallback = (0, runtimeMemoryBudget_1.runtimeMemoryBudget)().maxResidentRuntimes;
+        const configured = Number(this.options.maxResidentRuntimes ?? fallback);
+        return Number.isFinite(configured) ? Math.max(1, Math.floor(configured)) : fallback;
     }
     async serializeCapacity(operation) {
         const previous = this.capacityTail;
@@ -661,7 +684,7 @@ class ElectronUtilityRuntimePool {
     }
     scheduleIdle(entry) {
         this.touch(entry);
-        const ttl = Math.max(10, Number(this.options.idleTtlMs ?? 5 * 60 * 1000));
+        const ttl = Math.max(10, Number(this.options.idleTtlMs ?? (0, runtimeMemoryBudget_1.runtimeMemoryBudget)().idleTtlMs));
         const timer = setTimeout(() => {
             void this.evictIfIdle(entry.target.runtimeKey, entry.lastUsedAt);
         }, ttl);
@@ -677,6 +700,13 @@ class ElectronUtilityRuntimePool {
                 this.scheduleIdle(entry);
                 return;
             }
+            // dev-0.6.6: an idle host that grew past this machine's visual budget
+            // (long ComputerUse/BrowserControl conversations) is recycled rather than
+            // reused, so the next turn starts from a clean process.
+            if (this.hostOverMemoryBudget(entry)) {
+                await this.stopEntry(entry);
+                return;
+            }
             let snapshot;
             try {
                 snapshot = await entry.client.snapshot();
@@ -697,6 +727,42 @@ class ElectronUtilityRuntimePool {
             await this.stopEntry(entry);
         });
     }
+    /**
+     * Recycle every idle host whose resident memory is over the machine's visual
+     * budget. Returns the runtime keys that were recycled.
+     */
+    async reclaimIdleHostsOverMemory() {
+        const recycled = [];
+        for (const entry of Array.from(this.entries.values())) {
+            const runtimeKey = entry.target.runtimeKey;
+            if (entry.activeOperations > 0 || entry.stopIntent || this.restarting.has(runtimeKey) || this.disposing.has(runtimeKey))
+                continue;
+            if (!this.hostOverMemoryBudget(entry))
+                continue;
+            try {
+                await this.stopEntry(entry);
+                recycled.push(runtimeKey);
+            }
+            catch { /* a host that cannot be stopped stays until it exits by itself */ }
+        }
+        return recycled;
+    }
+    hostOverMemoryBudget(entry) {
+        const sampler = this.options.sampleProcessMemoryBytes;
+        if (!sampler)
+            return false;
+        const pid = Number(entry.client.status().pid || 0);
+        if (!pid)
+            return false;
+        let rssBytes = 0;
+        try {
+            rssBytes = Number(sampler(pid) || 0);
+        }
+        catch {
+            return false;
+        }
+        return (0, conversationVisualBudget_1.shouldRecycleIdleHost)(rssBytes, (this.options.visualBudget || conversationVisualBudget_1.conversationVisualBudget)());
+    }
     findEntry(target) {
         const direct = this.entries.get((0, conversationTarget_1.normalizeConversationTarget)(target).runtimeKey);
         if (direct)
@@ -826,17 +892,20 @@ class ElectronUtilityRuntimePool {
         return true;
     }
     supervisorSnapshot(entry) {
+        // `stopIntent` is present for a requested stop; a force stop run driven by
+        // the archive path may reach here purely through `disposing`/`restarting`.
         const intent = entry.stopIntent;
         const cached = entry.lastSnapshot;
         return {
             ...cached,
             target: entry.target,
             runtime: {
+                ...(cached?.runtime || {}),
                 target: entry.target,
                 workspaceKey: entry.target.workspaceKey,
                 runtimeKey: entry.target.runtimeKey,
-                runId: intent.runId,
-                generation: intent.generation,
+                runId: intent?.runId || entry.lastRunId,
+                generation: intent?.generation || entry.lastGeneration,
                 running: true,
                 stopRequested: true,
                 workRuns: cached?.runtime?.workRuns || [],