pi-session-mcp 0.0.0-stage → 0.6.2

package/dist/session-registry.d.ts

@@ -0,0 +1,104 @@
+import { type PiSessionAdapter } from "./pi-adapter.js";
+import type { PermissionProfile, ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
+export type SessionState = "idle" | "running" | "failed" | "closing" | "closed";
+export type TurnState = "running" | "completed" | "failed" | "aborted";
+export interface SessionView {
+    id: string;
+    workspace: string;
+    executionProfile: string;
+    profile: PermissionProfile;
+    provider: string;
+    model: string;
+    thinkingLevel: ThinkingLevel;
+    state: SessionState;
+    createdAt: string;
+    updatedAt: string;
+    lastError?: string;
+}
+/**
+ * `updatedAt` is the registry's own last-activity stamp: while a turn runs it advances on a
+ * completed tool execution or completed assistant message, then freezes at the terminal
+ * transition. It is a liveness lower bound, not a progress count, and does not prove that a
+ * silent turn is healthy.
+ */
+export interface TurnView {
+    turnId: string;
+    sessionId: string;
+    state: TurnState;
+    startedAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    assistantText?: string;
+    truncated?: boolean;
+    error?: {
+        code: "turn_failed";
+        message: "Pi turn failed";
+    };
+}
+export interface PromptResult {
+    session: SessionView;
+    turn: TurnView;
+}
+export type RegistryErrorCode = "unknown_workspace" | "unknown_session" | "session_running" | "prompt_rejected" | "prompt_timeout" | "abort_failed" | "abort_timeout" | "unknown_turn" | "unknown_execution_profile" | "server_stopping";
+export declare class RegistryError extends Error {
+    readonly code: RegistryErrorCode;
+    constructor(code: RegistryErrorCode);
+}
+export declare const MAX_TURNS_PER_SESSION = 20;
+export declare const MAX_TURN_TEXT_BYTES: number;
+export declare const MAX_CLOSED_TOMBSTONES = 100;
+export declare const PREFLIGHT_DEADLINE_MS = 5000;
+export declare const ABORT_DEADLINE_MS = 5000;
+export declare const CLOSE_CLEANUP_DEADLINE_MS = 5000;
+export declare const SHUTDOWN_DEADLINE_MS = 12000;
+export interface SessionRegistryOptions {
+    preflightDeadlineMs?: number;
+    abortDeadlineMs?: number;
+    closeCleanupDeadlineMs?: number;
+    shutdownDeadlineMs?: number;
+}
+export declare class SessionRegistry {
+    private readonly adapter;
+    private readonly workspaces;
+    private readonly sessions;
+    private readonly closed;
+    private readonly pendingStarts;
+    private readonly options;
+    private stopping;
+    private readonly shutdownController;
+    constructor(adapter: PiSessionAdapter, workspaces: ReadonlyMap<string, string>, options?: SessionRegistryOptions);
+    start(workspace: string, executionProfile: ResolvedExecutionProfile): Promise<SessionView>;
+    private createAndRegister;
+    list(): SessionView[];
+    get(id: string): SessionView;
+    getTurn(sessionId: string, turnId: string): TurnView;
+    prompt(id: string, text: string): Promise<PromptResult>;
+    abort(id: string): Promise<SessionView>;
+    close(id: string): Promise<SessionView>;
+    shutdown(): Promise<void>;
+    private require;
+    private verifySelection;
+    private completeTurn;
+    private failTurn;
+    /**
+     * Liveness only. A completed tool execution or assistant message advances this turn,
+     * never another turn or the session. Activity after accepted preflight but before
+     * publication is stamped and applied only if the turn is published; callbacks before
+     * acceptance or after terminal cleanup cannot publish or revive a turn.
+     */
+    private recordActivity;
+    /** The registry's own clock: never earlier than `current`, even across a wall-clock step. */
+    private advance;
+    private publishTurn;
+    private restorePreflight;
+    private trim;
+    private beginAbort;
+    private quarantineTimedOutPreflight;
+    private dispose;
+    private disposeHandle;
+    private rememberClosed;
+    private turnView;
+    private view;
+    private withTimeout;
+    private serial;
+}

package/dist/session-registry.js

@@ -0,0 +1,373 @@
+import { randomUUID } from "node:crypto";
+import { PiSessionCreationError } from "./pi-adapter.js";
+const REGISTRY_ERROR_MESSAGES = {
+    unknown_workspace: "Unknown workspace",
+    unknown_session: "Unknown session",
+    session_running: "Session already has a running turn",
+    prompt_rejected: "Pi rejected the prompt during preflight",
+    prompt_timeout: "Pi prompt preflight timed out",
+    abort_failed: "Pi abort failed",
+    abort_timeout: "Pi abort timed out",
+    unknown_turn: "Unknown turn",
+    unknown_execution_profile: "Unknown execution profile",
+    server_stopping: "Server is shutting down",
+};
+export class RegistryError extends Error {
+    code;
+    constructor(code) {
+        super(REGISTRY_ERROR_MESSAGES[code]);
+        this.code = code;
+        this.name = "RegistryError";
+    }
+}
+export const MAX_TURNS_PER_SESSION = 20;
+export const MAX_TURN_TEXT_BYTES = 64 * 1024;
+export const MAX_CLOSED_TOMBSTONES = 100;
+export const PREFLIGHT_DEADLINE_MS = 5_000;
+export const ABORT_DEADLINE_MS = 5_000;
+export const CLOSE_CLEANUP_DEADLINE_MS = 5_000;
+export const SHUTDOWN_DEADLINE_MS = 12_000;
+const stamp = () => new Date().toISOString();
+function normalize(text) { const value = text.trim(); if (Buffer.byteLength(value, "utf8") <= MAX_TURN_TEXT_BYTES)
+    return { text: value, truncated: false }; let out = ""; let size = 0; for (const c of value) {
+    const n = Buffer.byteLength(c, "utf8");
+    if (size + n > MAX_TURN_TEXT_BYTES)
+        break;
+    out += c;
+    size += n;
+} return { text: out, truncated: true }; }
+export class SessionRegistry {
+    adapter;
+    workspaces;
+    sessions = new Map();
+    closed = new Map();
+    pendingStarts = new Set();
+    options;
+    stopping = false;
+    shutdownController = new AbortController();
+    constructor(adapter, workspaces, options = {}) {
+        this.adapter = adapter;
+        this.workspaces = workspaces;
+        this.options = { preflightDeadlineMs: options.preflightDeadlineMs ?? PREFLIGHT_DEADLINE_MS, abortDeadlineMs: options.abortDeadlineMs ?? ABORT_DEADLINE_MS, closeCleanupDeadlineMs: options.closeCleanupDeadlineMs ?? CLOSE_CLEANUP_DEADLINE_MS, shutdownDeadlineMs: options.shutdownDeadlineMs ?? SHUTDOWN_DEADLINE_MS };
+    }
+    async start(workspace, executionProfile) {
+        if (this.stopping)
+            throw new RegistryError("server_stopping");
+        const cwd = this.workspaces.get(workspace);
+        if (!cwd)
+            throw new RegistryError("unknown_workspace");
+        // Track registration and orphan cleanup too, not just the raw adapter promise.
+        const start = this.createAndRegister(cwd, workspace, executionProfile);
+        this.pendingStarts.add(start);
+        try {
+            return await start;
+        }
+        finally {
+            this.pendingStarts.delete(start);
+        }
+    }
+    async createAndRegister(cwd, workspace, executionProfile) {
+        const handle = await Promise.resolve().then(() => this.adapter.create({ cwd, executionProfile, signal: this.shutdownController.signal }));
+        try {
+            if (this.stopping)
+                throw new RegistryError("server_stopping");
+            this.verifySelection(handle.appliedSelection, executionProfile);
+            const time = stamp();
+            const entry = {
+                id: randomUUID(), workspace, executionProfile: executionProfile.alias, profile: executionProfile.permissionProfile,
+                provider: handle.appliedSelection.provider, model: handle.appliedSelection.model,
+                thinkingLevel: handle.appliedSelection.thinkingLevel, state: "idle", createdAt: time, updatedAt: time,
+                handle, operation: Promise.resolve(), disposed: false, turns: new Map(), order: [],
+            };
+            this.sessions.set(entry.id, entry);
+            return this.view(entry);
+        }
+        catch (error) {
+            await this.disposeHandle(handle);
+            throw error;
+        }
+    }
+    list() { return [...this.sessions.values()].map((e) => this.view(e)); }
+    get(id) { return this.view(this.require(id)); }
+    getTurn(sessionId, turnId) {
+        const entry = this.require(sessionId);
+        const turn = entry.turns.get(turnId);
+        if (!turn)
+            throw new RegistryError("unknown_turn");
+        return this.turnView(turn);
+    }
+    async prompt(id, text) {
+        const entry = this.require(id);
+        return this.serial(entry, async () => {
+            if (entry.state === "running" || entry.abortPromise)
+                throw new RegistryError("session_running");
+            if (entry.state === "closing" || entry.state === "closed")
+                throw new RegistryError("unknown_session");
+            const previous = { state: entry.state, updatedAt: entry.updatedAt, lastError: entry.lastError };
+            const time = stamp();
+            const turn = { turnId: randomUUID(), sessionId: id, state: "running", startedAt: time, updatedAt: time, terminal: false };
+            entry.turn = turn;
+            entry.state = "running";
+            entry.updatedAt = time;
+            delete entry.lastError;
+            let accepted;
+            let signaled = false;
+            let signal;
+            const preflight = new Promise((resolve) => {
+                signal = (value) => {
+                    if (signaled)
+                        return;
+                    signaled = true;
+                    accepted = value;
+                    resolve(value);
+                };
+            });
+            let pendingActivityAt;
+            const onActivity = () => {
+                if (accepted !== true || this.stopping || entry.disposed || entry.turn !== turn || turn.terminal)
+                    return;
+                if (entry.turns.has(turn.turnId)) {
+                    this.recordActivity(entry, turn);
+                }
+                else {
+                    const time = stamp();
+                    if (pendingActivityAt === undefined || time > pendingActivityAt)
+                        pendingActivityAt = time;
+                }
+            };
+            const publishAcceptedTurn = () => {
+                this.publishTurn(entry, turn);
+                if (pendingActivityAt !== undefined)
+                    this.recordActivity(entry, turn, pendingActivityAt);
+            };
+            let operation;
+            try {
+                operation = Promise.resolve(entry.handle.prompt(text, signal, onActivity));
+            }
+            catch {
+                if (accepted === true) {
+                    publishAcceptedTurn();
+                    this.failTurn(entry, turn);
+                    return { session: this.view(entry), turn: this.turnView(turn) };
+                }
+                this.restorePreflight(entry, turn, undefined, previous);
+                throw new RegistryError("prompt_rejected");
+            }
+            entry.turnPromise = operation;
+            void operation.then(() => undefined, () => undefined);
+            const result = await this.withTimeout(Promise.race([
+                preflight.then((value) => ({ kind: "preflight", value })),
+                operation.then(() => ({ kind: "operation" }), () => ({ kind: "operation" })),
+            ]), this.options.preflightDeadlineMs, { kind: "timeout" });
+            if (result.kind === "timeout") {
+                this.quarantineTimedOutPreflight(entry, turn, operation, previous);
+                throw new RegistryError("prompt_timeout");
+            }
+            if (result.kind === "operation" || result.value === false) {
+                this.restorePreflight(entry, turn, operation, previous);
+                throw new RegistryError("prompt_rejected");
+            }
+            publishAcceptedTurn();
+            void operation.then((outcome) => this.completeTurn(entry, turn, outcome), () => this.failTurn(entry, turn));
+            return { session: this.view(entry), turn: this.turnView(turn) };
+        });
+    }
+    async abort(id) {
+        const entry = this.require(id);
+        const operation = this.serial(entry, async () => {
+            const turn = entry.turn;
+            if (entry.state !== "running" || !turn || turn.terminal)
+                return undefined;
+            return { turn, abortPromise: this.beginAbort(entry, turn) };
+        }).then(async (prepared) => {
+            if (!prepared)
+                return this.view(entry);
+            try {
+                await prepared.abortPromise;
+            }
+            catch {
+                throw new RegistryError("abort_failed");
+            }
+            if (entry.turns.has(prepared.turn.turnId) && entry.turn === prepared.turn && !prepared.turn.terminal && !entry.disposed) {
+                this.completeTurn(entry, prepared.turn, { status: "aborted" });
+            }
+            return this.view(entry);
+        });
+        const result = await this.withTimeout(operation.then((session) => ({ kind: "completed", session }), () => ({ kind: "failed" })), this.options.abortDeadlineMs, { kind: "timeout" });
+        if (result.kind === "timeout")
+            throw new RegistryError("abort_timeout");
+        if (result.kind === "failed")
+            throw new RegistryError("abort_failed");
+        return result.session;
+    }
+    async close(id) {
+        const existing = this.sessions.get(id);
+        if (!existing) {
+            const closed = this.closed.get(id);
+            if (closed)
+                return { ...closed };
+            throw new RegistryError("unknown_session");
+        }
+        return this.serial(existing, async () => {
+            if (existing.disposed)
+                return this.view(existing);
+            existing.state = "closing";
+            existing.updatedAt = stamp();
+            const turn = existing.turn;
+            if (turn && !turn.terminal) {
+                turn.terminal = true;
+                turn.state = "aborted";
+                const time = this.advance(turn.updatedAt);
+                turn.updatedAt = time;
+                turn.completedAt = time;
+                const abortPromise = this.beginAbort(existing, turn);
+                await this.withTimeout(abortPromise.then(() => undefined, () => undefined), this.options.closeCleanupDeadlineMs, undefined);
+            }
+            existing.turn = undefined;
+            existing.turnPromise = undefined;
+            existing.turns.clear();
+            existing.order.length = 0;
+            await this.dispose(existing);
+            existing.state = "closed";
+            existing.updatedAt = stamp();
+            const view = this.view(existing);
+            this.rememberClosed(id, view);
+            this.sessions.delete(id);
+            return view;
+        });
+    }
+    async shutdown() {
+        this.stopping = true;
+        this.shutdownController.abort();
+        const cleanup = Promise.all([
+            Promise.allSettled([...this.sessions.keys()].map((id) => this.close(id))),
+            Promise.allSettled([...this.pendingStarts]),
+        ]).then(() => undefined);
+        await this.withTimeout(cleanup, this.options.shutdownDeadlineMs, undefined);
+    }
+    require(id) { const entry = this.sessions.get(id); if (!entry)
+        throw new RegistryError("unknown_session"); return entry; }
+    verifySelection(applied, expected) {
+        if (applied.provider !== expected.provider || applied.model !== expected.model || applied.thinkingLevel !== expected.thinkingLevel) {
+            throw new PiSessionCreationError("execution_selection_mismatch");
+        }
+    }
+    completeTurn(entry, turn, outcome) { if (turn.terminal || entry.disposed)
+        return; turn.terminal = true; turn.updatedAt = this.advance(turn.updatedAt); turn.completedAt = turn.updatedAt; if (outcome.status === "completed") {
+        const normalized = normalize(outcome.assistantText);
+        turn.state = "completed";
+        turn.assistantText = normalized.text;
+        turn.truncated = normalized.truncated;
+    }
+    else if (outcome.status === "aborted")
+        turn.state = "aborted";
+    else {
+        turn.state = "failed";
+        turn.error = { code: "turn_failed", message: "Pi turn failed" };
+        entry.lastError = "Pi turn failed";
+    } if (entry.turn === turn)
+        entry.turn = undefined; if (entry.turnPromise)
+        entry.turnPromise = undefined; entry.state = turn.state === "failed" ? "failed" : "idle"; entry.updatedAt = turn.updatedAt; }
+    failTurn(entry, turn) { if (turn.terminal)
+        return; turn.terminal = true; turn.state = "failed"; turn.updatedAt = this.advance(turn.updatedAt); turn.completedAt = turn.updatedAt; turn.error = { code: "turn_failed", message: "Pi turn failed" }; if (entry.turn === turn)
+        entry.turn = undefined; if (entry.turnPromise)
+        entry.turnPromise = undefined; entry.state = "failed"; entry.updatedAt = turn.updatedAt; entry.lastError = "Pi turn failed"; }
+    /**
+     * Liveness only. A completed tool execution or assistant message advances this turn,
+     * never another turn or the session. Activity after accepted preflight but before
+     * publication is stamped and applied only if the turn is published; callbacks before
+     * acceptance or after terminal cleanup cannot publish or revive a turn.
+     */
+    recordActivity(entry, turn, observedAt) {
+        if (this.stopping || entry.disposed)
+            return;
+        if (entry.turn !== turn || !entry.turns.has(turn.turnId))
+            return;
+        if (entry.state !== "running" || turn.state !== "running" || turn.terminal)
+            return;
+        const time = this.advance(turn.updatedAt, observedAt);
+        // Sub-millisecond activity is simply the same stamp; a timestamp never moves backwards.
+        if (time === turn.updatedAt)
+            return;
+        turn.updatedAt = time;
+    }
+    /** The registry's own clock: never earlier than `current`, even across a wall-clock step. */
+    advance(current, observedAt = stamp()) { return observedAt > current ? observedAt : current; }
+    publishTurn(entry, turn) { if (entry.turns.has(turn.turnId))
+        return; entry.turns.set(turn.turnId, turn); entry.order.push(turn.turnId); this.trim(entry); }
+    restorePreflight(entry, turn, operation, previous) { turn.terminal = true; if (entry.turn === turn)
+        entry.turn = undefined; if (!operation || entry.turnPromise === operation)
+        entry.turnPromise = undefined; entry.state = previous.state; entry.updatedAt = previous.updatedAt; if (previous.lastError === undefined)
+        delete entry.lastError;
+    else
+        entry.lastError = previous.lastError; }
+    trim(entry) { while (entry.order.length > MAX_TURNS_PER_SESSION) {
+        const old = entry.order.shift();
+        if (old)
+            entry.turns.delete(old);
+    } }
+    beginAbort(entry, turn) {
+        if (turn.abortPromise)
+            return turn.abortPromise;
+        const pending = Promise.resolve().then(() => entry.handle.abort());
+        turn.abortPromise = pending;
+        entry.abortPromise = pending;
+        void pending.then(() => {
+            if (entry.abortPromise === pending)
+                entry.abortPromise = undefined;
+            if (entry.turns.has(turn.turnId) && entry.turn === turn && !turn.terminal && !entry.disposed) {
+                this.completeTurn(entry, turn, { status: "aborted" });
+            }
+        }, () => {
+            if (entry.abortPromise === pending)
+                entry.abortPromise = undefined;
+            if (turn.abortPromise === pending)
+                turn.abortPromise = undefined;
+        });
+        return pending;
+    }
+    quarantineTimedOutPreflight(entry, turn, operation, previous) {
+        let promptSettled = false;
+        let abortSettled = false;
+        const releaseIfSafe = () => {
+            if (turn.terminal || entry.disposed || entry.turn !== turn)
+                return;
+            if (abortSettled && promptSettled)
+                this.restorePreflight(entry, turn, operation, previous);
+        };
+        void operation.then(() => { promptSettled = true; releaseIfSafe(); }, () => { promptSettled = true; releaseIfSafe(); });
+        const abortPromise = this.beginAbort(entry, turn);
+        void abortPromise.then(() => { abortSettled = true; releaseIfSafe(); }, () => { abortSettled = true; releaseIfSafe(); });
+    }
+    async dispose(entry) {
+        if (entry.disposed)
+            return;
+        entry.disposed = true;
+        await this.disposeHandle(entry.handle);
+    }
+    async disposeHandle(handle) {
+        try {
+            const cleanup = Promise.resolve(handle.dispose()).then(() => undefined, () => undefined);
+            await this.withTimeout(cleanup, this.options.closeCleanupDeadlineMs, undefined);
+        }
+        catch { /* Cleanup errors must never expose adapter internals. */ }
+    }
+    rememberClosed(id, view) { this.closed.set(id, view); while (this.closed.size > MAX_CLOSED_TOMBSTONES)
+        this.closed.delete(this.closed.keys().next().value); }
+    turnView({ terminal: _terminal, abortPromise: _abortPromise, ...turn }) { return { ...turn }; }
+    view({ handle: _handle, turn: _turn, turnPromise: _turnPromise, abortPromise: _abortPromise, operation: _operation, disposed: _disposed, turns: _turns, order: _order, ...view }) { return { ...view }; }
+    async withTimeout(promise, milliseconds, fallback) { if (milliseconds <= 0)
+        return fallback; let timer; const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(fallback), milliseconds); }); try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    } }
+    async serial(entry, action) { const previous = entry.operation; let release; entry.operation = new Promise((resolve) => { release = resolve; }); await previous.catch(() => undefined); try {
+        return await action();
+    }
+    finally {
+        release();
+    } }
+}

package/dist/setup-cli.d.ts

@@ -0,0 +1,11 @@
+import { SetupOrchestrator, type SetupRequest } from "./setup.js";
+import type { SetupResult } from "./setup-result.js";
+/** Small argv adapter; command execution remains injected in SetupClientAdapter. */
+export interface SetupCliRequest extends SetupRequest {
+    readonly json: boolean;
+}
+export declare function parseSetupArgs(argv: readonly string[]): SetupCliRequest;
+export declare function runSetupCli(argv: readonly string[], orchestrator: SetupOrchestrator): Promise<SetupResult>;
+/** Both report modes are projections of the same sanitized result. */
+export declare function formatSetupResult(setupResult: SetupResult): string;
+export declare function formatSetupHuman(setupResult: SetupResult): string;

package/dist/setup-cli.js

@@ -0,0 +1,38 @@
+export function parseSetupArgs(argv) {
+    let operation;
+    let json = false;
+    const targets = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--json") {
+            if (json)
+                throw new Error("json_repeated");
+            json = true;
+            continue;
+        }
+        if (argument === "--dry-run" || argument === "--apply" || argument === "--verify" || argument === "--rollback" || argument === "--remove") {
+            if (operation)
+                throw new Error("operation_repeated");
+            operation = argument.slice(2);
+            continue;
+        }
+        if (argument === "--target") {
+            const value = argv[++index];
+            const parts = value?.split(":");
+            if (!parts || parts.length !== 3)
+                throw new Error("target_invalid");
+            targets.push({ client: parts[0], scope: parts[1], alias: parts[2] });
+            continue;
+        }
+        throw new Error("argument_unsupported");
+    }
+    return operation ? { operation, targets, json } : { targets, json };
+}
+export async function runSetupCli(argv, orchestrator) {
+    return orchestrator.run(parseSetupArgs(argv));
+}
+/** Both report modes are projections of the same sanitized result. */
+export function formatSetupResult(setupResult) {
+    return JSON.stringify(setupResult);
+}
+export function formatSetupHuman(setupResult) { return [`${setupResult.operation}: ${setupResult.status}`, ...setupResult.findings.map((x) => `${x.target.client}/${x.target.scope}/${x.target.alias}: ${x.status} (${x.code})`)].join("\n"); }

package/dist/setup-command-guardian.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};