# Spec: Tauri Pi Agent Integrated App

## Objective

Build PiAgentUI into a faster desktop-first Tauri app where creating a new agent session is near-instant from the user's perspective while Pi remains the authoritative runtime. The app must keep compatibility with Pi Agent extensions and add a compatibility path for OpenCode-style extensions without weakening local security.

Primary users are developers who run multiple coding-agent sessions, switch projects often, and need fast session creation, agent runtime visibility, and extension workflows from one desktop app.

## Assumptions

- Existing `PiAgentUi/` is the active app: React 19, Vite 8, TypeScript, Tauri 2.
- Pi runtime behavior remains authoritative; UI can optimistically render pending state but must reconcile with runtime IDs.
- Pi extension compatibility means preserving package `pi.extensions` discovery and current `extensions/piagentui-server.ts` behavior.
- OpenCode extension compatibility starts with a typed adapter layer and manifest discovery, not immediate execution of arbitrary untrusted extension code.
- No dependency or lockfile changes without explicit approval.

## Tech Stack

- Frontend: React 19, TypeScript 5.9, Tailwind CSS v4, Vite 8.
- Desktop: Tauri 2.
- Local backend: Pi extension server in `extensions/piagentui-server.ts`.
- Tests: Vitest and Testing Library.
- Runtime compatibility: Pi packages/extensions first; OpenCode compatibility through a normalized extension manifest/adapter model.

## Commands

- Dev: `npm run dev`
- Desktop dev: `npm run tauri dev`
- Targeted test: `npx vitest run <path>`
- Full app check: `npm run check`
- Typecheck: `npm run typecheck && npm run typecheck:extensions`

## Project Structure

- `src/features/sessions/` — fast session launch UX, optimistic session draft helpers, session route behavior.
- `src/store/` — session list/message state reconciliation.
- `src/api/` — typed client methods to call local PiAgentUI endpoints.
- `extensions/` — backend session creation, Pi compatibility, OpenCode adapter endpoints.
- `src-tauri/` — desktop shell, permissions, Tauri config.
- `docs/superpowers/specs/` — specs.
- `docs/superpowers/plans/` — implementation plans.

## Code Style

Use focused TypeScript modules with explicit types and testable pure helpers.

```ts
export interface OptimisticSessionDraftInput {
  directory?: string
  title?: string
  parentID?: string
  id?: string
  now?: number
}

export function createOptimisticSessionDraft(input: OptimisticSessionDraftInput): ApiSession {
  // Pure, deterministic when id and now are injected by tests.
}
```

## Testing Strategy

- TDD for every new behavior.
- Pure session/extension helpers get small Vitest unit tests.
- React integration changes get Testing Library tests.
- Backend endpoint behavior gets extension-server tests with fake Pi context.
- Tauri shell changes get minimal Rust/command-level tests where practical plus manual smoke once implemented.

## Boundaries

- Always: keep Pi runtime authoritative; add tests before behavior; avoid lockfile changes; keep secrets backend-only.
- Ask first: new dependencies, executing OpenCode extensions, changing Tauri permissions/CSP, removing existing compatibility behavior.
- Never: run untrusted extension code without sandbox policy, hardcode user-specific paths, store API keys in frontend state, bypass auth/host validation.

## Success Criteria

- New session action gives immediate visual feedback and navigates without a blank/grey wait state.
- Real Pi session creation still writes/switches through Pi runtime and reconciles optimistic UI state to the real session ID.
- Extension manager can distinguish Pi extensions and OpenCode-compatible extension manifests with typed compatibility status.
- Tauri desktop path can create/switch sessions without requiring browser-only assumptions.
- Existing tests pass for touched modules; new behavior has tests.

## Risks and Mitigations

- Session ID mismatch between optimistic UI and Pi runtime: store pending sessions under a prefixed temporary ID and atomically replace on success.
- Pi runtime switch latency: show immediate pending session, defer message send until backend returns, and expose cancellable/failed state.
- Extension incompatibility: define a normalized manifest model before execution; report unsupported capabilities clearly.
- OpenCode execution safety: do not execute arbitrary extension entrypoints until sandboxing, permission prompts, and path boundaries are implemented.
- Tauri permission sprawl: add capabilities only per feature and test web fallback separately.
- Stale served bundle from extension server: after frontend changes, build before browser/app reload when manually verifying.
- Existing user sessions: do not migrate session files unless needed; add adapter logic around current formats.
- Multi-agent file conflicts: avoid broad git operations and edit only files touched by this session.

## Open Questions

- Exact OpenCode extension manifest sources and execution semantics need confirmation before execution support.
- Visual direction is not finalized because `.impeccable.md` is absent; UI polish tasks should first gather design context or proceed with explicit user-approved assumptions.