Add Side Quest conversations

Author: gatsby74

docs/reference/plans/2026-07-11-side-quests.md

@@ -0,0 +1,103 @@
+# Side Quests: viability and delivery plan
+
+## Outcome
+
+Side Quests are viable on Orca's existing terminal-group and native-chat foundations. The delivered
+vertical slice opens a durable provider-owned Codex conversation beside the source terminal,
+optionally carries selected terminal output into the native composer as quoted context, and leaves
+the original process running and interactive.
+
+Local Codex Side Quests use one warm `codex app-server` process and do not create a hidden PTY.
+Claude and SSH worktrees retain the read-only terminal-backed compatibility path. Runtime-owned web,
+paired, and headless worktrees need a host API improvement before they can bind context safely.
+
+## User flow
+
+1. Select terminal output and choose **Add Selection to Side Quest** from the floating action, or
+   right-click the terminal and choose the same action.
+2. To start without context, right-click and choose **New Side Quest**.
+3. Orca creates a split to the right and starts a durable, read-only Codex provider thread for local
+   worktrees. Compatibility environments launch the matching/default terminal agent.
+4. The new pane opens directly in native chat and is labeled **Side Quest**.
+5. Selected output appears as a removable quote card. The user adds a question and sends both as one
+   bounded prompt with an explicit untrusted-context boundary.
+6. The original terminal continues without receiving input, focus, or an interrupt.
+
+## Architecture
+
+| Concern | Existing Orca primitive | Side Quest behavior |
+| --- | --- | --- |
+| Side-by-side layout | terminal split groups | create an empty right split beside the source group |
+| Independent agent | Codex app-server manager | reuse one warm process and create a provider-owned thread per Side Quest |
+| Agent choice | detected leaf, launched tab, default-agent settings | prefer the detected source agent, then launch metadata, then default |
+| Chat surface | experimental native chat | force the created unified terminal tab to chat mode |
+| Context | bounded session transcript cleaner | strip terminal control data and cap context at the existing transcript budget |
+| Prompt safety | native chat send path | fence output as untrusted quoted text and append the user's question |
+| Pending handoff | bounded renderer cache keyed by terminal tab ID | seed before chat's first render and clear after send/removal |
+| Durability | terminal-tab workspace state | persist only the Side Quest/provider thread reference; the provider owns messages |
+| Live updates | preload IPC subscription | stream agent deltas, completed items, turn completion, errors, and interrupts |
+
+Codex app-server threads use `sandbox: read-only` and `approvalPolicy: never`. Inherited MCP servers
+and apps are disabled for these research conversations, avoiding both unwanted capabilities and the
+startup delay that motivated the direct provider transport. Claude launches with
+`--permission-mode plan` on the compatibility path. Terminal fallbacks intentionally bypass
+configured command overrides because an override can embed unrestricted flags that would defeat
+the shared-worktree guarantee.
+
+## Platform viability
+
+| Environment | Status | Notes |
+| --- | --- | --- |
+| macOS, Linux, Windows local worktrees | Supported | cross-platform process spawning plus the existing split/chat UI |
+| WSL worktrees | Supported by provider manager | converts renderer UNC paths to the selected distro's Linux path |
+| Ordinary SSH worktrees | Compatibility path | existing terminal launch routing keeps process creation on the SSH target |
+| Runtime-owned web/paired/headless worktrees | Blocked on host API | renderer receives no created tab ID, so context cannot be bound to a specific chat safely |
+
+The runtime fix should make host terminal creation awaitable and return the created terminal and
+unified-tab identities. The same transaction should accept the target group, initial view mode,
+label, and pending Side Quest context. Until then the UI reports this limitation and avoids creating
+an orphan local split.
+
+Local provider creation is asynchronous after tab allocation, so the composer remains draftable
+while the provider thread starts. The vertical slice rolls back tab-registration and split-creation
+failures, surfaces provider startup errors inline, and treats an app-server thread as an empty
+conversation until its first user turn materializes it.
+
+## Delivery phases
+
+### Phase 1 — vertical slice
+
+- Selection floating action and terminal context-menu entry.
+- No-selection context-menu entry.
+- Right split, independent read-only provider thread, native chat mode, and Side Quest label.
+- Bounded removable quote card and safe first-question composition.
+- Unit coverage for agent choice, launch rollback, context fencing, composer handoff, and UI actions.
+
+### Phase 2 — durable product model (partially delivered)
+
+- Persist a `sideQuest` provider-thread reference rather than relying on terminal labels.
+- Reuse one warm Codex app-server and resume durable threads after process/app restart.
+- Persist unsent quoted context across app restarts.
+- Add Side Quest history, rename, close/archive, and source-conversation metadata.
+- Add `@side-quest` mention/search so a main conversation can import a bounded summary or selected
+  messages without coupling the two live sessions.
+
+### Phase 3 — runtime parity and polish
+
+- Extend the runtime host create-tab API and enable web/paired/headless worktrees.
+- Add an awaited agent-readiness result so late local/SSH startup failures can close the tab and
+  collapse its split automatically.
+- Add keyboard access and command-palette launch.
+- Add telemetry for launch, first question, context removal, and return-to-main-thread behavior.
+- Run interaction QA on macOS, Linux, Windows, local SSH, and high-latency SSH.
+
+## Acceptance criteria
+
+- Launching never writes to or interrupts the source terminal.
+- The Side Quest agent runs in the same worktree and execution environment as the source.
+- The created surface is native chat, not the TUI, when experimental native chat is enabled.
+- Selected output is visibly quoted, removable, bounded, cleaned of terminal escape data, and treated
+  as untrusted input.
+- Slash commands remain valid and do not accidentally consume pending quote context.
+- A failed launch collapses the empty split and shows a user-facing error.
+- Platform-specific behavior stays behind existing runtime checks.

src/main/ipc/register-core-handlers.test.ts

@@ -59,6 +59,7 @@ const {
   registerWorkspacePortHandlersMock,
   registerLocalhostWorktreeLabelHandlersMock,
   registerNativeChatHandlersMock,
+  registerSideQuestHandlersMock,
   registerEmulatorFrameStreamHandlersMock,
   registerEmulatorVideoStreamHandlersMock
 } = vi.hoisted(() => ({
@@ -120,16 +121,22 @@ const {
   registerWorkspacePortHandlersMock: vi.fn(),
   registerLocalhostWorktreeLabelHandlersMock: vi.fn(),
   registerNativeChatHandlersMock: vi.fn(),
+  registerSideQuestHandlersMock: vi.fn(() => vi.fn()),
   registerEmulatorFrameStreamHandlersMock: vi.fn(),
   registerEmulatorVideoStreamHandlersMock: vi.fn()
 }))
 
 vi.mock('electron', () => ({
   app: {
-    getPath: getPathMock
+    getPath: getPathMock,
+    once: vi.fn()
   }
 }))
 
+vi.mock('./side-quest', () => ({
+  registerSideQuestHandlers: registerSideQuestHandlersMock
+}))
+
 vi.mock('../../shared/runtime-environment-store', () => ({
   listEnvironments: listEnvironmentsMock
 }))
@@ -416,6 +423,8 @@ describe('registerCoreHandlers', () => {
     registerWorkspacePortHandlersMock.mockReset()
     registerLocalhostWorktreeLabelHandlersMock.mockReset()
     registerNativeChatHandlersMock.mockReset()
+    registerSideQuestHandlersMock.mockReset()
+    registerSideQuestHandlersMock.mockReturnValue(vi.fn())
     registerEmulatorFrameStreamHandlersMock.mockReset()
     registerEmulatorVideoStreamHandlersMock.mockReset()
   })
@@ -468,6 +477,7 @@ describe('registerCoreHandlers', () => {
     expect(registerCodexAccountHandlersMock).toHaveBeenCalledWith(codexAccounts)
     expect(registerAgentHookHandlersMock).toHaveBeenCalledWith(runtime)
     expect(registerPetHandlersMock).toHaveBeenCalled()
+    expect(registerSideQuestHandlersMock).toHaveBeenCalled()
     expect(registerClaudeAccountHandlersMock).toHaveBeenCalledWith(claudeAccounts)
     expect(registerMiniMaxCredentialsHandlersMock).toHaveBeenCalledWith(rateLimits)
     expect(registerGrokAccountHandlersMock).toHaveBeenCalled()

src/main/ipc/register-core-handlers.ts

@@ -27,6 +27,7 @@ import { registerRuntimeEnvironmentHandlers } from './runtime-environments'
 import { registerEphemeralVmHandlers } from './ephemeral-vm'
 import { registerAiVaultHandlers } from './ai-vault'
 import { registerNativeChatHandlers } from './native-chat'
+import { registerSideQuestHandlers } from './side-quest'
 import { registerNotificationHandlers } from './notifications'
 import { registerNotebookHandlers } from './notebook'
 import { registerOnboardingHandlers } from './onboarding'
@@ -189,6 +190,10 @@ export function registerCoreHandlers(
       scanRuntimeAiVaultSessions(app.getPath('userData'), environmentId, args, options)
   })
   registerNativeChatHandlers()
+  const disposeSideQuests = registerSideQuestHandlers()
+  // Why: the warm provider process is app-scoped rather than tab-scoped, so
+  // closing one Side Quest must not stop it; app shutdown is its owner boundary.
+  app.once('before-quit', disposeSideQuests)
   registerClipboardHandlers(store)
   registerUpdaterHandlers(store)
   registerSpeechHandlers(store)

src/main/ipc/side-quest.ts

@@ -0,0 +1,181 @@
+import { ipcMain, type IpcMainEvent, type WebContents } from 'electron'
+import type {
+  SideQuestCreateArgs,
+  SideQuestCreateResult,
+  SideQuestInterruptArgs,
+  SideQuestReadArgs,
+  SideQuestReadResult,
+  SideQuestSendArgs,
+  SideQuestSendResult,
+  SideQuestStreamEvent,
+  SideQuestStreamPayload,
+  SideQuestSubscribeArgs
+} from '../../shared/side-quest-runtime-types'
+import {
+  CodexSideQuestManager,
+  type CodexSideQuestManagerOptions
+} from '../side-quest/codex-side-quest-manager'
+import {
+  codexSideQuestItemToMessage,
+  codexSideQuestThreadMessages,
+  codexSideQuestTurnError,
+  isCodexSideQuestEmptyThreadReadError
+} from '../side-quest/codex-side-quest-native-chat'
+import type { CodexAppServerEvent } from '../side-quest/codex-app-server-protocol'
+
+type SideQuestSubscription = {
+  sender: WebContents
+  subscriptionId: string
+  providerThreadId: string
+}
+
+const subscriptions = new Map<number, Map<string, SideQuestSubscription>>()
+const senderCleanupRegistered = new Set<number>()
+
+function removeSubscription(senderId: number, subscriptionId: string): void {
+  const senderSubscriptions = subscriptions.get(senderId)
+  senderSubscriptions?.delete(subscriptionId)
+  if (senderSubscriptions?.size === 0) {
+    subscriptions.delete(senderId)
+  }
+}
+
+function removeSenderSubscriptions(senderId: number): void {
+  subscriptions.delete(senderId)
+  senderCleanupRegistered.delete(senderId)
+}
+
+function subscribe(event: IpcMainEvent, args: SideQuestSubscribeArgs): void {
+  if (event.sender.isDestroyed()) {
+    return
+  }
+  if (!senderCleanupRegistered.has(event.sender.id)) {
+    senderCleanupRegistered.add(event.sender.id)
+    event.sender.once('destroyed', () => removeSenderSubscriptions(event.sender.id))
+  }
+  const senderSubscriptions = subscriptions.get(event.sender.id) ?? new Map()
+  senderSubscriptions.set(args.subscriptionId, {
+    sender: event.sender,
+    subscriptionId: args.subscriptionId,
+    providerThreadId: args.providerThreadId
+  })
+  subscriptions.set(event.sender.id, senderSubscriptions)
+}
+
+function publish(event: SideQuestStreamEvent): void {
+  for (const senderSubscriptions of subscriptions.values()) {
+    for (const subscription of senderSubscriptions.values()) {
+      if (
+        subscription.providerThreadId !== event.providerThreadId ||
+        subscription.sender.isDestroyed()
+      ) {
+        continue
+      }
+      const payload: SideQuestStreamPayload = {
+        subscriptionId: subscription.subscriptionId,
+        event
+      }
+      subscription.sender.send('sideQuest:event', payload)
+    }
+  }
+}
+
+function publishManagerEvent(event: CodexAppServerEvent): void {
+  if (event.type === 'agent-message-delta') {
+    publish({
+      type: event.type,
+      providerThreadId: event.threadId,
+      turnId: event.turnId,
+      itemId: event.itemId,
+      delta: event.delta
+    })
+    return
+  }
+  if (event.type === 'item-completed') {
+    const message = codexSideQuestItemToMessage({
+      item: event.item,
+      turnId: event.turnId,
+      timestamp: event.completedAtMs,
+      source: 'hook'
+    })
+    if (message) {
+      publish({
+        type: 'message-completed',
+        providerThreadId: event.threadId,
+        turnId: event.turnId,
+        message
+      })
+    }
+    return
+  }
+  if (event.type === 'turn-completed') {
+    publish({
+      type: 'turn-completed',
+      providerThreadId: event.threadId,
+      turnId: event.turn.id,
+      status: event.turn.status,
+      error: codexSideQuestTurnError(event.turn)
+    })
+    return
+  }
+  if (event.threadId) {
+    publish({ type: 'error', providerThreadId: event.threadId, message: event.message })
+  }
+}
+
+export function registerSideQuestHandlers(options: CodexSideQuestManagerOptions = {}): () => void {
+  const manager = new CodexSideQuestManager(options)
+  const unsubscribeManager = manager.subscribe(publishManagerEvent)
+
+  ipcMain.handle(
+    'sideQuest:create',
+    async (_event, args: SideQuestCreateArgs): Promise<SideQuestCreateResult> => {
+      const thread = await manager.startSession({ cwd: args.cwd })
+      return { providerThreadId: thread.id }
+    }
+  )
+  ipcMain.handle(
+    'sideQuest:read',
+    async (_event, args: SideQuestReadArgs): Promise<SideQuestReadResult> => {
+      try {
+        return {
+          messages: codexSideQuestThreadMessages(await manager.readSession(args.providerThreadId))
+        }
+      } catch (error) {
+        // Why: app-server does not materialize a new durable thread until its
+        // first turn. Before then, an unavailable includeTurns view means the
+        // conversation is empty—not broken.
+        if (isCodexSideQuestEmptyThreadReadError(error)) {
+          return { messages: [] }
+        }
+        throw error
+      }
+    }
+  )
+  ipcMain.handle(
+    'sideQuest:send',
+    async (_event, args: SideQuestSendArgs): Promise<SideQuestSendResult> => {
+      const turn = await manager.startTurn({
+        threadId: args.providerThreadId,
+        text: args.text,
+        clientUserMessageId: args.clientUserMessageId,
+        effort: 'low'
+      })
+      return { turnId: turn.id }
+    }
+  )
+  ipcMain.handle('sideQuest:interrupt', async (_event, args: SideQuestInterruptArgs) => {
+    await manager.interruptTurn(args.providerThreadId, args.turnId)
+  })
+  ipcMain.on('sideQuest:subscribe', (event, args: SideQuestSubscribeArgs) => subscribe(event, args))
+  ipcMain.on('sideQuest:unsubscribe', (event, args: { subscriptionId: string }) =>
+    removeSubscription(event.sender.id, args.subscriptionId)
+  )
+
+  return () => {
+    unsubscribeManager()
+    manager.dispose()
+    subscriptions.clear()
+    senderCleanupRegistered.clear()
+  }
+}

src/main/native-chat/transcript-read-cache.ts

@@ -91,7 +91,10 @@ export async function readNativeChatTranscriptCached(
 ): Promise<ReadTranscriptResult> {
   const filePath = await resolveSessionFilePath(agent, sessionId, { transcriptPath })
   if (!filePath) {
-    return { error: `No transcript found for ${agent} session ${sessionId}` }
+    return {
+      error: `No transcript found for ${agent} session ${sessionId}`,
+      code: 'transcript_not_found'
+    }
   }
 
   const key = cacheKey(agent, filePath)

src/main/native-chat/transcript-reader.ts

@@ -9,7 +9,9 @@ import {
 } from './transcript-line-decoders'
 import { decodeTranscriptStream } from './transcript-stream-lines'
 
-export type ReadTranscriptResult = { messages: NativeChatMessage[] } | { error: string }
+export type ReadTranscriptResult =
+  | { messages: NativeChatMessage[] }
+  | { error: string; code?: 'transcript_not_found' }
 
 export type ReadTranscriptOptions = ResolveSessionFileOptions & {
   /** Resolve directly to this file, skipping path discovery (used by tests). */
@@ -30,7 +32,10 @@ export async function readNativeChatTranscript(
 ): Promise<ReadTranscriptResult> {
   const filePath = options.filePath ?? (await resolveSessionFilePath(agent, sessionId, options))
   if (!filePath) {
-    return { error: `No transcript found for ${agent} session ${sessionId}` }
+    return {
+      error: `No transcript found for ${agent} session ${sessionId}`,
+      code: 'transcript_not_found'
+    }
   }
   try {
     if (agent === 'claude') {