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

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.

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.