@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.226

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/adapter.js

@@ -1,11 +1,13 @@
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { copyToClipboard, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, } from "@earendil-works/pi-coding-agent";
-import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiSnapshot, } from "../owned-ui-contracts/index.js";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { configureOwnedHttpDispatcher } from "./http-dispatcher.js";
+import { copyToClipboard, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
+import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiSnapshot, } from "../../../contracts/owned-ui/index.js";
 import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "./workflows.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
 import { PiSessionCommandIntegration } from "./session-integration.js";
@@ -16,19 +18,25 @@ const execFileAsync = promisify(execFile);
  * that a streaming burst never holds input, large enough that an ordinary turn is one
  * batch.
  */
-const EVENT_DELIVERY_BATCH = 16;
+// Performance: deliver at most one engine event per event-loop turn. Transcript updates can
+// be expensive in long sessions; a larger synchronous batch starves terminal
+// input and makes an in-progress mouse selection appear frozen.
+const EVENT_DELIVERY_BATCH = 1;
+const TOOL_UPDATE_COALESCE_MS = 50;
 const DEFAULT_SURFACE = {
     columns: 100,
     rows: 32,
     focusedRegion: "editor",
     hardwareCursor: false,
 };
+/** Owns the pinned Pi session lifecycle and translates its events into the neutral agent-engine contract. */
 export class PiEngineAdapter {
     #runtimeFactory;
     #checkPackageUpdates;
     #cwd;
     #agentDir;
     #sessionId;
+    #sessionPath;
     #workflowHost;
     #workflowInteraction;
     #listeners = new Set();
@@ -64,6 +72,10 @@ export class PiEngineAdapter {
     #messageBlockIds = new WeakMap();
     #messageFallbackIds = new Map();
     #toolBlockIds = new Map();
+    #transcriptImageAssets = new Map();
+    #pendingToolUpdates = new Map();
+    #toolUpdateFlush = null;
+    #usageCache;
     #nextBlockSequence = 0;
     #diagnostics = [];
     #eventQueue = [];
@@ -77,12 +89,16 @@ export class PiEngineAdapter {
     #extensionShutdown;
     #extensionBound = false;
     #disposed = false;
-    /** Lists the themes installed on this machine, when the caller supplies one. */
+    #settingsProductMode;
+    #projectTrustPrompt;
+    #settingsIntegration;
+    #settingsIntegrationManager;
     #availableThemes;
     constructor(options = {}) {
         this.#cwd = options.cwd ?? process.cwd();
         this.#agentDir = options.agentDir ?? getAgentDir();
         this.#sessionId = options.sessionId ?? "owned-session-1";
+        this.#sessionPath = options.sessionPath;
         this.#runtimeFactory = options.createRuntime ?? createDefaultPiRuntime;
         this.#checkPackageUpdates = options.checkPackageUpdates
             ?? (options.createRuntime
@@ -90,6 +106,8 @@ export class PiEngineAdapter {
                 : settingsManager => checkDefaultPiPackageUpdates(this.#cwd, this.#agentDir, settingsManager));
         this.#workflowHost = options.workflowHost ?? defaultWorkflowHost();
         this.#availableThemes = options.availableThemes ?? null;
+        this.#settingsProductMode = options.settingsProductMode ?? "bare";
+        this.#projectTrustPrompt = options.projectTrustPrompt;
         this.#workflowInteraction = { prompt: async () => null, notify() { } };
     }
     setWorkflowInteractionHost(interaction) {
@@ -104,6 +122,29 @@ export class PiEngineAdapter {
     get agentDir() {
         return this.#agentDir;
     }
+    resolveTranscriptImage(assetId) {
+        return this.#transcriptImageAssets.get(assetId) ?? null;
+    }
+    currentSessionFile() {
+        const value = this.#session?.sessionManager?.getSessionFile?.();
+        return typeof value === "string" && value.length > 0 ? value : null;
+    }
+    currentSessionResumeMetadata() {
+        const manager = this.#session?.sessionManager;
+        if (manager === undefined
+            || typeof manager.isPersisted !== "function"
+            || typeof manager.getSessionId !== "function"
+            || typeof manager.getSessionDir !== "function"
+            || typeof manager.usesDefaultSessionDir !== "function"
+            || manager.isPersisted() !== true
+            || this.currentSessionFile() === null)
+            return null;
+        const sessionId = manager.getSessionId();
+        const sessionDir = manager.getSessionDir();
+        if (!sessionId || !sessionDir)
+            return null;
+        return { sessionId, sessionDir, usesDefaultSessionDir: manager.usesDefaultSessionDir() };
+    }
     get disposed() {
         return this.#disposed;
     }
@@ -114,6 +155,8 @@ export class PiEngineAdapter {
             cwd: this.#cwd,
             agentDir: this.#agentDir,
             sessionId: this.#sessionId,
+            ...(this.#sessionPath === undefined ? {} : { sessionPath: this.#sessionPath }),
+            ...(this.#projectTrustPrompt === undefined ? {} : { projectTrustPrompt: this.#projectTrustPrompt }),
         }).catch(error => {
             this.#lifecycle = "failed";
             this.#addDiagnostic("error", "engine-startup", error instanceof Error ? error.message : String(error), false);
@@ -133,6 +176,7 @@ export class PiEngineAdapter {
             this.#addDiagnostic(diagnostic.type === "error" ? "error" : diagnostic.type === "warning" ? "warning" : "info", "engine-startup", diagnostic.message, diagnostic.type !== "error");
         }
         this.#bindSession(runtime.session);
+        await this.#announceChangelog(runtime.services.settingsManager);
         this.#lifecycle = "ready";
         this.#editor = { ...this.#editor, submitEnabled: true };
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
@@ -140,6 +184,19 @@ export class PiEngineAdapter {
         void this.#announcePackageUpdates(runtime.services.settingsManager);
         return this.view();
     }
+    async #announceChangelog(settingsManager) {
+        if (!settingsManager || typeof settingsManager.getLastChangelogVersion !== "function"
+            || typeof settingsManager.setLastChangelogVersion !== "function")
+            return;
+        if (settingsManager.getLastChangelogVersion() === VERSION)
+            return;
+        const markdown = await this.#workflowHost.readChangelog().catch(() => "");
+        if (markdown.trim().length > 0) {
+            this.#addDiagnostic("info", settingsManager.getCollapseChangelog() ? "changelog-collapsed" : "changelog-expanded", markdown, true);
+        }
+        settingsManager.setLastChangelogVersion(VERSION);
+        await settingsManager.flush();
+    }
     async #announcePackageUpdates(settingsManager) {
         if (process.env.PI_OFFLINE)
             return;
@@ -162,6 +219,7 @@ export class PiEngineAdapter {
         return () => this.#listeners.delete(listener);
     }
     async flushEvents() {
+        this.#flushPendingToolUpdates();
         while (this.#eventQueueProcessing)
             await this.#eventQueueProcessing;
     }
@@ -424,16 +482,107 @@ export class PiEngineAdapter {
     /** Settings port for the live runtime, or null before the runtime is available. */
     settingsPort() {
         const settings = this.#runtime?.services.settingsManager;
-        if (!settings)
+        if (!settings || typeof settings.getCompactionEnabled !== "function")
             return null;
-        const session = this.#runtime?.session;
-        return new PiSettingsIntegration(settings, {
-            ...(this.#availableThemes === null ? {} : { themes: this.#availableThemes }),
-            thinkingLevels: () => {
-                const levels = session?.getAvailableThinkingLevels?.();
-                return Array.isArray(levels) ? levels.map(level => String(level)) : [];
-            },
-        });
+        if (this.#settingsIntegration === undefined || this.#settingsIntegrationManager !== settings) {
+            this.#settingsIntegrationManager = settings;
+            configureOwnedHttpDispatcher(settings.getHttpIdleTimeoutMs());
+            this.#settingsIntegration = new PiSettingsIntegration(settings, {
+                ...(this.#availableThemes === null ? {} : { themes: this.#availableThemes }),
+                thinkingLevels: () => {
+                    const levels = this.#runtime?.session?.getAvailableThinkingLevels?.();
+                    return Array.isArray(levels) ? levels.map(level => String(level)) : [];
+                },
+                productMode: this.#settingsProductMode,
+            });
+            this.#settingsIntegration.bindOwner("shell", {
+                enableSkillCommands: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Skill commands value is invalid");
+                        settings.setEnableSkillCommands(value);
+                    } },
+                doubleEscapeAction: { apply: value => {
+                        if (value !== "tree" && value !== "fork" && value !== "none")
+                            throw new TypeError("Double-Escape action is invalid");
+                        settings.setDoubleEscapeAction(value);
+                    } },
+                treeFilterMode: { apply: value => {
+                        if (value !== "default" && value !== "no-tools" && value !== "user-only" && value !== "labeled-only" && value !== "all")
+                            throw new TypeError("Tree filter mode is invalid");
+                        settings.setTreeFilterMode(value);
+                    } },
+                showCacheMissNotices: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Cache-miss notice setting is invalid");
+                        settings.setShowCacheMissNotices(value);
+                    } },
+            });
+            this.#settingsIntegration.bindOwner("startup", {
+                // Invariant: deferred application is the owner operation: the next preflight reads
+                // the persisted default before constructing project-backed services.
+                defaultProjectTrust: { apply() { } },
+                collapseChangelog: { apply() { } },
+            });
+            this.#settingsIntegration.bindOwner("agent", {
+                autoCompact: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Auto compact value is invalid");
+                        this.#requireWorkflowSession().setAutoCompactionEnabled(value);
+                    } },
+                autoResizeImages: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Auto-resize images value is invalid");
+                        settings.setImageAutoResize(value);
+                    } },
+                blockImages: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Block images value is invalid");
+                        settings.setBlockImages(value);
+                    } },
+                steeringMode: { apply: value => {
+                        if (value !== "all" && value !== "one-at-a-time")
+                            throw new TypeError("Steering mode is invalid");
+                        this.#requireWorkflowSession().setSteeringMode(value);
+                    } },
+                followUpMode: { apply: value => {
+                        if (value !== "all" && value !== "one-at-a-time")
+                            throw new TypeError("Follow-up mode is invalid");
+                        this.#requireWorkflowSession().setFollowUpMode(value);
+                    } },
+                transport: { apply: value => {
+                        if (value !== "sse" && value !== "websocket" && value !== "websocket-cached" && value !== "auto")
+                            throw new TypeError("Transport is invalid");
+                        this.#requireWorkflowSession().agent.transport = value;
+                    } },
+                httpIdleTimeoutMs: { apply: value => {
+                        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+                            throw new TypeError("HTTP idle timeout is invalid");
+                        // Invariant: provider streaming reads the manager per request; global fetch uses
+                        // the matching owned dispatcher and zero maps to disabled semantics.
+                        configureOwnedHttpDispatcher(value);
+                        settings.setHttpIdleTimeoutMs(value);
+                    } },
+                thinkingLevel: { apply: value => {
+                        if (!isThinkingLevel(value))
+                            throw new TypeError("Thinking level is invalid");
+                        this.#requireWorkflowSession().setThinkingLevel(value);
+                        this.#thinkingLevel = readThinkingLevel(this.#requireWorkflowSession().thinkingLevel);
+                        this.#emitView();
+                    } },
+                warnings: { apply: value => {
+                        if (!isRecord(value) || Object.values(value).some(flag => typeof flag !== "boolean"))
+                            throw new TypeError("Warnings setting is invalid");
+                        settings.setWarnings(value);
+                    } },
+            });
+        }
+        return this.#settingsIntegration;
+    }
+    bindSettingsOwner(owner, handlers) {
+        const settings = this.settingsPort();
+        if (settings === null)
+            return () => { };
+        return settings.bindOwner(owner, handlers);
     }
     pinnedModelSelectorContext() {
         const session = this.#requireWorkflowSession();
@@ -710,9 +859,9 @@ export class PiEngineAdapter {
             excludeFromContext,
         };
     }
-    applyPinnedSettingValue(callback, value) {
+    async applyPinnedSettingValue(callback, value) {
         try {
-            return this.#applyPinnedSetting(callback, value, true);
+            return await this.#applyPinnedSetting(callback, value, true);
         }
         catch (error) {
             return workflowResult("settings", "failed", error instanceof Error ? error.message : String(error));
@@ -742,7 +891,7 @@ export class PiEngineAdapter {
                 ...this.#status,
                 diagnostics: [...this.#status.diagnostics],
                 badges: [...this.#status.badges],
-                usage: this.#readUsage(),
+                usage: this.#usageCache ??= this.#readUsage(),
                 footer: {
                     branch: this.#gitBranch,
                     sessionName: this.#session?.sessionManager?.getSessionName() ?? null,
@@ -808,6 +957,12 @@ export class PiEngineAdapter {
         if (this.#disposed)
             return;
         this.#disposed = true;
+        if (this.#toolUpdateFlush !== null) {
+            clearTimeout(this.#toolUpdateFlush);
+            this.#toolUpdateFlush = null;
+        }
+        this.#pendingToolUpdates.clear();
+        this.#transcriptImageAssets.clear();
         this.#extensionBound = false;
         this.#extensionUi = undefined;
         this.#extensionShutdown = undefined;
@@ -833,7 +988,7 @@ export class PiEngineAdapter {
             case "settings": {
                 if (!selection)
                     return workflowResult(request.command, "failed", "Settings requires the owned settings controller");
-                return this.#applyPinnedSetting(selection);
+                return await this.#applyPinnedSetting(selection);
             }
             case "model": {
                 const reference = selection ?? argument;
@@ -1223,7 +1378,7 @@ export class PiEngineAdapter {
             return [];
         return sessionInfoOptions(await SessionManager.list(cwd, typeof sessionDir === "string" ? sessionDir : undefined));
     }
-    #applyPinnedSetting(selection, selectedValue, hasSelectedValue = false) {
+    async #applyPinnedSetting(selection, selectedValue, hasSelectedValue = false) {
         if (!PINNED_PI_SETTINGS_CALLBACKS.includes(selection)) {
             return workflowResult("settings", "failed", `Unknown setting callback: ${selection}`);
         }
@@ -1270,29 +1425,19 @@ export class PiEngineAdapter {
             selectedValue = currentValues[callback];
             hasSelectedValue = true;
         }
-        const settings = this.#runtime?.services.settingsManager;
-        if (!settings)
+        const port = this.settingsPort();
+        if (port === null)
             return workflowResult("settings", "failed", "Settings are unavailable");
-        const session = this.#requireWorkflowSession();
-        if (callback === "onThinkingLevelChange") {
-            if (!isThinkingLevel(selectedValue))
-                return workflowResult("settings", "failed", "Thinking level is invalid");
-            session.setThinkingLevel(selectedValue);
-        }
-        else {
-            const key = settingKeyForCallback(callback);
-            if (key === null)
-                return workflowResult("settings", "failed", `${settingLabel(callback)} is unavailable in this runtime`);
-            const value = agentJsonValue(selectedValue);
-            if (callback === "onAutoCompactChange") {
-                if (typeof value !== "boolean")
-                    return workflowResult("settings", "failed", "Auto compact value is invalid");
-                session.setAutoCompactionEnabled?.(value);
-            }
-            new PiSettingsIntegration(settings).writeSettingNow(key, value);
+        const key = settingKeyForCallback(callback);
+        if (key === null)
+            return workflowResult("settings", "failed", `${settingLabel(callback)} is unavailable in this runtime`);
+        const result = await port.writeSetting(key, agentJsonValue(selectedValue));
+        if (result.status === "failed" || result.status === "unavailable") {
+            return workflowResult("settings", "failed", result.failure ?? result.limitationReason ?? `${settingLabel(callback)} is unavailable`);
         }
         this.#emitView();
-        return workflowResult("settings", "completed", `${settingLabel(callback)}: ${String(selectedValue)}`);
+        const suffix = result.status === "deferred" ? ` (${result.application})` : "";
+        return workflowResult("settings", "completed", `${settingLabel(callback)}: ${String(selectedValue)}${suffix}`);
     }
     async #perform(command) {
         const runtime = this.#runtime;
@@ -1307,7 +1452,11 @@ export class PiEngineAdapter {
             case "retry":
             case "compact": {
                 const result = await this.#sessionCommands?.execute(command.type === "prompt" || command.type === "steer" || command.type === "follow-up"
-                    ? { type: command.type, text: command.text }
+                    ? {
+                        type: command.type,
+                        text: command.text,
+                        ...(command.images === undefined ? {} : { images: [...command.images] }),
+                    }
                     : { type: command.type });
                 if (!result || result.outcome === "rejected" || result.outcome === "failed") {
                     throw new Error(command.type === "retry" ? "no previous prompt is available to retry" : `Pi session command failed: ${command.type}`);
@@ -1367,6 +1516,7 @@ export class PiEngineAdapter {
         this.#activeModel = readModel(session.model);
         this.#reconcileActiveModelAvailability();
         this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
+        this.#transcriptImageAssets.clear();
         this.#rebuildTranscript(session.messages, "finalized");
         this.#unsubscribe = session.subscribe(event => this.#handlePiEvent(event));
         if (this.#extensionUi !== undefined)
@@ -1416,23 +1566,24 @@ export class PiEngineAdapter {
             this.#emitView();
         }
     }
-    /**
-     * Replaces the transcript and the index that finds a block by its identifier. Every
-     * lookup goes through the index, so streaming a chunk costs the same in a long session
-     * as in a new one.
-     */
+    // Performance: replacing the transcript rebuilds its index so block lookup stays constant-time.
     #setTranscript(blocks) {
         this.#transcript = blocks;
         this.#transcriptIndex.clear();
         for (const [index, block] of blocks.entries())
             this.#transcriptIndex.set(block.id, index);
+        const retainedAssets = new Set(blocks.flatMap(block => block.imageReferences?.map(reference => reference.assetId) ?? []));
+        for (const assetId of this.#transcriptImageAssets.keys()) {
+            if (!retainedAssets.has(assetId))
+                this.#transcriptImageAssets.delete(assetId);
+        }
         this.#transcriptSnapshot = undefined;
     }
     #transcriptBlock(id) {
         const index = this.#transcriptIndex.get(id);
         return index === undefined ? undefined : this.#transcript[index];
     }
-    /** Shows the state named by `kind`, which becomes the state a later end can clear. */
+    // Invariant: the named work state is the only state a matching end may clear.
     #enterWorkState(kind, message) {
         const wasBusy = this.#lifecycle === "busy";
         this.#statusKind = kind;
@@ -1442,21 +1593,16 @@ export class PiEngineAdapter {
             this.#emitEvent({ type: "session-lifecycle", lifecycle: "busy", reason: null });
         this.#emitEvent({ type: "status", status: this.#status });
     }
-    /**
-     * Ends one named state. A state the shell is not in is left alone, so a finished
-     * compaction or retry cannot clear the working state it never replaced. While the run
-     * continues, ending either of those returns to working rather than to idle.
-     */
+    // Invariant: ending retry or compaction cannot clear a different active work state.
     #endWorkState(kind) {
         if (this.#statusKind !== kind)
             return;
         if (this.#agentRunActive) {
-            this.#enterWorkState("working", "Working...");
+            this.#enterWorkState("working", "Working");
             return;
         }
         this.#leaveWorkStates();
     }
-    /** Leaves every work state and reports the session idle. */
     #leaveWorkStates() {
         this.#statusKind = null;
         this.#lifecycle = "ready";
@@ -1467,10 +1613,15 @@ export class PiEngineAdapter {
     #handlePiEvent(event) {
         if (!isRecord(event) || typeof event.type !== "string")
             return;
+        // Invariant: usage moves at message and lifecycle boundaries, not with stream chunks, so the
+        // two streaming event kinds keep the memo and everything else drops it.
+        if (event.type !== "message_update" && event.type !== "tool_execution_update")
+            this.#usageCache = undefined;
         switch (event.type) {
             case "agent_start":
                 this.#agentRunActive = true;
-                this.#enterWorkState("working", "Working...");
+                this.#emitEvent({ type: "agent-run-started" });
+                this.#enterWorkState("working", "Working");
                 return;
             case "message_start":
                 this.#upsertMessageBlock(event.message, "live");
@@ -1479,7 +1630,7 @@ export class PiEngineAdapter {
                 const delta = isRecord(event.assistantMessageEvent) && typeof event.assistantMessageEvent.delta === "string"
                     ? event.assistantMessageEvent.delta
                     : undefined;
-                // The delta is folded in before the block is stored, so a chunk is one update to
+                // Invariant: the delta is folded in before the block is stored, so a chunk is one update to
                 // one block rather than a store without the delta followed by a store with it.
                 const blocks = this.#messageBlocks(event.message, "live", this.#transcript.length);
                 for (const [index, block] of blocks.entries()) {
@@ -1491,6 +1642,12 @@ export class PiEngineAdapter {
             }
             case "message_end":
                 this.#upsertMessageBlock(event.message, "finalized");
+                // Compatibility: preserve the same semantic boundary v2 counted. Transcript block
+                // finalization is intentionally not a substitute: rebuilds, retries,
+                // thinking parts, and tool rows can all finalize independently.
+                if (isRecord(event.message) && event.message.role === "assistant") {
+                    this.#emitEvent({ type: "assistant-message-completed" });
+                }
                 return;
             case "turn_end":
                 this.#upsertMessageBlock(event.message, "finalized");
@@ -1500,10 +1657,17 @@ export class PiEngineAdapter {
                 }
                 return;
             case "tool_execution_start":
-            case "tool_execution_update":
-            case "tool_execution_end":
+            case "tool_execution_end": {
+                // Concurrency: the end supersedes any update still waiting on the coalescing timer.
+                const toolCallId = stringValue(event.toolCallId);
+                if (toolCallId !== undefined)
+                    this.#pendingToolUpdates.delete(toolCallId);
                 this.#upsertToolExecutionBlock(event);
                 return;
+            }
+            case "tool_execution_update":
+                this.#coalesceToolExecutionUpdate(event);
+                return;
             case "agent_settled":
             case "agent_end": {
                 if (event.type === "agent_end" && event.willRetry === true)
@@ -1515,7 +1679,7 @@ export class PiEngineAdapter {
                     this.#rebuildTranscript(finalMessages, "finalized");
                 else
                     this.#setTranscript(this.#transcript.map(block => block.status === "live" ? { ...block, status: "finalized" } : block));
-                // Ending a turn leaves the working state, as the recorded pinned baseline does, but
+                // Compatibility: ending a turn leaves the working state, as the recorded pinned baseline does, but
                 // it leaves only that state: a compaction or retry being shown outlives the turn
                 // that ended under it. Settlement ends the run, and with it every state — the
                 // engine ends a turn for each continuation it makes and settles once.
@@ -1541,13 +1705,13 @@ export class PiEngineAdapter {
                 return;
             }
             case "auto_retry_start":
-                this.#enterWorkState("retry", "Retrying…");
+                this.#enterWorkState("retry", "Retrying");
                 return;
             case "auto_retry_end":
                 this.#endWorkState("retry");
                 return;
             case "compaction_start":
-                this.#enterWorkState("compaction", "Compacting…");
+                this.#enterWorkState("compaction", "Compacting");
                 return;
             case "compaction_end":
                 this.#endWorkState("compaction");
@@ -1640,7 +1804,7 @@ export class PiEngineAdapter {
                 }
             }
         }
-        // An authoritative rebuild restates most of what is already there. Reusing the block
+        // Performance: an authoritative rebuild restates most of what is already there. Reusing the block
         // that already says it keeps its revision, and with it the rows the shell rendered for
         // it — otherwise every turn that ends re-renders the whole session.
         this.#setTranscript(blocks.map(block => {
@@ -1667,7 +1831,12 @@ export class PiEngineAdapter {
                     revision: this.#nextBlockRevision(baseId),
                     title: "User",
                     text: textFromContent(message.content),
-                    payload: { role: "user", imageCount: contentImageCount(message.content) },
+                    imageReferences: this.#imageReferences(message.content, "user"),
+                    payload: {
+                        role: "user",
+                        imageCount: contentImageCount(message.content),
+                        timestamp: typeof message.timestamp === "number" && Number.isFinite(message.timestamp) ? message.timestamp : null,
+                    },
                 }];
         }
         if (message.role === "bashExecution") {
@@ -1740,6 +1909,7 @@ export class PiEngineAdapter {
                     revision: this.#nextBlockRevision(blockId),
                     title: stringValue(message.toolName) ?? existing?.title ?? "Tool result",
                     text: textFromContent(message.content),
+                    imageReferences: this.#imageReferences(message.content, "tool-result"),
                     payload: {
                         ...(existingPayload ?? {}),
                         role: "toolResult",
@@ -1795,6 +1965,48 @@ export class PiEngineAdapter {
         }
         return blocks;
     }
+    #imageReferences(content, source) {
+        if (!Array.isArray(content))
+            return [];
+        const references = [];
+        for (const item of content) {
+            if (references.length >= 16 || !isRecord(item) || item.type !== "image"
+                || typeof item.data !== "string" || item.data.length === 0
+                || typeof item.mimeType !== "string" || !/^image\/[a-z0-9.+-]+$/i.test(item.mimeType))
+                continue;
+            const byteLength = Buffer.from(item.data, "base64").byteLength;
+            if (byteLength < 1 || byteLength > 20 * 1024 * 1024)
+                continue;
+            const assetId = `image-${createHash("sha256").update(item.mimeType).update("\0").update(item.data).digest("hex").slice(0, 24)}`;
+            this.#transcriptImageAssets.set(assetId, { type: "image", data: item.data, mimeType: item.mimeType });
+            references.push({ assetId, mimeType: item.mimeType, byteLength, source });
+        }
+        return references;
+    }
+    // Performance: coalescing each tool to its newest chunk bounds work by frames, not stream events.
+    #coalesceToolExecutionUpdate(event) {
+        const toolCallId = stringValue(event.toolCallId);
+        if (!toolCallId)
+            return;
+        this.#pendingToolUpdates.set(toolCallId, event);
+        this.#toolUpdateFlush ??= setTimeout(() => {
+            this.#toolUpdateFlush = null;
+            if (!this.#disposed)
+                this.#flushPendingToolUpdates();
+        }, TOOL_UPDATE_COALESCE_MS);
+    }
+    #flushPendingToolUpdates() {
+        if (this.#toolUpdateFlush !== null) {
+            clearTimeout(this.#toolUpdateFlush);
+            this.#toolUpdateFlush = null;
+        }
+        if (this.#pendingToolUpdates.size === 0)
+            return;
+        const pending = [...this.#pendingToolUpdates.values()];
+        this.#pendingToolUpdates.clear();
+        for (const update of pending)
+            this.#upsertToolExecutionBlock(update);
+    }
     #upsertToolExecutionBlock(event) {
         const toolCallId = stringValue(event.toolCallId);
         if (!toolCallId)
@@ -1814,7 +2026,9 @@ export class PiEngineAdapter {
                 toolCallId,
                 toolName: stringValue(event.toolName) ?? "unknown",
                 arguments: jsonSummary(event.args),
-                result: jsonSummary(source),
+                // Performance: a partial result repeats the whole accumulated output on every chunk;
+                // summarizing it each time would cost quadratic work over the stream.
+                result: ended ? jsonSummary(source) : { summary: "", json: null },
                 partialResult: event.type === "tool_execution_update",
                 argsComplete: ended,
                 isError: event.isError === true,
@@ -1825,7 +2039,7 @@ export class PiEngineAdapter {
         const index = this.#transcriptIndex.get(block.id);
         if (index !== undefined) {
             const existing = this.#transcript[index];
-            // Nothing to tell the shell about a block that repeats itself, and keeping the
+            // Performance: nothing is emitted for a block that repeats itself, and keeping the
             // revision keeps the rows it already rendered.
             if (existing !== undefined && sameBlockContent(existing, block))
                 return;
@@ -1897,6 +2111,7 @@ export class PiEngineAdapter {
         this.#emitEvent({ type: "diagnostic", diagnostic });
     }
     #emitView() {
+        this.#usageCache = undefined;
         this.#viewRevision += 1;
         this.#emitEvent({ type: "session-view", view: this.view() });
     }
@@ -1941,7 +2156,7 @@ export class PiEngineAdapter {
                     }
                 }
                 deliveredSinceYield += 1;
-                // A microtask chain runs to exhaustion before the loop turns, so a streaming
+                // Concurrency: a microtask chain runs to exhaustion before the loop turns, so a streaming
                 // burst would hold typed input, pointer reports, and timed indicators until it
                 // drained. Yielding on a macrotask hands those their turn between batches.
                 if (deliveredSinceYield >= EVENT_DELIVERY_BATCH && this.#eventQueue.length > 0) {
@@ -1985,7 +2200,12 @@ export async function createPiEngineAdapter(options = {}) {
     return adapter;
 }
 async function createDefaultPiRuntime(input) {
-    return createPiRuntimeIntegration({ cwd: input.cwd, agentDir: input.agentDir });
+    return createPiRuntimeIntegration({
+        cwd: input.cwd,
+        agentDir: input.agentDir,
+        ...(input.sessionPath === undefined ? {} : { sessionPath: input.sessionPath }),
+        ...(input.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: input.projectTrustPrompt }),
+    });
 }
 async function checkDefaultPiPackageUpdates(cwd, agentDir, settingsManager) {
     const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
@@ -2211,7 +2431,7 @@ function settingKeyForCallback(callback) {
         onAutoCompactChange: "autoCompact", onShowImagesChange: "showImages", onImageWidthCellsChange: "imageWidthCells",
         onAutoResizeImagesChange: "autoResizeImages", onBlockImagesChange: "blockImages", onEnableSkillCommandsChange: "enableSkillCommands",
         onSteeringModeChange: "steeringMode", onFollowUpModeChange: "followUpMode", onTransportChange: "transport",
-        onHttpIdleTimeoutMsChange: "httpIdleTimeoutMs", onThemeChange: "theme", onThemePreview: "theme",
+        onHttpIdleTimeoutMsChange: "httpIdleTimeoutMs", onThinkingLevelChange: "thinkingLevel", onThemeChange: "theme", onThemePreview: "theme",
         onHideThinkingBlockChange: "hideThinkingBlock", onMermaidRenderingModeChange: "mermaidRenderingMode",
         onShowCacheMissNoticesChange: "showCacheMissNotices", onCollapseChangelogChange: "collapseChangelog",
         onEnableInstallTelemetryChange: "enableInstallTelemetry", onQuietStartupChange: "quietStartup",
@@ -2412,7 +2632,8 @@ function sameBlockContent(left, right) {
         && left.status === right.status
         && left.title === right.title
         && left.text === right.text
-        && sameValue(left.payload, right.payload);
+        && sameValue(left.payload, right.payload)
+        && sameValue(left.imageReferences ?? [], right.imageReferences ?? []);
 }
 function sameValue(left, right) {
     if (left === right)