@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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

@@ -0,0 +1,648 @@
+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 { PiEventDelivery } from "./event-delivery.js";
+import { PiExtensionUiBinding } from "./extension-ui-binding.js";
+import { PiPromptSuggestions } from "./prompt-suggestions.js";
+import { PiResourceCatalog } from "./resource-catalog.js";
+import { PiEngineRuntime } from "./session-runtime.js";
+import { PiEngineSettings } from "./settings-port.js";
+import { PiSessionEvents } from "./session-events.js";
+import { readUsageView } from "./usage-view.js";
+import { PiWorkflowContexts } from "./workflow-contexts.js";
+import { PiWorkflowRunner } from "./workflow-runner.js";
+import { defaultWorkflowHost } from "./workflow-support.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 translates its events into the neutral agent-engine contract. */
+export class PiEngineAdapter {
+    #agentDir;
+    #sessionId;
+    #workflowHost;
+    #engine;
+    #workflowInteraction;
+    #contexts;
+    #workflows;
+    #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";
+    #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,
+        sessionGeneration: () => this.#engine.generation,
+        transcriptBlock: id => this.#projection.block(id),
+        retainEvent: event => this.#projection.assets.retainEvent(event),
+        isPendingCommand: correlationId => this.#commands.isPending(correlationId),
+        cancelForOverload: () => this.#cancelForOverload(),
+        reconcileOverload: cancelled => this.#reconcileOverload(cancelled),
+        listenerFailed: message => { this.#recordDiagnostic("warning", "event-listener", message, true); },
+    });
+    #admissionStopped = false;
+    #runningCommands = 0;
+    #commands;
+    #events = new PiSessionEvents(this.#projection, {
+        sessionGeneration: () => this.#engine.generation,
+        sessionMessages: () => this.#engine.session?.messages ?? [],
+        activeModel: () => this.#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)
+                this.#emitEvent({ type: "session-lifecycle", lifecycle: "busy", reason: null });
+            this.#emitEvent({ type: "status", status: this.#status });
+        },
+        leaveWork: () => {
+            this.#lifecycle = "ready";
+            this.#status = { ...this.#status, workingMessage: null, workingProgress: null };
+            this.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
+            this.#emitEvent({ type: "status", status: this.#status });
+        },
+        workProgress: percent => {
+            if (this.#status.workingProgress === percent)
+                return;
+            this.#status = { ...this.#status, workingProgress: percent };
+            this.#emitEvent({ type: "status", status: this.#status });
+        },
+        queueChanged: queuedSubmissions => {
+            this.#editor = { ...this.#editor, queuedSubmissions: [...queuedSubmissions], historyRevision: this.#editor.historyRevision + 1 };
+            this.#emitEvent({ type: "editor-state", editor: this.#editor });
+        },
+        thinkingLevelChanged: level => { this.#thinkingLevel = level; },
+        usageInvalidated: () => { this.#usageCache = undefined; },
+        compactionStarted: () => { this.#engine.compactionStarted(); },
+        compactionEnded: () => { this.#engine.compactionEnded(); },
+        deliverQueuedAfterCompaction: () => { this.#engine.deliverQueuedAfterCompaction(); },
+    });
+    #extensions = new PiExtensionUiBinding({
+        session: () => this.#engine.session,
+        diagnostic: (severity, code, message, recoverable) => { this.#addDiagnostic(severity, code, message, recoverable); },
+        emitView: () => { this.#emitView(); },
+    });
+    #disposed = false;
+    constructor(options = {}) {
+        this.#agentDir = options.agentDir ?? getAgentDir();
+        this.#sessionId = options.sessionId ?? "owned-session-1";
+        this.#workflowHost = options.workflowHost ?? defaultWorkflowHost();
+        this.#workflowInteraction = { prompt: async () => null, notify() { } };
+        this.#engine = new PiEngineRuntime({
+            cwd: options.cwd ?? process.cwd(),
+            agentDir: this.#agentDir,
+            sessionId: this.#sessionId,
+            sessionPath: options.sessionPath,
+            sessionSelection: options.sessionSelection,
+            sessionForkPrompt: options.sessionForkPrompt,
+            projectTrustPrompt: options.projectTrustPrompt,
+            createRuntime: options.createRuntime,
+            checkPackageUpdates: options.checkPackageUpdates,
+            host: this.#workflowHost,
+        }, {
+            disposed: () => this.#disposed,
+            started: runtime => {
+                this.#terminal = {
+                    ...this.#terminal,
+                    hardwareCursor: runtime.services.settingsManager?.getShowHardwareCursor?.() ?? this.#terminal.hardwareCursor,
+                };
+            },
+            rebindBlocked: () => this.#delivery.overloaded || this.#admissionStopped || this.#disposed,
+            sessionReplacing: () => { this.#commands.cancelPending(["new-session", "resume-session"]); },
+            sessionReplaced: session => { this.#sessionReplaced(session); },
+            rebound: () => { this.#emitView(); },
+            event: event => { this.#events.handle(event); },
+            compactionProgress: percent => { this.#events.compactionProgress(percent); },
+            diagnostic: (severity, code, message, recoverable) => { this.#addDiagnostic(severity, code, message, recoverable); },
+            emitView: () => { this.#emitView(); },
+        });
+        this.#contexts = new PiWorkflowContexts({ agentDir: this.#agentDir }, {
+            cwd: () => this.#engine.cwd,
+            session: () => this.#engine.session,
+            runtime: () => this.#engine.runtime,
+            disposed: () => this.#disposed,
+            activeModel: () => this.#activeModel,
+            emitView: () => { this.#emitView(); },
+        });
+        this.#workflows = new PiWorkflowRunner({ agentDir: this.#agentDir, host: this.#workflowHost, contexts: this.#contexts }, {
+            session: () => this.#engine.session,
+            runtime: () => this.#engine.runtime,
+            disposed: () => this.#disposed,
+            sessionGeneration: () => this.#engine.generation,
+            interaction: () => this.#workflowInteraction,
+            admissionStopped: () => this.#delivery.overloaded || this.#admissionStopped || this.#disposed,
+            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; },
+            emitView: () => { this.#emitView(); },
+            reconcileActiveModelAvailability: () => { this.#reconcileActiveModelAvailability(); },
+            bindExtensionUiToSession: () => this.#extensions.rebind(),
+            applyPinnedSetting: selection => this.#settings.applyPinnedSetting(selection),
+            snapshot: () => this.snapshot(),
+            dispose: () => this.dispose(),
+        });
+        this.#commands = new PiCommandDispatch({
+            sessionId: () => this.#sessionId,
+            notRunning: () => this.#disposed || !this.#engine.runtime || !this.#engine.session,
+            admissionStopped: () => this.#delivery.overloaded || this.#admissionStopped,
+            pendingWorkflowCount: () => this.#workflows.pendingCount,
+            sessionGeneration: () => this.#engine.generation,
+            beginRunning: () => { this.#runningCommands++; },
+            endRunning: () => { this.#runningCommands--; },
+            perform: command => this.#perform(command),
+            emit: value => { this.#emitEvent(value); },
+            emitView: () => { this.#emitView(); },
+            diagnostic: (severity, code, message, recoverable) => { this.#addDiagnostic(severity, code, message, recoverable); },
+        });
+        this.#resources = new PiResourceCatalog({ contexts: this.#contexts }, {
+            session: () => this.#engine.session,
+            runtime: () => this.#engine.runtime,
+        });
+        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(); },
+            emitView: () => { this.#emitView(); },
+        });
+        this.#suggestions = new PiPromptSuggestions({
+            session: () => this.#engine.session,
+            runtime: () => this.#engine.runtime,
+            activeModel: () => this.#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,
+        });
+    }
+    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) {
+        return this.#projection.assets.resolve(assetId);
+    }
+    currentSessionFile() {
+        return this.#engine.currentSessionFile();
+    }
+    currentSessionResumeMetadata() {
+        return this.#engine.currentSessionResumeMetadata();
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    suggestionReasoningPolicy() {
+        return this.#suggestions.reasoningPolicy();
+    }
+    generate(request) {
+        return this.#suggestions.generate(request);
+    }
+    async start() {
+        if (this.#engine.started)
+            return this.view();
+        await this.#engine.start().catch(error => {
+            this.#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.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
+        this.#emitView();
+        void this.#engine.announcePackageUpdates();
+        return this.view();
+    }
+    onEvent(listener) {
+        return this.#delivery.subscribe(listener, this.#delivery.stamp({ type: "session-view", view: this.view() }));
+    }
+    /** Developer-only pressure evidence; never mirrored into visible diagnostic/status arrays. */
+    deliveryDiagnostics() {
+        return { ...this.#delivery.diagnostics(), pendingCommands: this.#commands.pendingCount + this.#workflows.pendingCount };
+    }
+    async flushEvents() {
+        const failed = this.#delivery.failed;
+        await this.#delivery.settle();
+        if (failed || this.#delivery.failed || this.#disposed && this.#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);
+    }
+    pinnedModelSelectorContext() {
+        return this.#contexts.pinnedModelSelectorContext();
+    }
+    pinnedProjectTrustContext() {
+        return this.#contexts.pinnedProjectTrustContext();
+    }
+    persistProjectTrust(updates) {
+        this.#contexts.persistProjectTrust(updates);
+    }
+    pinnedSessionSelectorContext() {
+        return this.#contexts.pinnedSessionSelectorContext();
+    }
+    pinnedScopedModelsContext() {
+        return this.#contexts.pinnedScopedModelsContext();
+    }
+    updateScopedModels(enabledModelIds) {
+        this.#contexts.updateScopedModels(enabledModelIds);
+    }
+    persistScopedModels(enabledModelIds) {
+        this.#contexts.persistScopedModels(enabledModelIds);
+    }
+    refreshScopedModels(signal) {
+        return this.#contexts.refreshScopedModels(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();
+    }
+    pinnedTreeSelectorContext() {
+        return this.#contexts.pinnedTreeSelectorContext();
+    }
+    /** 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();
+    }
+    executeWorkflow(request) {
+        return this.#workflows.executeWorkflow(request);
+    }
+    /**
+     * The theme the engine is configured with, in the engine's own grammar: a
+     * theme's name, or a `light/dark` pair meaning "follow the terminal".
+     */
+    configuredTheme() {
+        return this.#settings.configuredTheme();
+    }
+    /** 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();
+    }
+    applyPinnedSettingValue(callback, value) {
+        return this.#settings.applyPinnedSettingValue(callback, value);
+    }
+    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 }));
+    }
+    pinnedToolDefinition(toolName) {
+        return this.#requireWorkflowSession().extensionRunner?.getToolDefinition?.(toolName);
+    }
+    clearQueuedWorkflows() {
+        const session = this.#requireWorkflowSession();
+        const result = session.clearQueue?.();
+        this.#engine.sessionCommands?.forgetQueuedImages();
+        if (!isRecord(result))
+            return [];
+        return [...readStringArray(result.steering), ...readStringArray(result.followUp)];
+    }
+    view() {
+        return {
+            contractVersion: 1,
+            sessionId: this.#sessionId,
+            revision: this.#viewRevision,
+            lifecycle: this.#lifecycle,
+            transcript: this.#projection.snapshot(),
+            editor: { ...this.#editor, queuedSubmissions: [...this.#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),
+                footer: {
+                    branch: this.#engine.gitBranch,
+                    sessionName: this.#engine.session?.sessionManager?.getSessionName() ?? null,
+                    availableProviderCount: new Set(this.#engine.runtime?.services.modelRuntime.getAvailableSnapshot?.().map(model => model.provider).filter(provider => provider !== undefined) ?? []).size,
+                    extensionStatuses: [],
+                },
+            },
+            terminal: { ...this.#terminal },
+            activeModel: this.#activeModel === null ? null : { ...this.#activeModel },
+            thinkingLevel: this.#thinkingLevel,
+            activeCommandIds: [...this.#commands.activeCommandIds],
+            dialog: null,
+            overlay: null,
+            customizations: [],
+            diagnostics: this.#diagnostics.map(diagnostic => ({ ...diagnostic })),
+        };
+    }
+    snapshot() {
+        const snapshot = {
+            contractVersion: 1,
+            snapshotId: `snapshot-${this.#viewRevision}`,
+            sessionId: this.#sessionId,
+            sequence: this.#delivery.sequence,
+            view: this.view(),
+        };
+        assertOwnedUiSnapshot(snapshot);
+        return snapshot;
+    }
+    execute(command) {
+        return this.#commands.execute(command);
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#commands.cancelPending(["shutdown"]);
+        // Compatibility: /quit owns normal disposal and must report its actual completion, not cancel itself.
+        this.#workflows.cancelPending("quit");
+        this.#projection.assets.clear();
+        await this.#extensions.unbind();
+        this.#lifecycle = "stopping";
+        this.#emitEvent({ type: "session-lifecycle", lifecycle: "stopping", reason: null });
+        await this.#engine.dispose();
+        this.#lifecycle = "stopped";
+        this.#emitEvent({ type: "session-lifecycle", lifecycle: "stopped", reason: null });
+        this.#emitView();
+        try {
+            await this.flushEvents();
+        }
+        catch (error) {
+            if (!(error instanceof EngineDeliveryError))
+                throw error;
+        }
+    }
+    #requireWorkflowSession() {
+        if (this.#disposed || !this.#engine.runtime || !this.#engine.session)
+            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: the runtime already advanced the generation and subscribed; this rebuilds what the view derives from a session.
+    #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.#events.reset();
+        this.#activeModel = readModel(session.model);
+        this.#reconcileActiveModelAvailability();
+        this.#thinkingLevel = readThinkingLevel(session.thinkingLevel);
+        this.#projection.assets.clear();
+        // Invariant: a new binding cannot inherit arguments/results from a reused invocation id.
+        this.#setTranscript([]);
+        this.#setTranscript(this.#projection.rebuild(session.messages, "finalized"));
+        if (this.#extensions.attached)
+            void this.#extensions.rebind();
+    }
+    #reconcileActiveModelAvailability() {
+        const modelRuntime = this.#engine.runtime?.services.modelRuntime;
+        if (!modelRuntime) {
+            this.#activeModel = null;
+            return;
+        }
+        const available = modelRuntime.getAvailableSnapshot?.() ?? [];
+        const sessionModel = readModel(this.#engine.session?.model);
+        const authoritative = this.#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;
+    }
+    #setTranscript(blocks) {
+        // Invariant: lazy delivery snapshots must freeze before their authoritative source can be removed.
+        if (!this.#delivery.seal()) {
+            this.#delivery.beginOverload();
+            return;
+        }
+        this.#projection.replace(blocks);
+    }
+    #addDiagnostic(severity, code, message, recoverable) {
+        const diagnostic = this.#recordDiagnostic(severity, code, message, recoverable);
+        this.#emitEvent({ type: "diagnostic", diagnostic });
+    }
+    #emitView() {
+        this.#usageCache = undefined;
+        this.#viewRevision += 1;
+        this.#emitEvent({ type: "session-view", view: this.view() });
+    }
+    #emitEvent(value) {
+        if (value.type !== "session-view")
+            this.#viewRevision += 1;
+        this.#delivery.emit(value);
+    }
+    // Concurrency: cancellation runs synchronously so the overload reservation already guards reentrant outcomes.
+    #cancelForOverload() {
+        this.#commands.cancelPending();
+        this.#workflows.cancelPending();
+        const session = this.#engine.session;
+        return Promise.resolve().then(() => session?.abort()).then(() => undefined);
+    }
+    async #reconcileOverload(cancelled) {
+        const canResume = cancelled === true && this.#runningCommands === 0;
+        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;
+        // 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" });
+        this.#setTranscript(this.#projection.blocks.map(block => block.status === "live" ? { ...block, status: "finalized", revision: block.revision + 1 } : block));
+        for (const [correlationId, result] of this.#delivery.takeReservedOutcomes()) {
+            this.#delivery.deliverNow(this.#delivery.stamp({ type: "command-outcome", correlationId, ...result }));
+            await new Promise(resolve => setImmediate(resolve));
+        }
+        // Invariant: one out-of-band authoritative reconciliation, not an emergency transcript/event log.
+        this.#delivery.deliverNow(this.#delivery.stamp({ type: "session-view", view: this.view() }));
+        if (this.#disposed)
+            this.#delivery.deliverNow(this.#delivery.stamp({ type: "session-lifecycle", lifecycle: "stopped", reason: null }));
+        if (canResume && !this.#disposed)
+            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;
+    }
+}
+export async function createPiEngineAdapter(options = {}) {
+    const adapter = new PiEngineAdapter(options);
+    await adapter.start();
+    return adapter;
+}

package/dist/integrations/pi/engine/changelog.d.ts

@@ -0,0 +1,2 @@
+export declare function readPinnedCommandChangelog(sinceVersion?: string): Promise<string>;
+export declare function formatPinnedCommandChangelog(content: string, sinceVersion?: string): string;