@evandu/super-pi 0.1.93 → 0.1.95

package/dist/server/pi-session-pool.js

@@ -0,0 +1,262 @@
+/**
+ * THE SESSION POOL: one live Pi session per conversation, kept across turns.
+ *
+ * WHAT IT OWNS. A conversation's Pi session, its fingerprint, and the rule that decides when the live
+ * session has gone stale and must be thrown away. Everything that can make a session stale is a
+ * FINGERPRINT (see `pi-session.ts`): the agent's prompt, the tool allowlist, the mounted extensions,
+ * the workspace, the model. Pi decides all of those when a session is created and cannot change any of
+ * them afterwards, so a session whose fingerprint no longer matches the conversation's current
+ * requirements is not "slightly wrong" - it is the wrong session, and the only honest response is to
+ * replace it.
+ *
+ * WHY THE POOL IS EXPLICIT ABOUT EVICTING. A session holds a model client, a session file handle and a
+ * conversation context. Left alone, a server that has seen fifty conversations would hold fifty of
+ * them, and the ones nobody is using would be the ones costing the most memory. So an idle session is
+ * evicted after a while, and the conversation's context is not lost with it: Pi writes the transcript
+ * to disk, and the next session for that conversation is rebuilt from that file.
+ *
+ * THE REVERT CASE. `revert` truncates the transcript on disk. A live session's in-memory context does
+ * NOT change, and nothing in Pi would notice: the model would keep answering from history the user
+ * has withdrawn. So a revert must EVICT the session, and the next turn rebuilds from the truncated
+ * file. This is the one case where eviction is not an optimization but a correctness requirement.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createPiSession, sameFingerprint, superPiExtensionPaths, } from "./pi-session.js";
+/** How long an idle session survives before it is evicted. */
+const IDLE_EVICTION_MS = 10 * 60_000;
+/**
+ * The environment variable the session's credential travels in.
+ *
+ * THE SAME NAME THE EXTENSION READS, written out rather than imported: `agents/` is loaded by Pi's
+ * module loader and `src/` by tsc, so an import across the two would resolve differently under each.
+ * `scripts/task-tool.test.mjs` asserts that the two copies agree.
+ */
+const CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
+const TOOLS_CAPABILITY_ENV = "SUPER_PI_TOOLS_CAPABILITY";
+/**
+ * The pool.
+ *
+ * One instance per server. It is deliberately not a general-purpose pool: the sessions it holds differ
+ * from each other in their agent, their tools and their workspace, so there is nothing to share between
+ * them and no reason to try.
+ */
+export class PiSessionPool {
+    sessionDir;
+    repositoryRoot;
+    agentDir;
+    onSessionDestroyed;
+    factory;
+    mintCapability;
+    sessions = new Map();
+    constructor(
+    /** Where Pi keeps its session files. */
+    sessionDir, 
+    /** The repository root, for locating Super Pi's own extensions. */
+    repositoryRoot, 
+    /** Pi's global configuration directory, when it is not Pi's own default. */
+    agentDir, 
+    /**
+     * Called when a session is destroyed, so the caller can release whatever the session was holding.
+     *
+     * A session holds a capability: the token its extension read out of the environment when it was
+     * loaded. When the session goes, that token must go with it - a credential whose holder no longer
+     * exists is exactly the shape the capability model exists to prevent. The pool does not know what a
+     * capability is, so it says WHEN and the caller says WHAT.
+     */
+    onSessionDestroyed, 
+    /**
+     * How a session is built. Injectable so a test can drive a session without a real Pi behind it.
+     */
+    factory = createPiSession, 
+    /**
+     * Mints the credential the session's extension will hold. Injected rather than imported so the pool
+     * does not have to know what a capability is - it needs to know WHEN one is needed, and the caller
+     * knows what one looks like.
+     */
+    mintCapability = () => "") {
+        this.sessionDir = sessionDir;
+        this.repositoryRoot = repositoryRoot;
+        this.agentDir = agentDir;
+        this.onSessionDestroyed = onSessionDestroyed;
+        this.factory = factory;
+        this.mintCapability = mintCapability;
+    }
+    /**
+     * The session for a conversation, built if there is none and REPLACED if the live one is stale.
+     *
+     * The fingerprint comparison is what makes a stale session impossible to use: it happens BEFORE the
+     * session is handed out, not after, so a caller can never accidentally run a turn on a session whose
+     * tool allowlist has changed.
+     */
+    async acquire(request) {
+        const fingerprint = this.fingerprintOf(request);
+        const existing = this.sessions.get(request.conversationId);
+        if (existing) {
+            if (sameFingerprint(existing.fingerprint, fingerprint)) {
+                existing.lastUsedAt = Date.now();
+                // A session that is still being built is joined, not rebuilt: two sends arriving together must
+                // not produce two sessions, and the second one would be a duplicate model client talking to the
+                // same conversation.
+                if (existing.building)
+                    return existing.building;
+                return existing.session;
+            }
+            // STALE. The conversation's requirements changed underneath the live session, so it is thrown away
+            // BEFORE the new one is built, and not after - a session that is being disposed of while the new
+            // one starts would have two contexts for one conversation.
+            await this.evict(request.conversationId);
+        }
+        // THE CREDENTIAL IS MINTED HERE, WHERE THE SESSION IS BORN. The capability travels in the
+        // extension's environment, and the extension reads its environment when it is LOADED - which happens
+        // once per session. A token minted per TURN would be replaced before the second turn of the
+        // conversation, and the extension would still be holding the first turn's value: the server would
+        // (correctly) refuse it, and delegation would break after the first message.
+        //
+        // So the token belongs to the SESSION, and it is minted exactly when the session is created. The
+        // server separately requires that a turn is RUNNING for the token to be usable, which is what keeps a
+        // longer-lived token from being a weaker credential than a per-turn one.
+        const capability = this.mintCapability(request.conversationId);
+        const extensionEnv = { ...request.extensionEnv, [CAPABILITY_ENV]: capability, [TOOLS_CAPABILITY_ENV]: capability };
+        const building = this.build({ ...request, extensionEnv }, fingerprint);
+        this.sessions.set(request.conversationId, { session: undefined, fingerprint, lastUsedAt: Date.now(), building });
+        try {
+            const session = await building;
+            const entry = this.sessions.get(request.conversationId);
+            if (entry) {
+                entry.session = session;
+                entry.building = undefined;
+            }
+            return session;
+        }
+        catch (error) {
+            // A failed build must not leave a broken entry behind: the next turn would find it and treat the
+            // failure as "the session exists", and every later turn would fail the same way with no reason.
+            this.sessions.delete(request.conversationId);
+            // And a failed build must not leave a CREDENTIAL behind either: the session it belonged to was
+            // never born, so the token is a credential with no owner.
+            this.onSessionDestroyed?.(request.conversationId);
+            throw error;
+        }
+    }
+    async build(request, fingerprint) {
+        const creation = {
+            cwd: request.cwd,
+            sessionId: request.conversationId,
+            sessionDir: this.sessionDir,
+            extensionPaths: superPiExtensionPaths(this.repositoryRoot),
+            extensionEnv: request.extensionEnv,
+            ...(request.systemPromptFile ? { systemPromptFile: request.systemPromptFile } : {}),
+            ...(request.systemPromptMode ? { systemPromptMode: request.systemPromptMode } : {}),
+            ...(request.tools ? { tools: request.tools } : {}),
+            ...(request.excludeTools ? { excludeTools: request.excludeTools } : {}),
+            ...(request.model ? { model: request.model } : {}),
+            ...(request.thinkingLevel ? { thinkingLevel: request.thinkingLevel } : {}),
+            ...(this.agentDir ? { agentDir: this.agentDir } : {}),
+        };
+        return this.factory(creation);
+    }
+    fingerprintOf(request) {
+        return {
+            cwd: request.cwd,
+            agentId: request.agentId,
+            tools: request.tools,
+            excludeTools: request.excludeTools,
+            extensions: superPiExtensionPaths(this.repositoryRoot),
+            model: request.model,
+            thinkingLevel: request.thinkingLevel,
+        };
+    }
+    /**
+     * The live session for a conversation, without building one.
+     *
+     * Absent when there is none - including when the session is still being built, because a session
+     * that is not ready cannot be steered into.
+     */
+    get(conversationId) {
+        const entry = this.sessions.get(conversationId);
+        return entry && !entry.building ? entry.session : undefined;
+    }
+    /**
+     * Whether a conversation has a live session, without building one.
+     *
+     * Used by the paths that need to know whether a session EXISTS - `revert` has to know whether there is
+     * an in-memory context to invalidate - and by the tests.
+     */
+    has(conversationId) {
+        return this.sessions.has(conversationId);
+    }
+    /**
+     * Throws away a conversation's session.
+     *
+     * The reason this is a PUBLIC operation and not an internal detail is that the callers are the ones
+     * that know WHY the session is stale. `revert` calls it because the disk changed under the session;
+     * a configuration change calls it because the requirements changed. The pool does not second-guess
+     * either - it disposes what it is told to dispose.
+     */
+    async evict(conversationId) {
+        const entry = this.sessions.get(conversationId);
+        if (!entry)
+            return;
+        this.sessions.delete(conversationId);
+        // The credential the session was holding dies with it, in every path - including the one where the
+        // build is still running, because a session that finishes building after its eviction would
+        // otherwise come back holding a token the server has already forgotten.
+        this.onSessionDestroyed?.(conversationId);
+        if (entry.building) {
+            // The build is still running. Awaiting it before disposing is what guarantees the session is
+            // actually released rather than leaked - a session that finishes building after the eviction has
+            // no owner left to dispose it.
+            const session = await entry.building.catch(() => undefined);
+            session?.dispose();
+            return;
+        }
+        try {
+            entry.session?.dispose();
+        }
+        catch (error) {
+            console.warn(`Super Pi: disposing the Pi session of ${conversationId} threw: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+    }
+    /**
+     * Throws away every session that has not been used for a while.
+     *
+     * The conversation is not lost: Pi wrote the transcript to disk, and the next turn rebuilds the
+     * session from that file. What is lost is the in-memory context, which is exactly what an idle
+     * conversation does not need.
+     */
+    async evictIdle(now = Date.now()) {
+        for (const [conversationId, entry] of [...this.sessions]) {
+            if (now - entry.lastUsedAt >= IDLE_EVICTION_MS)
+                await this.evict(conversationId);
+        }
+    }
+    /** Throws away every session. Used at shutdown. */
+    async disposeAll() {
+        for (const conversationId of [...this.sessions.keys()])
+            await this.evict(conversationId);
+    }
+    /** The conversations with a live session. */
+    get conversationIds() {
+        return [...this.sessions.keys()];
+    }
+}
+/**
+ * Where Super Pi's repository root is, found from the compiled server's own location.
+ *
+ * The extensions are mounted by PATH, and Pi resolves a relative path against the CONVERSATION's
+ * workspace rather than the server's directory - so the path has to be absolute, and it has to be
+ * derived from something that is the same in every way the server runs (built to `dist/server/`, or run
+ * from `src/server/` under tsx). `import.meta.dirname` is that thing.
+ */
+export function repositoryRootFrom(from = import.meta.dirname) {
+    return join(from, "..", "..");
+}
+/** Whether Super Pi's own extensions are present on disk. */
+export function extensionsAvailable(repositoryRoot) {
+    return superPiExtensionPaths(repositoryRoot).length > 0;
+}
+/** Whether the extension directory exists at all, for a clearer failure message. */
+export function extensionDirectoryExists(repositoryRoot) {
+    return existsSync(join(repositoryRoot, "agents", "super-pi-task", "index.ts"));
+}

package/dist/server/pi-session.d.ts

@@ -0,0 +1,204 @@
+/**
+ * THE SESSION LAYER: one Pi session per Super Pi conversation, alive across turns.
+ *
+ * WHY THIS FILE EXISTS. Super Pi used to spawn a fresh `pi --mode rpc` process for every turn and kill
+ * it when the turn ended. That cost ~400ms of spawn plus ~380ms of handshake plus a full replay of the
+ * transcript on EVERY message, and it is why an interrupt had to kill a process and start another one:
+ * the turn and the process were the same thing. Pi's own `abort` takes 147ms and leaves the session
+ * usable, so the process churn was Super Pi's choice, not a property of interrupting.
+ *
+ * Pi's SDK (`@earendil-works/pi-coding-agent`) is the supported way to embed it - Pi's own RPC docs
+ * recommend it for Node applications. A session here is a Pi `AgentSession`: it keeps the conversation
+ * context in memory across turns, and `abort()` returns as soon as the agent is idle.
+ *
+ * WHAT THIS FILE IS NOT. It is not a second runtime. The one-shot paths (memory review, knowledge
+ * rerank, autotitle, tool LLM, catalog probe) keep spawning their own throwaway children, because their
+ * identity, tool set and lifecycle are deliberately different from the primary agent's and sharing a
+ * session with them would be a correctness bug, not an optimization. See `runtime.ts`.
+ *
+ * THE ONE HARD CONSTRAINT. Pi's agent prompt, its tool allowlist and the extensions it mounts are all
+ * decided when the session is CREATED. None of them can be changed on a live session. So a session carries
+ * a FINGERPRINT of everything that was decided at creation, and the caller compares fingerprints: a
+ * change means the session is stale and must be replaced. `revert` is the sharpest case - it truncates
+ * the transcript on disk while the live session still holds the old context in memory, and nothing in Pi
+ * would notice the difference.
+ */
+/** Whether the SDK could be loaded. Used by the server to report the reason instead of failing a turn. */
+export declare function piSdkAvailable(): Promise<{
+    available: true;
+} | {
+    available: false;
+    reason: string;
+}>;
+/**
+ * Everything that was DECIDED when a session was created and cannot be changed afterwards.
+ *
+ * A change in any of these means the live session is no longer the session the user asked for, and the
+ * only honest response is to throw it away and build the right one. The fingerprint exists so that
+ * decision is made in one place, by comparison, rather than by a human remembering to restart.
+ */
+export interface SessionFingerprint {
+    /** The workspace directory. Pi resolves its session file by cwd, so a different cwd is a different file. */
+    cwd: string;
+    /** The agent's id, or null for Pi's own defaults. The prompt body is read from disk at creation. */
+    agentId: string | null;
+    /** The tool allowlist, exactly as it was passed to Pi. */
+    tools: string[] | undefined;
+    /** The denylist, exactly as it was passed to Pi. */
+    excludeTools: string[] | undefined;
+    /** Which of Super Pi's own extensions were mounted. */
+    extensions: string[];
+    /** The model and thinking level, when they were pinned at creation. */
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    thinkingLevel?: string;
+}
+/**
+ * Fingerprints are compared by VALUE, and this is where that comparison is spelled out.
+ *
+ * The array fields are compared as SETS, not sequences: the tool allowlist is a set of names, and a
+ * caller that happens to list them in a different order is asking for the same session, not a new one.
+ * Getting this wrong in the strict direction would throw away a perfectly good session on every turn
+ * (a latency bug that looks like nothing at all), and getting it wrong in the loose direction would keep
+ * a session whose allowlist had genuinely changed (a permission bug). So: order-insensitive, and every
+ * element compared exactly.
+ */
+export declare function sameFingerprint(a: SessionFingerprint, b: SessionFingerprint): boolean;
+/**
+ * The values Super Pi's own extensions read out of their environment.
+ *
+ * Pi's extension model has no per-session environment: an extension reads `process.env` when it is
+ * LOADED. That is fine for a one-process-per-turn design (each turn was its own process) and it is a
+ * problem for a shared process, where two conversations would otherwise read each other's values.
+ *
+ * The resolution is the order of operations, and it is verified rather than assumed: the environment is
+ * set, the loader is RELOADED (which is when Pi calls the extension factory, and the factory is what
+ * captures the value), and only then is the environment cleared. Two sessions built in an interleaved
+ * order each captured their own value - see `scripts/pi-session-isolation.test.mjs`.
+ */
+export interface ExtensionEnvironment {
+    /** The variable name to value pairs, in the order they should be applied. */
+    values: Record<string, string>;
+}
+/**
+ * Runs `work` with the given environment applied, and restores the previous values afterwards.
+ *
+ * The values are applied SYNCHRONOUSLY and the whole of `work` is awaited inside the window, because
+ * the extension factory runs during the loader's reload and reads the environment at that moment. A
+ * concurrent session's environment would otherwise land in the middle of this one.
+ */
+export declare function withEnvironment<T>(values: Record<string, string>, work: () => Promise<T>): Promise<T>;
+/**
+ * The live session for one conversation.
+ *
+ * The Pi types are structural rather than imported, so this file does not force the SDK to be installed
+ * for the type checker to work. The shapes here are the ones this code actually uses, and they are
+ * checked against the SDK at runtime by the session tests.
+ */
+export interface PiSessionLike {
+    /** Runs one turn. Resolves when the agent settles. */
+    prompt(message: string, options?: {
+        images?: unknown[];
+        streamingBehavior?: "steer" | "followUp";
+    }): Promise<void>;
+    /** Aborts the current operation and waits for the session to become idle. */
+    abort(): Promise<void>;
+    /** Subscribes to session events. Returns the unsubscribe function. */
+    subscribe(listener: (event: unknown) => void): () => void;
+    /** Releases the session's resources. */
+    dispose(): void;
+    /** The file Pi writes this session to, when it writes one. */
+    readonly sessionFile?: string | undefined;
+    /** The id of the session. */
+    readonly sessionId?: string | undefined;
+    /**
+     * The session's transcript, for naming a position in it.
+     *
+     * This is what makes a message a REVERT BOUNDARY on the session path: the one-shot path asked Pi over
+     * RPC (`get_entries`, then `get_entries(since: leaf)`); a live session already holds the same entries
+     * in memory, so the same question is two synchronous reads - `getLeafId` before the prompt, `getBranch`
+     * after it settles. Optional because a test double has no transcript; its absence means "this turn's
+     * message cannot be a revert boundary", reported in words, exactly as a failed RPC read was.
+     */
+    readonly sessionManager?: {
+        /** The id of the current leaf entry, or null when the session is still empty. */
+        getLeafId(): string | null;
+        /** The entries from the root to `fromId` (or the current leaf), in path order. */
+        getBranch(fromId?: string): unknown[];
+    };
+    /**
+     * The session's extension runner, for binding a UI context AFTER creation.
+     *
+     * Pi's extensions reach `ctx.ui` through this runner, and the runner starts life with a no-op context
+     * that silently answers `undefined`/`false` to everything - which for `confirm` is a fabricated "no"
+     * the user never gave. The host binds a real bridging context the first time it runs a turn on the
+     * session. Optional for the same reason as `sessionManager`: a test double has no extensions.
+     */
+    readonly extensionRunner?: {
+        setUIContext(uiContext: unknown, mode?: string): void;
+    };
+}
+/** How a session should be built. Everything here is decided once, at creation. */
+export interface SessionCreation {
+    /** The workspace. Pi resolves tools and the session file against it. */
+    cwd: string;
+    /** The session id, which is the Super Pi conversation id. */
+    sessionId: string;
+    /** The directory Pi keeps its session files in. */
+    sessionDir: string;
+    /** Super Pi's extensions to mount, as absolute paths. */
+    extensionPaths: string[];
+    /** The environment those extensions read when they are loaded. */
+    extensionEnv: Record<string, string>;
+    /** The agent's system prompt file, or undefined for Pi's own defaults. */
+    systemPromptFile?: string;
+    /** Whether the agent prompt REPLACES Pi's own or is appended to it. */
+    systemPromptMode?: "replace" | "append";
+    /** The tool allowlist. */
+    tools?: string[];
+    /** The tool denylist. */
+    excludeTools?: string[];
+    /** The model to pin. */
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    /** The thinking level to pin. */
+    thinkingLevel?: string;
+    /** Pi's global configuration directory. Defaults to Pi's own resolution. */
+    agentDir?: string;
+    /** Whether the session writes a file at all. A memory review must not. */
+    persist?: boolean;
+}
+/**
+ * Builds one Pi session.
+ *
+ * The order of operations here IS the isolation mechanism, and each step is load-bearing:
+ *
+ * 1. The environment is applied, so the extension factories that run during the reload read this
+ *    session's values rather than another session's.
+ * 2. The loader is created and reloaded, which is when Pi calls the extension factories. The factories
+ *    CAPTURE the values; they do not read them later.
+ * 3. The session is created with that loader.
+ *
+ * Step 2 happening outside step 1 would give every session the same configuration, and step 1 happening
+ * after step 2 would give every session no configuration at all. The window is the whole of the reload.
+ *
+ * THE FACTORY IS INJECTABLE. A test needs to drive a session without a real Pi behind it - to check what
+ * a session was BUILT with (its working directory, its allowlist) rather than what it eventually
+ * produced. The factory is therefore a parameter rather than a hard-coded call, and production passes
+ * the real one.
+ */
+export type PiSessionFactory = (creation: SessionCreation) => Promise<PiSessionLike>;
+export declare function createPiSession(creation: SessionCreation): Promise<PiSessionLike>;
+/**
+ * The Super Pi extension files, as absolute paths.
+ *
+ * Resolved from the repository root, exactly as `runtime.ts` resolves the `--extension` argument it
+ * passes to a child process: Pi resolves a relative `--extension` against the CONVERSATION's workspace
+ * rather than against the server's directory, so a relative path would find a different file for every
+ * workspace. The SDK takes an absolute path, and this keeps the two paths of the same file.
+ */
+export declare function superPiExtensionPaths(repositoryRoot: string): string[];