@jmfederico/pi-web 1.202606.3 → 1.202606.5

package/dist/server/sessions/piSessionService.js

@@ -8,10 +8,21 @@ import { findArchiveCandidateByIdOrPrefix, planSessionArchiveTree } from "./sess
 import { fallbackSessionName, generateShortSessionName } from "./sessionNameGenerator.js";
 import { computeEditPreview } from "./editPreview.js";
 import { createPiSessionManagerGateway } from "./piSessionManagerGateway.js";
+import { attachmentsToInlineImages, saveAttachmentsToWorkspace } from "./attachmentService.js";
+import { parsePromptAttachments } from "../../shared/promptAttachments.js";
 import { cwdPathsEqual } from "../workingDirectory.js";
+import { createSpawnSessionToolDefinition } from "./spawnSessionTool.js";
+import { createSubsessionToolDefinitions } from "./spawnSubsessionTool.js";
+import { buildTranscriptView } from "./subsessionTranscript.js";
+const noopLogger = { info() { } };
 function noop() {
     // Intentionally empty default unsubscribe callback.
 }
+function spawnTargetError(decision) {
+    if (decision.reason === "not-registered")
+        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(", ")}`);
+}
 function authLossWarningKey(sessionId, provider, modelId) {
     return `${sessionId}:${provider}/${modelId}`;
 }
@@ -41,10 +52,14 @@ function defaultCreateAgentRuntime(createRuntime, options) {
         throw new Error("Default runtime creation requires an SDK SessionManager");
     return createAgentSessionRuntime(createRuntime, { ...options, sessionManager: options.sessionManager });
 }
-function createDefaultRuntimeFactory(authStorage, modelRegistry) {
+function createDefaultRuntimeFactory(authStorage, modelRegistry, spawn, subsessions) {
     return async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
         const services = await createAgentSessionServices({ cwd, agentDir, authStorage, modelRegistry });
-        const customTools = [createPiWebEditToolDefinition(cwd)];
+        const customTools = [
+            createPiWebEditToolDefinition(cwd),
+            ...(spawn === undefined ? [] : [createSpawnSessionToolDefinition(cwd, { spawn })]),
+            ...(subsessions === undefined ? [] : createSubsessionToolDefinitions(cwd, subsessions)),
+        ];
         const options = sessionStartEvent === undefined
             ? { services, sessionManager, customTools }
             : { services, sessionManager, sessionStartEvent, customTools };
@@ -81,15 +96,35 @@ export class PiSessionService {
         this.compactionPromptQueues = new Map();
         this.compactionDrainTimers = new Map();
         this.authLossWarnings = new Set();
+        /** Tracked subsession id -> the parent session id that spawned it. */
+        this.subsessionParents = new Map();
+        /** Parent session id -> the set of tracked subsession ids it spawned. */
+        this.subsessionChildren = new Map();
+        /**
+         * Tracked subsession id -> whether a completion notification is armed.
+         * Armed when the child starts working; firing on completion disarms it so a
+         * child that works again (and stops again) notifies the parent each time.
+         */
+        this.subsessionNotifyArmed = new Map();
         this.archiveStore = deps.archiveStore ?? new SessionArchiveStore();
         this.agentDir = deps.agentDir ?? getAgentDir();
         this.sessionManager = deps.sessionManager ?? createPiSessionManagerGateway({ agentDir: this.agentDir });
         this.modelRegistry = deps.modelRegistry ?? ModelRegistry.create(AuthStorage.create());
-        this.createRuntime = deps.createRuntime ?? createDefaultRuntimeFactory(this.modelRegistry.authStorage, this.modelRegistry);
+        this.spawnTargets = deps.spawnTargets;
+        this.logger = deps.logger ?? noopLogger;
+        // Subsessions are a beta capability 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.modelRegistry.authStorage, this.modelRegistry, this.spawnTargets === undefined ? undefined : (input) => this.spawnSession(input), !subsessionsActive ? undefined : {
+            spawn: (input) => this.spawnSubsession(input),
+            list: (parentSessionId) => this.listSubsessions(parentSessionId),
+            check: (parentSessionId, sessionId) => this.checkSubsession(parentSessionId, sessionId),
+            read: (parentSessionId, sessionId, query) => this.readSubsession(parentSessionId, sessionId, query),
+        });
         this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime;
         this.workspaceActivity = deps.workspaceActivity;
         this.heartbeat = setInterval(() => { this.publishHeartbeats(); }, deps.heartbeatIntervalMs ?? 2000);
-        this.commandService = new SessionCommandService((sessionId) => this.getActive(sessionId), (sessionId, text) => this.prompt(sessionId, text), events, {
+        this.commandService = new SessionCommandService((sessionId) => this.getActive(sessionId), (sessionId, text) => this.prompt(sessionId, text, undefined, undefined, { echoUserMessage: false }), events, {
             onCompactionStart: (session) => {
                 this.publishActivity(session, "compacting", "active");
                 this.publishStatus(session);
@@ -111,6 +146,9 @@ export class PiSessionService {
         this.activities.clear();
         this.compactionPromptQueues.clear();
         this.authLossWarnings.clear();
+        this.subsessionParents.clear();
+        this.subsessionChildren.clear();
+        this.subsessionNotifyArmed.clear();
         await Promise.all(activeSessions.map(async (active) => {
             active.unsubscribe();
             this.workspaceActivity?.removeSession(active.runtime.session.sessionId, active.runtime.session.sessionManager.getCwd());
@@ -133,10 +171,10 @@ export class PiSessionService {
             .filter(isDefined);
         return [...unarchivedSessions, ...archivedSessions];
     }
-    async start(cwd) {
-        const active = await this.create(this.sessionManager.create(cwd), cwd);
+    async start(cwd, parentSession) {
+        const active = await this.create(this.sessionManager.create(cwd, parentSession === undefined ? undefined : { parentSession }), cwd);
         const { session } = active.runtime;
-        return {
+        const created = {
             id: session.sessionId,
             path: session.sessionFile ?? "",
             cwd,
@@ -144,8 +182,153 @@ export class PiSessionService {
             modified: new Date().toISOString(),
             messageCount: session.messages.length,
             firstMessage: "",
+            // Include the parent so listeners can nest the new session in the tree
+            // immediately, instead of showing it flat until the next reload.
+            ...(parentSession === undefined ? {} : { parentSessionPath: parentSession }),
+        };
+        // Broadcast so other clients (and the spawning agent's UI) can add the new
+        // session to their list without a manual reload.
+        this.events.publishGlobal({ type: "session.created", session: created });
+        return created;
+    }
+    /**
+     * Start a new session on behalf of a LLM and deliver an initial prompt to it.
+     * The target cwd is constrained to a workspace of the same registered project
+     * as the spawning session so the new session is visible in the web UI.
+     */
+    async spawnSession(input) {
+        if (this.spawnTargets === undefined)
+            throw new Error("Spawning sessions is disabled");
+        const decision = await this.spawnTargets.resolveSpawnTarget(input.spawningCwd, input.cwd);
+        if (!decision.allowed)
+            throw spawnTargetError(decision);
+        const created = await this.start(decision.cwd);
+        await this.prompt(created.id, input.prompt);
+        this.logger.info({ spawningCwd: input.spawningCwd, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length }, "spawn_session started a new session");
+        return { sessionId: created.id, cwd: decision.cwd };
+    }
+    /**
+     * 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.
+     */
+    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 (!decision.allowed)
+            throw spawnTargetError(decision);
+        const created = await this.start(decision.cwd, input.parentSessionFile);
+        this.registerSubsession(input.parentSessionId, created.id);
+        await this.prompt(created.id, input.prompt);
+        this.logger.info({ parentSessionId: input.parentSessionId, sessionId: created.id, cwd: decision.cwd, promptLength: input.prompt.length }, "spawn_subsession started a tracked child session");
+        return { sessionId: created.id, cwd: decision.cwd };
+    }
+    /** Summaries of the tracked subsessions spawned by `parentSessionId`. */
+    async listSubsessions(parentSessionId) {
+        const childIds = this.subsessionChildren.get(parentSessionId);
+        if (childIds === undefined)
+            return [];
+        return Promise.all([...childIds].map(async (childId) => ({ sessionId: childId, ...(await this.subsessionSummaryFields(childId)) })));
+    }
+    /** Status and final result of a subsession, scoped to the caller's children. */
+    async checkSubsession(parentSessionId, sessionId) {
+        const session = await this.openSubsession(parentSessionId, sessionId);
+        const messages = historyMessages(session);
+        return {
+            sessionId,
+            cwd: session.sessionManager.getCwd(),
+            status: await this.subsessionStatus(session),
+            finalText: finalAssistantText(messages),
+            messageCount: messages.length,
         };
     }
+    /** Filtered, paginated transcript of a subsession, scoped to the caller's children. */
+    async readSubsession(parentSessionId, sessionId, query) {
+        const session = await this.openSubsession(parentSessionId, sessionId);
+        const view = buildTranscriptView(historyMessages(session), query);
+        return {
+            sessionId,
+            cwd: session.sessionManager.getCwd(),
+            status: await this.subsessionStatus(session),
+            ...view,
+        };
+    }
+    /** Open a session after verifying it is one of the caller's tracked children. */
+    async openSubsession(parentSessionId, sessionId) {
+        if (this.subsessionParents.get(sessionId) !== parentSessionId) {
+            throw new Error(`Session ${sessionId} is not one of your subsessions`);
+        }
+        return this.getOrOpen(sessionId);
+    }
+    registerSubsession(parentSessionId, childSessionId) {
+        this.subsessionParents.set(childSessionId, parentSessionId);
+        const children = this.subsessionChildren.get(parentSessionId) ?? new Set();
+        children.add(childSessionId);
+        this.subsessionChildren.set(parentSessionId, children);
+        this.subsessionNotifyArmed.set(childSessionId, false);
+    }
+    async subsessionSummaryFields(childSessionId) {
+        const active = this.active.get(childSessionId);
+        if (active !== undefined) {
+            return { cwd: active.runtime.cwd, status: await this.subsessionStatus(active.runtime.session) };
+        }
+        const archived = await this.archiveStore.get(childSessionId);
+        if (archived !== undefined)
+            return { cwd: archived.cwd, status: "archived" };
+        return { cwd: "", status: "unknown" };
+    }
+    async subsessionStatus(session) {
+        if (await this.archiveStore.isArchived(session.sessionId))
+            return "archived";
+        if (this.hasActiveWork(session))
+            return "working";
+        if (this.activities.get(session.sessionId)?.phase === "error")
+            return "error";
+        return "idle";
+    }
+    /**
+     * Drive parent notifications from a tracked child's status. Arms a pending
+     * notification while the child is working, and when it stops fires a single
+     * follow-up message to the parent via {@link prompt} (which queues if the
+     * parent is busy and delivers immediately when it is idle).
+     */
+    updateSubsessionTracking(session) {
+        const childId = session.sessionId;
+        const parentId = this.subsessionParents.get(childId);
+        if (parentId === undefined)
+            return;
+        if (this.hasActiveWork(session)) {
+            this.subsessionNotifyArmed.set(childId, true);
+            return;
+        }
+        if (this.subsessionNotifyArmed.get(childId) !== true)
+            return;
+        this.subsessionNotifyArmed.set(childId, false);
+        const status = this.activities.get(childId)?.phase === "error" ? "error" : "idle";
+        const finalText = finalAssistantText(historyMessages(session));
+        const preview = finalText === "" ? "(no output)" : truncateForNotification(finalText);
+        const text = `Subsession ${childId} stopped working (status: ${status}). Latest output:\n\n${preview}\n\nUse check_subsession with sessionId "${childId}" for its status and latest output, or read_subsession to look through its full transcript.`;
+        void this.notifyParentOfSubsession(parentId, childId, text);
+    }
+    /**
+     * Deliver a subsession-completion notice to the parent as a system-authored
+     * custom message rather than a user message, so it is not attributed to the
+     * human in the transcript. It still wakes an idle parent (`triggerTurn`) and
+     * queues behind in-flight work (`deliverAs: "followUp"`), preserving the
+     * established "queue if busy, send and act if idle" behavior.
+     */
+    async notifyParentOfSubsession(parentId, childId, text) {
+        try {
+            const session = await this.getOrOpen(parentId);
+            await session.sendCustomMessage({ customType: SUBSESSION_NOTIFICATION_CUSTOM_TYPE, content: text, display: true, details: { sessionId: childId } }, { triggerTurn: true, deliverAs: "followUp" });
+            this.publishStatus(session);
+        }
+        catch (error) {
+            this.logger.info({ parentSessionId: parentId, sessionId: childId, error: error instanceof Error ? error.message : String(error) }, "failed to notify parent of subsession completion");
+        }
+    }
     async messages(ref, page) {
         const session = await this.getOrOpen(ref);
         return pageMessagesAtSafeBoundary(historyMessages(session), page);
@@ -194,7 +377,13 @@ export class PiSessionService {
     async setThinkingLevel(ref, level) {
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
-        session.setThinkingLevel(level);
+        // pi owns the valid set; validate against the session's live levels rather
+        // than a hardcoded union so this stays correct if pi changes the set.
+        const available = session.getAvailableThinkingLevels();
+        const match = available.find((candidate) => candidate === level);
+        if (match === undefined)
+            throw new Error(`Invalid thinking level: ${level}`);
+        session.setThinkingLevel(match);
         this.publishActivity(session, `thinking: ${session.thinkingLevel}`, "idle");
         this.publishStatus(session);
         return this.statusFromSession(session);
@@ -223,30 +412,38 @@ export class PiSessionService {
         }
         return commands.sort((a, b) => a.name.localeCompare(b.name));
     }
-    async prompt(ref, text, streamingBehavior) {
+    async prompt(ref, text, streamingBehavior, attachments, options) {
         const promptText = requirePromptText(text);
+        // Command-forwarded prompts (e.g. /skill:*) are expanded by the agent, which
+        // streams the canonical message back. The client doesn't render the raw
+        // command text, so the server must not echo it either, or it would show up
+        // as a transient line that vanishes on reload.
+        const echoUserMessage = options?.echoUserMessage !== false;
         const requestedBehavior = parsePromptStreamingBehavior(streamingBehavior);
+        const parsedAttachments = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false });
+        const images = (await attachmentsToInlineImages(parsedAttachments)).map((entry) => entry.image);
         await this.assertWritable(ref);
         const session = await this.getOrOpen(ref);
         this.maybeGenerateSessionName(session, promptText);
         const isQueued = session.isStreaming || session.isCompacting;
         const behavior = isQueued ? requestedBehavior ?? "followUp" : undefined;
-        if (isQueued && this.hasQueuedMessageText(session, promptText)) {
+        if (isQueued && images.length === 0 && this.hasQueuedMessageText(session, promptText)) {
             this.publishActivity(session, "duplicate queued message ignored", "active");
             this.publishStatus(session);
             return;
         }
         if (session.isCompacting) {
-            this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp");
+            this.enqueuePromptDuringCompaction(session, promptText, behavior ?? "followUp", images, echoUserMessage);
             return;
         }
-        void this.submitPrompt(session, promptText, behavior);
+        void this.submitPrompt(session, promptText, behavior, images, echoUserMessage);
     }
-    submitPrompt(session, text, behavior) {
+    submitPrompt(session, text, behavior, images = [], echoUserMessage = true) {
         this.publishActivity(session, behavior === "steer" ? "steering queued" : behavior === "followUp" ? "message queued" : "prompt accepted", "active");
-        if (behavior === undefined)
-            this.events.publish(session.sessionId, { type: "message.append", message: userTextMessage(text) });
-        const promptPromise = session.prompt(text, behavior === undefined ? undefined : { streamingBehavior: behavior }).catch((error) => {
+        if (behavior === undefined && echoUserMessage)
+            this.events.publish(session.sessionId, { type: "message.append", message: userMessage(text, images) });
+        const promptOptions = buildPromptOptions(behavior, images);
+        const promptPromise = session.prompt(text, promptOptions).catch((error) => {
             const message = error instanceof Error ? error.message : String(error);
             this.publishActivity(session, "error", "error", message);
             this.events.publish(session.sessionId, { type: "session.error", message });
@@ -254,13 +451,21 @@ export class PiSessionService {
         void promptPromise;
         return promptPromise;
     }
-    enqueuePromptDuringCompaction(session, text, kind) {
+    enqueuePromptDuringCompaction(session, text, kind, images = [], echoUserMessage = true) {
         const queue = this.compactionPromptQueues.get(session.sessionId) ?? [];
-        queue.push({ kind, text });
+        queue.push({ kind, text, ...(images.length > 0 ? { images } : {}), ...(echoUserMessage ? {} : { echoUserMessage: false }) });
         this.compactionPromptQueues.set(session.sessionId, queue);
         this.publishActivity(session, "message queued during compaction", "active");
         this.publishStatus(session);
     }
+    async saveAttachments(ref, attachments, folder) {
+        const parsed = parsePromptAttachments(attachments, { enforceInlineSizeLimit: false });
+        if (parsed.length === 0)
+            return [];
+        await this.assertWritable(ref);
+        const active = await this.getActive(ref);
+        return saveAttachmentsToWorkspace(active.runtime.cwd, parsed, folder === undefined ? {} : { folder });
+    }
     async shell(ref, text) {
         await this.assertWritable(ref);
         const active = await this.getActive(ref);
@@ -352,6 +557,15 @@ export class PiSessionService {
             await this.ensureArchivedRecordMoved(record);
         await this.archiveStore.deleteArchived(record.sessionId);
     }
+    async reload(ref) {
+        await this.assertWritable(ref);
+        const session = await this.getOrOpen(ref);
+        if (this.hasActiveWork(session))
+            throw new Error("Stop current session activity before reloading");
+        await this.closeActive(session.sessionId);
+        const reopened = await this.getActive(ref);
+        this.publishStatus(reopened.runtime.session);
+    }
     async detachParent(ref) {
         const session = await this.getOrOpen(ref);
         const sessionFile = session.sessionFile;
@@ -472,6 +686,10 @@ export class PiSessionService {
         this.workspaceActivity?.removeSession(sessionId, active.runtime.session.sessionManager.getCwd());
         this.clearAuthLossWarningsForSession(sessionId);
         this.clearCompactionPromptQueue(sessionId);
+        // Disarm subsession notification before teardown so the abort below cannot
+        // emit a "stopped working" event that notifies the parent (e.g. on archive).
+        // The parent/children link is kept so the parent can still see the child.
+        this.subsessionNotifyArmed.delete(sessionId);
         clearSessionQueue(active.runtime.session);
         active.unsubscribe();
         try {
@@ -562,6 +780,7 @@ export class PiSessionService {
             if (eventType === "agent_start" || eventType === "agent_end")
                 this.scheduleCompactionQueueDrain(session.sessionId);
             this.publishStatus(session);
+            this.updateSubsessionTracking(session);
         });
         this.active.set(session.sessionId, active);
     }
@@ -589,14 +808,14 @@ export class PiSessionService {
                 return;
             this.publishStatus(session);
             for (const prompt of queued)
-                void this.submitPrompt(session, prompt.text, prompt.kind);
+                void this.submitPrompt(session, prompt.text, prompt.kind, prompt.images, prompt.echoUserMessage ?? true);
             return;
         }
         const prompt = this.shiftCompactionPrompt(sessionId);
         if (prompt === undefined)
             return;
         this.publishStatus(session);
-        const submitted = this.submitPrompt(session, prompt.text, undefined);
+        const submitted = this.submitPrompt(session, prompt.text, undefined, prompt.images, prompt.echoUserMessage ?? true);
         void submitted.finally(() => { this.scheduleCompactionQueueDrain(sessionId); });
     }
     takeCompactionPromptQueue(sessionId) {
@@ -691,6 +910,10 @@ export class PiSessionService {
     publishHeartbeats() {
         for (const active of this.active.values()) {
             const { session } = active.runtime;
+            // Re-evaluate subsession completion here too: agent_end can arrive while
+            // the session still reports active work transiently, so the event-driven
+            // latch may not fire. The heartbeat re-checks once the session settles.
+            this.updateSubsessionTracking(session);
             const activity = this.activities.get(session.sessionId);
             if (!this.hasActiveWork(session)) {
                 if (activity?.phase === "active")
@@ -998,6 +1221,28 @@ function queuedMessagesFromSession(session, extraQueuedMessages = []) {
 function userTextMessage(text) {
     return { role: "user", content: text };
 }
+/**
+ * Build the optimistic user message echoed to clients. When images are present
+ * we mirror pi's content-array shape (`[{type:"text"}, {type:"image"}, ...]`) so
+ * the local echo matches what pi persists in the session branch.
+ */
+function userMessage(text, images) {
+    if (images.length === 0)
+        return userTextMessage(text);
+    const content = [];
+    if (text !== "")
+        content.push({ type: "text", text });
+    content.push(...images);
+    return { role: "user", content };
+}
+function buildPromptOptions(behavior, images) {
+    const options = {};
+    if (behavior !== undefined)
+        options.streamingBehavior = behavior;
+    if (images.length > 0)
+        options.images = images;
+    return Object.keys(options).length > 0 ? options : undefined;
+}
 function stringValue(value) {
     return typeof value === "string" ? value : "";
 }
@@ -1017,6 +1262,35 @@ function historyMessages(session) {
     }
     return messages;
 }
+/** customType marking a parent-facing subsession-completion notice. */
+const SUBSESSION_NOTIFICATION_CUSTOM_TYPE = "subsession.completion";
+const SUBSESSION_NOTIFICATION_PREVIEW_CHARS = 2000;
+function truncateForNotification(text) {
+    if (text.length <= SUBSESSION_NOTIFICATION_PREVIEW_CHARS)
+        return text;
+    return `${text.slice(0, SUBSESSION_NOTIFICATION_PREVIEW_CHARS)}…`;
+}
+/** Most recent assistant text from a history message list, or "" if none. */
+function finalAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (!isRecord(message) || message["role"] !== "assistant")
+            continue;
+        const content = message["content"];
+        if (typeof content === "string")
+            return content;
+        if (!Array.isArray(content))
+            continue;
+        const texts = [];
+        for (const part of content) {
+            if (isRecord(part) && part["type"] === "text" && typeof part["text"] === "string")
+                texts.push(part["text"]);
+        }
+        if (texts.length > 0)
+            return texts.join("\n").trim();
+    }
+    return "";
+}
 function toClientEvent(event) {
     const eventType = getString(event, "type");
     const assistantMessageEvent = getProperty(event, "assistantMessageEvent");