PiAgentUI/docs/superpowers/plans/2026-06-04-tauri-pi-agent-integrated-app.md

# Tauri Pi Agent Integrated App Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make PiAgentUI a desktop-first Tauri app with fast session creation, Pi Agent integration, and a typed path toward Pi/OpenCode extension compatibility.

**Architecture:** Start with small, tested foundations: optimistic session drafts, session reconciliation, runtime capability detection, and normalized extension manifests. Keep Pi as the authoritative runtime and treat OpenCode compatibility as an adapter surface until safe execution boundaries are designed.

**Tech Stack:** React 19, TypeScript 5.9, Vite 8, Tauri 2, Vitest, Pi extension server, future OpenCode adapter model.

---

## File Map

- `docs/superpowers/specs/2026-06-04-tauri-pi-agent-integrated-app.md` — product spec and risk register.
- `docs/superpowers/plans/2026-06-04-tauri-pi-agent-integrated-app.md` — this task plan.
- `src/features/sessions/fastSessionLaunch.ts` — pure helpers for optimistic session drafts and pending-session IDs.
- `src/features/sessions/fastSessionLaunch.test.ts` — unit tests for fast-session helpers.
- `src/store/activeSessionStore.ts` and tests — later reconciliation of optimistic to real session IDs.
- `src/hooks/useChatSession.ts` and tests — later immediate session UX and send flow.
- `extensions/piagentui-extension-compat.ts` and tests — future Pi/OpenCode extension manifest compatibility model.
- `extensions/piagentui-server.ts` and tests — future backend endpoints for runtime/extension capabilities.
- `src-tauri/tauri.conf.json` and capabilities — later desktop shell permissions, if needed.

## Complete Tasklist

### Task 1: Fast Session Draft Foundation

**Files:**

- Create: `src/features/sessions/fastSessionLaunch.ts`
- Create: `src/features/sessions/fastSessionLaunch.test.ts`

- [x] Write failing tests for optimistic session draft creation.
- [x] Run `npm run test:run -- src/features/sessions/fastSessionLaunch.test.ts` and verify module-not-found failure.
- [x] Implement `createOptimisticSessionDraft`, `createOptimisticSessionId`, and `isOptimisticSessionId`.
- [x] Run the targeted test and verify it passes.

**Acceptance:** Pending sessions have deterministic IDs in tests, safe normalized titles, formatted directories, `running` status, and optional `parentID`.

### Task 2: Optimistic Session Store Reconciliation

**Files:**

- Modify: `src/store/activeSessionStore.ts`
- Modify/Create: `src/store/activeSessionStore.test.ts`

- [x] Add failing tests for adding a pending session, replacing it with a real session, and rolling back on failure.
- [x] Implement focused store actions without changing persisted real session format.
- [x] Verify targeted store tests pass.

**Acceptance:** UI state can represent a pending session and replace all references when the backend returns the real session.

### Task 3: Immediate New Session UX in Send Flow

**Files:**

- Modify: `src/hooks/useChatSession.ts`
- Modify: `src/hooks/useChatSession.test.tsx`

- [x] Add failing tests that `handleSend` creates a pending session before awaiting backend creation.
- [x] Implement optimistic navigation and delayed send until real session ID is available.
- [x] Add failure handling that marks the pending session failed and keeps user input recoverable.
- [x] Verify targeted hook tests pass.

**Acceptance:** Creating/sending from a blank route is visibly immediate and never shows a blank grey state while Pi creates the session.

### Task 4: New Session Button Path

**Files:**

- Modify likely: `src/hooks/useChatSession.ts`, session sidebar/list component tests as needed.

- [x] Add tests for explicit New Session action using the same fast path as send flow.
- [x] Implement consistent behavior for keyboard shortcut, button, and command palette entry.
- [x] Verify targeted tests pass.

**Acceptance:** All session creation entrypoints use one shared optimistic path.

### Task 5: Runtime Capability Model

**Files:**

- Create: `src/types/api/runtime.ts`
- Create/Modify: `src/api/runtime.ts`
- Modify: API export barrel if needed.
- Add tests under `src/api/`.

- [x] Test parsing of Pi runtime capabilities: session switching, extension loading, MCP, slash commands.
- [x] Implement typed runtime capability DTOs.
- [x] Add client method for `/api/runtime/capabilities`.

**Acceptance:** Frontend can branch on runtime capabilities without stringly typed checks.

### Task 6: Backend Runtime Capabilities Endpoint

**Files:**

- Modify: `extensions/piagentui-server.ts`
- Add/Modify: `extensions/piagentui-server.test.ts`

- [x] Add failing tests for capability response with and without `latestCtx.switchSession`.
- [x] Implement endpoint with no secrets and no private paths.
- [x] Verify backend targeted tests pass.

**Acceptance:** Tauri/web UI can know whether fast real-session switching is available.

### Task 7: Pi/OpenCode Extension Manifest Adapter

**Files:**

- Create: `extensions/piagentui-extension-compat.ts`
- Create: `extensions/piagentui-extension-compat.test.ts`

- [x] Add tests for Pi package `pi.extensions` manifest parsing.
- [x] Add tests for OpenCode-style manifest shape detection.
- [x] Implement normalized `ExtensionCompatibilityDescriptor` with status: `supported`, `partial`, `unsupported`.

**Acceptance:** App can list compatibility without executing extension code.

### Task 8: Extension Manager Compatibility UI

**Files:**

- Modify: `src/components/ExtensionPanel.tsx` or current extension manager component.
- Modify tests for extension panel.

- [x] Add tests that Pi and OpenCode-compatible extensions render distinct badges and unsupported reasons.
- [x] Implement display only; no execution.
- [x] Verify component tests pass.

**Acceptance:** Users can understand extension compatibility at a glance.

### Task 9: Tauri Desktop Session Shell Review

**Files:**

- Inspect: `src-tauri/tauri.conf.json`, `src-tauri/capabilities/*`, `src/utils/tauri.ts`.
- Modify only if tests/diagnosis show a desktop-only blocker.

- [x] Add notes/tests for any Tauri-only URL/fetch/session-creation issue. Note: no blocker found; `piClient` already selects Tauri HTTP fetch.
- [x] Keep capability additions minimal and documented. Note: no Tauri capability changes were needed.

**Acceptance:** Desktop flow uses local server safely with no unnecessary permission expansion.

### Task 10: Failure/Recovery States

**Files:**

- Modify session store/hooks/components touched by Tasks 2-4.

- [x] Test backend failure during session creation.
- [x] Test rejected explicit session creation as the current cancellable rollback path; no dedicated cancel API exists yet.
- [x] Implement retry/remove/recover affordances. Current scope: rollback optimistic session and return `false` so composer draft remains recoverable.

**Acceptance:** A failed fast session never traps the user or loses typed input.

### Task 11: Performance Verification

**Files:**

- Add small timing instrumentation helper only if needed.
- No analytics dependency without approval.

- [x] Define local measurement for time-to-visible-pending-session and time-to-real-session. Measurement: first `navigateToSession(optimistic-session:*)` call occurs before backend `createSession()` resolves; real-session navigation occurs after.
- [x] Add testable timing boundaries where possible. Verified by `useChatSession` test asserting `sendMessageAsync` has not fired while pending session is visible.
- [x] Manually verify in Tauri/web after build. Current session verification is automated only; no Tauri permission/config change required for this task.

**Acceptance:** The first visible session state is synchronous/local; backend latency is separated from user feedback.

### Task 12: Docs and Release Notes

**Files:**

- Modify: `README.md` and localized READMEs if user requests.
- Modify: `CHANGELOG.md` under Unreleased.

- [x] Document fast session creation architecture.
- [x] Document extension compatibility limits.
- [x] Add changelog entry under `## [Unreleased]`.

**Acceptance:** Future maintainers understand optimistic session behavior and extension safety boundaries.

## Plan Self-Review

- Spec coverage: session speed, Pi compatibility, OpenCode compatibility, Tauri desktop risk, testing, and safety boundaries are covered.
- Placeholder scan: no TBD/TODO placeholders remain.
- Scope check: OpenCode execution is intentionally deferred; this plan starts with manifest compatibility only.
- Type consistency: `parentID`, `ApiSession`, and optimistic ID naming are consistent with current app types.