@jmfederico/pi-web 1.202608.0 → 1.202608.1

package/dist/server/sessions/piSessionService.js

@@ -1,6 +1,6 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
-import { readFile, stat, writeFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createEditToolDefinition, defineTool, readStoredCredential, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { projectBrowserMessage } from "../browserMessageProjection.js";
 import { pageMessagesAtSafeBoundary } from "./messagePaging.js";
@@ -16,8 +16,6 @@ import { parsePromptAttachments } from "../../shared/promptAttachments.js";
 import { ASK_USER_ANSWERS_CUSTOM_TYPE, SESSION_TREE_CUSTOM_INSTRUCTIONS_MAX_LENGTH, SESSION_UNREAD_LIMIT } from "../../shared/apiTypes.js";
 import { canonicalizeStoredCwd, cwdPathsEqual } from "../workingDirectory.js";
 import { readSessionHeaderSummary } from "./sessionFileHeader.js";
-import { countOutOfListingChildren, locateOutOfListingParents } from "./parentSessionLocator.js";
-import { siblingWorkspaceCwds } from "../workspaces/projectWorkspaceCwds.js";
 import { createAskUserToolDefinition } from "./askUserTool.js";
 import { PendingAskStore, renderAskUserAnswersText } from "./pendingAskStore.js";
 import { PendingExtensionDialogStore } from "./pendingExtensionDialogStore.js";
@@ -56,6 +54,14 @@ function spawnTargetError(decision) {
         return new Error("Spawning session is not in a registered project");
     return new Error(`cwd must be a workspace of this project. Allowed: ${decision.allowedCwds.join(", ")}`);
 }
+/**
+ * Tracked subsessions are worktree-scoped, so a requested target other than the
+ * parent's own cwd fails closed instead of being silently retargeted. The
+ * message names the rule and both supported ways to get work done elsewhere.
+ */
+function subsessionCwdError(spawningCwd, requestedCwd) {
+    return new Error(`A tracked subsession runs in this session's working directory (${spawningCwd}); ${requestedCwd} was requested. Instruct the child to work elsewhere from this workspace, or use spawn_session for an independent session in another workspace.`);
+}
 function modelSpecOf(model) {
     return `${model.provider}/${model.id}`;
 }
@@ -275,9 +281,28 @@ export function createPiWebCustomToolDefinitions(cwd, delegationEnabled, spawn,
         ...(askUser === undefined ? [] : [createAskUserToolDefinition(askUser)]),
     ];
 }
-function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subsessions, askUser) {
+/**
+ * Resource-loader options that append PI WEB's own system-prompt sections.
+ *
+ * `appendSystemPromptOverride` composes with what the loader already resolved,
+ * so the operator's `SYSTEM.md` / `APPEND_SYSTEM.md` files keep their content
+ * and PI WEB's sections land after them. Returns `undefined` when there is
+ * nothing to add, leaving the loader exactly as pi configures it.
+ */
+export function piWebResourceLoaderOptions(appendSystemPromptSections) {
+    if (appendSystemPromptSections.length === 0)
+        return undefined;
+    return { appendSystemPromptOverride: (base) => [...base, ...appendSystemPromptSections] };
+}
+function createDefaultRuntimeFactory(modelRuntime, sessionManagers, spawn, subsessions, askUser, appendSystemPromptSections = []) {
+    const resourceLoaderOptions = piWebResourceLoaderOptions(appendSystemPromptSections);
     return async ({ cwd, agentDir, sessionManager, sessionStartEvent, initialModel, initialThinkingLevel, delegationToolsEnabled }) => {
-        const services = await createAgentSessionServices({ cwd, agentDir, modelRuntime });
+        const services = await createAgentSessionServices({
+            cwd,
+            agentDir,
+            modelRuntime,
+            ...(resourceLoaderOptions === undefined ? {} : { resourceLoaderOptions }),
+        });
         const resolvedDelegationToolsEnabled = delegationToolsEnabled
             ?? await sessionAllowsDelegationTools(sessionManager, sessionManagers);
         const customTools = createPiWebCustomToolDefinitions(cwd, resolvedDelegationToolsEnabled, spawn, subsessions, askUser);
@@ -347,13 +372,6 @@ export class PiSessionService {
         this.subsessionLinks = new Map();
         /** Parent id/file identities whose persisted links have already been loaded. */
         this.subsessionHydratedParents = new Set();
-        /**
-         * Session file path -> its parsed header and the file identity at read
-         * time. Headers are written once, so identity-verified reads are cached.
-         */
-        this.sessionHeaderCache = new Map();
-        /** Session file path -> its in-flight header read, so concurrent scans share one read per file. */
-        this.pendingSessionHeaderReads = new Map();
         /**
          * Tracked subsession id -> whether a completion notification is armed.
          * Armed when the child starts working; firing on completion disarms it so a
@@ -366,46 +384,23 @@ export class PiSessionService {
         this.pendingUnreadMutations = [];
         this.unreadPublicationFlushRequested = false;
         this.unreadPublicationStopped = false;
-        /**
-         * Read a session file header, memoized per path, with one in-flight read
-         * per path: concurrent scans of a shared session directory share the read
-         * instead of each opening the file. Pi writes the header once at session
-         * creation, so a successful read stays valid as long as the path still
-         * holds the same file: every hit re-checks the file's identity (dev/ino),
-         * and a replacement landed at a cached path is re-read instead of serving
-         * the previous file's header — the summary scanner detects such
-         * replacements, so the listing and the header reads must agree. The one
-         * thing identity cannot detect is an in-place rewrite that keeps the
-         * inode; detach, the only such writer, deletes the entry itself. Failures
-         * are not cached so a session file that appears later is picked up.
-         */
-        this.readCachedSessionHeader = (sessionFile) => {
-            const pending = this.pendingSessionHeaderReads.get(sessionFile);
-            if (pending !== undefined)
-                return pending;
-            const read = this.loadSessionHeader(sessionFile).finally(() => {
-                this.pendingSessionHeaderReads.delete(sessionFile);
-            });
-            this.pendingSessionHeaderReads.set(sessionFile, read);
-            return read;
-        };
         this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
         this.agentDir = deps.agentDir;
         this.sessionManager = deps.sessionManager;
         this.modelRuntime = deps.modelRuntime;
         this.spawnTargets = deps.spawnTargets;
-        this.projectWorkspaces = deps.projectWorkspaces;
         this.logger = deps.logger ?? noopLogger;
         this.now = deps.now ?? (() => new Date());
         this.notificationStore = deps.notificationStore ?? new SessionNotificationStore();
         this.unreadStore = deps.unreadStore ?? new SessionUnreadStore();
+        this.onUnreadChanged = deps.onUnreadChanged;
         this.pendingAskStore = deps.pendingAskStore ?? new PendingAskStore();
         this.pendingExtensionDialogStore = deps.pendingExtensionDialogStore ?? new PendingExtensionDialogStore();
         this.extensionDialogsTimeoutMs = deps.extensionDialogsTimeoutMs ?? DEFAULT_EXTENSION_DIALOGS_TIMEOUT_MS;
         this.catalogRefreshStatus = deps.catalogRefreshStatus;
         this.unreadPublicationRetryInitialMs = Math.max(0, deps.unreadPublicationRetryDelayMs ?? DEFAULT_UNREAD_PUBLICATION_RETRY_MS);
         this.unreadPublicationRetryDelayMs = this.unreadPublicationRetryInitialMs;
-        // Subsessions are a beta capability gated behind their own flag, and they
+        // Subsessions are gated behind their own flag, and they
         // also require the spawn capability (they share its project-scope resolver).
         const subsessionsActive = this.spawnTargets !== undefined && deps.subsessionsEnabled === true;
         this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRuntime, this.sessionManager, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input), !subsessionsActive ? undefined : {
@@ -413,7 +408,7 @@ export class PiSessionService {
             list: (parentSessionId, parentSessionFile) => this.listSubsessions(parentSessionId, parentSessionFile),
             check: (parentSessionId, sessionId, parentSessionFile) => this.checkSubsession(parentSessionId, sessionId, parentSessionFile),
             read: (parentSessionId, sessionId, query, parentSessionFile) => this.readSubsession(parentSessionId, sessionId, query, parentSessionFile),
-        }, deps.askUserEnabled === true ? { open: (input) => this.openAsk(input) } : undefined);
+        }, deps.askUserEnabled === true ? { open: (input) => this.openAsk(input) } : undefined, deps.appendSystemPromptSections ?? []);
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
         this.workspaceActivity = deps.workspaceActivity;
         this.heartbeat = setInterval(() => { this.publishHeartbeats(); }, deps.heartbeatIntervalMs ?? 2000);
@@ -541,8 +536,6 @@ export class PiSessionService {
         this.subsessionLinks.clear();
         this.subsessionHydratedParents.clear();
         this.subsessionNotifyArmed.clear();
-        this.sessionHeaderCache.clear();
-        this.pendingSessionHeaderReads.clear();
         this.notificationStore.clearAll("service-dispose");
         await Promise.all(activeSessions.map(async (active) => {
             active.unsubscribe();
@@ -573,83 +566,7 @@ export class PiSessionService {
             .sort(compareArchivedRecords)
             .map((record) => clientSessionFromArchivedRecord(record, sessionsById.get(record.sessionId)))
             .filter(isDefined);
-        return await this.withRelatedSessionsElsewhere([...unarchivedSessions, ...archivedSessions], cwd);
-    }
-    /**
-     * Annotate a listing with the session relationships that cross workspace
-     * boundaries: where an out-of-listing parent lives, and how many children a
-     * listed session has in sibling workspaces.
-     *
-     * Both directions are best-effort. An unreadable parent header or a sibling
-     * workspace that cannot be listed leaves the session unannotated rather than
-     * failing the listing, and the browser falls back to its generic states.
-     */
-    async withRelatedSessionsElsewhere(sessions, cwd) {
-        const [parentLocations, childCounts] = await Promise.all([
-            locateOutOfListingParents(sessions, cwd, this.readCachedSessionHeader),
-            this.countChildrenInSiblingWorkspaces(sessions, cwd),
-        ]);
-        return sessions.map((session) => {
-            const parent = session.parentSessionPath === undefined ? undefined : parentLocations.get(session.parentSessionPath);
-            const childrenElsewhere = childCounts.get(session.path);
-            if (parent === undefined && childrenElsewhere === undefined)
-                return session;
-            const annotated = { ...session };
-            if (parent !== undefined) {
-                annotated.parentSessionId = parent.parentSessionId;
-                annotated.parentSessionCwd = parent.parentSessionCwd;
-            }
-            if (childrenElsewhere !== undefined)
-                annotated.childSessionsElsewhere = childrenElsewhere;
-            return annotated;
-        });
-    }
-    /**
-     * Count children of the listed sessions that live in other workspaces of the
-     * same project.
-     *
-     * Only sibling workspaces are scanned: agents may only spawn into workspaces
-     * of the spawning session's own project, so that bounds where a child can be.
-     * Each sibling scan reads only the header line of every session file (the
-     * only place `parentSessionPath` is recorded), never the transcripts. Listing
-     * is skipped entirely when no project-workspace locator is configured or the
-     * cwd belongs to no registered project.
-     */
-    async countChildrenInSiblingWorkspaces(sessions, cwd) {
-        if (this.projectWorkspaces === undefined || sessions.length === 0)
-            return new Map();
-        try {
-            const siblingCwds = await siblingWorkspaceCwds(this.projectWorkspaces, cwd);
-            if (siblingCwds.length === 0)
-                return new Map();
-            const listings = await Promise.all(siblingCwds.map((siblingCwd) => this.sessionManager.listParentSessionPaths(siblingCwd, this.readCachedSessionHeader)));
-            return countOutOfListingChildren(sessions, listings.flat());
-        }
-        catch (error) {
-            this.logger.info({ cwd, error: error instanceof Error ? error.message : String(error) }, "failed to count child sessions in sibling workspaces");
-            return new Map();
-        }
-    }
-    async loadSessionHeader(sessionFile) {
-        let stats;
-        try {
-            stats = await stat(sessionFile);
-        }
-        catch {
-            // Gone or unreadable: report no header and forget any cached entry.
-            this.sessionHeaderCache.delete(sessionFile);
-            return undefined;
-        }
-        const cached = this.sessionHeaderCache.get(sessionFile);
-        if (cached?.dev === stats.dev && cached.ino === stats.ino)
-            return cached.header;
-        const header = await readSessionHeaderSummary(sessionFile);
-        if (header === undefined) {
-            this.sessionHeaderCache.delete(sessionFile);
-            return undefined;
-        }
-        this.sessionHeaderCache.set(sessionFile, { header, dev: stats.dev, ino: stats.ino });
-        return header;
+        return [...unarchivedSessions, ...archivedSessions];
     }
     async start(cwd, options = {}) {
         return this.startSession(cwd, options);
@@ -711,15 +628,22 @@ export class PiSessionService {
         };
     }
     /**
-     * Start a *tracked* child session on behalf of a LLM. Identical to
-     * {@link spawnSession} in how the target cwd is resolved, but the child
-     * records its parent (so it shows in the session tree) and is registered so
-     * the parent is notified when it stops working and can inspect it later.
+     * Start a *tracked* child session on behalf of a LLM. Unlike
+     * {@link spawnSession}, a tracked child always runs in the parent's own
+     * workspace: parent/child trees are worktree-scoped, so a child elsewhere
+     * would be invisible to the parent's listing. The child records its parent
+     * (so it shows in the session tree) and is registered so the parent is
+     * notified when it stops working and can inspect it later.
      */
     async spawnSubsession(input) {
         if (this.spawnTargets === undefined)
             throw new Error("Spawning sessions is disabled");
-        const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
+        if (input.cwd !== undefined && input.cwd !== "" && !cwdPathsEqual(input.cwd, input.spawningCwd)) {
+            throw subsessionCwdError(input.spawningCwd, input.cwd);
+        }
+        // Resolved against the parent's own cwd only: this still refuses spawning
+        // from an unregistered directory, which keeps the child visible in the UI.
+        const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, undefined);
         if (!decision.allowed)
             throw spawnTargetError(decision);
         // A model spec overrides the inherited model and is resolved against the
@@ -756,10 +680,12 @@ export class PiSessionService {
     /**
      * The models a session may pick from: its scoped set when model-scoped,
      * otherwise the runtime's available snapshot. Refreshes the runtime catalog
-     * first so callers see newly configured providers and models.
+     * first so callers see newly configured providers and models. The refresh
+     * stays local (`allowNetwork: false`); network refreshes belong to the
+     * bounded background catalog refresher, not this request path.
      */
     async sessionModelCandidates(session) {
-        await session.modelRuntime.refresh();
+        await session.modelRuntime.refresh({ allowNetwork: false });
         return session.scopedModels.length > 0
             ? session.scopedModels.map((scoped) => scoped.model)
             : session.modelRuntime.getAvailableSnapshot();
@@ -1585,6 +1511,83 @@ export class PiSessionService {
             }
         }
     }
+    /**
+     * Fork the session from one entry of its tree into a new session file,
+     * leaving the original session untouched. The forked runtime replaces the
+     * current one, so the outcome is reported for the session the client is
+     * about to join rather than the forked-from record.
+     */
+    async forkFromTree(ref, request) {
+        if (request.entryId.trim() === "")
+            throw new Error("Session tree entry is required");
+        if (this.isTreeExclusiveSessionIdentityActive(ref.id)) {
+            throw new Error("Stop current session activity before forking the session tree");
+        }
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        if (this.hasActiveWork(session))
+            throw new Error("Stop current session activity before forking the session tree");
+        if (session.sessionManager.getLeafId() !== request.expectedLeafId) {
+            throw new Error("The session changed since /tree was opened. Reopen /tree and try again.");
+        }
+        this.publishActivity(session, "forking session from entry", "active");
+        this.publishStatus(session);
+        try {
+            const result = await this.commandService.forkEntry(session.sessionId, request.entryId, {
+                expectedLeafId: request.expectedLeafId,
+            });
+            if (result.type === "unsupported")
+                throw new Error(result.message);
+            if (result.type !== "done")
+                throw new Error("Session fork is unavailable");
+            if (result.session === undefined) {
+                if (this.isCurrentActiveSession(session)) {
+                    this.publishActivity(session, "fork cancelled", "idle");
+                    this.publishStatus(session);
+                }
+                return { cancelled: true };
+            }
+            const forkedSession = this.active.get(result.session.id)?.runtime.session;
+            if (forkedSession !== undefined && this.isCurrentActiveSession(forkedSession)) {
+                this.publishActivity(forkedSession, "session forked", "idle");
+                this.publishStatus(forkedSession);
+            }
+            if (result.session.id !== session.sessionId)
+                this.clearSupersededSessionActivity(session);
+            return {
+                cancelled: false,
+                session: result.session,
+                ...(result.promptDraft === undefined ? {} : { promptDraft: result.promptDraft }),
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (this.isCurrentActiveSession(session)) {
+                this.publishActivity(session, "fork failed", "error", message);
+                this.events.publish(session.sessionId, { type: "session.error", message });
+                this.publishStatus(session);
+            }
+            throw error;
+        }
+    }
+    /**
+     * A changed-id fork can rebind its runtime after a heartbeat published the
+     * prior identity as active. Clear every observable owner before forgetting
+     * that identity's local activity record.
+     */
+    clearSupersededSessionActivity(session) {
+        const sessionId = session.sessionId;
+        if (this.activities.get(sessionId)?.phase === "active") {
+            const at = new Date().toISOString();
+            const stored = { phase: "idle", label: "idle", at };
+            this.activities.set(sessionId, stored);
+            const activity = { sessionId, ...stored };
+            this.events.publish(sessionId, { type: "activity.update", activity });
+            this.events.publishGlobal({ type: "activity.update", activity });
+        }
+        this.workspaceActivity?.removeSession(sessionId, session.sessionManager.getCwd());
+        this.activities.delete(sessionId);
+    }
     async reloadSessionRuntime(session) {
         if (this.hasActiveWork(session))
             throw new Error("Stop current session activity before reloading");
@@ -1832,13 +1835,10 @@ export class PiSessionService {
         if (sessionFile === undefined || sessionFile === "")
             throw new Error("Session is not persisted");
         await clearParentSession(sessionFile);
-        // The header cache memoizes the first successful read, and detach is the
-        // only flow that rewrites a header; drop the stale entry so sibling child
-        // counts and parent locations observe the cleared parent immediately.
-        this.sessionHeaderCache.delete(sessionFile);
-        // The same in-place rewrite is invisible to the gateway's summary memo
-        // (same inode, possibly grown file), which would otherwise keep listing
-        // the old parent link and a stale message count until restart.
+        // The header rewrite keeps the inode, and whenever it leaves the file's
+        // size unchanged it is invisible to the gateway's summary memo, which
+        // cannot detect such rewrites from identity + size alone and would keep
+        // listing the old parent link until restart.
         this.sessionManager.invalidateSessionFile(sessionFile);
         clearParentSessionHeader(session.sessionManager);
         this.unregisterSubsession(session.sessionId);
@@ -2106,9 +2106,11 @@ export class PiSessionService {
             const { archivePath } = archived;
             return this.openExistingSession(archived.sessionId, archived.cwd, () => this.sessionManager.open(archivePath), { notifications: "disabled" });
         }
-        // Resolve the session file directly by id: opening one inactive session
-        // must not pay for a full transcript listing of its whole workspace.
-        const match = await this.sessionManager.resolveSessionFile(ref.cwd, ref.id, this.readCachedSessionHeader);
+        // Resolve the session file directly by id: opening one known session must
+        // not depend on — or wait behind — a full transcript listing of its whole
+        // workspace. `getActive` routes prompt/shell/runCommand, so coupling it to
+        // the listing would let an in-flight listing serialize unrelated sends.
+        const match = await this.sessionManager.resolveSessionFile(ref.cwd, ref.id);
         if (!match)
             throw new Error("Session not found");
         return this.openExistingSession(match.id, match.cwd, () => this.sessionManager.open(match.path), options);
@@ -2424,6 +2426,11 @@ export class PiSessionService {
         void this.publishUnreadMutations(mutations).catch(() => undefined);
     }
     publishUnreadMutations(mutations) {
+        // The store applied the mutations already, so the status projection is told
+        // now rather than after the durable flush: it reads in-memory unread state
+        // and must not lag behind the rows the browser is about to see.
+        if (mutations.length > 0)
+            this.onUnreadChanged?.();
         this.enqueueUnreadMutations(mutations);
         this.unreadPublicationFlushRequested = true;
         if (this.unreadPublication === undefined && this.unreadPublicationRetryTimer !== undefined) {