@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/integrations/pi/engine/adapter.js

@@ -2,7 +2,7 @@ import { PiTranscriptProjection } from "./transcript-projection.js";
 import { isRecord, readModel, readStringArray, readThinkingLevel, stringProperty } from "./message-values.js";
 import { getAgentDir } from "../startup-public.js";
 import { assertOwnedUiSnapshot, } from "../../../contracts/owned-ui/index.js";
-import { PiCommandDispatch } from "./command-dispatch.js";
+import { PiCommandDispatch, performEngineCommand } from "./command-dispatch.js";
 import { PiEventDelivery } from "./event-delivery.js";
 import { PiExtensionUiBinding } from "./extension-ui-binding.js";
 import { PiPromptSuggestions } from "./prompt-suggestions.js";
@@ -15,16 +15,12 @@ import { readUsageView } from "./usage-view.js";
 import { PiWorkflowContexts } from "./workflow-contexts.js";
 import { PiWorkflowRunner } from "./workflow-runner.js";
 import { defaultWorkflowHost } from "./workflow-support.js";
+import { EngineViewState } from "./view-state.js";
+import { createEnginePorts } from "./ports.js";
 /** Explicit flush failure when required delivery was interrupted rather than completed. */
 export class EngineDeliveryError extends Error {
     constructor() { super("Engine delivery did not complete"); this.name = "EngineDeliveryError"; }
 }
-const DEFAULT_SURFACE = {
-    columns: 100,
-    rows: 32,
-    focusedRegion: "editor",
-    hardwareCursor: false,
-};
 /** Owns the pinned Pi session lifecycle and serves it to the owned shell as the neutral session backend. */
 export class PiEngineAdapter {
     #agentDir;
@@ -38,31 +34,11 @@ export class PiEngineAdapter {
     #resources;
     #settings;
     #suggestions;
-    #viewRevision = 0;
-    #lifecycle = "starting";
-    #editor = {
-        text: "",
-        queuedSubmissions: [],
-        selection: null,
-        cursorOffset: 0,
-        historyRevision: 0,
-        submitEnabled: false,
-    };
-    #status = {
-        title: "Pi",
-        workingMessage: null,
-        diagnostics: [],
-        badges: [],
-    };
-    #terminal = DEFAULT_SURFACE;
-    #activeModel = null;
-    #thinkingLevel = "medium";
+    #state = new EngineViewState();
     #projection = new PiTranscriptProjection({
         retryAttempt: () => this.#engine.session?.retryAttempt ?? 0,
         blockChanged: block => this.#emitEvent({ type: "transcript-block", block }),
     });
-    #usageCache;
-    #diagnostics = [];
     // Invariant: every port closes over adapter state read at call time, so delivery is built before a session binds.
     #delivery = new PiEventDelivery({
         sessionId: () => this.#sessionId,
@@ -80,36 +56,30 @@ export class PiEngineAdapter {
     #events = new PiSessionEvents(this.#projection, {
         sessionGeneration: () => this.#engine.generation,
         sessionMessages: () => this.#engine.session?.messages ?? [],
-        activeModel: () => this.#activeModel,
+        activeModel: () => this.#state.activeModel,
         replaceTranscript: blocks => { this.#setTranscript(blocks); },
         emit: value => { this.#emitEvent(value); },
         emitView: () => { this.#emitView(); },
         enterWork: message => {
-            const wasBusy = this.#lifecycle === "busy";
-            this.#lifecycle = "busy";
-            this.#status = { ...this.#status, workingMessage: message, workingProgress: null };
-            if (!wasBusy)
+            if (!this.#state.enterWork(message))
                 this.#emitEvent({ type: "session-lifecycle", lifecycle: "busy", reason: null });
-            this.#emitEvent({ type: "status", status: this.#status });
+            this.#emitEvent({ type: "status", status: this.#state.status });
         },
         leaveWork: () => {
-            this.#lifecycle = "ready";
-            this.#status = { ...this.#status, workingMessage: null, workingProgress: null };
+            this.#state.leaveWork();
             this.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
-            this.#emitEvent({ type: "status", status: this.#status });
+            this.#emitEvent({ type: "status", status: this.#state.status });
         },
         workProgress: percent => {
-            if (this.#status.workingProgress === percent)
-                return;
-            this.#status = { ...this.#status, workingProgress: percent };
-            this.#emitEvent({ type: "status", status: this.#status });
+            if (this.#state.setWorkProgress(percent))
+                this.#emitEvent({ type: "status", status: this.#state.status });
         },
         queueChanged: queuedSubmissions => {
-            this.#editor = { ...this.#editor, queuedSubmissions: [...queuedSubmissions], historyRevision: this.#editor.historyRevision + 1 };
-            this.#emitEvent({ type: "editor-state", editor: this.#editor });
+            this.#state.setQueuedSubmissions(queuedSubmissions);
+            this.#emitEvent({ type: "editor-state", editor: this.#state.editor });
         },
-        thinkingLevelChanged: level => { this.#thinkingLevel = level; },
-        usageInvalidated: () => { this.#usageCache = undefined; },
+        thinkingLevelChanged: level => { this.#state.thinkingLevel = level; },
+        usageInvalidated: () => { this.#state.invalidateUsage(); },
         compactionStarted: () => { this.#engine.compactionStarted(); },
         compactionEnded: () => { this.#engine.compactionEnded(); },
         deliverQueuedAfterCompaction: () => { this.#engine.deliverQueuedAfterCompaction(); },
@@ -146,10 +116,7 @@ export class PiEngineAdapter {
         }, {
             disposed: () => this.#disposed,
             started: runtime => {
-                this.#terminal = {
-                    ...this.#terminal,
-                    hardwareCursor: runtime.services.settingsManager?.getShowHardwareCursor?.() ?? this.#terminal.hardwareCursor,
-                };
+                this.#state.setHardwareCursor(runtime.services.settingsManager?.getShowHardwareCursor?.() ?? this.#state.terminal.hardwareCursor);
                 const httpIdleTimeoutMs = runtime.services.settingsManager?.getHttpIdleTimeoutMs?.();
                 if (typeof httpIdleTimeoutMs === "number")
                     this.#engineHost.httpPolicyLoaded(httpIdleTimeoutMs, this.#sessionId);
@@ -168,7 +135,7 @@ export class PiEngineAdapter {
             session: () => this.#engine.session,
             runtime: () => this.#engine.runtime,
             disposed: () => this.#disposed,
-            activeModel: () => this.#activeModel,
+            activeModel: () => this.#state.activeModel,
             emitView: () => { this.#emitView(); },
         });
         this.#workflows = new PiWorkflowRunner({ agentDir: this.#agentDir, host: this.#workflowHost, contexts: this.#contexts }, {
@@ -181,10 +148,10 @@ export class PiEngineAdapter {
             pendingCommandCount: () => this.#commands.pendingCount,
             beginRunning: () => { this.#runningCommands++; },
             endRunning: () => { this.#runningCommands--; },
-            activeModel: () => this.#activeModel,
-            setActiveModel: model => { this.#activeModel = model; },
-            thinkingLevel: () => this.#thinkingLevel,
-            setThinkingLevel: level => { this.#thinkingLevel = level; },
+            activeModel: () => this.#state.activeModel,
+            setActiveModel: model => { this.#state.activeModel = model; },
+            thinkingLevel: () => this.#state.thinkingLevel,
+            setThinkingLevel: level => { this.#state.thinkingLevel = level; },
             emitView: () => { this.#emitView(); },
             reconcileActiveModelAvailability: () => { this.#reconcileActiveModelAvailability(); },
             bindExtensionUiToSession: () => this.#extensions.rebind(),
@@ -200,7 +167,7 @@ export class PiEngineAdapter {
             sessionGeneration: () => this.#engine.generation,
             beginRunning: () => { this.#runningCommands++; },
             endRunning: () => { this.#runningCommands--; },
-            perform: command => this.#perform(command),
+            perform: command => performEngineCommand(command, this.#commandContext()),
             emit: value => { this.#emitEvent(value); },
             emitView: () => { this.#emitView(); },
             diagnostic: (severity, code, message, recoverable) => { this.#addDiagnostic(severity, code, message, recoverable); },
@@ -212,14 +179,14 @@ export class PiEngineAdapter {
         this.#settings = new PiEngineSettings({ availableThemes: options.availableThemes ?? null, productMode: options.settingsProductMode ?? "bare" }, {
             runtime: () => this.#engine.runtime,
             requireSession: () => this.#requireWorkflowSession(),
-            thinkingLevelChanged: level => { this.#thinkingLevel = level; this.#emitView(); },
+            thinkingLevelChanged: level => { this.#state.thinkingLevel = level; this.#emitView(); },
             httpPolicyChanged: timeoutMs => { this.#engineHost.httpPolicyChanged(timeoutMs, this.#sessionId); },
             emitView: () => { this.#emitView(); },
         });
         this.#suggestions = new PiPromptSuggestions({
             session: () => this.#engine.session,
             runtime: () => this.#engine.runtime,
-            activeModel: () => this.#activeModel,
+            activeModel: () => this.#state.activeModel,
             identity: () => ({ sessionId: this.#sessionId, sessionGeneration: this.#engine.generation, runSequence: this.#events.runSequence, responseSequence: this.#events.responseSequence }),
             unavailable: () => this.#disposed || this.#delivery.overloaded || this.#admissionStopped,
         });
@@ -236,42 +203,21 @@ export class PiEngineAdapter {
     setWorkflowInteractionHost(interaction) {
         this.#workflowInteraction = interaction;
     }
-    get sessionId() {
-        return this.#sessionId;
-    }
-    get sessionGeneration() {
-        return this.#engine.generation;
-    }
-    /** Actual session replacements, excluding delivery-only invalidation of callbacks. */
-    get sessionBindingGeneration() { return this.#engine.bindingGeneration; }
-    get cwd() {
-        return this.#engine.cwd;
-    }
-    get agentDir() {
-        return this.#agentDir;
-    }
-    resolveTranscriptImage(assetId) {
+    #resolveTranscriptImage(assetId) {
         return this.#projection.assets.resolve(assetId);
     }
-    currentSessionFile() {
-        return this.#engine.currentSessionFile();
-    }
-    currentSessionResumeMetadata() {
-        return this.#engine.currentSessionResumeMetadata();
-    }
-    get disposed() {
-        return this.#disposed;
-    }
-    /**
-     * Report a newer A1 release found by the startup check. The shell renders the diagnostic as
-     * pinned Pi's `Update Available` notice; it arrives whenever the check resolves, so a late
-     * result is appended to the transcript like Pi's own fire-and-forget version check.
-     */
-    announceReleaseUpdate(release) {
+    // Rationale: the startup check's newer release becomes pinned Pi's `Update Available` notice; it arrives
+    // whenever the check resolves, so a late result is appended like Pi's own fire-and-forget version check.
+    #announceReleaseUpdate(release) {
         if (this.#disposed)
             return;
-        const changelog = release.changelogUrl === null ? "" : `\nChangelog: ${release.changelogUrl}`;
-        this.#addDiagnostic("info", "release-update", `New version ${release.version} is available. Run ${release.command}${changelog}`, true);
+        if (release.status === "installed") {
+            this.#addDiagnostic("info", "release-update-installed", `Update ${release.version} installed; restart to update.`, true);
+        }
+        else {
+            const changelog = release.changelogUrl === null ? "" : `\nChangelog: ${release.changelogUrl}`;
+            this.#addDiagnostic("info", "release-update", `New version ${release.version} is available. Run ${release.command}${changelog}`, true);
+        }
         this.#emitView();
     }
     suggestionReasoningPolicy() {
@@ -280,16 +226,18 @@ export class PiEngineAdapter {
     generate(request) {
         return this.#suggestions.generate(request);
     }
+    generateResidentTabName(instruction, maxTokens, signal) {
+        return this.#suggestions.completeInstruction(instruction, maxTokens, signal);
+    }
     async start() {
         if (this.#engine.started)
             return this.view();
         await this.#engine.start().catch(error => {
-            this.#lifecycle = "failed";
+            this.#state.lifecycle = "failed";
             this.#addDiagnostic("error", "engine-startup", error instanceof Error ? error.message : String(error), false);
             throw error;
         });
-        this.#lifecycle = "ready";
-        this.#editor = { ...this.#editor, submitEnabled: true };
+        this.#state.markReady();
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
         this.#emitView();
         return this.view();
@@ -312,94 +260,14 @@ export class PiEngineAdapter {
     async flushEvents() {
         const failed = this.#delivery.failed;
         await this.#delivery.settle();
-        if (failed || this.#delivery.failed || this.#disposed && this.#lifecycle !== "stopped") {
+        if (failed || this.#delivery.failed || this.#disposed && this.#state.lifecycle !== "stopped") {
             this.#delivery.clearFailure();
             throw new EngineDeliveryError();
         }
     }
-    nonVisualResources() {
-        return this.#resources.nonVisualResources();
-    }
-    extensionResources() {
-        return this.#resources.extensionResources();
-    }
-    workflowAutocompleteCommands() {
-        return this.#resources.workflowAutocompleteCommands();
-    }
-    visualExtensionSupport() {
-        return this.#extensions.support();
-    }
-    bindExtensionUi(ui, shutdown) {
-        return this.#extensions.bind(ui, shutdown);
-    }
-    unbindExtensionUi() {
-        return this.#extensions.unbind();
-    }
-    async cycleModelWorkflow(direction) {
-        return this.#workflows.cycleModelWorkflow(direction);
-    }
-    pinnedProjectTrustContext() {
-        return this.#contexts.pinnedProjectTrustContext();
-    }
-    persistProjectTrust(updates) {
-        this.#contexts.persistProjectTrust(updates);
-    }
-    pinnedScopedModelsContext() {
-        return this.#contexts.pinnedScopedModelsContext();
-    }
-    updateScopedModels(enabledModelIds) {
-        this.#contexts.updateScopedModels(enabledModelIds);
-    }
-    persistScopedModels(enabledModelIds) {
-        this.#contexts.persistScopedModels(enabledModelIds);
-    }
-    refreshScopedModels(signal) {
-        return this.#contexts.refreshScopedModels(signal);
-    }
-    modelsContext() {
-        return this.#contexts.modelsContext();
-    }
-    setSessionModelScope(scopeIds) {
-        this.#contexts.setSessionModelScope(scopeIds);
-    }
-    persistModelScope(scopeIds) {
-        this.#contexts.persistModelScope(scopeIds);
-    }
-    refreshModels(signal) {
-        return this.#contexts.refreshModels(signal);
-    }
-    pinnedLoginOptions(authType) {
-        return this.#contexts.loginOptions(authType);
-    }
-    pinnedLoginMethodOptions(providerReference) {
-        return this.#contexts.pinnedLoginMethodOptions(providerReference);
-    }
-    pinnedAmbientAuthentication(selection) {
-        return this.#contexts.pinnedAmbientAuthentication(selection);
-    }
-    pinnedLogoutOptions() {
-        return this.#contexts.logoutOptions();
-    }
-    pinnedForkOptions() {
-        return this.#contexts.pinnedForkOptions();
-    }
-    /** Bind the owned UI's clipboard lifecycle without changing the comparison host. True means acknowledged delivery. */
-    bindClipboardWriter(writer) {
-        return this.#workflows.bindClipboardWriter(writer);
-    }
-    /** Workflow and tree copying share the active owner's write fence and delivery acknowledgment. */
-    copyWorkflowText(text) {
-        return this.#workflows.copyWorkflowText(text);
-    }
     abortBashWorkflow() {
         this.#workflows.abortBashWorkflow();
     }
-    executeBashWorkflow(command, excludeFromContext) {
-        return this.#workflows.executeBashWorkflow(command, excludeFromContext);
-    }
-    reloadBlockedResult() {
-        return this.#workflows.reloadBlockedResult();
-    }
     async executeWorkflow(request) {
         const result = await this.#workflows.executeWorkflow(request);
         if (request.command === "tree" && result.outcome === "completed" && request.selection !== undefined) {
@@ -414,40 +282,13 @@ export class PiEngineAdapter {
     configuredTheme() {
         return this.#settings.configuredTheme();
     }
-    /** Persist the global thinking default without changing the live session level. */
-    setDefaultThinkingLevel(level) {
-        this.#settings.setDefaultThinkingLevel(level);
-    }
     /** Settings port for the live runtime, or null before the runtime is available. */
     settingsPort() {
         return this.#settings.settingsPort();
     }
-    /** Which settings surface this adapter serves; hidden-in-bare effects are unbindable in bare mode. */
-    get settingsProductMode() {
-        return this.#settings.productMode;
-    }
-    bindSettingsOwner(owner, handlers) {
-        return this.#settings.bindSettingsOwner(owner, handlers);
-    }
     pinnedSettingsSnapshot() {
         return this.#settings.pinnedSettingsSnapshot();
     }
-    #pinnedMessageRenderer(customType) {
-        return this.#requireWorkflowSession().extensionRunner?.getMessageRenderer?.(customType);
-    }
-    #pinnedShortcutDescriptions(bindings) {
-        const shortcuts = this.#requireWorkflowSession().extensionRunner?.getShortcuts?.(bindings);
-        return shortcuts === undefined ? [] : [...shortcuts].map(([key, shortcut]) => ({ key, description: shortcut.description ?? shortcut.extensionPath }));
-    }
-    #pinnedToolRenderers(toolName) {
-        const runner = this.#requireWorkflowSession().extensionRunner;
-        if (runner === undefined)
-            return undefined;
-        if (typeof runner.resolveToolRenderers === "function") {
-            return runner.resolveToolRenderers(toolName, () => runner.getToolDefinition?.(toolName));
-        }
-        return runner.getToolDefinition?.(toolName);
-    }
     clearQueuedWorkflows() {
         const session = this.#requireWorkflowSession();
         const result = session.clearQueue?.();
@@ -462,15 +303,15 @@ export class PiEngineAdapter {
         return {
             contractVersion: 1,
             sessionId: this.#sessionId,
-            revision: this.#viewRevision,
-            lifecycle: this.#lifecycle,
+            revision: this.#state.revision,
+            lifecycle: this.#state.lifecycle,
             transcript: this.#projection.snapshot(),
-            editor: { ...this.#editor, queuedSubmissions: [...this.#editor.queuedSubmissions] },
+            editor: { ...this.#state.editor, queuedSubmissions: [...this.#state.editor.queuedSubmissions] },
             status: {
-                ...this.#status,
-                diagnostics: [...this.#status.diagnostics],
-                badges: [...this.#status.badges],
-                usage: this.#usageCache ??= readUsageView(this.#engine.session, this.#engine.runtime, this.#activeModel),
+                ...this.#state.status,
+                diagnostics: [...this.#state.status.diagnostics],
+                badges: [...this.#state.status.badges],
+                usage: this.#state.usage(() => readUsageView(this.#engine.session, this.#engine.runtime, this.#state.activeModel)),
                 footer: {
                     branch: this.#engine.gitBranch,
                     repositoryPath: this.#engine.repositoryCwd,
@@ -480,24 +321,24 @@ export class PiEngineAdapter {
                     extensionStatuses: [],
                 },
             },
-            terminal: { ...this.#terminal },
-            activeModel: this.#activeModel === null ? null : { ...this.#activeModel },
+            terminal: { ...this.#state.terminal },
+            activeModel: this.#state.activeModel === null ? null : { ...this.#state.activeModel },
             routedModel: routedModel === null ? null : {
                 model: routedModel,
                 ...(routed?.thinkingLevel === undefined ? {} : { thinkingLevel: readThinkingLevel(routed.thinkingLevel) }),
             },
-            thinkingLevel: this.#thinkingLevel,
+            thinkingLevel: this.#state.thinkingLevel,
             activeCommandIds: [...this.#commands.activeCommandIds],
             dialog: null,
             overlay: null,
             customizations: [],
-            diagnostics: this.#diagnostics.map(diagnostic => ({ ...diagnostic })),
+            diagnostics: this.#state.diagnostics.map(diagnostic => ({ ...diagnostic })),
         };
     }
     snapshot() {
         const snapshot = {
             contractVersion: 1,
-            snapshotId: `snapshot-${this.#viewRevision}`,
+            snapshotId: `snapshot-${this.#state.revision}`,
             sessionId: this.#sessionId,
             sequence: this.#delivery.sequence,
             view: this.view(),
@@ -517,10 +358,10 @@ export class PiEngineAdapter {
         this.#workflows.cancelPending("quit");
         this.#projection.assets.clear();
         await this.#extensions.unbind();
-        this.#lifecycle = "stopping";
+        this.#state.lifecycle = "stopping";
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "stopping", reason: null });
         await this.#engine.dispose();
-        this.#lifecycle = "stopped";
+        this.#state.lifecycle = "stopped";
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "stopped", reason: null });
         this.#emitView();
         try {
@@ -531,27 +372,17 @@ export class PiEngineAdapter {
                 throw error;
         }
     }
-    // Invariant: every sub-port member delegates at call time, so ports built once follow session replacement.
+    // Invariant: every port member delegates at call time, so ports built once follow session replacement.
     #createPorts() {
-        const engine = this.#engine;
-        const contexts = this.#contexts;
-        const workflows = this.#workflows;
-        const settings = this.#settings;
-        const resources = this.#resources;
-        const extensions = this.#extensions;
-        const isDisposed = () => this.#disposed;
-        const sessionId = this.#sessionId;
-        const agentDir = this.#agentDir;
-        return {
-            identity: {
-                sessionId,
-                agentDir,
-                get cwd() { return engine.cwd; },
-                get sessionGeneration() { return engine.generation; },
-                get sessionBindingGeneration() { return engine.bindingGeneration; },
-                get disposed() { return isDisposed(); },
-                currentSessionResumeMetadata: () => engine.currentSessionResumeMetadata(),
-            },
+        return createEnginePorts({
+            sessionId: this.#sessionId,
+            agentDir: this.#agentDir,
+            engine: this.#engine,
+            contexts: this.#contexts,
+            workflows: this.#workflows,
+            settings: this.#settings,
+            resources: this.#resources,
+            extensions: this.#extensions,
             session: {
                 start: () => this.start(),
                 view: () => this.view(),
@@ -561,67 +392,22 @@ export class PiEngineAdapter {
                 flushEvents: () => this.flushEvents(),
                 dispose: () => this.dispose(),
             },
-            workflows: {
-                executeWorkflow: request => this.executeWorkflow(request),
-                executeBashWorkflow: (command, excludeFromContext) => workflows.executeBashWorkflow(command, excludeFromContext),
-                cycleModelWorkflow: direction => workflows.cycleModelWorkflow(direction),
-                workflowAutocompleteCommands: () => resources.workflowAutocompleteCommands(),
-                clearQueuedWorkflows: () => this.clearQueuedWorkflows(),
-                reloadBlockedResult: () => workflows.reloadBlockedResult(),
-                copyWorkflowText: text => workflows.copyWorkflowText(text),
-                setWorkflowInteractionHost: interaction => { this.setWorkflowInteractionHost(interaction); },
-            },
-            settings: {
-                get productMode() { return settings.productMode; },
-                snapshot: () => {
-                    // Invariant: the selector-only model values travel on the presentation source, not in the neutral snapshot.
-                    const { currentModel: _currentModel, availableDefaultModels: _availableDefaultModels, ...snapshot } = settings.pinnedSettingsSnapshot();
-                    return snapshot;
-                },
-                bindOwner: (owner, handlers) => settings.bindSettingsOwner(owner, handlers),
-                setDefaultThinkingLevel: level => { settings.setDefaultThinkingLevel(level); },
-                configuredTheme: () => settings.configuredTheme(),
-            },
-            catalog: {
-                modelsContext: () => contexts.modelsContext(),
-                setSessionModelScope: scopeIds => { contexts.setSessionModelScope(scopeIds); },
-                persistModelScope: scopeIds => { contexts.persistModelScope(scopeIds); },
-                refreshModels: signal => contexts.refreshModels(signal),
-                pinnedScopedModelsContext: () => contexts.pinnedScopedModelsContext(),
-                updateScopedModels: enabledModelIds => { contexts.updateScopedModels(enabledModelIds); },
-                persistScopedModels: enabledModelIds => { contexts.persistScopedModels(enabledModelIds); },
-                refreshScopedModels: signal => contexts.refreshScopedModels(signal),
-                pinnedProjectTrustContext: () => contexts.pinnedProjectTrustContext(),
-                persistProjectTrust: updates => { contexts.persistProjectTrust(updates); },
-                pinnedLoginOptions: authType => contexts.loginOptions(authType),
-                pinnedLoginMethodOptions: providerReference => contexts.pinnedLoginMethodOptions(providerReference),
-                pinnedAmbientAuthentication: selection => contexts.pinnedAmbientAuthentication(selection),
-                pinnedLogoutOptions: () => contexts.logoutOptions(),
-                pinnedForkOptions: () => contexts.pinnedForkOptions(),
-            },
-            extensions: {
-                nonVisualResources: () => resources.nonVisualResources(),
-                extensionResources: () => resources.extensionResources(),
-                resolveTranscriptImage: assetId => this.resolveTranscriptImage(assetId),
-                visualExtensionSupport: () => extensions.support(),
-                bindExtensionUi: (ui, shutdown) => extensions.bind(ui, shutdown),
-                unbindExtensionUi: () => extensions.unbind(),
-                bindClipboardWriter: writer => workflows.bindClipboardWriter(writer),
-                announceReleaseUpdate: release => { this.announceReleaseUpdate(release); },
-            },
-            presentation: {
-                pinnedModelSelectorContext: () => contexts.pinnedModelSelectorContext(),
-                pinnedSessionSelectorContext: () => contexts.pinnedSessionSelectorContext(),
-                pinnedTreeSelectorContext: () => contexts.pinnedTreeSelectorContext(),
-                pinnedMessageRenderer: customType => this.#pinnedMessageRenderer(customType),
-                pinnedToolRenderers: toolName => this.#pinnedToolRenderers(toolName),
-                pinnedShortcutDescriptions: bindings => this.#pinnedShortcutDescriptions(bindings),
-                pinnedSettingsModels: () => {
-                    const { currentModel, availableDefaultModels } = settings.pinnedSettingsSnapshot();
-                    return { ...(currentModel === undefined ? {} : { currentModel }), availableDefaultModels };
-                },
-                applyPinnedSettingValue: (callback, value) => settings.applyPinnedSettingValue(callback, value),
-            },
+            disposed: () => this.#disposed,
+            executeWorkflow: request => this.executeWorkflow(request),
+            clearQueuedWorkflows: () => this.clearQueuedWorkflows(),
+            setWorkflowInteractionHost: interaction => { this.setWorkflowInteractionHost(interaction); },
+            announceReleaseUpdate: release => { this.#announceReleaseUpdate(release); },
+            resolveTranscriptImage: assetId => this.#resolveTranscriptImage(assetId),
+            extensionRunner: () => this.#requireWorkflowSession().extensionRunner,
+        });
+    }
+    #commandContext() {
+        return {
+            engine: this.#engine,
+            state: this.#state,
+            admissionOpen: () => !this.#delivery.overloaded && !this.#admissionStopped,
+            emit: value => { this.#emitEvent(value); },
+            dispose: () => this.dispose(),
         };
     }
     #requireWorkflowSession() {
@@ -629,75 +415,16 @@ export class PiEngineAdapter {
             throw new Error("engine adapter is not running");
         return this.#engine.session;
     }
-    async #perform(command) {
-        const runtime = this.#engine.runtime;
-        const session = this.#engine.session;
-        const generation = this.#engine.generation;
-        if (!runtime || !session)
-            throw new Error("engine session is unavailable");
-        switch (command.type) {
-            case "prompt":
-            case "steer":
-            case "follow-up":
-            case "abort":
-            case "retry":
-            case "compact": {
-                const result = await this.#engine.sessionCommands?.execute(command.type === "prompt" || command.type === "steer" || command.type === "follow-up"
-                    ? {
-                        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}`);
-                }
-                return;
-            }
-            case "set-model": {
-                const model = runtime.services.modelRuntime.getModel(command.model.providerId, command.model.modelId);
-                if (!model) {
-                    throw new Error(`model is unavailable: ${command.model.providerId}/${command.model.modelId}`);
-                }
-                await session.setModel(model);
-                if (generation === this.#engine.generation && !this.#delivery.overloaded && !this.#admissionStopped)
-                    this.#activeModel = { ...command.model };
-                return;
-            }
-            case "set-thinking-level":
-                session.setThinkingLevel(command.thinkingLevel);
-                this.#thinkingLevel = command.thinkingLevel;
-                return;
-            case "new-session":
-                await runtime.newSession();
-                return;
-            case "resume-session":
-                await runtime.switchSession(command.sessionPath);
-                return;
-            case "resize-surface":
-                this.#terminal = { ...command.surface };
-                this.#emitEvent({ type: "terminal-surface", surface: this.#terminal });
-                return;
-            case "shutdown":
-                await this.dispose();
-                return;
-            case "set-setting":
-            case "apply-customization":
-            case "remove-customization":
-                throw new Error("owned UI state commands belong to the owned UI layer, not the Pi engine adapter");
-        }
-    }
     // Invariant: in-place tree navigation rebuilds derived content without clearing the editor draft.
     #refreshNavigatedSession(editorText) {
         const session = this.#engine.session;
         if (!session)
             return;
-        if (editorText && !this.#editor.text.trim()) {
-            this.#editor = { ...this.#editor, text: editorText, selection: null, cursorOffset: editorText.length };
-        }
-        this.#activeModel = readModel(session.model);
+        if (editorText)
+            this.#state.offerEditorText(editorText);
+        this.#state.activeModel = readModel(session.model);
         this.#reconcileActiveModelAvailability();
-        this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
+        this.#state.thinkingLevel = readThinkingLevel(session.thinkingLevel);
         this.#projection.assets.clear();
         this.#setTranscript(this.#projection.rebuild(session.messages, "finalized"));
         this.#emitView();
@@ -706,19 +433,11 @@ export class PiEngineAdapter {
     #sessionReplaced(session) {
         this.#delivery.discardObsolete(this.#engine.generation);
         this.#commands.reset();
-        this.#editor = {
-            text: "",
-            queuedSubmissions: [],
-            selection: null,
-            cursorOffset: 0,
-            historyRevision: this.#editor.historyRevision + 1,
-            submitEnabled: true,
-        };
-        this.#status = { ...this.#status, workingMessage: null, workingProgress: null, badges: [] };
+        this.#state.replaceSession();
         this.#events.reset();
-        this.#activeModel = readModel(session.model);
+        this.#state.activeModel = readModel(session.model);
         this.#reconcileActiveModelAvailability();
-        this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
+        this.#state.thinkingLevel = readThinkingLevel(session.thinkingLevel);
         this.#projection.assets.clear();
         // Invariant: a new binding cannot inherit arguments/results from a reused invocation id.
         this.#setTranscript([]);
@@ -729,17 +448,17 @@ export class PiEngineAdapter {
     #reconcileActiveModelAvailability() {
         const modelRuntime = this.#engine.runtime?.services.modelRuntime;
         if (!modelRuntime) {
-            this.#activeModel = null;
+            this.#state.activeModel = null;
             return;
         }
         const available = modelRuntime.getAvailableSnapshot?.() ?? [];
         const sessionModel = readModel(this.#engine.session?.model);
-        const authoritative = this.#activeModel ?? sessionModel;
+        const authoritative = this.#state.activeModel ?? sessionModel;
         if (authoritative === null)
             return;
         const remainsAvailable = available.some(model => stringProperty(model, "provider") === authoritative.providerId
             && stringProperty(model, "id") === authoritative.modelId);
-        this.#activeModel = remainsAvailable ? authoritative : null;
+        this.#state.activeModel = remainsAvailable ? authoritative : null;
     }
     #setTranscript(blocks) {
         // Invariant: lazy delivery snapshots must freeze before their authoritative source can be removed.
@@ -754,13 +473,12 @@ export class PiEngineAdapter {
         this.#emitEvent({ type: "diagnostic", diagnostic });
     }
     #emitView() {
-        this.#usageCache = undefined;
-        this.#viewRevision += 1;
+        this.#state.invalidate();
         this.#emitEvent({ type: "session-view", view: this.view() });
     }
     #emitEvent(value) {
         if (value.type !== "session-view")
-            this.#viewRevision += 1;
+            this.#state.advance();
         this.#delivery.emit(value);
     }
     // Concurrency: cancellation runs synchronously so the overload reservation already guards reentrant outcomes.
@@ -775,10 +493,7 @@ export class PiEngineAdapter {
         this.#admissionStopped = !canResume;
         this.#engine.suspend();
         this.#events.abandonRun();
-        this.#status = { ...this.#status, workingMessage: null, workingProgress: null };
-        this.#lifecycle = this.#disposed ? "stopped" : canResume ? "ready" : "failed";
-        this.#editor = { ...this.#editor, submitEnabled: canResume && !this.#disposed };
-        this.#viewRevision += 1;
+        this.#state.settleOverload(canResume, this.#disposed);
         // Invariant: overload publishes one authoritative view; settle tool phases before finalizing other live blocks.
         this.#projection.settleFailedDeclarations({ role: "assistant", stopReason: cancelled ? "aborted" : "error",
             errorMessage: "Tool result unavailable after UI delivery overload" });
@@ -795,21 +510,7 @@ export class PiEngineAdapter {
             this.#engine.resume();
     }
     #recordDiagnostic(severity, code, message, recoverable) {
-        const diagnostic = {
-            sequence: this.#diagnostics.length,
-            code,
-            severity,
-            message,
-            recoverable,
-        };
-        this.#diagnostics.push(diagnostic);
-        if (this.#diagnostics.length > 100)
-            this.#diagnostics.shift();
-        this.#status = {
-            ...this.#status,
-            diagnostics: [...this.#status.diagnostics, message].slice(-8),
-        };
-        return diagnostic;
+        return this.#state.recordDiagnostic(severity, code, message, recoverable);
     }
 }
 export async function createPiEngineAdapter(options) {