AGENTS.md · abcwyc/pi-agent-desktop

Sections

1. Quick Start
2. Local environment traps
3. Architecture
4. File Map
5. Topic Notes
6. Pi Session File Format
7. Styling: fork CSS lives only in app/native-theme.css
8. CSS Variables (app/globals.css, re-tokened in app/native-theme.css)

First lines (shown under the repo's MIT license)

# Pi Web - Development Notes

## Quick Start

```bash
npm run dev   # port 30141
```

Typecheck: `node_modules/.bin/tsc --noEmit` · Lint: `npm run lint`

**Never run `next build` during dev**: it pollutes `.next/` and breaks `npm run dev`.

---

## Local environment traps

- **Building (or starting a fresh `next dev`) from inside the Pi desktop app's shell
  fails.** The app exports `NODE_ENV=production`, `__NEXT_PRIVATE_ORIGIN` and
  `__NEXT_PRIVATE_STANDALONE_CONFIG` (its own serialized Next config, from which function
  values are gone). Next's CLI prefers that serialized config over `next.config.ts`, so
  `next build` dies with `TypeError: generate is not a function` and a fresh `next dev`
  with `Missing field turbopackMemoryEviction` — while a dev server that was already
  running keeps working, which makes it look like a repo bug. `scripts/prepare-desktop.mjs`
  deletes both `__NEXT_PRIVATE_*` vars for this exact reason; do the same (or run from a
  normal terminal) before any `next build` / `npm run test:e2e`.
- The `node` on `PATH` may not be the one the project runs on: the Pi app bundles its own
  runtime, while a dev server started from a terminal uses another install. Check with
  `ps -o command= -p $(lsof -nP -iTCP:30141 -sTCP:LISTEN -t)`.
- `npm run test:e2e` refuses to start while a dev server holds `.next/dev/lock`, and
  `E2E_SERVER_MODE=start` (the mode CI uses) needs a production build. Both can be
  satisfied without touching the dev state by building into the isolated desktop dir and
  pointing the harness at it:
  `PI_WEB_DESKTOP_BUILD=1 node_modules/next/dist/bin/next build --webpack` then
  `E2E_SERVER_MODE=start PI_WEB_DESKTOP_BUILD=1 node e2e/run.mjs` (`next.config.ts` swaps
  `distDir` to `.next-desktop`, which is gitignored).
- A worktree's `node_modules` can lag the lockfile (created before an SDK bump), which
  fails tests that pin newer SDK behaviour. `npm test` runs `npm run check:deps` first and
  stops with the mismatched packages; `npm ci` fixes it.
- Windows test fixtures use `scripts/test-platform.mjs`: directory links are junctions,
  unavailable file links skip only their own subtests, and POSIX mode checks remain
  active on POSIX hosts. Shell-command fixtures select native Git Bash inside the
  test process; trust fixtures must not inherit the user's ancestor skills. Await
  session shutdown before deleting MCP working directories. Real PTY integration
  runs in a child process; fake-clock tests use a controlled PTY.
- **`next dev` rewrites `AGENTS.md`**: it appends a "This is NOT the Next.js you know" block
  to this file on every start. Preserve the project and user instructions here; review generated
  additions separately and never reset the entire file to discard development output.

---

## Architecture

- **Browsing** (read-only, no AgentSession): `GET /api/sessions` lists `~/.pi/agent/sessions/`; `GET /api/sessions/[id]` reads the `.jsonl` through SDK `SessionManager` helpers and `lib/session-reader.ts`, or an open wrapper's in-memory `SessionManager`. `GET /api/agent/running` snapshots the running ids.
- **Sending**: `POST /api/agent/[id]` → `startRpcSession()` (`lib/rpc-manager.ts`) creates the AgentSession in-process (`createAgentSessionFromServices()`); `session.send(cmd)` → `session.prompt()`.
- **Events**: `GET /api/agent/[id]/events` streams SSE `data: {...}` from `session.onEvent()`, fed by `session.subscribe()`.

---

## File Map

```
app/api/
  sessions/route.ts               GET  list all sessions
  sessions/[id]/route.ts          GET/PATCH/DELETE session
  sessions/[id]/context/route.ts  GET ?leafId= — context for a specific leaf
  sessions/[id]/export/route.ts   GET exported HTML for a session
  agent/new/route.ts              POST { cwd, message, toolNames?, provider?, modelId? }
  agent/[id]/route.ts             GET state | POST any command
  agent/[id]/events/route.ts      GET SSE stream
  agent/running/route.ts          GET currently-running session ids
  agent/running/events/route.ts   GET SSE stream of currently-running session ids
  auth/all-providers/route.ts     GET API-key provider list
  auth/api-key/[provider]/route.ts GET/POST/DELETE provider API key status/storage
  auth/login/[provider]/route.ts  GET OAuth/device-code SSE | POST manual code
  auth/logout/[provider]/route.ts POST OAuth logout
  auth/providers/route.ts         GET OAuth provider list
  cwd/validate/route.ts           POST validate/select a cwd
  default-cwd/route.ts            POST create ~/pi-cwd-YYYYMMDD
  files/[...path]/route.ts        GET file contents for viewer
  home/route.ts                   GET user home directory
  models/route.ts                 GET { models, modelList, defaultModel }
  models/enabled/route.ts         GET/PUT enabledModels switches for the Models panel
  models/refresh/route.ts         POST fetch provider catalogs from pi.dev on demand
  models/nonchat/route.ts         GET classifier + image models (with sign-in state) and the global Code mode choice
  models-config/route.ts          GET/PUT — read/write ~/.pi/agent/models.json
  models-config/catalog/route.ts  GET models.dev pricing presets
  models-config/discover/route.ts POST fetch a configured provider's upstream model list
  models-config/test/route.ts     POST test a configured model/provider
  plugins/route.ts                GET/POST package plugin management
  skills/route.ts                 GET/PATCH loaded skills and disable-model-invocation
  skills/install/route.ts         POST install skills through npx skills add
  skills/search/route.ts          GET/POST skills.sh search
  scheduled-tasks/**              GET/POST tasks, PATCH/DELETE [id], POST [id]/run, GET [id]/runs, POST run seen, POST preview, GET events (SSE)
  worktrees/route.ts              GET list / POST create / PUT switch branch / DELETE git worktrees
  worktrees/fetch/route.ts        POST git fetch --prune + fresh branch lists
  desktop/read-images/route.ts    POST read natively-picked images into attachment payloads
  desktop/save/route.ts           POST copy a file to, or write bytes at, a natively-picked path
  artifacts/settings/route.ts     GET/PUT the "artifacts in the side panel" prompt switch

lib/
  agent-client.ts      typed fetch helper for /api/agent commands
  artifacts.ts         `:::artifact` scanner, markdown encoding, version collection
  artifact-store.ts    client store shared by ChatWindow, message cards and the artifact panel
  artifact-settings.ts / artifact-guide-extension.ts  prompt switch file + `<artifacts>` prompt section
  html-preview.ts      inline HTML/SVG/React preview detection, sandbox, srcdoc bootstrap, React document
  preview-runtime.ts   loads public/preview-runtime/ (bundled React, Sucrase, Tailwind) for React previews
  app-prefs.ts         APP_PREF_KEYS + typed localStorage accessors (SSR/private-mode safe)
  desktop-connection.ts useDesktopConnection() — local server health probe for the reconnect banner
  desktop-native.ts    native dialogs, open/reveal path, external links, save/import, window lifecycle
  desktop-notify.ts    native completion notifications (skipped while the window is focused)
  draft-store.ts       local draft persistence helpers
  file-access.ts       allowed file roots for /api/files and worktrees
  file-paths.ts        client/server path encoding helpers
  enabled-models.ts    pure minimal-edit engine for the `enabledModels` pattern list
  enabled-models-runtime.ts  SDK adapter: per-pattern resolution, provider kinds, settings IO
  markdown.ts          shared markdown helpers
  npx.ts               npx runner used by skill install
  pi-types.ts          local structural types for pi SDK objects
  rpc-manager.ts      AgentSessionWrapper + registry + startRpcSession
  scheduled-tasks/    scheduler, runner, cron, store, run index for scheduled tasks (see docs/agents/scheduled-tasks.md)
  session-reader.ts   SessionManager wrappers + path cache + buildSessionContext adapter
  tool-presets.ts     PRESET_NONE/DEFAULT/FULL + getPresetFromTools()
  types.ts            shared TypeScript types
  normalize.ts        normalizeToolCalls() — field name mismatch between file format and our types
  workspace-state.ts  persisted session/cwd/file-tab restore for desktop cold starts
  worktree.ts         project/worktree resolution and git worktree operations

components/
  AppShell.tsx        layout + URL state + tab management
  SessionSidebar.tsx  session tree + FileExplorer
  ChatWindow.tsx      chat composition + completion sound wrapper
  ChatInput.tsx       input bar + model/thinking/tools/compact controls
  MessageView.tsx     renders one message (user/assistant/toolCall/toolResult)
  BranchNavigator.tsx in-session branch switcher
  MarkdownBody.tsx    markdown renderer
  HtmlPreviewBlock.tsx / HtmlPreviewErrorBar.tsx  inline previews and their error strip
  ArtifactCard.tsx / ArtifactPanel.tsx / artifact-tabs.ts  artifact card in messages, right-panel tab
  ModelsConfig.tsx    modal for editing models.json (opened from sidebar bottom)
  EnabledModelsSection.tsx  model switches inside ModelsConfig, backed by enabledModels
  AgentsConfig.tsx    built-in subagent toggle + agent profile editor
  PluginsConfig.tsx   modal for installed package plugins
  SkillsConfig.tsx    modal for loaded/search/installable skills
  scheduled/          Scheduled page (list, detail, editor, run history) and its sidebar row
  SettingsPanel.tsx   settings dialog; its General tab hosts the app intro, Version & Updates and the desktop-only switches
  AppUpdatesSection.tsx  Version & Updates block at the top of General
  desktop/DesktopAppSection.tsx  window/tray prefs; renders nothing outside Tauri
  FileExplorer.tsx    file tree inside sidebar
  FileIcons.tsx       file icon helpers
  FileViewer.tsx      file content in a tab
  TabBar.tsx          tab bar (Chat + open file tabs)

hooks/
  useAgentSession.ts       messages, streaming, SSE, fork/navigate, reconciliation; built-in slash commands (/session, bare /mcp)
  useAudio.ts              completion sound + AudioContext unlock
  useDragDrop.ts           shared drag/drop state
  useIsMobile.ts           responsive breakpoint
  useScheduledTasks.ts     shared store + SSE for scheduled tasks
  useKeyboardShortcuts.ts  Esc stops the running agent unless a field or nearer handler took it; Ctrl+Alt+N
  useTheme.ts              theme state
```