PiAgentUI/docs/superpowers/specs/2026-05-30-piagentui-active-session-switch-design.md

PiAgentUI Active Session Switch Design

Goal

When the user opens an existing session in PiAgentUI and sends a message, the message must be delivered to that selected Pi session, not to whichever session was active when the Pi TUI launched.

Current finding

• The frontend route/store correctly loads selected sessions and their messages.
• src/hooks/useChatSession.ts sends the selected sessionId to sendMessageAsync().
• extensions/piagentui-server.ts receives sessionId, but still calls pi.sendUserMessage(parsed.text).
• pi.sendUserMessage() always targets the current active Pi runtime session.
• Pi exposes switchSession() only on ExtensionCommandContext, not on normal event ExtensionContext used by session_start and the HTTP server.
• AgentSessionRuntime.switchSession() intentionally emits session_shutdown, disposes the old session, creates the replacement session, rebinds extensions, then runs withSession(replacedCtx).
• The existing PiAgentUI extension currently stops the web server on every session_shutdown, so a normal Pi session switch can close the HTTP/SSE server and force reconnects.

Selected approach: activate and send on the backend

The backend should become authoritative for message routing:

1. Resolve requested sessionId to the JSONL session file in the current session directory.
2. If the requested session differs from the active Pi session, switch the real Pi runtime to that session.
3. Send the user message inside the replacement session callback so the message cannot land in the old session.
4. Keep the existing frontend model: route/session selection still works as today; sendMessageAsync() keeps passing sessionId.

This preserves the current UI while making the server guarantee correctness.

Required changes

Pi core

Expose a safe session-switch capability to extension event contexts, or a narrowly-scoped equivalent that can be used by long-lived extension services.

Preferred API shape:

interface ExtensionContext {
  switchSession(
    sessionPath: string,
    options?: { withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
  ): Promise<{ cancelled: boolean }>
}

Implementation should reuse the existing switchSessionHandler already used by createCommandContext(). The important behavior is not a new session implementation; it is making the already-existing runtime switch available to the PiAgentUI HTTP server context.

PiAgentUI extension server

Add helpers in extensions/piagentui-server.ts:

• getSessionFileForId(sessionId) scans latestCtx.sessionManager.getSessionDir() for *_${sessionId}.jsonl.
• sendUserMessageToSession(parsed) validates sessionId, resolves the session file, switches if needed, and sends in the correct context.
• session_shutdown handling must not tear down the HTTP server on reason === 'resume' if the server is intentionally switching sessions for the web UI. The server should keep the port stable and update latestCtx on the following session_start.

Target send flow:

if (requestedSessionId && requestedSessionId !== activeSessionId) {
  const sessionFile = getSessionFileForId(requestedSessionId)
  const result = await latestCtx.switchSession(sessionFile, {
    withSession: async replacedCtx => {
      await maybeSetModel(replacedCtx, parsed.model)
      await replacedCtx.sendUserMessage(parsed.text)
    },
  })
  if (result.cancelled) return HTTP 409
  return HTTP 202
}

await maybeSetModel(latestCtx, parsed.model)
pi.sendUserMessage(parsed.text)

If sessionId is missing or already active, keep the existing path.

Frontend

Keep frontend mostly unchanged.

Small additions only if needed:

• sendMessageAsync() continues sending sessionId.
• Optional: handle HTTP 409/404 with a clear toast if target session cannot be activated.
• Optional: add activeSessionId from server.connected/session.status later, but not required for the core fix.

Alternatives considered

Activate on session selection

Frontend would call /api/sessions/:id/activate when a user clicks a session. This matches the user's mental model, but it introduces a race: if the user sends before activation completes, the message can still hit the old session unless send also validates activation. It is useful as a UX enhancement after backend routing is correct, not as the primary correctness mechanism.

Frontend guard only

Frontend could block sending if selected session differs from active Pi session. This avoids Pi core changes but makes UX worse and still requires a trustworthy active-session signal from the backend. It detects the problem instead of solving it.

Tests

Extension/unit tests

Add or update extension server tests to cover:

1. Sending with active sessionId calls pi.sendUserMessage() without switching.
2. Sending with different sessionId resolves the matching JSONL file and calls ctx.switchSession(sessionFile, { withSession }).
3. The withSession callback calls replacedCtx.sendUserMessage(text).
4. Unknown sessionId returns 404 and does not send to the active session.
5. Cancelled switch returns 409 and does not send.
6. session_shutdown with reason: 'resume' does not close the web server during web-initiated session switching.

Frontend tests

Add or update API/hook tests to cover:

1. sendMessageAsync() includes sessionId in the payload.
2. Send error responses surface through the existing error handling path.
3. Existing route/session selection behavior remains unchanged.

Manual verification

1. Start Pi in session A.
2. Open PiAgentUI.
3. Select existing session B in the sidebar.
4. Send a message.
5. Verify new user and assistant messages appear in session B.
6. Verify session A JSONL is unchanged.
7. Verify /global/event remains connected and streaming works without F5.

Risks and mitigations

• Switching sessions invalidates old extension contexts. Mitigation: send inside withSession(replacedCtx) and avoid captured stale pi/ctx after switch.
• Current extension closes the HTTP server on session_shutdown. Mitigation: preserve server across resume switches and update latestCtx on session_start.
• Pi core API change can be too broad. Mitigation: expose only the existing switch handler; do not create parallel session logic.
• Session file lookup by suffix must be strict. Mitigation: only match _${sessionId}.jsonl inside the current session dir.

Acceptance criteria

• Sending from selected session B never writes to active-at-launch session A.
• Frontend routing and message loading stay visually the same.
• The web server port remains stable during a session switch initiated by PiAgentUI.
• Streaming still updates live after switch.
• Typecheck, extension typecheck, relevant tests, and build pass.