@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.512

package/dist/integrations/pi/engine/session-integration.js

@@ -0,0 +1,195 @@
+import { AGENT_ENGINE_CONTRACT_VERSION, } from "../../../contracts/agent-engine/index.js";
+/** Routes neutral session commands to Pi while preserving Pi streaming and retry semantics. */
+export class PiSessionCommandIntegration {
+    #lastPrompt = null;
+    // Rationale: Pi's queue restore returns text only, so the attachments of messages queued
+    // during compaction are kept here until the queue is delivered or cleared.
+    #queuedImages = [];
+    session;
+    constructor(session) { this.session = session; }
+    async execute(command) {
+        switch (command.type) {
+            case "prompt":
+                this.#lastPrompt = command.text;
+                await this.session.prompt(command.text, command.images === undefined
+                    ? this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined
+                    : {
+                        ...(this.session.isStreaming ? { streamingBehavior: "followUp" } : {}),
+                        images: [...command.images],
+                    });
+                return { outcome: "completed" };
+            case "steer":
+            case "follow-up": {
+                this.#lastPrompt = command.text;
+                const mode = command.type === "steer" ? "steer" : "followUp";
+                if (this.session.isCompacting && !this.#isExtensionCommand(command.text)) {
+                    // Compatibility: match interactive Pi: prompt() refuses input during manual compaction,
+                    // while the engine queue accepts it at any time and delivers it when compaction ends.
+                    await this.#queue(mode, command.text, command.images);
+                    return { outcome: "completed" };
+                }
+                // Compatibility: match interactive Pi: prompt() owns template/extension expansion and
+                // turns the accepted steering message into the visible user row while
+                // later messages remain in the pending queue.
+                await this.session.prompt(command.text, {
+                    streamingBehavior: mode,
+                    ...(command.images === undefined ? {} : { images: [...command.images] }),
+                });
+                return { outcome: "completed" };
+            }
+            case "abort":
+                if (this.session.isRetrying)
+                    this.session.abortRetry();
+                if (this.session.isCompacting)
+                    this.session.abortCompaction();
+                await this.session.abort();
+                return { outcome: "cancelled" };
+            case "retry":
+                if (this.#lastPrompt === null)
+                    return { outcome: "rejected" };
+                await this.session.prompt(this.#lastPrompt, this.session.isStreaming ? { streamingBehavior: "followUp" } : undefined);
+                return { outcome: "completed" };
+            case "compact":
+                return { outcome: "completed", value: await this.session.compact() };
+            case "bash": {
+                if (!this.session.executeBash)
+                    return { outcome: "rejected" };
+                const value = await this.session.executeBash(command.command, command.onChunk, { excludeFromContext: command.excludeFromContext });
+                if (!value || typeof value !== "object")
+                    throw new TypeError("Pi bash result is malformed");
+                const result = value;
+                if (typeof result.cancelled !== "boolean" || (result.exitCode !== undefined && typeof result.exitCode !== "number"))
+                    throw new TypeError("Pi bash result is malformed");
+                return { outcome: result.cancelled ? "cancelled" : result.exitCode === 0 ? "completed" : "failed", value };
+            }
+        }
+    }
+    /**
+     * Delivers the messages queued during a manual compaction. The session is idle when a manual
+     * compaction ends, so nothing would consume the queue: the first message starts one run
+     * through the ordinary prompt path with its mode, and the rest are re-queued for that run,
+     * whose initial poll injects them in order. Automatic compaction needs no delivery: its
+     * continuing run or pending prompt consumes the queue itself. The run is not awaited; when
+     * the start is refused before the message is accepted, the queue is restored and the error
+     * reported through `onFailure`.
+     */
+    async deliverQueuedAfterCompaction(onFailure) {
+        if (this.session.isStreaming || this.session.isCompacting)
+            return;
+        const { steering, followUp } = this.session.clearQueue();
+        const queued = [
+            ...steering.map(text => ({ mode: "steer", text, images: this.#takeImages(text) })),
+            ...followUp.map(text => ({ mode: "followUp", text, images: this.#takeImages(text) })),
+        ];
+        this.#queuedImages = [];
+        const [first, ...rest] = queued;
+        if (first === undefined)
+            return;
+        this.#lastPrompt = first.text;
+        let accepted = false;
+        const started = this.session.prompt(first.text, {
+            streamingBehavior: first.mode,
+            preflightResult: success => { accepted = success; },
+            ...(first.images === undefined ? {} : { images: [...first.images] }),
+        });
+        for (const item of rest)
+            await this.#queue(item.mode, item.text, item.images);
+        started.catch(async (error) => {
+            // Security: a run that reached the provider is never resent; only a refused start restores.
+            try {
+                if (!accepted)
+                    await this.#restoreQueue(queued);
+            }
+            finally {
+                onFailure(error);
+            }
+        }).catch(() => undefined);
+    }
+    /** Forgets the attachments kept for queued messages; the queue itself was cleared by the caller. */
+    forgetQueuedImages() {
+        this.#queuedImages = [];
+    }
+    // Rationale: the rest were re-queued before the refused start surfaced, so the queue is rebuilt
+    // in the original order; anything queued in between keeps its place after it.
+    async #restoreQueue(queued) {
+        const { steering, followUp } = this.session.clearQueue();
+        const restored = new Set(queued.map(item => item.text));
+        const extra = [
+            ...steering.filter(text => !restored.has(text)).map(text => ({ mode: "steer", text, images: this.#takeImages(text) })),
+            ...followUp.filter(text => !restored.has(text)).map(text => ({ mode: "followUp", text, images: this.#takeImages(text) })),
+        ];
+        this.#queuedImages = [];
+        for (const item of [...queued, ...extra])
+            await this.#queue(item.mode, item.text, item.images);
+    }
+    async #queue(mode, text, images) {
+        if (images !== undefined && images.length > 0)
+            this.#queuedImages.push({ text, images: [...images] });
+        if (mode === "steer")
+            await this.session.steer(text, images === undefined ? undefined : [...images]);
+        else
+            await this.session.followUp(text, images === undefined ? undefined : [...images]);
+    }
+    #takeImages(text) {
+        const index = this.#queuedImages.findIndex(item => item.text === text);
+        if (index === -1)
+            return undefined;
+        const [item] = this.#queuedImages.splice(index, 1);
+        return item?.images;
+    }
+    #isExtensionCommand(text) {
+        if (!text.startsWith("/"))
+            return false;
+        const spaceIndex = text.indexOf(" ");
+        const name = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        return this.session.extensionRunner?.getCommand(name) !== undefined;
+    }
+}
+export function subscribeToPiSessionEvents(session, sessionId, emit, malformed) {
+    let sequence = 0;
+    let disposed = false;
+    const unsubscribe = session.subscribe(event => {
+        if (disposed)
+            return;
+        sequence += 1;
+        try {
+            const converted = convertPiSessionEvent(event, sessionId, sequence);
+            if (converted)
+                emit(converted);
+        }
+        catch (error) {
+            malformed(`Pi session event ${sequence} is malformed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    return { dispose() { if (disposed)
+            return; disposed = true; unsubscribe(); } };
+}
+export function convertPiSessionEvent(event, sessionId, sequence) {
+    const base = { contractVersion: AGENT_ENGINE_CONTRACT_VERSION, sessionId, sequence };
+    switch (event.type) {
+        case "agent_start": return { ...base, type: "lifecycle", lifecycle: "busy", reason: null };
+        case "agent_settled": return { ...base, type: "lifecycle", lifecycle: "ready", reason: null };
+        case "agent_end": return event.willRetry ? null : { ...base, type: "lifecycle", lifecycle: "ready", reason: null };
+        case "message_start":
+        case "message_update":
+        case "message_end":
+            return { ...base, type: "content", content: toAgentMessage(event.message, event.type === "message_end" ? "final" : "streaming", sequence) };
+        default: return null;
+    }
+}
+function toAgentMessage(value, status, sequence) {
+    if (!value || typeof value !== "object")
+        throw new TypeError("message payload is not an object");
+    const message = value;
+    const role = message.role === "user" || message.role === "assistant" || message.role === "tool" || message.role === "system" ? message.role : "assistant";
+    const source = Array.isArray(message.content) ? message.content : [];
+    const text = source.flatMap(part => part && typeof part === "object" && typeof part.text === "string" ? [part.text] : []).join("");
+    return {
+        id: typeof message.id === "string" ? message.id : `message-${sequence}`,
+        role,
+        status,
+        content: text.length > 0
+            ? [{ kind: "text", text }]
+            : [{ kind: "unknown", sourceType: "pi-message", payload: { role: String(message.role ?? "unknown") } }],
+    };
+}

package/dist/integrations/pi/engine/session-runtime.d.ts

@@ -0,0 +1,84 @@
+import { PiSessionCommandIntegration } from "./session-integration.js";
+import { type AgentSession, type AgentSessionRuntime, type AgentSessionServices } from "../startup-public.js";
+import type { PiProjectTrustPreflightPrompt } from "./project-trust-preflight.js";
+import type { PiSessionForkPrompt, PiSessionSelection } from "./session-selection.js";
+import type { OwnedUiDiagnostics } from "../../../contracts/owned-ui/index.js";
+import type { PiSessionResumeMetadata, PiWorkflowHost } from "./workflows.js";
+export interface PiEngineRuntimeFactoryInput {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly sessionId: string;
+    readonly sessionPath?: string;
+    readonly sessionSelection?: PiSessionSelection;
+    readonly sessionForkPrompt?: PiSessionForkPrompt;
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
+}
+export type PiEngineRuntimeFactory = (input: PiEngineRuntimeFactoryInput) => Promise<AgentSessionRuntime>;
+export type PiEnginePackageUpdateProbe = (settingsManager: AgentSessionServices["settingsManager"]) => Promise<readonly string[]>;
+export interface PiEngineRuntimeOptions {
+    readonly cwd: string;
+    readonly agentDir: string;
+    readonly sessionId: string;
+    readonly sessionPath: string | undefined;
+    readonly sessionSelection: PiSessionSelection | undefined;
+    readonly sessionForkPrompt: PiSessionForkPrompt | undefined;
+    readonly projectTrustPrompt: PiProjectTrustPreflightPrompt | undefined;
+    readonly createRuntime: PiEngineRuntimeFactory | undefined;
+    readonly checkPackageUpdates: PiEnginePackageUpdateProbe | undefined;
+    readonly host: PiWorkflowHost;
+}
+export interface PiEngineRuntimePorts {
+    disposed(): boolean;
+    /** The runtime exists and its cwd and git branch are known; nothing is bound yet. */
+    started(runtime: AgentSessionRuntime): void;
+    /** True while a runtime-initiated rebind must be ignored: delivery overload, stopped admission, or disposal. */
+    rebindBlocked(): boolean;
+    /** The current session is about to be replaced; admitted work that belongs to it is cancelled here. */
+    sessionReplacing(): void;
+    /** A session was bound and subscribed under a new generation; the adapter rebuilds the state it derives from one. */
+    sessionReplaced(session: AgentSession): void;
+    /** A runtime-initiated rebind completed; the adapter publishes the rebuilt view. */
+    rebound(): void;
+    /** A pinned Pi session event for the current generation. */
+    event(event: unknown): void;
+    compactionProgress(percent: number): void;
+    diagnostic(severity: OwnedUiDiagnostics["severity"], code: string, message: string, recoverable: boolean): void;
+    emitView(): void;
+}
+/**
+ * The pinned Pi runtime and the session bound to it: creation through the runtime factory, the
+ * session generation that stamps and invalidates events, the subscription that forwards session
+ * events, compaction progress observation, the queued-input integration, and disposal order. The
+ * adapter derives its view state from the session it is handed and never touches these directly.
+ */
+export declare class PiEngineRuntime {
+    #private;
+    constructor(options: PiEngineRuntimeOptions, ports: PiEngineRuntimePorts);
+    get runtime(): AgentSessionRuntime | undefined;
+    get session(): AgentSession | undefined;
+    /** Bumped on every bind and on overload recovery; events from an earlier generation are invalid. */
+    get generation(): number;
+    /** Actual session replacements, excluding delivery-only invalidation of callbacks. */
+    get bindingGeneration(): number;
+    get cwd(): string;
+    get gitBranch(): string | null;
+    get sessionCommands(): PiSessionCommandIntegration | undefined;
+    get started(): boolean;
+    /** Create the runtime, bind its first session, and announce the changelog; startup failures propagate. */
+    start(): Promise<AgentSessionRuntime>;
+    /** Probe extension packages for updates after startup and report them as an informational diagnostic. */
+    announcePackageUpdates(): Promise<void>;
+    currentSessionFile(): string | null;
+    currentSessionResumeMetadata(): PiSessionResumeMetadata | null;
+    /** Replace the bound session under a new generation and subscribe to its events. */
+    bindSession(session: AgentSession): void;
+    /** Stop forwarding the current session's events and open a new generation; overload recovery resumes or abandons it. */
+    suspend(): void;
+    /** Forward the current session's events again under the current generation. */
+    resume(): void;
+    compactionStarted(): void;
+    compactionEnded(): void;
+    deliverQueuedAfterCompaction(): void;
+    /** Unsubscribe, stop observing compaction, and dispose the runtime; the session reference is kept for final reads. */
+    dispose(): Promise<void>;
+}

package/dist/integrations/pi/engine/session-runtime.js

@@ -0,0 +1,249 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { observeCompactionProgress } from "./compaction-progress.js";
+import { createPiRuntimeIntegration } from "./runtime-integration.js";
+import { PiSessionCommandIntegration } from "./session-integration.js";
+import { DefaultPackageManager, VERSION } from "../startup-public.js";
+const execFileAsync = promisify(execFile);
+/**
+ * The pinned Pi runtime and the session bound to it: creation through the runtime factory, the
+ * session generation that stamps and invalidates events, the subscription that forwards session
+ * events, compaction progress observation, the queued-input integration, and disposal order. The
+ * adapter derives its view state from the session it is handed and never touches these directly.
+ */
+export class PiEngineRuntime {
+    #options;
+    #ports;
+    #runtimeFactory;
+    #checkPackageUpdates;
+    #cwd;
+    #runtime;
+    #session;
+    #unsubscribe;
+    #sessionGeneration = 0;
+    #sessionBindingGeneration = 0;
+    #sessionCommands;
+    #compactionProgress = null;
+    #gitBranch = null;
+    constructor(options, ports) {
+        this.#options = options;
+        this.#ports = ports;
+        this.#cwd = options.cwd;
+        this.#runtimeFactory = options.createRuntime ?? createDefaultPiRuntime;
+        this.#checkPackageUpdates = options.checkPackageUpdates
+            ?? (options.createRuntime
+                ? async () => []
+                : settingsManager => checkDefaultPiPackageUpdates(this.#cwd, options.agentDir, settingsManager));
+    }
+    get runtime() {
+        return this.#runtime;
+    }
+    get session() {
+        return this.#session;
+    }
+    /** Bumped on every bind and on overload recovery; events from an earlier generation are invalid. */
+    get generation() {
+        return this.#sessionGeneration;
+    }
+    /** Actual session replacements, excluding delivery-only invalidation of callbacks. */
+    get bindingGeneration() {
+        return this.#sessionBindingGeneration;
+    }
+    get cwd() {
+        return this.#runtime?.cwd ?? this.#cwd;
+    }
+    get gitBranch() {
+        return this.#gitBranch;
+    }
+    get sessionCommands() {
+        return this.#sessionCommands;
+    }
+    get started() {
+        return this.#runtime !== undefined;
+    }
+    /** Create the runtime, bind its first session, and announce the changelog; startup failures propagate. */
+    async start() {
+        const runtime = await this.#runtimeFactory({
+            cwd: this.#cwd,
+            agentDir: this.#options.agentDir,
+            sessionId: this.#options.sessionId,
+            ...(this.#options.sessionPath === undefined ? {} : { sessionPath: this.#options.sessionPath }),
+            ...(this.#options.sessionSelection === undefined ? {} : { sessionSelection: this.#options.sessionSelection }),
+            ...(this.#options.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: this.#options.sessionForkPrompt }),
+            ...(this.#options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: this.#options.projectTrustPrompt }),
+        });
+        this.#runtime = runtime;
+        this.#cwd = runtime.cwd ?? this.#cwd;
+        this.#gitBranch = await readGitBranch(this.#cwd);
+        this.#ports.started(runtime);
+        runtime.setRebindSession(async (session) => {
+            if (this.#ports.rebindBlocked())
+                return;
+            this.bindSession(session);
+            this.#ports.rebound();
+        });
+        for (const diagnostic of [...runtime.diagnostics, ...runtime.services.diagnostics]) {
+            this.#ports.diagnostic(diagnostic.type === "error" ? "error" : diagnostic.type === "warning" ? "warning" : "info", "engine-startup", diagnostic.message, diagnostic.type !== "error");
+        }
+        this.bindSession(runtime.session);
+        await this.#announceChangelog(runtime.services.settingsManager);
+        return runtime;
+    }
+    /** Probe extension packages for updates after startup and report them as an informational diagnostic. */
+    async announcePackageUpdates() {
+        const runtime = this.#runtime;
+        if (process.env.PI_OFFLINE || runtime === undefined)
+            return;
+        let updates;
+        try {
+            updates = await this.#checkPackageUpdates(runtime.services.settingsManager);
+        }
+        catch {
+            return;
+        }
+        if (this.#ports.disposed() || updates.length === 0)
+            return;
+        const packages = updates.map(name => `- ${name}`).join("\n");
+        this.#ports.diagnostic("info", "package-updates", `Package updates are available. Run ${PRODUCT_IDENTITY.commandName} pi update --extensions\nPackages:\n${packages}`, true);
+        this.#ports.emitView();
+    }
+    currentSessionFile() {
+        const value = this.#session?.sessionManager?.getSessionFile?.();
+        return typeof value === "string" && value.length > 0 ? value : null;
+    }
+    currentSessionResumeMetadata() {
+        const manager = this.#session?.sessionManager;
+        if (manager === undefined
+            || typeof manager.isPersisted !== "function"
+            || typeof manager.getSessionId !== "function"
+            || typeof manager.getSessionDir !== "function"
+            || typeof manager.usesDefaultSessionDir !== "function"
+            || manager.isPersisted() !== true
+            || !existsSync(this.currentSessionFile() ?? ""))
+            return null;
+        const sessionId = manager.getSessionId();
+        const sessionDir = manager.getSessionDir();
+        if (!sessionId || !sessionDir)
+            return null;
+        return { sessionId, sessionDir, usesDefaultSessionDir: manager.usesDefaultSessionDir() };
+    }
+    /** Replace the bound session under a new generation and subscribe to its events. */
+    bindSession(session) {
+        this.#unsubscribe?.();
+        this.#ports.sessionReplacing();
+        this.#sessionGeneration += 1;
+        this.#sessionBindingGeneration += 1;
+        this.#session = session;
+        this.#sessionCommands = new PiSessionCommandIntegration(session);
+        this.#compactionProgress?.dispose();
+        this.#compactionProgress = observeCompactionProgress(session, percent => {
+            if (this.#session === session && !this.#ports.disposed())
+                this.#ports.compactionProgress(percent);
+        });
+        // Invariant: the subscription is live before the adapter rebuilds its state so the extension
+        // rebind that finishes the rebuild cannot emit an event nobody is listening to.
+        this.#subscribe();
+        this.#ports.sessionReplaced(session);
+    }
+    /** Stop forwarding the current session's events and open a new generation; overload recovery resumes or abandons it. */
+    suspend() {
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#compactionProgress?.dispose();
+        this.#compactionProgress = null;
+        ++this.#sessionGeneration;
+    }
+    /** Forward the current session's events again under the current generation. */
+    resume() {
+        if (this.#session === undefined)
+            return;
+        this.#subscribe();
+    }
+    compactionStarted() {
+        this.#compactionProgress?.begin();
+    }
+    compactionEnded() {
+        this.#compactionProgress?.end();
+    }
+    // Rationale: a manual compaction ends with an idle session, so the engine would never consume
+    // the messages queued during it; automatic compaction returns to a run or a pending prompt.
+    deliverQueuedAfterCompaction() {
+        const commands = this.#sessionCommands;
+        const generation = this.#sessionGeneration;
+        if (commands === undefined)
+            return;
+        const report = (error) => {
+            if (generation !== this.#sessionGeneration || this.#ports.disposed())
+                return;
+            this.#ports.diagnostic("error", "engine-command", `Queued input could not be sent after compaction: ${error instanceof Error ? error.message : String(error)}`, true);
+            this.#ports.emitView();
+        };
+        commands.deliverQueuedAfterCompaction(report).catch(report);
+    }
+    /** Unsubscribe, stop observing compaction, and dispose the runtime; the session reference is kept for final reads. */
+    async dispose() {
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+        this.#compactionProgress?.dispose();
+        this.#compactionProgress = null;
+        await this.#runtime?.dispose();
+    }
+    #subscribe() {
+        const session = this.#session;
+        if (session === undefined)
+            return;
+        const generation = this.#sessionGeneration;
+        this.#unsubscribe = session.subscribe(event => {
+            if (generation === this.#sessionGeneration && !this.#ports.disposed())
+                this.#ports.event(event);
+        });
+    }
+    async #announceChangelog(settingsManager) {
+        if (!settingsManager || typeof settingsManager.getLastChangelogVersion !== "function"
+            || typeof settingsManager.setLastChangelogVersion !== "function")
+            return;
+        if ((this.#session?.messages.length ?? 0) > 0)
+            return;
+        const lastVersion = settingsManager.getLastChangelogVersion();
+        if (lastVersion === VERSION)
+            return;
+        if (!lastVersion) {
+            settingsManager.setLastChangelogVersion(VERSION);
+            await settingsManager.flush();
+            return;
+        }
+        const markdown = await this.#options.host.readChangelog(lastVersion).catch(() => "");
+        if (markdown.trim().length > 0) {
+            this.#ports.diagnostic("info", settingsManager.getCollapseChangelog() ? "changelog-collapsed" : "changelog-expanded", markdown, true);
+            settingsManager.setLastChangelogVersion(VERSION);
+            await settingsManager.flush();
+        }
+    }
+}
+async function createDefaultPiRuntime(input) {
+    return createPiRuntimeIntegration({
+        cwd: input.cwd,
+        agentDir: input.agentDir,
+        ...(input.sessionPath === undefined ? {} : { sessionPath: input.sessionPath }),
+        ...(input.sessionSelection === undefined ? {} : { sessionSelection: input.sessionSelection }),
+        ...(input.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: input.sessionForkPrompt }),
+        ...(input.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: input.projectTrustPrompt }),
+    });
+}
+async function checkDefaultPiPackageUpdates(cwd, agentDir, settingsManager) {
+    const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const updates = await packageManager.checkForAvailableUpdates();
+    return updates.map(update => update.displayName);
+}
+async function readGitBranch(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { cwd, windowsHide: true });
+        const branch = stdout.trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/integrations/pi/engine/session-selection.d.ts

@@ -0,0 +1,28 @@
+import { SessionManager, type SessionInfo } from "../startup-public.js";
+export interface PiSessionSelection {
+    readonly target: string;
+    readonly sessionDir?: string;
+}
+export type PiSessionForkPrompt = (request: {
+    readonly sourceCwd: string;
+}) => Promise<boolean>;
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export declare class PiSessionSelectionError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+interface SessionSelectionOptions {
+    readonly cwd: string;
+    readonly selection: PiSessionSelection;
+    readonly sessionDir?: string;
+    readonly forkPrompt?: PiSessionForkPrompt;
+    /** Public API seam for deterministic lookup/open race and listing-order evidence. */
+    readonly sessions?: Pick<typeof SessionManager, "list" | "open" | "forkFrom"> & {
+        readonly listAll: (sessionDir?: string) => Promise<SessionInfo[]>;
+    };
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export declare function openSelectedPiSession(options: SessionSelectionOptions): Promise<SessionManager>;
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export declare function resolveSessionArgumentPath(path: string, cwd: string): string;
+export {};

package/dist/integrations/pi/engine/session-selection.js

@@ -0,0 +1,90 @@
+import { accessSync, constants, existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { SessionManager } from "../startup-public.js";
+/** Expected resume outcomes are concise CLI diagnostics, not engine crashes. */
+export class PiSessionSelectionError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "PiSessionSelectionError";
+    }
+}
+/** Pinned Pi 0.84.2 main.ts policy, using SDK APIs rather than importing the CLI. */
+export async function openSelectedPiSession(options) {
+    try {
+        const sessions = options.sessions ?? SessionManager;
+        const cwd = resolve(options.cwd);
+        const directory = options.selection.sessionDir ?? options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR;
+        const sessionDir = directory === undefined ? undefined : resolveSessionArgumentPath(directory, cwd);
+        const target = options.selection.target;
+        let path;
+        let global;
+        if (target.includes("/") || target.includes("\\") || target.endsWith(".jsonl")) {
+            path = resolveSessionArgumentPath(target, cwd);
+        }
+        else {
+            const local = matchSession(await sessions.list(cwd, sessionDir), target);
+            const globalMatch = local ? undefined : matchSession(await sessions.listAll(sessionDir), target);
+            // Compatibility: macOS may expose one temporary directory as /var to one process
+            // and /private/var to another. Physical path identity must not turn that alias into
+            // a cross-project fork prompt.
+            global = globalMatch && !sameProjectDirectory(globalMatch.cwd, cwd) ? globalMatch : undefined;
+            const matched = local ?? globalMatch;
+            if (!matched)
+                throw new PiSessionSelectionError(`No session found matching '${target}'`);
+            path = matched.path;
+        }
+        assertResumeFile(path);
+        if (global) {
+            if (!options.forkPrompt || !await options.forkPrompt({ sourceCwd: global.cwd })) {
+                throw new PiSessionSelectionError("Session resume cancelled.", 0);
+            }
+            assertResumeFile(path);
+            assertCwd(cwd);
+            return sessions.forkFrom(path, cwd, sessionDir);
+        }
+        // Invariant: no await between the final guard and SDK open. A disappeared target
+        // can otherwise produce a new in-memory header instead of an existing session.
+        const manager = sessions.open(path, sessionDir);
+        assertResumeFile(path);
+        assertCwd(manager.getCwd());
+        return manager;
+    }
+    catch (error) {
+        if (error instanceof PiSessionSelectionError)
+            throw error;
+        throw new PiSessionSelectionError(`Could not resume session: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function sameProjectDirectory(left, right) {
+    try {
+        const first = realpathSync.native(resolve(left));
+        const second = realpathSync.native(resolve(right));
+        return process.platform === "win32" ? first.toLowerCase() === second.toLowerCase() : first === second;
+    }
+    catch {
+        return resolve(left) === resolve(right);
+    }
+}
+function matchSession(sessions, target) {
+    return sessions.find(session => session.id === target) ?? sessions.find(session => session.id.startsWith(target));
+}
+/** Resolve before switching effective cwd, including quoted home-relative paths. */
+export function resolveSessionArgumentPath(path, cwd) {
+    const expanded = path === "~" ? homedir() : /^~[/\\]/.test(path) ? resolve(homedir(), path.slice(2)) : path;
+    return resolve(cwd, expanded);
+}
+function assertResumeFile(path) {
+    if (!existsSync(path))
+        throw new PiSessionSelectionError(`Session file does not exist: ${path}`);
+    const metadata = statSync(path);
+    if (!metadata.isFile() || metadata.size === 0)
+        throw new PiSessionSelectionError(`Session file is empty or not a regular file: ${path}`);
+    accessSync(path, constants.R_OK);
+}
+function assertCwd(cwd) {
+    if (!existsSync(cwd) || !statSync(cwd).isDirectory())
+        throw new PiSessionSelectionError(`Session working directory does not exist: ${cwd}`);
+}