@timurproko/a1 0.2.7-dev.806 → 0.2.7-dev.809

package/dist/app/session-shell/login-interaction.js

@@ -0,0 +1,91 @@
+import { createPiShellExtensionSelector, createPiShellLoginDialog, } from "../../integrations/pi/components/shell-selectors-dialogs.js";
+import { componentRuntime } from "./shell-host.js";
+/**
+ * The engine's login flow in the dock: one login dialog at a time, the prompts and selections the
+ * engine asks through it, and the terminal's blocked-on-authentication status while it is open.
+ */
+export class LoginInteraction {
+    #ports;
+    #dialog;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    start(request) {
+        this.finish();
+        const dialog = createPiShellLoginDialog(componentRuntime(this.#ports.terminal), request.providerId, success => {
+            if (!success)
+                this.finish();
+        }, request.providerName);
+        this.#dialog = dialog;
+        this.#ports.root.setInputSurface(dialog);
+        this.#ports.programStatus.setBlocked("authentication", {
+            kind: "auth",
+            message: `Log in to ${request.providerName}`,
+        });
+        this.#ports.syncProgress();
+        this.#ports.terminal.requestRender();
+    }
+    /** Answers an engine prompt through the open dialog; null when no login is in progress or it is cancelled. */
+    requestInput(request) {
+        const dialog = this.#dialog;
+        if (!dialog)
+            return Promise.resolve(null);
+        if (request.type === "select") {
+            return new Promise(resolve => {
+                const options = request.options ?? [];
+                const labels = options.map(option => option.label);
+                const restoreDialog = () => {
+                    if (this.#dialog === dialog)
+                        this.#ports.root.setInputSurface(dialog);
+                    this.#ports.terminal.requestRender();
+                };
+                const selector = createPiShellExtensionSelector(request.message, labels, label => {
+                    const id = options.find(option => option.label === label)?.id;
+                    restoreDialog();
+                    resolve(id ?? null);
+                }, () => {
+                    restoreDialog();
+                    resolve(null);
+                });
+                this.#ports.root.setInputSurface(selector, false);
+                this.#ports.terminal.requestRender();
+            });
+        }
+        const response = request.type === "manual-code"
+            ? dialog.showManualInput(request.message)
+            : dialog.showPrompt(request.message, request.placeholder);
+        this.#ports.terminal.requestRender();
+        return response.then(value => value, () => null);
+    }
+    notify(event) {
+        const dialog = this.#dialog;
+        if (!dialog)
+            return;
+        if (event.type === "auth_url")
+            dialog.showAuth(event.url, event.instructions);
+        else if (event.type === "device_code") {
+            dialog.showDeviceCode(event);
+            dialog.showWaiting("Waiting for authentication...");
+        }
+        else if (event.type === "info")
+            dialog.showInfo(event.message, event.links);
+        else if (event.type === "waiting")
+            dialog.showWaiting(event.message);
+        else
+            dialog.showProgress(event.message);
+        this.#ports.terminal.requestRender();
+    }
+    finish() {
+        if (!this.#dialog)
+            return;
+        this.#dialog = undefined;
+        this.#ports.root.setInputSurface(null);
+        this.#ports.programStatus.setBlocked("authentication", undefined);
+        this.#ports.syncProgress();
+        this.#ports.terminal.requestRender();
+    }
+    /** A replaced session forgets its dialog; the presenter clears the input surface as part of the same replacement. */
+    onSessionReplaced() {
+        this.#dialog = undefined;
+    }
+}

package/dist/app/session-shell/prompt-submission.d.ts

@@ -0,0 +1,48 @@
+import type { OwnedUiCommand, OwnedUiCommandResult, OwnedUiSessionBackend, OwnedUiSessionViewModel, PromptHistoryImageSidecarPort } from "../../contracts/owned-ui/index.js";
+import type { PromptHistoryController } from "./prompt-history-controller.js";
+import type { ResidentTabCoordinator } from "./resident-tab-coordinator.js";
+import type { SessionConcern } from "./session-concern.js";
+import type { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+import type { OwnedUiPresenterTerminal } from "./shell-host.js";
+export interface PromptSubmissionPorts {
+    readonly backend: Pick<OwnedUiSessionBackend, "session" | "identity" | "workflows">;
+    readonly root: Pick<OwnedUiSessionShellRoot, "editor" | "hasPendingPastes" | "waitForPromptPastes" | "setExtensionWidget" | "prepareHistoryText" | "imageChipAttachmentsFromEditor" | "preparePromptSubmission" | "omitUnsentPromptImages" | "resumeViewportFollowing" | "beginImageSubmissionStatus" | "appendWorkflowResult">;
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "requestRender">;
+    readonly residentTab: ResidentTabCoordinator;
+    readonly cwd: string;
+    promptHistory(): PromptHistoryController | null;
+    imageSidecar(): PromptHistoryImageSidecarPort | undefined;
+    disposed(): boolean;
+    correlation(prefix: string): string;
+    lifecycle(): OwnedUiSessionViewModel["lifecycle"];
+    currentSessionFile(): string | null;
+    /** Slash input the presenter routes itself: owned routes, workflows, and skills. */
+    slashCommand(text: string): Promise<OwnedUiCommandResult>;
+    /** A prompt is about to be submitted; a pending suggestion for the old draft no longer applies. */
+    invalidateSuggestions(): void;
+}
+/**
+ * Turns editor input into engine commands: prompts, steering, follow-ups, and bash, each recorded
+ * in history first. It holds a submission whose image pastes are still preparing, journals prompts
+ * for resident tabs, and recovers the draft when a submission is rejected.
+ */
+export declare class PromptSubmission implements SessionConcern {
+    #private;
+    constructor(ports: PromptSubmissionPorts);
+    /** True while a submission waits for its image pastes. */
+    get waiting(): boolean;
+    /** The editor changed; a later recovery never overwrites input typed after its submission. */
+    noteEditorChange(): void;
+    submit(text: string): Promise<OwnedUiCommandResult>;
+    queueFollowUp(draft: string): Promise<OwnedUiCommandResult>;
+    cancelWaiting(): void;
+    /** Puts waiting submissions and the engine's queued input back into the editor. */
+    restoreQueued(): void;
+    /** Sends slash text the shell does not own as engine prompt input; history keeps what was typed. */
+    sendSlashPrompt(text: string, typed?: string): Promise<OwnedUiCommandResult>;
+    /** Executes a command; with a draft, a rejected or failed submission puts the draft back for recovery. */
+    execute(command: OwnedUiCommand, draft?: string): Promise<OwnedUiCommandResult>;
+    reportError(error?: unknown, message?: string): void;
+    onSessionReplaced(): void;
+    dispose(): void;
+}

package/dist/app/session-shell/prompt-submission.js

@@ -0,0 +1,276 @@
+import { assertOwnedUiCommand, assertPromptImages, ImageAttachmentError, } from "../../contracts/owned-ui/index.js";
+import { renderPiShellStatusText } from "../../integrations/pi/components/shell-presenters-info.js";
+const rejected = (diagnostic) => ({ outcome: "rejected", diagnostic });
+/**
+ * Turns editor input into engine commands: prompts, steering, follow-ups, and bash, each recorded
+ * in history first. It holds a submission whose image pastes are still preparing, journals prompts
+ * for resident tabs, and recovers the draft when a submission is rejected.
+ */
+export class PromptSubmission {
+    #ports;
+    #waiting = new Map();
+    #editorRevision = 0;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    /** True while a submission waits for its image pastes. */
+    get waiting() {
+        return this.#waiting.size > 0;
+    }
+    /** The editor changed; a later recovery never overwrites input typed after its submission. */
+    noteEditorChange() {
+        this.#editorRevision++;
+    }
+    submit(text) {
+        return this.#whenReady(text, () => this.#submit(text));
+    }
+    queueFollowUp(draft) {
+        return this.#whenReady(draft, () => this.#queueFollowUp(draft));
+    }
+    cancelWaiting() {
+        for (const item of this.#waiting.values())
+            item.controller.abort();
+    }
+    /** Puts waiting submissions and the engine's queued input back into the editor. */
+    restoreQueued() {
+        const queued = [...this.#waiting.keys(), ...this.#ports.backend.workflows.clearQueuedWorkflows()];
+        this.cancelWaiting();
+        if (queued.length === 0)
+            return;
+        this.#ports.root.editor.setText(queued.join("\n"));
+        this.#ports.terminal.requestRender();
+    }
+    /** Sends slash text the shell does not own as engine prompt input; history keeps what was typed. */
+    sendSlashPrompt(text, typed = text) {
+        this.#rememberInput(typed, "slash");
+        this.#ports.root.resumeViewportFollowing();
+        return this.execute({
+            type: this.#ports.lifecycle() === "busy" ? "steer" : "prompt",
+            correlationId: this.#ports.correlation("prompt-command"),
+            sessionId: this.#ports.backend.identity.sessionId,
+            text,
+        });
+    }
+    /** Executes a command; with a draft, a rejected or failed submission puts the draft back for recovery. */
+    async execute(command, draft) {
+        const { backend } = this.#ports;
+        if (draft === undefined)
+            return backend.session.execute(command);
+        const revision = this.#editorRevision;
+        try {
+            assertOwnedUiCommand(command);
+        }
+        catch (error) {
+            return this.#recover(draft, revision, error);
+        }
+        try {
+            const result = await backend.session.execute(command);
+            if (result.outcome === "rejected")
+                return this.#recover(draft, revision);
+            return result;
+        }
+        catch {
+            // Security: dispatch might already have reached the provider. Never retry automatically.
+            this.#ports.root.editor.addToHistory(draft);
+            this.#ports.promptHistory()?.rememberRecovery(draft);
+            this.reportError(undefined, "Submission failed; delivery is uncertain. Check the conversation before retrying. Press Up to recover the draft.");
+            return { outcome: "failed", diagnostic: "submission delivery is uncertain" };
+        }
+    }
+    reportError(error, message) {
+        // Security: arbitrary provider/extension error messages can contain the entire request.
+        try {
+            this.#ports.root.appendWorkflowResult({ command: "debug", outcome: "failed", message: message
+                    ?? (error instanceof ImageAttachmentError ? error.message : "Submission failed. Check the prompt and try again.") }, error instanceof ImageAttachmentError ? error.code : undefined);
+            this.#ports.terminal.requestRender();
+        }
+        catch { /* Security: error presentation cannot create another rejected submission callback. */ }
+    }
+    onSessionReplaced() {
+        this.cancelWaiting();
+    }
+    dispose() {
+        this.cancelWaiting();
+    }
+    #whenReady(draft, action) {
+        const { root, backend } = this.#ports;
+        const previous = this.#waiting.get(draft);
+        if (previous !== undefined)
+            return previous.result;
+        if (!root.hasPendingPastes(draft))
+            return this.#guard(draft, action);
+        const controller = new AbortController();
+        const generation = backend.identity.sessionGeneration;
+        const result = this.#guard(draft, async () => {
+            await root.waitForPromptPastes(draft, controller.signal);
+            if (controller.signal.aborted || this.#ports.disposed() || backend.identity.sessionGeneration !== generation)
+                return rejected("image submission canceled");
+            return action();
+        }).finally(() => {
+            this.#waiting.delete(draft);
+            if (!this.#ports.disposed())
+                this.#showWaiting();
+        });
+        this.#waiting.set(draft, { controller, result });
+        if (root.editor.getText() === draft)
+            root.editor.setText("");
+        this.#showWaiting();
+        return result;
+    }
+    #showWaiting() {
+        const count = this.#waiting.size;
+        this.#ports.root.setExtensionWidget("owned-image-preparation", count === 0 ? null : {
+            render: width => [...renderPiShellStatusText(`Waiting for images (${count} submission${count === 1 ? "" : "s"}) — Esc cancels; dequeue restores`, width)],
+            invalidate: () => { },
+        }, "aboveEditor");
+        this.#ports.terminal.requestRender();
+    }
+    async #guard(draft, action) {
+        const revision = this.#editorRevision;
+        try {
+            return await action();
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError && error.code === "image-canceled")
+                return rejected("image submission canceled");
+            return this.#recover(draft, revision, error);
+        }
+    }
+    #recover(draft, revision, error) {
+        const { root } = this.#ports;
+        root.editor.addToHistory(draft);
+        this.#ports.promptHistory()?.rememberRecovery(draft);
+        // Concurrency: never overwrite input typed (even typed and cleared) after this submission.
+        if (revision === this.#editorRevision && root.editor.getText().length === 0)
+            root.editor.setText(draft);
+        const message = error instanceof ImageAttachmentError ? error.message : "Submission rejected. Check the prompt and attachments.";
+        this.reportError(error, error instanceof ImageAttachmentError && error.code === "image-count"
+            ? message
+            : `${message} Press Up to recover the draft.`);
+        return rejected(message);
+    }
+    #rememberInput(text, kind) {
+        const { root } = this.#ports;
+        root.editor.addToHistory(text);
+        const history = this.#ports.promptHistory();
+        if (history === null)
+            return;
+        const reusable = root.prepareHistoryText(text);
+        if (reusable.length === 0) {
+            history.rememberRecovery(text);
+            return;
+        }
+        // Rationale: write the image chip payloads referenced by an editor draft to the sidecar
+        // directory before their history row commits. Missing sidecar dependency = silent skip; the
+        // recall path treats an absent sidecar the same as a corrupt one.
+        const sidecar = this.#ports.imageSidecar();
+        if (sidecar !== undefined) {
+            for (const record of root.imageChipAttachmentsFromEditor(text)) {
+                sidecar.write(record.id, { tag: record.tag, data: record.image.data, mimeType: record.image.mimeType, savedAt: new Date().toISOString() });
+            }
+        }
+        history.capture(reusable, kind, this.#ports.cwd, this.#ports.backend.identity.sessionId);
+    }
+    async #submit(text) {
+        this.#ports.invalidateSuggestions();
+        const displayInput = text.trim();
+        if (!displayInput)
+            return { outcome: "completed", diagnostic: null };
+        if (displayInput.startsWith("/"))
+            return this.#ports.slashCommand(displayInput);
+        const { root, backend } = this.#ports;
+        const prepared = root.preparePromptSubmission(displayInput);
+        assertPromptImages(prepared.images);
+        const input = prepared.text.trim();
+        if (input.startsWith("!")) {
+            const bash = await this.#bash(input, displayInput);
+            if (bash !== undefined)
+                return bash;
+        }
+        // Compatibility: match interactive Pi: input during compaction is queued steering; the engine
+        // shows it in the pending rows and delivers it when compaction ends.
+        const type = this.#ports.lifecycle() === "busy" ? "steer" : "prompt";
+        this.#rememberInput(root.omitUnsentPromptImages(displayInput).trim(), type);
+        root.resumeViewportFollowing();
+        const command = {
+            type,
+            correlationId: this.#ports.correlation(type),
+            sessionId: backend.identity.sessionId,
+            text: input,
+            ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+        };
+        let submission;
+        try {
+            submission = await this.#ports.residentTab.admit({
+                sessionId: command.sessionId,
+                sessionFile: this.#ports.currentSessionFile(),
+                kind: type,
+                text: input,
+            });
+        }
+        catch {
+            if (root.editor.getText().length === 0)
+                root.editor.setText(displayInput);
+            const message = "Prompt was not sent because its recovery journal could not be synchronized.";
+            this.reportError(undefined, message);
+            return rejected(message);
+        }
+        const finishSending = prepared.images.length === 0 ? () => { } : root.beginImageSubmissionStatus();
+        try {
+            const result = await this.execute(command, displayInput);
+            if (submission !== undefined && result.outcome !== "rejected") {
+                await this.#ports.residentTab.dispatched(submission.id, command.correlationId);
+            }
+            return result;
+        }
+        finally {
+            finishSending();
+        }
+    }
+    // Protocol: `!command` runs bash with its output in context, `!!command` keeps it out; an empty command is prompt text.
+    async #bash(input, displayInput) {
+        const excludeFromContext = input.startsWith("!!");
+        const command = input.slice(excludeFromContext ? 2 : 1).trim();
+        if (!command)
+            return undefined;
+        this.#rememberInput(displayInput, "bash");
+        try {
+            const result = await this.#ports.backend.workflows.executeBashWorkflow(command, excludeFromContext);
+            const workflow = {
+                command: "debug",
+                outcome: result.cancelled ? "cancelled" : result.exitCode === 0 || result.exitCode === undefined ? "completed" : "failed",
+                message: result.cancelled ? "Bash command cancelled" : `Bash exited ${result.exitCode ?? 0}: ${command}`,
+                ...(result.output ? { detail: result.output } : {}),
+            };
+            this.#ports.root.appendWorkflowResult(workflow);
+            this.#ports.terminal.requestRender();
+            return workflow.outcome === "failed" ? rejected(workflow.message) : { outcome: "completed", diagnostic: null };
+        }
+        catch (error) {
+            const message = `Bash command failed: ${error instanceof Error ? error.message : String(error)}`;
+            this.#ports.root.appendWorkflowResult({ command: "debug", outcome: "failed", message });
+            this.#ports.terminal.requestRender();
+            return rejected(message);
+        }
+    }
+    async #queueFollowUp(draft) {
+        const { root, backend } = this.#ports;
+        const displayInput = draft.trim();
+        if (!displayInput)
+            return rejected("nothing to queue");
+        const prepared = root.preparePromptSubmission(displayInput);
+        assertPromptImages(prepared.images);
+        const text = prepared.text.trim();
+        this.#rememberInput(displayInput, "follow-up");
+        if (root.editor.getText() === draft)
+            root.editor.setText("");
+        root.resumeViewportFollowing();
+        return this.execute({
+            type: "follow-up",
+            correlationId: this.#ports.correlation("follow-up"),
+            sessionId: backend.identity.sessionId,
+            text,
+            ...(prepared.images.length === 0 ? {} : { images: prepared.images }),
+        }, displayInput);
+    }
+}

package/dist/app/session-shell/resident-tab-coordinator.d.ts

@@ -0,0 +1,41 @@
+import type { OwnedUiEvent, PromptHistoryImageSidecarPort } from "../../contracts/owned-ui/index.js";
+import type { SessionConcern } from "./session-concern.js";
+import type { OwnedUiShellEngineOptions, OwnedUiSessionShellRoot } from "./session-shell-root.js";
+import type { OwnedUiPresenterTerminal } from "./shell-host.js";
+export type ResidentTabOptions = NonNullable<OwnedUiShellEngineOptions["residentTab"]>;
+export interface ResidentTabCoordinatorPorts {
+    readonly root: Pick<OwnedUiSessionShellRoot, "appendWorkflowStatus" | "rehydrateHistoryText" | "editor">;
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "requestRender">;
+    readonly disposed: () => boolean;
+}
+/**
+ * The session presenter's side of a resident tab: recovered input, the progress and stall status
+ * it reports to the strip, prompt admission and correlation through the recovery journal, draft
+ * checkpoints, detach on quit, and the graceful stop when the presenter is released. Outside a
+ * resident tab every operation is a no-op.
+ */
+export declare class ResidentTabCoordinator implements SessionConcern {
+    #private;
+    constructor(options: ResidentTabOptions | undefined, ports: ResidentTabCoordinatorPorts);
+    /** True inside a resident tab, where Settings and the session name live in the global strip. */
+    get active(): boolean;
+    checkpoint(text: string): void;
+    closeOwnedRoute(route: string): void;
+    /** Puts the prompts and draft a previous tab process left unfinished back into the editor. */
+    restoreInput(imageSidecar?: PromptHistoryImageSidecarPort): void;
+    /** Tracks working, idle, and stalled status from session events and arms the stall notice. */
+    observeProgress(event: OwnedUiEvent): void;
+    /** Journals a prompt before it is sent; undefined outside a resident tab. Rejects when the journal cannot sync. */
+    admit(input: Parameters<NonNullable<ResidentTabOptions["admit"]>>[0]): Promise<{
+        readonly id: string;
+    } | undefined>;
+    /** The admitted prompt reached the engine; its journal entry is correlated with the engine's entry. */
+    dispatched(submissionId: string, entryId: string): Promise<void>;
+    /**
+     * Leaves the tab without stopping its engine. Returns undefined outside a resident tab, true when
+     * the client detached, or the notice to show when detaching is unavailable.
+     */
+    detach(): Promise<true | string | undefined>;
+    gracefulStop(sessionFile: string | null): Promise<void>;
+    dispose(): void;
+}

package/dist/app/session-shell/resident-tab-coordinator.js

@@ -0,0 +1,120 @@
+const PROGRESS_EVENTS = new Set([
+    "transcript-block", "session-view", "assistant-message-completed", "agent-run-started",
+]);
+/**
+ * The session presenter's side of a resident tab: recovered input, the progress and stall status
+ * it reports to the strip, prompt admission and correlation through the recovery journal, draft
+ * checkpoints, detach on quit, and the graceful stop when the presenter is released. Outside a
+ * resident tab every operation is a no-op.
+ */
+export class ResidentTabCoordinator {
+    #options;
+    #ports;
+    #progressTimer;
+    #working = false;
+    #stalled = false;
+    constructor(options, ports) {
+        this.#options = options;
+        this.#ports = ports;
+    }
+    /** True inside a resident tab, where Settings and the session name live in the global strip. */
+    get active() {
+        return this.#options !== undefined;
+    }
+    checkpoint(text) {
+        this.#options?.checkpoint?.(text);
+    }
+    closeOwnedRoute(route) {
+        this.#options?.closeOwnedRoute?.(route);
+    }
+    /** Puts the prompts and draft a previous tab process left unfinished back into the editor. */
+    restoreInput(imageSidecar) {
+        const recovered = this.#options?.recovered;
+        if (recovered === undefined)
+            return;
+        const { root } = this.#ports;
+        const prompts = recovered.prompts
+            .map(prompt => root.rehydrateHistoryText(prompt.text, id => imageSidecar?.readAttachment(id) ?? null))
+            .filter(Boolean);
+        if (prompts.length > 0) {
+            root.editor.setText(prompts[0]);
+            if (recovered.draft)
+                root.editor.addToHistory(recovered.draft);
+            for (const additional of prompts.slice(1))
+                root.editor.addToHistory(additional);
+            root.appendWorkflowStatus(recovered.draft
+                ? `Recovered an unfinished prompt; the prior draft and ${Math.max(0, prompts.length - 1)} additional prompt${prompts.length === 2 ? "" : "s"} are in editor history.`
+                : `Recovered an unfinished prompt${prompts.length > 1 ? `; ${prompts.length - 1} additional prompts are in editor history` : ""}.`);
+        }
+        else if (recovered.draft) {
+            root.editor.setText(recovered.draft);
+            root.appendWorkflowStatus("Recovered the editor draft from the previous tab process.");
+        }
+    }
+    /** Tracks working, idle, and stalled status from session events and arms the stall notice. */
+    observeProgress(event) {
+        const resident = this.#options;
+        const seconds = resident?.stallNoticeSeconds;
+        if (resident === undefined || seconds === undefined)
+            return;
+        if (event.type === "session-lifecycle") {
+            this.#working = event.lifecycle === "busy";
+            if (!this.#working) {
+                this.#clearTimer();
+                this.#stalled = false;
+                resident.reportStatus?.("idle");
+                return;
+            }
+        }
+        else if (!this.#working || !PROGRESS_EVENTS.has(event.type)) {
+            return;
+        }
+        if (this.#stalled) {
+            this.#stalled = false;
+            resident.reportStatus?.("working");
+        }
+        this.#clearTimer();
+        this.#progressTimer = setTimeout(() => {
+            this.#progressTimer = undefined;
+            if (this.#ports.disposed() || !this.#working)
+                return;
+            this.#stalled = true;
+            resident.reportStatus?.("stalled");
+            const minutes = Math.max(1, Math.round(seconds / 60));
+            this.#ports.root.appendWorkflowStatus(`No progress for ${minutes} min — Esc interrupts · use the tab restart action to restart`);
+            this.#ports.terminal.requestRender();
+        }, seconds * 1_000);
+        this.#progressTimer.unref?.();
+    }
+    /** Journals a prompt before it is sent; undefined outside a resident tab. Rejects when the journal cannot sync. */
+    admit(input) {
+        return this.#options?.admit?.(input) ?? Promise.resolve(undefined);
+    }
+    /** The admitted prompt reached the engine; its journal entry is correlated with the engine's entry. */
+    async dispatched(submissionId, entryId) {
+        this.#options?.dispatched?.();
+        await this.#options?.correlated?.(submissionId, entryId).catch(() => undefined);
+    }
+    /**
+     * Leaves the tab without stopping its engine. Returns undefined outside a resident tab, true when
+     * the client detached, or the notice to show when detaching is unavailable.
+     */
+    async detach() {
+        const resident = this.#options;
+        if (resident === undefined)
+            return undefined;
+        const detached = await resident.requestDetach().catch(() => false);
+        return detached ? true : resident.unavailableNotice ?? "Press Ctrl+C twice to leave; this agent keeps running.";
+    }
+    gracefulStop(sessionFile) {
+        return this.#options?.gracefulStop?.(sessionFile) ?? Promise.resolve();
+    }
+    dispose() {
+        this.#clearTimer();
+    }
+    #clearTimer() {
+        if (this.#progressTimer !== undefined)
+            clearTimeout(this.#progressTimer);
+        this.#progressTimer = undefined;
+    }
+}

package/dist/app/session-shell/session-concern.d.ts

@@ -0,0 +1,22 @@
+/**
+ * One piece of a session presenter's state that resets itself when the backend replaces the
+ * session and releases itself when the presenter is released.
+ */
+export interface SessionConcern {
+    /** The backend replaced the session: drop the pending work, timers, and surfaces that belonged to it. */
+    onSessionReplaced?(): void;
+    /** Release everything this concern holds; called at most once. */
+    dispose?(): void;
+}
+/**
+ * The presenter's concerns in their declared order. Session replacement and disposal fan out in
+ * that order, because later resets depend on earlier ones (copy intent before pastes before the
+ * input surface), and disposal is idempotent.
+ */
+export declare class SessionConcerns {
+    #private;
+    constructor(concerns: readonly SessionConcern[]);
+    replaceSession(): void;
+    /** Disposes each concern once, through `attempt` so one failure does not skip the rest. */
+    dispose(attempt?: (action: () => void) => void): void;
+}

package/dist/app/session-shell/session-concern.js

@@ -0,0 +1,29 @@
+/**
+ * The presenter's concerns in their declared order. Session replacement and disposal fan out in
+ * that order, because later resets depend on earlier ones (copy intent before pastes before the
+ * input surface), and disposal is idempotent.
+ */
+export class SessionConcerns {
+    #concerns;
+    #disposed = false;
+    constructor(concerns) {
+        this.#concerns = concerns;
+    }
+    replaceSession() {
+        if (this.#disposed)
+            return;
+        for (const concern of this.#concerns)
+            concern.onSessionReplaced?.();
+    }
+    /** Disposes each concern once, through `attempt` so one failure does not skip the rest. */
+    dispose(attempt = action => action()) {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const concern of this.#concerns) {
+            const dispose = concern.dispose;
+            if (dispose !== undefined)
+                attempt(() => dispose.call(concern));
+        }
+    }
+}

package/dist/app/session-shell/session-lifecycle.d.ts

@@ -0,0 +1,29 @@
+export interface SessionResumeCommandMetadata {
+    readonly sessionId: string;
+    readonly sessionDir: string;
+    readonly usesDefaultSessionDir: boolean;
+}
+export declare function formatSessionResumeCommand(metadata: SessionResumeCommandMetadata): string;
+export declare function quoteCommandArgument(value: string): string;
+export interface ExitTextInput {
+    readonly terminalMode: "regular" | "fullscreen";
+    readonly customViewport: boolean;
+    readonly exitMode: "transcript" | "resume-hint";
+    readonly resume: SessionResumeCommandMetadata | null;
+    /** The styled transcript, rendered only when the pinned profile asks for it. */
+    readonly transcript: () => string;
+}
+/**
+ * What a fullscreen leave prints into the parent terminal: nothing after a regular-screen session,
+ * only the resume hint for bare A1 or when configured, and otherwise the transcript then the hint.
+ */
+export declare function composeExitText(input: ExitTextInput): string;
+/** Resolves once when the session stops, whether it stopped itself, was quit, or was disposed. */
+export declare class SessionStopLatch {
+    #private;
+    readonly stopped: Promise<void>;
+    constructor();
+    resolve(): void;
+    /** The engine stopped on its own: dispose the shell, then resolve whether or not disposal failed. */
+    settleAfter(dispose: () => Promise<void>): void;
+}