Evandro
98b5db029f
Origem: D:/Documents/Github/PiAgentUI/PiAgentUi Arquivos omitidos (segredos, bancos de dados, logs, >50 MB): 4
98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# 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.
|