# Technical Documentation: getpaseo/paseo > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/getpaseo/paseo) ### Overview (`README.md`)

Paseo logo

Paseo

English · 简体中文 · 日本語 · 한국어

GitHub stars GitHub release X Discord Reddit

One interface for Claude Code, Codex, Copilot, OpenCode, Pi, Antigravity, and Muse Code agents.

Paseo app screenshot

Paseo mobile app

Paseo is an open source agentic development environment for desktop, mobile, web, and CLI. Open the desktop app and work: agents, editor, terminals, diffs, pull requests, and a browser in one window. Run many agents at once, each in its own worktree, on one machine or several. The mobile app is the full app, native on iOS and Android. - **Parallel agents:** Run many agents at once, each in its own worktree. - **Built-in orchestration:** Agents in Paseo can create worktrees, launch other agents, and talk to them, across providers. - **Complete development workflow:** Edit files, review diffs, open pull requests, and run terminals, in split panes you arrange how you want. - **Self-hosted:** Agents run on your machine with your full dev environment. Use your tools, your configs, and your skills. - **Multi-provider:** Claude Code, Codex, Copilot, OpenCode, Pi, Antigravity, and Muse Code through the same interface. Pick the right model for each job. - **Voice control:** Dictate tasks or talk through problems in voice mode. Hands-free when you need it. - **Cross-device:** iOS, Android, desktop, web, and CLI. Start work at your desk, check in from your phone, script it from the terminal. - **Privacy-first:** Paseo doesn't have any telemetry, tracking, or forced log-ins. [Run parallel tasks in Paseo](https://paseo.sh/docs/parallel-development): start agents in separate worktrees, review their diffs, run each app, and check it in the built-in browser. ## Sponsors
Hoplite
Cloud coding agents		 Become a sponsor Become a sponsor
## Plugins Plugins run on the daemon and show up in every client you connect, with the same UI on desktop, web, iOS, and Android. Write a plugin once and it is on your phone. - **UI:** screens, sidebar items, workspace panels, Command Center items, slash commands, composer pills, attachment sources, timeline items, themes. - **Agent lifecycle:** change configuration, environment, and MCP servers, answer permissions, follow up when a turn ends. - **Providers:** add a coding agent as a provider. Install from the registry with `paseo plugin add owner/slug`, or from Git or a local directory. **[Browse plugins](https://paseo.sh/plugins)** · **[Plugin docs](https://paseo.sh/docs/plugins)** Plugins run with access to your daemon machine and inside connected clients; install only code you trust. ## Getting Started Paseo runs a local server called the daemon that manages your coding agents. Clients like the desktop app, mobile app, web app, and CLI connect to it. ### Prerequisites You need at least one agent CLI installed and configured with your credentials: - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - [Codex](https://github.com/openai/codex) - [GitHub Copilot](https://github.com/features/copilot/cli/) - [OpenCode](https://github.com/anomalyco/opencode) - [Pi](https://pi.dev) - [Antigravity](https://paseo.sh/docs/supported-providers#antigravity) - [Muse Code](https://paseo.sh/docs/muse-code) ### Desktop app (recommended) Download it from [paseo.sh/download](https://paseo.sh/download) or the [GitHub releases page](https://github.com/getpaseo/paseo/releases). Open the app and the daemon starts automatically. Nothing else to install. To connect from your phone, open **Settings → your host → Pair Device**. ### Server For a server, a VM, or any machine without the desktop app. Install the CLI and start the daemon: ```bash npm install @getpaseo/cli paseo ``` Paseo starts, then asks whether to enable the end-to-end encrypted relay for device pairing. If you decline, connect directly over TCP, Tailscale, or another VPN. The desktop, mobile, and web apps connect to this daemon like any other host. For full setup and configuration, see: - [Docs](https://paseo.sh/docs) - [Connectivity guide](https://paseo.sh/docs/connectivity) - [Configuration reference](https://paseo.sh/docs/configuration) ### Docker Run the Paseo daemon and self-hosted web UI in Docker: ```bash docker run -d --name paseo \ -p 6767:6767 \ -e PASEO_PASSWORD=change-me \ -v "$PWD/paseo-home:/home/paseo" \ -v "$PWD:/workspace" \ ghcr.io/getpaseo/paseo:latest ``` Open `http://localhost:6767` after it starts. Extend the base image with the agent CLIs you use, then provide credentials through environment variables or the persistent `/home/paseo` volume. See the [Docker documentation](docs/docker.md) for full setup details. ## CLI Everything you can do in the app, you can do from the terminal. ```bash paseo run --provider claude/opus-4.6 "implement user authentication" paseo run --provider codex/gpt-5.5 --worktree feature-x "implement feature X" paseo ls # list running agents paseo attach abc123 # stream live output paseo send abc123 "also add tests" # follow-up task # run on a remote daemon; --cwd is a path on that host paseo run --host workstation.local:6767 --cwd /workspace "run the full test suite" ``` See the [full CLI reference](https://paseo.sh/docs/cli) for more. ## TypeScript SDK Build issue integrations, dashboards, and orchestration services with `@getpaseo/client`: ```ts import { createPaseoClient } from "@getpaseo/client"; const client = createPaseoClient({ url: "ws://127.0.0.1:6767/ws" }); await client.connect(); const agent = await client.agents.create({ config: { provider: "codex/gpt-5.5" }, cwd: "/Users/me/dev/storefront", prompt: "Review the current diff and name the riskiest change.", }); const result = await agent.waitForFinish(); console.log(result.lastMessage); await client.close(); ``` See the [SDK quickstart](https://paseo.sh/docs/sdk/quickstart), [recipes](https://paseo.sh/docs/sdk/recipes), and [API reference](https://paseo.sh/docs/sdk/reference). ## Skills Skills teach your agent to use Paseo to orchestrate other agents. ```bash npx skills add getpaseo/paseo ``` Then use them in any agent conversation: - `/paseo-handoff` — hand off work between agents. I use this to plan with Claude and then handoff to Codex to implement. - `/paseo-advisor` — spin up a single agent as an advisor for a second opinion, without delegating the work itself. - `/paseo-committee` — form a committee of two contrasting agents to step back, do root cause analysis, and produce a plan. ## Development Quick monorepo package map: - `packages/server`: Paseo daemon (agent process orchestration, WebSocket API, MCP server) - `packages/app`: Expo client (iOS, Android, web) - `packages/cli`: `paseo` CLI for daemon and agent workflows - `packages/desktop`: Electron desktop app - `packages/relay`: Relay transport and encryption used by the daemon and clients - `packages/website`: Marketing site and documentation (`paseo.sh`) Common commands: ```bash # run all local dev services npm run dev # run individual surfaces npm run dev:server npm run dev:app npm run dev:desktop npm run dev:website # build the server stack npm run build:server # repo-wide checks npm run typecheck ``` ## Support Paseo Paseo is an independent project used by tens of thousands of developers daily, built by one person and funded by the people who use it. Support the work on [GitHub Sponsors](https://github.com/sponsors/boudra). Companies can [sponsor Paseo](https://paseo.sh/sponsor#spot) monthly and have their logo shown at the top of this README and on the paseo.sh homepage and docs. ## Related projects - [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay) — official distributed relay, written in Elixir - [paseo-vscode](https://marketplace.visualstudio.com/items?itemName=hinnes.paseo-vscode) — VS Code extension ## License Apache-2.0 --- ### Overview (`docker/README.md`) # Paseo Docker Image This directory contains the official Paseo daemon image. The image runs the daemon headless and serves the bundled web UI from the same HTTP origin. Start it, then open the daemon URL in a browser. ```bash docker run -d --name paseo \ -p 6767:6767 \ -e PASEO_PASSWORD=change-me \ -v "$PWD/paseo-home:/home/paseo" \ -v "$PWD:/workspace" \ ghcr.io/getpaseo/paseo:latest ``` Then open `http://localhost:6767`. The base image intentionally does not bundle agent CLIs. Extend it with the agents you use: ```Dockerfile FROM ghcr.io/getpaseo/paseo:latest USER root RUN npm install @openai/codex @anthropic-ai/claude-code ``` See [docs/docker.md](../docs/docker.md) for Compose, reverse proxy, security, agent auth, and troubleshooting notes. --- ### Overview (`packages/app/README.md`) # Welcome to your Expo app 👋 This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app). ## Get started 1. Install dependencies ```bash npm install ``` 2. Start the app ```bash npx expo start ``` In the output, you'll find options to open the app in a - [development build](https://docs.expo.dev/develop/development-builds/introduction/) - [Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/) - [iOS simulator](https://docs.expo.dev/workflow/ios-simulator/) - [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction). ## Get a fresh project When you're ready, run: ```bash npm run reset-project ``` This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing. ## Learn more To learn more about developing your project with Expo, look at the following resources: - [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides). - [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web. ## Join the community Join our community of developers creating universal apps. - [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute. - [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions. ## Dictation debugging Set `EXPO_PUBLIC_ENABLE_AUDIO_DEBUG=1` before running `npx expo start` to render the in-app audio debug card. Pair it with the server-side `STT_DEBUG_AUDIO_DIR` flag so every dictation includes a copyable path to the saved raw audio file. --- ### Overview (`packages/client/README.md`) # @getpaseo/client TypeScript SDK for building integrations on top of a Paseo daemon. ```bash npm install @getpaseo/client ``` ```ts import { createPaseoClient } from "@getpaseo/client"; const client = createPaseoClient({ url: "ws://127.0.0.1:6767/ws" }); await client.connect(); const agent = await client.agents.create({ config: { provider: "codex/gpt-5.5" }, cwd: "/Users/me/dev/storefront", prompt: "Review the current diff and name the riskiest change.", }); const result = await agent.waitForFinish(); console.log(result.lastMessage); await client.close(); ``` The public API is the package root. Imports under `@getpaseo/client/internal/*` are unsupported implementation details used by Paseo's own packages. Read the [SDK documentation](https://paseo.sh/docs/sdk) for agents, workspaces, terminals, provider discovery, events, recipes, and the API reference. Runnable TypeScript patterns also live in [`examples/`](./examples/README.md). ## Runtime The client needs a WebSocket implementation. Modern browsers and Node.js 22 provide one globally. Use a WebSocket URL ending in `/ws`, such as `ws://127.0.0.1:6767/ws`. Pass `password` when the daemon requires authentication. The client advertises its supported protocol capabilities by default. Optional `capabilities` overrides extend or override that declaration; browser hosting must be supplied by the caller. Connecting alone does not subscribe to agent timelines or catalog events. See the [event guide](https://paseo.sh/docs/sdk/events) for subscription lifetimes and timeline replacements. ## Stability The high-level API exported from `@getpaseo/client` is the supported SDK surface. The SDK and daemon remain protocol-compatible across versions, but newly added capabilities can require a newer daemon. --- ### Overview (`packages/expo-two-way-audio/README.md`) # Speechmatics Two Way Audio Expo module for capturing and playing pcm audio data in react-native apps (iOS and Android). The aim of the module is to facilitate creating real-time conversational apps. The following features are provided: - Request audio recording permissions - Get clean (applying Acoustic Echo Cancelling) microphone samples in PCM format (1 channel 16 bit at 16kHz) - Play audio samples in PCM format (1 channel 16 bit at 16kHz). Playback happens through main speaker unless external audio sources are connected. - Provide volume level both for the input and output samples. Float between 0 and 1. - [iOS only] Get microphone mode and prompt user to select a microphone mode. Check out our [examples/](./examples) to see the module in action. ## Installation ``` npm i @speechmatics/expo-two-way-audio ``` ## Usage Please check out our [examples/](./examples) to get full sample code. 1. Request permissions for recording audio ```JSX import {useMicrophonePermissions} from "@speechmatics/expo-two-way-audio"; const [micPermission, requestMicPermission] = useMicrophonePermissions(); console.log(micPermission); ``` 1. Initialize the module before calling any audio functionality. ```JSX useEffect(() => { const initializeAudio = async () => { await initialize(); }; initializeAudio(); }, []); ``` 1. Play audio > [!NOTE] > The sample below uses the `buffer` module: > `npm install buffer` ```JSX import { Buffer } from "buffer"; // As an example, let's play pcm data hardcoded in a variable. // The examples/basic-usage does this. Check it out for real base64 data. const audioChunk = "SOME PCM DATA BASE64 ENCODED HERE" const buffer = Buffer.from(audioChunk, "base64"); const pcmData = new Uint8Array(buffer); playPCMData(pcmData); ``` 1. Get microphone samples ```JSX // Set up a function to deal with microphone sample events. // In this case just print the data in the console. useExpoTwoWayAudioEventListener( "onMicrophoneData", useCallback((event) => { console.log(`MIC DATA: ${event.data}`); }, []), ); // Unmute the microphone to get microphone data events toggleRecording(true); ``` ## Notes Some audio features of expo-two-way-audio like Acoustic Echo Cancelling, noise reduction or microphone modes (iOS) don't work on simulator. Run the example on a real device to test these features. ```bash # iOS npx expo run:ios --device --configuration Release # Android npx expo run:android --device --variant release ``` For Android, the following permissions are needed: `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`. In Expo apps they can be added in your `app.json` file: ```javascript expo.android.permissions: ["RECORD_AUDIO", "MODIFY_AUDIO_SETTINGS"] ``` --- ### Overview (`packages/protocol/README.md`) # @getpaseo/protocol Shared Paseo protocol schemas, codecs, and wire types. ## Stability This package is public so Paseo's published packages can depend on it cleanly. It is not a stable public API yet. Schemas, exports, wire helpers, and types may change or disappear in any release without advance notice. Use it outside Paseo at your own risk until the package is explicitly documented as stable. --- ### Overview (`packages/server/README.md`) # Voice Assistant A voice-controlled terminal assistant that runs as a single local service. ## Quick Start ```bash # Install dependencies npm install # Copy environment variables cp .env.example .env # Edit .env and add your API keys (OpenAI, Deepgram) # Run development servers npm run dev # Open browser to http://localhost:5173 ``` ## Architecture - **Express Server** (port 3000) - Serves API and built UI in production - **Vite Dev Server** (port 5173) - Hot-reload React UI in development - **WebSocket** (`/ws`) - Real-time bidirectional communication - **Agent** - STT → LLM → TTS pipeline with terminal control - **Daemon** - tmux-based terminal management (in-process) ## Development ```bash # Run both servers (recommended) npm run dev # Or run separately: npm run dev:server # Express on port 3000 npm run dev:ui # Vite on port 5173 # Type checking npm run typecheck # Build for production npm run build # Start production server npm start ``` ## Project Status **✅ Completed** (Phases 1-2): - Package setup and configuration - Express server with WebSocket - React UI with Vite - WebSocket client with ping/pong testing **⏳ In Progress** (Phase 3): - Terminal control (tmux integration) **📋 Planned** (Phases 4-9): - LLM integration (OpenAI GPT-4) - Agent orchestrator - Speech-to-Text (Deepgram) - Text-to-Speech (OpenAI) - Audio streaming - UI polish See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) for complete details. ## Environment Variables ```bash OPENAI_API_KEY=your-openai-key-here # GPT-4 and TTS DEEPGRAM_API_KEY=your-deepgram-key-here # Streaming STT STT_MODEL=whisper-1 # Optional: override to gpt-4o-transcribe, etc. STT_CONFIDENCE_THRESHOLD=-3.0 # Optional: reject low-confidence clips STT_DEBUG_AUDIO_DIR=.stt-debug # Optional: persist raw dictation audio for debugging PASEO_HOME=~/.paseo # Runtime state directory (agents/, etc.) PASEO_LISTEN=127.0.0.1:6767 # Listen address (host:port or /path/to/socket) ``` `PASEO_HOME` defaults to `~/.paseo` and isolates runtime artifacts like `agents/`. `PASEO_LISTEN` controls the daemon listen address. For blue/green testing you can run a parallel server without touching production state: ```bash PASEO_HOME=~/.paseo-blue PASEO_LISTEN=127.0.0.1:7777 npm run dev ``` ## Tech Stack - **Server**: Express, TypeScript, ws (WebSocket) - **Client**: React 18, Vite, TypeScript - **Terminal**: tmux (via child_process) - **AI**: OpenAI (LLM + TTS), Deepgram (STT) ## Testing Currently manual testing via: 1. Start servers: `npm run dev` 2. Open http://localhost:5173 3. Test WebSocket connection (green status indicator) 4. Click "Send Ping" button to test communication More testing guidance as features are implemented. ## License MIT --- ### Overview (`packages/website/README.md`) # Paseo website ## Plugin install counts Clients report an install by resolving a plugin with `X-Paseo-Install: 1` or `?intent=install`, using `/api/plugins/resolve//` or `/plugins//.json`. Ordinary resolves do not count. These numbers measure install intent, not successful artifact installation or npm downloads. The worker requires Cloudflare's `CF-Connecting-IP` header to count a report. It stores the plugin ID plus a SHA-256 hash of the IP in a `WEBSITE_CACHE` KV key with a one hour TTL, never the raw IP. An existing key skips the count; repeats do not extend the hour. Missing or empty IP headers do not count. Accepted reports increment the existing all-time total and UTC daily buckets in `WEBSITE_CACHE`. Daily buckets retain 60 days and supply the website's seven-day and thirty-day rankings. `/api/plugins/installs` still returns plugin IDs mapped to all-time totals. The [registry build](https://github.com/getpaseo/plugins/blob/main/scripts/build.ts) reads that endpoint into the published plugin details and index; the website reads windowed counts from KV through its five-minute cache. Existing counts remain intact. The KV guard is advisory: concurrent requests and KV propagation are not serialized. --- ### Overview (`plugin-examples/agent-configuration/README.md`) # Agent configuration Changes new Codex agents through `server.before("agent.create", ...)`: - Sets `config.providerOptions.sandbox_mode` to `workspace-write`. - Sets `config.providerOptions.approval_policy` to `on-request`. - Adds the `company` server to `config.mcpServers`. - Preserves other configuration, provider options, MCP servers, and environment overrides. Replace `https://tools.example.com/mcp` in `index.server.ts` with your MCP server URL before using this example. The URL is a placeholder. The `company` entry replaces an existing server with that name. Install on a daemon with plugins enabled: ```bash paseo plugin install /absolute/path/to/plugin-examples/agent-configuration ``` The callback receives the request after earlier plugins have transformed it. The nested spreads preserve their settings; the explicit values replace only the named fields. Paseo validates and saves the resulting configuration before starting the agent. Existing agents are unchanged. See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for ordering and callback shapes. [Lifecycle actions](../lifecycle-actions) demonstrates provider switching and environment injection. Its provider-switch callback clears provider options when changing Codex to Claude, so use these examples separately when trying the Codex-specific settings. --- ### Overview (`plugin-examples/buttons/README.md`) # Header buttons and composer pills Install this directory as a plugin, open an agent, and choose **Button examples: action** in the Command Center. One header button and one composer pill appear. Choose another mode to update those same registrations. Switching agents moves the example to that agent's workspace and composer. | Command Center command | Header | Composer | Try | | ------------------------------------- | ------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Button examples: action** | Refresh icon only | Refresh icon and label | Refresh reads the workspace from the daemon and updates the label and tooltip. Paseo owns pending and error feedback. | | **Button examples: menu** | Wrench, Tools, chevron | Wrench and Tools | Refresh, a separator, custom details, a Display submenu, and a disabled item. | | **Button examples: popover** | Reactive status dot, Details, chevron | Reactive status dot and Details | Workspace data updates through `useWorkspace`; Done closes the surface. | | **Button examples: hide / show** | Hide or restore the button | Hide or restore the pill | Visibility changes through `registration.update({ visible })`. | | **Button examples: disable / enable** | Disable or enable the button | Disable or enable the pill | Disabled state changes through `registration.update({ disabled })`. | On compact layouts the header button is borderless and icon-only. Menus and custom content open bottom sheets. Composer pills keep their icon and label, without a chevron, on every layout. The example contributes one header button at a time. Additional actions live under the named **Tools** button; the example does not add a three-dot control or trigger plugin overflow. | Action | Menu | Custom content | Compact sheet | | ------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | | | | | | The client entry owns the active example. [client/examples.tsx](client/examples.tsx) contains the descriptors, updates, and React content. Return `.remove()` cleanup when the example moves or stops. See the [button reference](../../public-docs/plugins/reference.md#button-descriptor) and [composer migration](../../public-docs/plugins/migration.md#composer-pills). From the repository root, `npm run typecheck --workspace=@getpaseo/plugin` checks this example against the SDK. Existing plugin projects must update `@getpaseo/plugin` before running their own `npm run typecheck` to detect the old `Component`/`onPress` pill shape and callable cleanup handle. The browser regression installs this exact directory in an isolated daemon and exercises both layouts, updates, and cleanup: ```sh npm run test:e2e --workspace=@getpaseo/app -- e2e/browser/plugin-button-example.spec.ts ``` The captures use Chromium at desktop and phone widths; native iOS and Android were not exercised. --- ### Overview (`plugin-examples/catppuccin/README.md`) # Catppuccin plugin example This example adds **Catppuccin Mocha** to Settings → Appearance. Paseo ships Catppuccin as a syntax-highlight theme; this contributes it as an app theme. A theme is client data, so the whole plugin is one `addTheme` call in `index.client.ts` and has no server entry or subprocess. Register it in `$PASEO_HOME/config.json`: ```json { "pluginsEnabled": true, "plugins": { "catppuccin": { "source": "directory", "path": "/absolute/path/to/paseo/plugin-examples/catppuccin" } } } ``` Then run `paseo reload` and pick **Catppuccin Mocha** in Settings → Appearance. The colors come straight from the [Catppuccin Mocha](https://catppuccin.com/palette/) palette: `base`, `text`, `surface0`, `surface1`, `mauve`, `subtext0`, and `overlay0`. Paseo expands them into the full token set, so `accent` (`mauve`) drives buttons and selection while `border` (`surface1`, shared with `control`) stays the border and raised-surface tint. --- ### Overview (`plugin-examples/inline-thinking/README.md`) # Inline thinking timeline example This plugin replaces reasoning rows from the first streaming delta and renders the paced text inline. Install the directory as `inline-thinking`, then run an agent that streams reasoning. `index.client.tsx` wires the transformer and renderer to the component in `client/thinking.tsx`. --- ### Overview (`plugin-examples/lifecycle-actions/README.md`) # Lifecycle actions Small callbacks using the existing SDK: - Send `Try again.` when the latest output contains `out of credits`. - Decline a shell request matching `rm -rf`; approve exactly `git status`; leave other requests alone. - Inject `PASEO_HOOK_CREATE_EXAMPLE=created` on creation and `PASEO_HOOK_OPEN_EXAMPLE=opened` on each session opening. - Change requested Codex agents to Claude Haiku before creation. - Create a worktree when a directory creation request is titled `Isolated lifecycle example`. This is a demonstration plugin: installing it enables all these behaviors on its host. Install it alongside `lifecycle-logger` on a test daemon with plugins enabled: ```bash paseo plugin install /absolute/path/to/plugin-examples/lifecycle-actions paseo plugin install /absolute/path/to/plugin-examples/lifecycle-logger paseo plugin logs lifecycle-logger ``` Outside the Paseo repository, `server/inspect.ts` needs `@getpaseo/protocol` installed for its type imports. Add it to your plugin development dependencies at the same version as `@getpaseo/plugin` before installing this example. Copy the callbacks you need into your own plugin. The follow-up example sends a new message; it does not replay attachments or undo previous tool effects. If the provider keeps returning the matching phrase, it keeps sending follow-ups. Add limits or delay in your plugin when your workflow needs them. The command regex illustrates a policy; it does not parse shell syntax or cover every deletion command. `server/inspect.ts` joins provider text chunks and excludes earlier turns and the current user prompt from the phrase match. The failing-first regression test records the split text observed with a real Claude agent. See [agent configuration](../agent-configuration) for a focused example that injects MCP servers and changes Codex sandbox and approval options while preserving other settings. See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for the API. --- ### Overview (`plugin-examples/lifecycle-logger/README.md`) # Lifecycle logger Registers all eleven server lifecycle hooks and logs their data as JSON. It observes agent creation, session opening, turns, permissions, archive, and workspace creation/archive. Before hooks return the request unchanged. Environment values are redacted; prompts and timeline content are logged. Install it on a daemon where plugins are enabled: ```bash paseo plugin install /absolute/path/to/plugin-examples/lifecycle-logger paseo plugin logs lifecycle-logger ``` The same entries appear in the target daemon's `daemon.log`. The plugin log viewer retains a bounded tail; use the daemon log for longer captures. Log lines are capped at 16 KiB, so a large timeline can be truncated. See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for callback shapes and delivery rules. The real-provider test in `packages/server/src/server/plugins/lifecycle.real.e2e.test.ts` runs both examples on an isolated daemon and saves evidence under `.dev/lifecycle-proof/`. Run it from `packages/server` on Linux with Claude configured: ```bash npx vitest run src/server/plugins/lifecycle.real.e2e.test.ts --bail=1 ``` The test uses real provider calls and a temporary daemon home. Its failure check uses Linux `/proc` to identify and terminate only its own Claude subprocess. The credits check asks the real agent to emit the matching phrase; it does not exhaust an account's credits. --- ### Overview (`plugin-examples/linear/README.md`) # Linear plugin example This example adds `Attach Linear issue` to the composer. Search by issue identifier or title, then send a stable issue snapshot to the agent. Set a personal API key in the daemon environment: ```bash export LINEAR_API_KEY="lin_api_..." ``` Start your daemon with that environment variable set. Then turn on **Enable plugins** in **Settings → Plugins** and install the example: ```bash paseo plugin add /absolute/path/to/paseo/plugin-examples/linear paseo plugin ls linear ``` Use `paseo plugin reload linear` after source edits. Changing the API key requires restarting the daemon with the new environment; installing or reloading plugin source does not. The split entry point demonstrates the complete attachment-source pattern: - define the validated search RPC and attachment metadata in `shared/issues.ts`; - handle it in the daemon subprocess from `server/issues.ts` and `index.server.ts`; - register the attachment source from `index.client.ts`; - keep credentials and vendor API calls out of the client bundle. --- ### Overview (`plugin-examples/markdown-panel/README.md`) # Markdown file panel example Requires Paseo 0.13.0 or later. Install the editor dependencies, then install this directory: ```sh cd plugin-examples/markdown-panel npm install paseo plugin install "$PWD" ``` Open a `.md` or `.markdown` file in Files. Choose **Rich Markdown — markdown-panel** in the picker. Check **Don't ask me again** to remember the choice on this device. The panel is a CodeMirror editor with Markdown highlighting, line numbers, undo, redo, and line wrapping. It reads the file once with `readText`, saves 500 ms after the last edit with `writeText`, and reports unsaved edits with `tab.setModified`. When the file changes on disk with nothing unsaved, it reads again; with unsaved edits, or when a write rejects with `PluginFileConflictError`, it offers **Reload** and **Overwrite**. **Open with…** in the tab menu switches the tab back to Paseo's Markdown panel. Native shows selectable, read-only text through `useFileText`. Paseo bundles the editor dependencies into this plugin. They are loaded only on web; the native path uses React Native primitives. DOM integration lives in `client/web.ts`. See the [file panel reference](https://paseo.sh/docs/plugins/reference#file-panels). --- ### Overview (`plugin-examples/modal-ui/README.md`) # Modal UI example Install on a Paseo host with npm source installation support and npm available: ```sh paseo plugin install npm:@getpaseo/plugin-example-modal-ui@0.1.1 ``` In host **Settings → Plugins**, paste the same `npm:` identifier into **Plugin source**. Enable plugins, then open **Modal examples** from the sidebar or a workspace tab. Choose **Open Form**, type into **Paste here**, and watch the **Input:** text update. The installed plugin ID is `modal-ui-example`. Host Settings shows the package identity and installed version. With reviewed-update support, run `paseo plugin update modal-ui-example --check` to check for a newer version, then `paseo plugin update modal-ui-example` to review and approve it. An explicit install version selects the initial content; later updates still check the latest release. The package ships the existing TypeScript entry and client sources. Paseo compiles them through its directory plugin loader; no package build or preparation command is required. React, React Native, and `@getpaseo/plugin` are peer contracts supplied by the host. npm is needed for installation, not loading or reloading. You can also install this directory while developing. See the [source reference](https://paseo.sh/docs/plugins/reference#plugin-sources) for supported identifiers and preparation rules. The examples demonstrate default and custom padding, a full-width body, author-owned ScrollView and FlatList scrolling, horizontal tabs, and clipboard actions with a keyboard-aware input. See the [host UI reference](https://paseo.sh/docs/plugins/reference#host-ui) for the API contract. The browser regression installs this exact example in an isolated daemon: ```sh cd packages/app npx playwright test e2e/browser/plugin-modal-body.spec.ts --project=browser --workers=1 ``` On Android, open each example and drag up on its content to expand the sheet, then scroll the list. In FlatList, expand before using **Jump to last row**; row 100 should be visible. At the top of either list, drag down on a row to dismiss the sheet. In Form, press **Copy text**, long-press the input, and choose **Paste**. The input should contain “Copied from Paseo”. With the system keyboard enabled, focusing the input should keep it visible. Run the [native sheet regression](https://github.com/getpaseo/paseo/blob/main/packages/app/e2e/mobile/modal-sheet/README.md) to check body dismissal, list scrolling and horizontal tabs together. These captures show Android copy/paste and custom padding on browser and wide native layouts. Android API 35 and Chromium were exercised; iOS and Electron were not tested. | Android copy/paste | Browser custom padding | Wide Android custom padding | | ---------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | | | | | --- ### Overview (`plugin-examples/pdf-panel/README.md`) # PDF file panel example Requires Paseo 0.13.0 or later. Install this directory with `paseo plugin install /absolute/path/to/plugin-examples/pdf-panel`, then open a `.pdf` in Files. The panel resolves the file's local URL with `useFileUrl`, shows `Loading` until it does, and passes it to `DocumentFrame`. Where a platform cannot show a PDF inline (Android), `DocumentFrame` says so. The plugin does not construct daemon URLs. See the [file panel reference](https://paseo.sh/docs/plugins/reference#file-panels). Inline PDF rendering needs a daemon from Paseo 0.13.0 or later; see the [DocumentFrame reference](https://paseo.sh/docs/plugins/reference#documentframe). --- ### Overview (`plugin-examples/provider-acp-transformer/README.md`) # ACP provider transformer example This server plugin registers an ACP command through `runAcpProvider()`. The helper owns ACP process and SDK details behind Paseo's callback-based provider connection. `server/vendor-edit.ts` shows the intended extension seam: a focused transformer converts one vendor tool payload into Paseo's ordinary file-edit shape. It does not translate the whole event stream. Replace the placeholder `example-acp --stdio` command with an installed ACP agent before enabling the plugin. --- ### Overview (`plugin-examples/provider-direct/README.md`) # Direct provider example This plugin implements `ProviderRegistration` directly. It demonstrates connection negotiation, catalog and session listing, session creation, prompt and command disposition, settings, persistence and replay, archive actions, and an ordinary child session. The provider emits versioned `provider-result` timeline items for its root and child sessions. `index.client.tsx` registers the Zod schema and React Native renderer for those items. The server and client share only the item kind and schema under `shared/`. The provider receives Paseo host tools through `config.mcpServers`; it does not receive a second callback tool API. --- ### Overview (`plugin-examples/settings/README.md`) # Settings example Install this directory with `paseo plugin install /absolute/path/to/plugin-examples/settings`. Open Settings → Plugins → settings-example → Display, or run **Configure agent monitor** in Command Center. The select and switch save immediately. The title editor keeps a draft and its original revision, so another client's save produces a conflict instead of overwriting its changes. Close and reopen the editor to discard the draft and use the latest settings. Every UI component is a plain named import. The custom preview shares the same values without using a form wrapper. Values are shared by clients connected to the same host. The same screen on [Android](screenshots/android.png), [Electron](screenshots/electron.png), and [compact web](screenshots/web-compact.png). --- ### Overview (`plugin-examples/timeline-items/README.md`) # Pi tasks timeline plugin example This example recognizes Pi `todo` tool calls from both `@juicesharp/rpiv-todo` and Pi's `examples/extensions/todo.ts`, replaces the tool-call entry with a versioned `pi-task-list` item, and renders the current task snapshot with a native React Native component. It transforms both running and completed calls. The rpiv shape preserves `pending`, `in_progress`, and `completed`; deleted tombstones are omitted. Pi's example shape maps `done` to `completed` or `pending`. Malformed results and unrelated tool calls return `undefined`, leaving Paseo's original timeline entry unchanged. The transformer is a pure client contribution. It receives each source item and its streaming phase while Paseo builds the render model, then returns plain plugin item objects. The renderer validates `data` before Paseo mounts the component. `index.client.tsx` wires the transformer from `shared/pi-tasks.ts` and renderer from `client/pi-tasks.tsx`. The plugin has no server entry or subprocess. --- ### Overview (`packages/app/maestro/README.md`) # Maestro Flows This directory contains local mobile UI flows. Keep flows small enough that a failure screenshot proves the intended behavior, not just that the app launched. ## iOS Sidebar Close Regression `ios-sidebar-close-regression.yaml` exercises close swipes over a semantic header and the nested workspace list without activating the content below the swipe. Start the `sh.paseo.debug` dev client against the intended Metro server first; the flow preserves that running connection. ```bash maestro test packages/app/maestro/ios-sidebar-close-regression.yaml --udid ``` ## iOS Sidebar Drag Cancellation Regression `test-sidebar-drag-cancellation-ios.sh` creates three temporary projects and uses real native slow swipes to cover successful reorder, a second touch during the drop spring, horizontal close cancellation, outer-list scroll recovery, and a subsequent reorder. The harness removes its daemon projects and local fixture directories on exit. Start the debug dev client against the intended Metro server, then run: ```bash bash packages/app/maestro/test-sidebar-drag-cancellation-ios.sh ``` ## New Workspace Android Flow Use these files when debugging or extending workspace creation on Android: - `test-workspace-create-android-crash.sh` runs the full regression harness. - `workspace-create-android-crash.yaml` is the full Maestro flow used by the harness. - `record-workspace-create-android-focus.sh` records only the focused repro window after setup. - `workspace-create-android-ready-sidebar.yaml` stages the app with the Android sidebar open and a prepared project visible. - `workspace-create-android-create-focused.yaml` starts from that staged sidebar and performs the actual workspace creation. The reusable pieces live in `flows/`: - `flows/android-dev-client.yaml` handles Expo dev launcher/dev menu screens. - `flows/connect-direct-if-welcome.yaml` connects to the local daemon only when the welcome screen is visible. - `flows/open-prepared-project-sidebar.yaml` waits for the home screen, opens the compact Android sidebar, and waits for the prepared project. - `flows/new-workspace-open-from-sidebar.yaml` taps the project row's new-workspace action and waits for `/new`. - `flows/new-workspace-select-codex-gpt54.yaml` selects a real provider/model. - `flows/new-workspace-submit-and-assert-created.yaml` taps `Create` and proves the app landed on the created workspace. Compose new workspace scenarios out of these primitives instead of copying the old full flow. The shell scripts render the top-level flows and every `flows/*.yaml` file into the same temp directory, so nested `runFlow: flows/...` paths keep working with `${PASEO_MAESTRO_*}` placeholders. The flow is intentionally strict. It must: 1. Open a prepared project from the daemon. 2. Tap the project row's new-workspace action. 3. Select an actual provider/model before tapping `Create`. 4. Tap `Create`. 5. Assert the app lands on a workspace header and the draft composer. 6. Assert `New workspace`, `Select a model`, and the Android redbox text are not visible. 7. For the shell harness, grep logcat for `failed to insert view` and `specified child already has a parent`. Do not weaken this flow to only wait for `message-input-root`. That can pass on the wrong route. The header assertion and the `New workspace` negative assertion are what prove the redirect actually completed. The scripts assume a development build with package id `sh.paseo.debug`, an already-running local daemon on `127.0.0.1:6767`, and a connected Android device or emulator. They call `adb reverse tcp:6767 tcp:6767`; they do not restart the daemon. ```bash bash packages/app/maestro/test-workspace-create-android-crash.sh bash packages/app/maestro/record-workspace-create-android-focus.sh ``` Optional environment: ```bash PASEO_MAESTRO_APP_ID=sh.paseo.debug PASEO_MAESTRO_DIRECT_ENDPOINT=127.0.0.1:6767 PASEO_MAESTRO_DAEMON_WS_URL=ws://127.0.0.1:6767/ws PASEO_MAESTRO_PROJECT_PATH=/path/to/git/repo ``` --- ### Overview (`packages/client/examples/README.md`) # Paseo Client SDK Examples These examples use only the public SDK root: ```ts import { createPaseoClient, type PaseoClient } from "@getpaseo/client"; ``` Each example takes the daemon WebSocket URL as an argument. In worktree dev, read it from the portless banner or `portless get daemon`; for the desktop-managed daemon, use the URL for that daemon. - `quickstart.ts` runs one agent and prints its reply. It is a standalone script with the URL at the top; the rest export functions. - `workspaces.ts` covers creating a fresh workspace, opening by directory, refreshing, and archiving. - `agents-and-providers.ts` covers provider discovery, creating agents, and waiting for turns. - `events-and-timeline.ts` covers subscribing to workspace, agent, and timeline events, plus refetching a timeline page. - `issue-to-agent.ts` turns an issue record into a visible Paseo workspace and agent. - `parallel-review.ts` launches several reviewers concurrently and cleans them up. - `provider-settings.ts` covers provider settings that are currently daemon config-backed. Provider profiles, provider env vars, custom binaries, and additional models are still raw daemon config behavior. The SDK exposes them through `client.config.get()` and `client.config.patch()` until first-class provider settings RPCs exist. --- ### Overview (`packages/protocol/codegen/README.md`) # Protocol Validator Codegen This directory is build-time only. The generator writes `generated/ws-outbound.compile.ts`, the zod-aot discovery entry for the inbound WebSocket validators: one for the envelope and one per session message type. The discovery entry and the generated runtime files under `../src/generated/validation/` are not committed. The protocol package owns every generation trigger through its npm lifecycle scripts. `zod-aot` is exact-pinned, and the protocol generator applies the small compiler patches it requires before generation. Treat changes to those patches like compiler changes: regenerate, inspect the output, and run the protocol validation regression tests before shipping. --- ### Overview (`packages/app/modules/paseo-diff-prototype/README.md`) # Native diff layout experiment Android-only Expo module for evaluating background wrapped-text layout. The normal diff surface does not call this module; it still uses the JavaScript model and renderer. This is a checkpoint of the layout experiment, not a replacement renderer. The C++ core owns cell text and wrapped grapheme geometry. Kotlin/JNI supplies the Android font manager and dispatches preparation through Expo's background queue. It links the Skia libraries shipped by the installed React Native Skia package. An iOS binding, renderer integration, and shipping library ownership are unfinished. ## Diagnostic interface Access the module through `expo.modules.PaseoDiffPrototype` in a development build: - `create()` returns a numeric handle. - `prepare(handle, texts, widths, family, fontSize)` asynchronously builds geometry and returns counts, copy/layout timings, and a partial geometry allocation estimate. Text and width arrays must have matching lengths. Input is copied; it is not zero-copy. - `read(handle, startCell, count)` synchronously returns packed numerical geometry for at most 256 cells. This exists for parity checks, not whole-model transfer. - `release(handle)` cancels pending work and releases ownership. Release handles after success or failure; module destruction also cancels and releases all handles. Each packed cell begins with its index and fragment count. Each fragment contains UTF-16 start/end offsets, width, and grapheme count, followed by each grapheme's UTF-16 start/end offsets and width. The caller retains source text. The experiment accepts normalized cell inputs. It does not parse wire payloads, construct file/header/review models, apply highlighting, or draw pixels. A renderer integration must preserve native ownership and request bounded visible data rather than reconstructing the entire JavaScript graph. Grapheme property ranges are generated at build time from the installed JavaScript dependency so segmentation uses the same data as the reference implementation. --- ### Overview (`packages/expo-two-way-audio/examples/basic-usage/README.md`) # Expo Two-Way-Audio Using Flow API This example showcases the basic functions of the expo-two-way-audio module: - Capture input raw pcm data - Play raw pcm data (from a hardcoded base64 string) - Display volume level for both input and output - In iOS: show/set microphone mode while recording. ## Requirements - Node.js - Expo CLI - [iOS](https://docs.expo.dev/workflow/ios-simulator/) and/or [Android](https://docs.expo.dev/workflow/android-studio-emulator/) dev environment setup. ## Run the app In the `examples/basic-usage` directory: 1. Install dependencies: ```sh npm install ``` 2. Run the app: ```sh # Run iOS npm run ios # Run Android npm run android ``` ## Notes Some audio features of expo-two-way-audio like Acoustic Echo Cancelling, noise reduction or microphone modes (iOS) don't work on simulator. Run the example on a real device to test these features. ```bash # iOS npx expo run:ios --device --configuration Release # Android npx expo run:android --device --variant release ``` --- ### Overview (`packages/expo-two-way-audio/examples/flow-api/README.md`) # Expo Two-Way-Audio Using Flow API This example shows how expo-two-way-audio can be used to communicate with [Speechmatics Flow API](https://www.speechmatics.com/flow) Flow is a conversational AI API and therefore, we need to send audio data in real time and play back the audio responses that we'll get from the API. ## Requirements - Node.js - Expo CLI - [iOS](https://docs.expo.dev/workflow/ios-simulator/) and/or [Android](https://docs.expo.dev/workflow/android-studio-emulator/) dev environment setup. - [Speechmatics Flow Client (React)](https://github.com/speechmatics/speechmatics-js-sdk/tree/main/packages/flow-client-react) - [`event-target-polyfill`](https://www.npmjs.com/package/event-target-polyfill) package, or any other polyfill for the [`EventTarget` class](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) A Speechmatics API key is also needed in order to run the example. The key is injected into the app via environment variable. It can be passed by creating a `.env` file in the same directory as the example with the following content: ``` EXPO_PUBLIC_SPEECHMATICS_API_KEY='YOUR-API-KEY-HERE' ``` An API key can be obtained from the [Speechmatics Portal](https://portal.speechmatics.com) > [!WARNING] > > The example uses the API key to request a temporary token (needed for communicating with flow). > In a real-world scenario, you should not expose your API key in your client-side code. > Instead, you should create a server-side endpoint that generates the temporary token (JWT) for you. ## Run the app In the `examples/flow-api` directory: 1. Install dependencies: ```sh npm install ``` 2. Run the app: ```sh # Run iOS npm run ios # Run Android npm run android ``` ## Notes Some audio features of expo-two-way-audio like Acoustic Echo Cancelling, noise reduction or microphone modes (iOS) don't work on simulator. Run the example on a real device to test these features. ```bash # iOS npx expo run:ios --device --configuration Release # Android npx expo run:android --device --variant release ``` --- ### Overview (`packages/app/e2e/mobile/composer-overlay/README.md`) # Late composer pill clearance This regression opens a completed conversation, relaunches the Android app, and registers a composer pill five seconds after the client plugin loads. It checks that the completed turn's Copy and Fork buttons remain fully above the pill. The daemon, plugin API, native app, layout, and accessibility bounds are real; no provider calls are needed during the test. Prerequisites: - Build the server and app dependencies with `npm run build:server` and `npm run build --workspace=@getpaseo/expo-two-way-audio`. - Run an isolated development daemon on a non-default port. - Run this checkout's Metro server and open the connected Android dev client with `agent-device`. The app must already know the isolated daemon. - Open a completed conversation on a compact portrait Android emulator, at the latest turn, with no other composer tracks visible. Keep the software keyboard closed. Note the workspace and agent IDs from the daemon. Set `WORKSPACE_ID` and `AGENT_ID` to that conversation, then run from the repository root, substituting the session and ports: ```sh PASEO_OVERLAY_ARTIFACTS_DIR=.dev/composer-overlay-evidence \ node packages/app/e2e/mobile/composer-overlay/android.mjs \ composer-overlay ws://127.0.0.1:6843/ws "$WORKSPACE_ID" "$AGENT_ID" sh.paseo.debug 8193 ``` The runner installs and removes its delayed plugin and leaves the conversation intact. It preserves the daemon's previous plugins-enabled setting. The evidence directory contains the cold-reopen screenshot and raw accessibility snapshot. Without an explicit directory, temporary evidence is removed with the fixture. To check an existing capture independently: ```sh node packages/app/e2e/mobile/composer-overlay/assert-footer-clear.mjs \ .dev/composer-overlay-evidence/cold-reopen.json 'Overlay regression pill' ``` On the failing baseline, the Copy button extends below the pill's top edge. With the correction, both actions are clear before the composer receives focus. Additional checks on the same conversation: opening the keyboard keeps the footer clear; after scrolling up, a newly registered pill must not jump back to the latest turn. Native iOS uses a different keyboard implementation and needs its own device verification. --- ### Overview (`packages/app/e2e/mobile/diff-tree/README.md`) # Mobile diff tree appearance ## Reproduce the row shadow Use an Android emulator with a workspace containing 80 modified text files, named `file-000.txt` through `file-079.txt`. Each file changes `before` to `after`. 1. Open the workspace's Changes sidebar, then **Jump to file**. 2. Swipe upward through the tree until `file-079.txt` is visible. 3. Inspect the row where the scroll gesture started. It must remain flat. 4. Swipe back to the first file, then return to the last file and select it. The sheet should close and show that file's diff. ## Recorded verification Android API 35, 1080×1920. The baseline produced a raised gray shadow around `file-074.txt` after scrolling. The fixed build reached the same last row without the shadow. Baseline scrolling in both directions and selection of the last file passed; the fixed build also reached the last row and closed the sheet on selection. The fixed-build assertion for the selected diff header did not match, so it does not establish the final jump position. | Before | After | | ---------------------------------- | -------------------------------- | | | | | Light | Dark | | --------------------------------- | ------------------------------- | | | | The shadow check is visual; the existing header-interaction unit test does not test Android rendering. iOS, browser web, and Electron were not manually exercised. --- ### Overview (`packages/app/e2e/mobile/modal-sheet/README.md`) # Native modal and sheet gestures ## Compact sheet gestures Use an Android emulator at 1080×1920, density 420, with the checkout's native app bundle loaded. Connect the app to an isolated daemon, enable plugins, and install `plugin-examples/modal-ui` there. Set `SHEET_QA_SERVER_ID` to that host's server ID, then run from the repository root: ```sh agent-device test packages/app/e2e/mobile/modal-sheet/gestures.android.ad \ --env EXAMPLES_URL="paseo://h/${SHEET_QA_SERVER_ID}/plugin/modal-ui-example/surface/main" \ --record-video --artifacts-dir .dev/sheet-qa/plugin agent-device test packages/app/e2e/mobile/modal-sheet/model.android.ad \ --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \ --record-video --artifacts-dir .dev/sheet-qa/model ``` The plugin journey checks body dismissal, reopening, expansion and last-row reachability with SDK ScrollView and FlatList, programmatic scrolling after expansion, downward list scrolling, and horizontal tab selection. The model journey checks body dismissal and the nested sheet's return to its parent without selecting a model or submitting a prompt. It does not assert catalog contents. These scripts live outside the default mobile suite because they require the installed example and an explicit connected host. See [mobile testing](../../../../../docs/mobile-testing.md) for device setup. ### Recorded verification Android API 35, 1080×1920 at density 420, development binary 0.7.2 with this checkout's JavaScript. Plugin tests used an isolated daemon. Recordings show the same body drag [before](evidence/android-before.mp4) and [after](evidence/android-after.mp4) the fix. The [browser recording](evidence/browser.webm) covers the existing plugin modal journey at wide and compact sizes. ```text Baseline dismissal regression: failed at step 6: wait timed out for selector: label="Open ScrollView" Current surface: Bottom sheet handle, Bottom Sheet, Close, Row 1. Fixed dismissal regression: 1 passed (6.47s) Full plugin gesture journey: 1 passed (44.3s) Model sheet dismissal/reopen journey: 1 passed (13.7s) Browser plugin-modal-body.spec.ts: 1 passed (33.4s) Root typecheck, lint and format: passed ``` The model form's catalog stayed on “Loading…” in the debug app even though the isolated daemon's provider API returned models. Its sheet dismissal/reopen was exercised; populated model selection was not. iOS and Electron were not exercised. ## Tablet model selection `model-tablet.android.ad` exercises the New workspace popover. `model-tablet-agent.android.ad` exercises the modal used by an existing agent's narrow composer on a wide device. Both drill into a populated provider, select a real model, assert the updated trigger, reopen, and dismiss with Android Back. New workspace also pans beyond the short list viewport and flings back without selecting a row or dismissing the popover. They do not submit a prompt. Use an English-language Android tablet at 1600×2560, density 320 (800dp), with this checkout's JavaScript and a connected isolated daemon. On a Pixel Tablet AVD, rotate to portrait explicitly; its natural landscape orientation letterboxes this portrait-locked app into the compact layout: ```sh adb -s "$ANDROID_SERIAL" shell settings put system accelerometer_rotation 0 adb -s "$ANDROID_SERIAL" shell settings put system user_rotation 1 adb -s "$ANDROID_SERIAL" shell wm density 320 ``` Prepare an idle agent through the daemon's public `createAgent` API with a real provider/model and no initial prompt. Set `MODEL_QA_AGENT_ID` and `MODEL_QA_AGENT_TITLE` to that agent. In New workspace, remember a model first (the phone layout works on the broken baseline), then close the picker. Choose a model visible on the provider's first page and set its catalog ID and displayed label. Set `MODEL_QA_LAST_MODEL_ID` to its initially offscreen last model; use a short overflowing catalog (six rows during this verification) for the coordinate-based pan/fling regression: ```sh agent-device test packages/app/e2e/mobile/modal-sheet/model-tablet.android.ad \ packages/app/e2e/mobile/modal-sheet/model-tablet-agent.android.ad \ --serial "$ANDROID_SERIAL" --metro-port "$MODEL_QA_METRO_PORT" \ --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \ --env AGENT_URL="paseo://h/${SHEET_QA_SERVER_ID}/agent/${MODEL_QA_AGENT_ID}" \ --env AGENT_TITLE="$MODEL_QA_AGENT_TITLE" \ --env PROVIDER_ID=codex --env MODEL_ID="$MODEL_QA_MODEL_ID" \ --env MODEL_LABEL="$MODEL_QA_MODEL_LABEL" --env LAST_MODEL_ID="$MODEL_QA_LAST_MODEL_ID" \ --artifacts-dir /tmp/paseo-model-tablet-qa ``` The existing-agent journey needs the sidebar pinned so its composer stays narrow. Start each run with no modal open; a failed provider tap leaves its modal open, so dismiss it before the next run. These host-dependent journeys remain outside the default mobile suite, alongside the compact sheet journeys above. Keep generated screenshots, recordings, and run logs outside the repository. ## Stacked adaptive sheets `stacked-pairing.ad` opens the welcome screen's pairing sheet and then the root-mounted host confirmation. It first types without tapping the input to verify autofocus, then cancels the confirmation, closes and reopens the underlying sheet, confirms again, and completes the password retry. `stacked-settings.ad` checks the same return and retry through Settings → add host → Direct connection → Advanced. Run both on phones and tablets so both the bottom sheet and centered dialog are exercised. These integration journeys require the host-confirmation flow in the test app. Include both the sheet fix and that flow in the QA checkout when verifying them; the production sheet component has no dependency on the host-confirmation feature. Use a fresh English app with notification permission granted and first-use keyboard prompts already dismissed. Load this checkout from an isolated Metro. Start an isolated password-protected daemon and a local Wrangler relay with `--var 'PASEO_RELAY_UPSTREAM:'`; the checked-in upstream setting otherwise forwards traffic to the hosted relay, which drops password rejection replies. Set `PAIRING_LINK` to the daemon's `relay://` URI with an intentionally incorrect `password` query parameter, and `PASSWORD` to its correct password. This exercises password retry even while the daemon accepts relay connections with no credential. ```sh agent-device replay packages/app/e2e/mobile/modal-sheet/stacked-pairing.ad \ --state-dir "$SHEET_QA_DEVICE_STATE" --session stacked-ipad --platform ios \ --udid "$SHEET_QA_IOS_UDID" \ --env PAIRING_LINK="$SHEET_QA_LINK" --env PASSWORD="$SHEET_QA_PASSWORD" \ --env OUT="$SHEET_QA_OUTPUT" ``` For Settings, first open Settings with Add host visible. With a saved host, open Switch host first. Use a second loopback spelling (`localhost` instead of `127.0.0.1`) for the same local relay so the saved host asks for confirmation of its changed connection. Pass that link to `stacked-settings.ad` with the same arguments. For an app with no saved hosts, use the original link; Add host is visible directly in Settings. Android uses the same journeys: copy each script outside the repository, change its context's `platform=ios` to `platform=android`, and pass `--serial` instead of `--udid`. Reverse both Metro (including the port advertised by its manifest) and the local relay ports. Keep driver state, artifacts, and sessions separate from other runs. These host-dependent journeys remain outside the default mobile suite, alongside the existing modal-sheet scripts. On iPhone, bulk replacement or bulk keyboard entry of the advanced URI field triggers a repeated-update error with both the parent and stacked-sheet implementations. Entering the complete URI one character at a time passed with both implementations; faster typing remains unverified. On iPad, replacing the field a second time appends text. For this Settings journey, use the native clipboard Paste menu, then continue the assertions manually. Dismiss the password keyboard with Done to submit when the Connect button is below the keyboard. The welcome pairing regression runs end to end without these adjustments. --- ### Overview (`packages/app/e2e/mobile/status-ring/README.md`) # Native retained status-ring regression This runs the production native ring and clock inside real retained panels with Reanimated on Android. A probe consumes the same public rotation hook and counts UI-runtime value changes. No Reanimated mocks or provider processes are used. Use an Android development client compatible with the checkout's native dependencies. In a disposable checkout, temporarily replace `packages/app/index.ts` with: ```tsx import "./src/polyfills/install-early"; import "./src/styles/unistyles"; import { registerRootComponent } from "expo"; import NativeRingRegression from "./e2e/mobile/status-ring/native"; registerRootComponent(NativeRingRegression); ``` Start Metro in `packages/app`: ```sh APP_VARIANT=development npx expo start --localhost --port 8096 ``` With one Android emulator running, open that bundle: ```sh agent-device open sh.paseo.debug 'exp+voice-mobile://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8096' --platform android --session status-ring --metro-port 8096 ``` From the repository root: ```sh node packages/app/e2e/mobile/status-ring/android.mjs status-ring http://127.0.0.1:8096 ``` The test checks visible rotation, hidden-panel inactivity while another ring is visible, inactivity with both panels hidden, and synchronized resumption. Each sample reads counters on the UI runtime; elapsed time includes device-command latency. The baseline fails at the first hidden-panel assertion. Restore the original `packages/app/index.ts`, close the agent-device session, and stop Metro afterward. The fixture substitutes running rings for a live agent and toggles retained panels directly; it does not exercise workspace navigation or measure whole-app CPU usage. It is excluded from routine unit tests because it requires a native runtime. --- ### Overview (`packages/protocol/src/generated/validation/README.md`) # Generated protocol validators `ws-outbound.aot.ts` is generated by zod-aot from `packages/protocol/codegen/generated/ws-outbound.compile.ts`, which the generator writes along with `ws-outbound-schema-metadata.ts`. Run: ```bash npm run generate:validators --workspace=@getpaseo/protocol ``` The generated TypeScript is intentionally gitignored. zod-aot is exact-pinned because this is a young solo-maintainer project; keep the generated validator behind protocol regression tests when upgrading it. --- ### Ad Hoc Daemon Testing (`docs/ad-hoc-daemon-testing.md`) # Ad-hoc daemon testing Spin up an isolated in-process daemon test harness without touching the main daemon on port 6767. This is for test code only. Executable daemon processes must start through `scripts/supervisor-entrypoint.ts` or `dist/scripts/supervisor-entrypoint.js`; do not use `createPaseoDaemon` as a product launch path. ## Quick start ``` /* Detailed source-code truncated for AI context efficiency. */ ``` Run with: ```bash npx tsx packages/server/src/server/your-script.ts ``` ## Using the test helper For simpler cases, `createTestPaseoDaemon` + `DaemonClient` handles temp dirs and port selection: ```typescript import { createTestPaseoDaemon } from "./test-utils/paseo-daemon.js"; import { DaemonClient } from "./test-utils/daemon-client.js"; const daemon = await createTestPaseoDaemon(); const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws`, appVersion: "0.1.70", }); await client.connect(); await client.fetchAgents({ subscribe: {} }); // ... test ... await client.close(); await daemon.close(); // stops daemon + cleans up temp dirs ``` The test helper does **not** expose `providerOverrides`. In test harnesses, use `createPaseoDaemon` directly when you need it (see quick start above). ## Common client methods ```typescript // Provider discovery const snapshot = await client.getProvidersSnapshot({ cwd: "/tmp" }); const models = await client.listProviderModels("claude"); const modes = await client.listProviderModes("claude"); // Agent lifecycle const agent = await client.createAgent({ provider: "claude", cwd: "/tmp" }); await client.sendMessage(agent.id, "Hello"); const updated = await client.waitForAgentUpsert(agent.id, (s) => s.status === "idle"); ``` ## Gotchas ### 1. appVersion gates provider visibility The daemon hides non-legacy providers (anything other than claude, codex, opencode) from clients that don't send an `appVersion >= 0.1.45`. The `DaemonClient` sends no version by default, so custom providers like ACP-based ones will be invisible in snapshot responses. Always pass `appVersion`: ```typescript const client = new DaemonClient({ url: `ws://127.0.0.1:${port}/ws`, appVersion: "0.1.70", }); ``` ### 2. Provider snapshots are async After the daemon starts, providers are probed in the background. The first `getProvidersSnapshot()` call will likely return `status: "loading"` for most providers. Poll until the provider you care about is no longer loading: ```typescript let snapshot = await client.getProvidersSnapshot({ cwd: "/tmp" }); for (let i = 0; i < 20; i++) { const entry = snapshot.entries.find((e) => e.provider === "gemini"); if (entry && entry.status !== "loading") break; await new Promise((r) => setTimeout(r, 2_000)); snapshot = await client.getProvidersSnapshot({ cwd: "/tmp" }); } ``` ### 3. fetchAgents is required before most operations Call `client.fetchAgents()` after connecting. The daemon session expects this handshake before it processes other requests — without it, messages like `get_providers_snapshot_request` will silently hang. ### 4. listen: "127.0.0.1:0" for port allocation Always use port `0` so the OS picks a free port. Never hardcode a port — it will collide with the main daemon or other test runs. ### 5. Script must live inside packages/server The test utilities use relative imports through the TypeScript project. Place your script somewhere under `packages/server/src/` and import from there. Scripts outside the repo will fail with module resolution errors. ### 6. Cleanup on failure Wrap your test logic in try/finally to ensure the daemon stops and temp dirs are cleaned up, even if an assertion fails: ```typescript try { // ... test logic ... } finally { await client.close(); await daemon.stop().catch(() => undefined); await rm(paseoHomeRoot, { recursive: true, force: true }); } ``` ### 7. ACP providers spawn real processes When testing ACP providers (e.g., Gemini with `extends: "acp"`), the daemon will spawn real processes to probe for models and modes. The binary must be installed and on PATH. Probing can take 5-15 seconds depending on the provider. --- ### Agent Lifecycle (`docs/agent-lifecycle.md`) # Agent lifecycle How an agent is created, runs, becomes a subagent, gets archived, and disappears from the UI. The model spans the daemon (lifecycle, archive) and the client (tabs, the subagents track). ## States ``` initializing → idle → running → idle (or error → closed) ↑ │ └────────┘ (agent completes a turn, awaits next prompt) ``` Each live agent in `AgentManager` carries a `lastStatus` of `initializing`, `idle`, `running`, or `error`. `closed` is the persisted, resumable state for an agent record that has no live provider runtime. State transitions persist to disk and stream to subscribed clients via WebSocket. ## Runtime residency An unarchived agent may be `closed` without being deleted or archived. Closing releases its provider processes and subscriptions while retaining its Paseo identity, persistence handle, timeline, workspace, labels, title, usage, attention, timestamps, and parent relationship. Opening or prompting the agent runs through `ensureAgentLoaded()`, which resumes the durable provider session under the same Paseo agent ID. Provider history is not appended again when the canonical timeline is already primed. Reload releases the old runtime before resuming its durable session: an idle provider process can still own an exclusive writer. A close failure retains that runtime for cleanup and blocks the replacement. Once closure succeeds, a failed resume leaves the durable agent closed and retryable. Idle agents remain resident indefinitely. Runtime closure happens only through an explicit lifecycle action such as archive, replacement, reload, workspace teardown, or daemon shutdown. A provider runtime can still die on its own — crash, OOM kill, host suspend. Work the agent parked inside that process dies with it: Claude Code's background Bash shells, `Monitor` watches, and workflows all live in the CLI process, and the completion notification that would have woken the agent never arrives. A runtime that dies mid-turn is reported by whatever is draining its stream, but between turns nothing is watching, so the agent sits at `idle` looking healthy while its background work is gone. Report that exit as a turn failure so the agent lands in `error` with a timeline entry. Claude and OMP report exits between turns. OMP relaunches from its session file on the next prompt; the unfinished turn is lost. ### Cancellation Provider interruption is idempotent at the `AgentSession` boundary. It resolves when the prior foreground turn can no longer run, including when the provider reports that it is already idle. It rejects only when the provider may still own the turn. Provider adapters translate native errors into that contract; lifecycle callers do not interpret provider-specific errors. After an acknowledged interrupt, the manager settles the captured run even when no terminal event arrives or the run was still waiting for its provider turn id. The captured run token prevents an older cancellation from settling a newer turn. If interruption is rejected or times out, the agent keeps its active foreground turn and replacement, reload, rewind, and Stop report the failure. Accepting new work after an ambiguous interruption would create a split-brain session. ## Relationships Agents can launch other agents via the agent-scoped `create_agent` MCP tool. Agent-scoped creation is always asynchronous and always stamps `paseo.parent-agent-id`, pointing back at the caller. Omit `workspaceId` to use the caller's workspace, or pass an existing workspace ID returned by `create_workspace`. Placement never changes parentage. - **Subagents** — exist as part of the creating agent's work, appear in that agent's subagent track, and are archived with it. - **Detached agents** — stand on their own after an explicit detach transition, do not appear in the former parent's subagent track, and are not archived with it. Parent archive detaches a subagent instead of archiving it when either condition holds: - The child belongs to another workspace. - The child is currently open in an agent tab. All other children archive with the parent. After the workspace layout hydrates, the client marks every managed subagent present in its tabs with `paseo.open-agent-tab.=true` through the generic agent metadata update. This includes background and restored tabs; navigation does not own the marker. Closing a tab sets that client's label to `false`. Any `true` client label keeps the child open. Detach clears the parent and every open-tab label. The surviving child therefore becomes a normal root agent immediately, and closing its still-open tab archives it. Runtime ownership is resolved from explicit workspace ID and caller context, never from `cwd`. Workspace creation is a separate operation with `local | worktree` isolation; agent creation reuses that workspace unless a new workspace is explicitly requested. Setup belongs to the workspace, including combined workspace-plus-agent creation and the supported agent `worktree` request. Run setup through the workspace workflow before launching configured terminals or scripts. Setup output is read in the Setup panel from per-command snapshots; never produce setup chat timeline rows or concatenate command logs. Legacy agent `git`/`worktreeName` inputs and hidden MCP worktree placement are rejected with workspace-creation guidance. Existing wire schemas retain an empty combined-log string for parsing compatibility. Users can also detach an existing subagent from the subagents track. Detach is deliberately a manual lifecycle gesture, not an agent-facing MCP tool. It removes the parent and open-tab lifecycle labels: it does not stop, archive, move, or restart the agent. The agent keeps its current `cwd` and `workspaceId`, leaves the former parent's track, and behaves like a root agent for tab close, workspace activity, and future parent archive. `notifyOnFinish` defaults to `true` for agent-scoped creation and prompt follow-ups because most delegated work needs to report back to the creating agent. Set it to `false` for explicit reporting or no completion callback. Agent-originated messages and automatic notifications share a recipient-daemon delivery module. A queued receipt acknowledges admission before provider dispatch, allowing a child to report and finish in the same two-second quiet window. Human prompts dispatch directly. Conflicting explicit interruption or session-mode choices retain separate ordered dispatches. The pending window is in memory. Clean shutdown flushes it before closing agents; an abrupt crash can lose it. A durable send receipt remains pending until actual dispatch acknowledgment, so a lost window never becomes a completed receipt. Completion waits cover queued admission within their original timeout and cancellation scope. Permission requests are notification checkpoints, not the end of that subscription. The caller is notified again after a permission response when the child finishes, errors, or requests another permission. The permission notification includes the normalized request plus the child and request IDs, so the caller can inspect it and respond without fetching agent status. A watched child that closes before its finish event also notifies the caller so delegated work cannot disappear silently during archive or workspace teardown. ## Provider-managed child agents Some providers can create their own child sessions inside one provider runtime. OMP's task tool reports these with `child_session` events; `AgentManager` imports the live provider handle, stamps `paseo.parent-agent-id`, and surfaces the result as a normal subagent in the parent's subagents track. The provider still owns the underlying runtime. Paseo keeps an agent record so the child can be opened, tracked, archived, and cascaded with the parent, but prompts and history hydration route through the provider adapter for that native child handle. ## Background workspaces `workspace.background` controls discovery only. Background workspaces contain ordinary durable agents and terminals: provider history, plugin hooks, parentage, archive, and restart recovery keep their normal behavior. Visibility is creation-only; selecting an existing workspace cannot change it. New workspaces default to false, inherit the caller workspace's value when an agent creates one without an override, and accept explicit true or false. The daemon derives agent discovery from workspace ownership. Default workspace and agent lists, including History requests, exclude background work; `filter.includeBackground` includes it. Exact-ID operations bypass discovery filtering. The app replicates both kinds and filters only its sidebar with **Show background**, so direct navigation and restored tabs remain available. Sequenced directories keep complete canonical collections. A filtered read must never replace those collections with its subset. Inclusive and default observations have distinct cursor scopes, so changing scope requires a fresh snapshot rather than reusing an incomplete cache. Clients gate creation and inclusive discovery on `features.backgroundWorkspaces`. ### Private daemon helpers Branch-name and commit-message generators still use private disposable internal runtimes. `AgentManager` does not persist them or their provider sessions, excludes them from public discovery and plugin hooks, and drops their timelines on archive. An archived helper retains its exact-ID result briefly to cover completion before a waiter attaches. This internal lifecycle is separate from public workspace visibility and is not a public creation option. ## Archive Archive is a **soft delete**: the agent record stays on disk with `archivedAt` set, the runtime is closed, and the agent disappears from active lists. Archive is **global** — it lives on the server and propagates to every connected client. Archive sets `archivedAt`, invokes the provider's native archive hook, and cascades to managed children. `create_agent_request` can opt an agent into `autoArchive`. In that mode the daemon archives the agent after the first terminal turn event (`turn_completed`, `turn_failed`, or `turn_canceled`). When the agent owns an isolated workspace, auto-archive archives that workspace too; the managed worktree is removed when its final workspace reference is gone. Archiving runs through `AgentManager.archiveAgent` (`packages/server/src/server/agent/agent-manager.ts`): 1. Snapshot the current session into the registry 2. Set `archivedAt` and normalize `lastStatus` away from `running`/`initializing` 3. Notify subscribers 4. Close the runtime (kills the process if still running) 5. **Resolve children** — detach cross-workspace and open-tab children; cascade-archive the rest recursively Cascade is what keeps subagent fleets from outliving their orchestrator. Workspace archive is a separate lifecycle. Archiving or removing a worktree can close a surviving agent record without setting the agent's `archivedAt`, while its `workspaceId` still points at the archived workspace. History navigation must not infer workspace lifecycle from `agent.archivedAt` or mutate either lifecycle. The workspace route asks the daemon for authoritative recovery state; only the route's explicit Unarchive or Restore action changes the archived workspace. History navigation opens the selected agent without changing either archive state. Workspace **Restore** recovers only the workspace; the selected archived agent stays open with its callout. The agent's **Unarchive** runs the provider's native unarchive hook before interactive resume and history hydration. Other archived agents stay archived. Opening an agent is a navigation choice, independent of whether its details are cached. The layout retains that choice across reload while the panel fetches the agent from the daemon. Once the daemon reports the agent active, its tab follows normal archive propagation again. An empty active list cannot cancel an explicit History selection. Agent-detail loading does not own selection or release the explicit open. Persisted resume, native restore, and both live and stored-only archive enter the same per-agent lifecycle queue. Resume chooses its history or interactive purpose from the durable record after entering that queue. Shutdown must finish before the manager releases runtime ownership; a failed close retains the runtime for cleanup and blocks replacement through that close operation. Authoritative timeline catch-up can use a runtime-only `history` resume purpose. The retained history session contains only the read results and must release its provider process once replay finishes. Codex reads the persisted thread and child histories on a temporary app-server and never loads, resumes, or unarchives a native thread, including legacy records whose native archive failed. ACP providers spawn the CLI, replay the session through `session/load`, and terminate the process before returning. Interactive resume remains responsible for repairing a provider session archived outside Paseo while its Paseo agent is active. Provider session connection owns every process it spawns until the session is registered with `AgentManager`. If initialization, persisted-session resume, or initial history hydration fails, `connect()` must dispose that process before rethrowing; the manager cannot clean up a session it never received. ## Tabs vs archive These are two distinct concepts that used to be conflated: | Concept | Scope | Triggers | | -------------------------- | ---------- | -------------------------- | | **Tab** (workspace layout) | Per-client | User opens/closes a view | | **Archive** (lifecycle) | Global | Explicit lifecycle gesture | Closing a tab on a **root agent** still archives — the tab is the agent's home, so closing it means "I'm done with this agent." A confirm dialog protects against archiving a running agent by accident. Closing a tab on a **subagent** (any agent with `parentAgentId`) is **layout-only**. The app clears the current client's open-tab label before removing the tab. Another client's open tab remains protected. The agent stays unarchived and stays in its parent's track, so a later parent archive cascades to it when no client still has it open. The user can re-open the tab from the track at any time. Single and bulk tab close apply the same policy. The asymmetry is intentional: a subagent's persistent relationship lives in the parent's track. Same-workspace subagents are not auto-opened as tabs; the user opens one from that track when needed. A cross-workspace subagent is also auto-opened as a tab in its own workspace so opening that workspace does not appear empty. It remains in the parent's track until it is actually detached. ## Workspace activity Agent lifecycle status stays literal: a parent agent is `idle` when its own turn is idle, even if a child is running. Workspace status is an aggregate activity signal computed **per `workspaceId`**. Ownership is never derived from `cwd` — many workspaces may share one directory, and same-`cwd` siblings do not clump under one status. Root agents and cross-workspace subagents contribute their normal state bucket to their own workspace. Same-workspace descendants contribute `running` to the nearest ancestor in that workspace; their non-running attention, permission, and error states stay in the parent's subagents track. This makes a cross-workspace subagent behave like a detached agent for workspace visibility and status without removing its parent relationship. Running provider-native subagents contribute `running` to the workspace owned by their parent agent. Their completed, failed, and canceled states stay in the parent's subagents track. A finished workspace can be marked unread after it has been reviewed. The daemon restores `finished` attention on its newest eligible workspace-root agent without sending a new completion notification. Opening the workspace clears that attention through the normal focus flow. Attention is set by the agent finishing or failing and cleared by the client's `workspace.clear_attention`, which fires when the user reads the chat. Loading an agent's runtime is neither, so resuming carries the stored attention and the stored last-activity time through untouched. Forging either makes a background resume look like the user read a workspace and like the agent worked in it just now, which rewrites the sidebar timestamp permanently — persisted `updatedAt` is what workspace `statusEnteredAt` is re-derived from on the next daemon start. ## The subagents track The track is a pill at the foot of an agent's pane (`packages/app/src/subagents/track.tsx`): a count you can read at a glance, and a panel behind it — a popover on wide screens, a sheet on compact ones — holding the rows. It floats over the transcript rather than sitting in a band above the composer, so the timeline scrolls underneath it; `packages/app/src/panels/agent-tracks.tsx` owns that placement, and the pill frame is shared with the task list in `packages/app/src/composer/tracks.tsx`. The rows combine two kinds of children: - **Paseo subagents** are full managed agents. Their membership rule (`packages/app/src/subagents/select.ts`) is: ``` parentAgentId === thisAgent.id AND !archivedAt ``` - **Provider subagents** are child executions owned by Claude, Codex, or OpenCode. They are not inserted into `AgentManager` as managed agents. Providers emit a separate descriptor and timeline stream through `agent.provider_subagents.*`; the client keeps that state outside the normal agent store and merges only the presentation rows into the track. A descriptor's optional `parentSubagentId` identifies its direct provider-subagent parent; an absent value identifies a direct child of the managed agent. Clicking either kind opens a workspace tab. On compact layouts it opens in a [sheet](explorer-sidebar.md#sheets) over the subagents list instead; the sheet hides the composer and shows the agent's model and thinking as one line in its place (`PaneSubtitle`, the row provider subagents already use), and a Paseo subagent's sheet offers **Open as tab** (the full-screen glyph in the header) to get the composer back. A Paseo subagent tab is a normal interactive agent pane. A provider subagent tab is a read-only timeline pane with no composer, archive, detach, rewind, or fork actions. It shows its own direct children in a subagents track. Both panes use `AgentStreamView`, so message, reasoning, tool-call, and layout rendering stay identical. Provider timelines use the same structural timeline item format but deliberately have a separate lifecycle and transport. A provider thread/session identifier is not a Paseo agent identifier, and closing its tab is always layout-only. Provider descriptors may include one compact subtitle. The provider owns its contents and formatting; clients display and truncate it without interpreting provider-specific model, thinking, or usage fields. ### Claude provider subagents: the task protocol Claude Code announces subagent lifecycle on the SDK stream (`task_started` / `task_updated` / `task_notification` / `task_progress`), and Paseo reads those announcements rather than reconstructing them from sidechain frames. The live source (`subagents/live-source.ts`) and the replay source (`subagents/replay-source.ts`) both translate into one observation vocabulary (`subagents/observation.ts`), so a fact is derived once for both paths instead of once per path. Gotchas that are not obvious from the SDK types: - **Not every announced task belongs in the track.** Task subagents announce as `local_agent` and workflows as `local_workflow`; a backgrounded shell announces as `local_bash` with the same `tool_use_id` shape, and ambient housekeeping sets `skip_transcript`. The Claude provider normalizes a workflow to a generic provider-subagent descriptor titled `Workflow`, using Claude's summary as its description and timeline opener. Shared storage, protocol, and UI do not distinguish it from another provider subagent. - **A task that was never declared gets no descriptor, by any route.** Filtered tasks still emit `task_notification`s carrying a `tool_use_id`, and still emit frames carrying `parent_tool_use_id`. Attributing either produces a descriptor with no identity and a defaulted `running` status — a nameless row that never finishes. Status, presentation updates, and sidechain frames all route through the declaration table. - **Task ids are session-scoped, not turn-scoped.** Cancelling a turn must not clear the routing table: a backgrounded child settles after the interrupt and needs its descriptor to still exist. Cancellation instead terminalizes the declared children that were running in the foreground, and a later `task_notification` is free to correct that guess. Backgrounded children are identified by `is_backgrounded` on `task_started` (set at spawn; a resumed subagent is always background) or, when moved there later, on `task_updated.patch`. - **A resumed task can be announced again with a new `tool_use_id`.** The first Task tool id remains the canonical descriptor and later ids are routing aliases for the same session-scoped task. The resumed prompt is added to that child timeline. - **Effort is only reachable through hooks.** It appears nowhere on the message stream at any depth, and the level Paseo requests is not necessarily the level that runs — a model that does not support it is silently downgraded. A hook firing inside a subagent reports the active post-downgrade level next to its `agent_id`, which is the same id `task_started` calls `task_id`. - **Backgrounded subagents emit no frames carrying `parent_tool_use_id` at all.** Everything keyed off that field sees nothing for one; they are visible only because the task protocol announces them. - **Only `system/init` and `result` bracket a main-session turn.** Background subagents emit neither on the main stream, while their task frames, their own background jobs' `task_notification`, and `rate_limit_event` arrive with no `parent_tool_use_id`, the same shape as main-session work. `session_state_changed` stays `running` for as long as any background subagent lives (Claude Code 2.1.280), so it cannot open a turn; its `idle` can close one. - **Nested ownership comes from the launching sidechain, not `spawn_depth` alone.** A sidechain's Agent or Bash tool call records the direct owner of that `tool_use_id`; the following `task_started` inherits it. This routes a grandchild descriptor and child-owned background notifications without relying on labels or flattening them into the managed parent. - **On replay, `/subagents/` holds every descendant beside the root.** Resolve the tree one proven generation at a time: the root transcript admits direct children, then each admitted sidechain transcript admits its children by `toolUseId`. `spawnDepth` orders candidates but does not establish ownership. Unresolved sidecars remain excluded as ambient or unrelated work. - **Replay `totalTokens` is a context-size reading, not cumulative spend.** Claude Code finalizes a subagent by summing the _last_ assistant message's usage block and shipping that as `usage.total_tokens`. Summing per-entry usage instead multiplies the cached prefix by the turn count and reports a number several times larger than the live path. Archived Paseo subagents disappear from the track, by design. To remove one from the track without closing its tab, use the **archive button** on the row — it opens a confirm dialog and archives the subagent on confirm. Provider-owned rows have no individual Paseo lifecycle controls. The **Archive finished** row at the foot of the panel covers every finished row. It archives idle or errored managed Paseo subagents one at a time, and hides completed, failed, or canceled provider-owned rows in the current app session. Native sessions and timelines are untouched. Running and initializing children remain in the track. If a hidden provider child starts running again, the app brings it back to the track. To keep the agent alive but remove it from the parent's track, use **detach**. The daemon clears the relationship lifecycle labels, emits the normal agent update, and every client reclassifies the agent from subagent to root/sibling from that updated snapshot. ## Why this shape The decision was to **decouple "close tab" from "archive" only for subagents**, rather than universally: - **Closing a tab on a root agent still archives** — preserves the existing UX users are trained on - **Closing a tab on a subagent is layout-only** — fixes the lossy "click to read, close to dismiss view, lose the row" flow - **Archive button on track rows** — gives subagents an explicit lifecycle gesture in their home surface - **Detach button on track rows** — lets a subagent continue independently without killing its work - **Cascade archive on parent** — keeps subagents from leaking when the parent is archived We considered universal decoupling (no tab close ever archives, archive is always explicit) but rejected it: it changes a behavior root-agent users rely on. ## Limitations ### Subagent accumulation under long-lived parents A parent that spawns many subagents will see the panel's list grow; the pill only counts them. Managed Paseo subagents can be archived individually or with **Archive finished**. That action hides finished provider-owned rows locally; this presentation state resets when the app restarts. ### Cross-client tab dismissal Closing a subagent's tab on one client doesn't affect other clients' layouts. This is the expected behavior of decoupled tabs and is consistent with how layouts have always worked. Archive remains the global gesture for cross-client cleanup. ## Storage ``` $PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json ``` `{cwd-with-dashes}` is derived from the agent's filesystem `cwd`. It is not the workspace id; agent storage stays cwd-keyed while workspace identity is the opaque workspace id. Each agent is a single JSON file. Fields relevant to this doc: | Field | Type | Meaning | | -------------------------------------------- | ------------- | ---------------------------------------------------------------------------------- | | `id` | `string` | Stable identifier | | `archivedAt` | `string?` | Soft-delete timestamp (ISO 8601) | | `labels["paseo.parent-agent-id"]` | `string?` | Parent agent ID, set automatically for agent-scoped creation and removed by detach | | `labels["paseo.open-agent-tab."]` | `string?` | `"true"` protects an open tab on that client; detach clears every matching label | | `lastStatus` | `AgentStatus` | `initializing` / `idle` / `running` / `error` / `closed` | See [`docs/data-model.md`](./data-model.md) for the full agent record. --- ### Agent Stream Performance (`docs/agent-stream-performance.md`) # Agent stream performance How assistant text gets from a provider to the screen, and why it is paced on the way. Read this before changing `packages/server/src/server/agent/agent-stream-coalescer.ts`, the reducer queue in `packages/app/src/timeline/session-stream-reducers.ts`, or the reveal in `packages/app/src/hooks/use-revealed-text.ts`. For terminal output, which is a separate pipeline with separate budgets, see [terminal-performance.md](terminal-performance.md). ## The pipeline ``` provider deltas (every provider streams incrementally) → AgentStreamCoalescer (daemon, leading + trailing, ≤1 message per 60ms per agent) → recordTimeline: one canonical row per flushed item → agent_stream ws message → reducer queue (app, one commit per frame) → session store → source-item plugin transforms → Markdown presentation / tool grouping → paced reveal (app, per displayed item) → paint ``` Every provider delivers incremental text, so there is no provider that needs special handling: Claude via `includePartialMessages`, Codex via `agent_message_delta`, ACP agents via `agent_message_chunk`, Pi and OMP via `text_delta`. ## Why the reveal is paced Arrival is lumpy and there is no fixing that at the source. A 60ms coalescing window carries however many characters the model produced in those 60ms, which swings by an order of magnitude within a single turn. Painting each delta as it lands makes the size of those lumps visible, and that is what reads as jagged. So arrival sets a _target_ and the reveal rate is derived from the backlog instead. A burst makes the text catch up faster; it does not make the text jump. Shrinking the coalescing window does not fix this — it makes the lumps smaller and more frequent, at the cost of message rate on a daemon loop that already contends with terminal frames and per-message relay encryption. ## Invariants - **The coalescer is leading + trailing.** The first delta after an idle window flushes synchronously; only the rest of the burst waits for the trailing timer. Reverting to trailing-only adds a full window to the first character of every turn. Same shape and the same reason as `TerminalOutputCoalescer`. - **The leading flush adds a canonical row, and that is fine.** A burst's first chunk lands as its own timeline row. `mergeAssistantChunks` / `mergeReasoningChunks` in `timeline-projection.ts` join contiguous same-turn rows, and clients read the projected timeline, so history is unaffected. Tests that assert on raw rows have to account for the extra row; tests that assert on what a client sees do not. - **The store holds the full text; only the rendered slice is paced.** Copy, selection, the chat outline, and scroll geometry all read the same string the user can see. Pacing the store instead would leave the bottom anchor chasing a content height that is ahead of the reveal. - **One source assistant message is one display row.** Presentation projects plugin output and caches unchanged history. The shared [Markdown renderer](markdown-renderer.md) owns rendering on every platform. Chat paces the visible source and applies a 32,000-character render cap on web; native keeps the complete message. The native renderer keeps closed blocks in a stable head and sends the paced suffix to a separate tail view during streaming; completion reunites them for selection. This stays inside the renderer, without promoting blocks into timeline history. - **Message identity survives completion.** Assistant row ids are source message ids. Plugin rows can replace a source, so find, scroll-to-message and history reveal still use `getStreamItemMessageId`. Width-specific measurements describe whole rendered messages. - **First sight of a text is revealed whole.** Only growth is paced. This is what makes history hydration, timeline replay, a virtualized row remounting on scroll, and an already-finished message all render complete on first paint without a special case for each. - **Leaving `phase: "streaming"` snaps the reveal.** A completed turn must never be left holding characters. `layoutStream` sets the phase, so anything outside the live head with an active turn is already complete. - **The reducer queue commits on a frame, with a timer as the ceiling.** A frame callback never fires in a hidden tab, so a timer races it and wins when nothing is painting — the store has to keep advancing either way. - **A history row re-renders only when its item or layout item identity changes.** The inverted FlatList hands every mounted cell a new `index` and `ref` whenever a row is prepended, so without a memo boundary each coalesced tick re-rendered every mounted row (about 50 on a phone, 100–250 ms of JS per tick). `layoutStream` keeps a layout item's identity when nothing about it changed, `useRevisedHistoryRows` hands a fresh item identity to rows whose tool-call group, expanded state, or breakpoint changed, and `StreamRow` memoizes on both. Every viewport runs its history through that hook; the web viewport once skipped it and history hosts of a live tool group went stale. A new field on `StreamLayoutItem` must be added to `areLayoutItemsEquivalent`, or sharing silently stops. - **Streaming cost must not grow with revealed history.** Reading older messages must not make the next reply progressively more expensive to display. Reuse unchanged history work while text arrives, and release obsolete window caches as the reader reveals more history; window caches must stay bounded while their source timeline remains loaded. ## Native parsing cost The native library reparses and measures its entire `markdown` prop on each update. During streaming, the renderer splits source at an mdast block boundary and memoizes the head, so per-frame updates parse only the tail. Boundary discovery runs when a source line completes, rather than on every reveal frame. The unfinished line and final parsed block stay in the tail, preserving list continuation, setext headings, tables and open fences. Reference-dependent source and HTML retain a larger tail because later source can change their meaning. A single long block therefore still carries its full parsing cost. Completion restores one native text view per Mermaid-delimited segment, so selection crosses prose paragraphs again. The head retains its trailing block margin while split. JS reveal remains the pacing source; native opacity animation stays disabled. ## Measuring - **Smoothness (user-perceived):** `packages/app/e2e/browser/agent-stream-smoothness.spec.ts`, gated behind `PASEO_AGENT_STREAM_PERF_E2E=1`. Drives the mock provider's `bursty-stream` model and reports coefficient of variation of characters painted per frame (smoothness) plus p95 gap between visible updates (stalls). Both numbers are needed: a stalled stream is perfectly smooth. - **Reproducing bursty arrival:** the `bursty-stream` model in `mock-load-test-agent.ts` emits uneven runs of tokens separated by idle gaps. Burst sizes come from a seeded generator, so a run repeats exactly. - **Rate policy in isolation:** `computeRevealStep` in `packages/app/src/agent-stream/text-reveal.ts` is pure; `text-reveal.test.ts` covers convergence and burst flattening without a renderer. - **Per-delta cost on a long timeline:** `npx vitest bench --project unit src/agent-stream/stream-tick.bench.ts` from `packages/app` replays 200 deltas over a 2,000-item timeline through the pure model and layout pipeline, with the default mounted window and with history fully revealed. It measures the JS work per delta, not paint. Healthy numbers (2026-08, Expo web against a local dev daemon, real Claude Haiku agent, ~8.5s samples during active streaming). Setting `TEXT_REVEAL_HORIZON_MS` to 0 makes the reveal paint on arrival, which is how the baseline column was taken: | | paint on arrival | paced | | -------------------------------- | ---------------- | ----- | | frames that advanced the text | 6% | 87% | | chars-per-frame CV | 4.11 | 1.86 | | gap between visible updates, p50 | 317ms | 17ms | | gap between visible updates, p95 | 383ms | 17ms | Total characters painted is roughly the same either way — the reveal changes when they land, not how many arrive. Measure the **total** length across every `assistant-message` element, not the last one. A turn emits many assistant messages, so the tail element keeps changing identity and its length is not monotonic; sampling only the tail reads those handovers as resets and reports almost no growth. `sampleStreamFrames` does this correctly. --- ### Android (`docs/android.md`) # Android ## App variants Controlled by `APP_VARIANT` in `packages/app/app.config.js` (vanilla Expo, no custom Gradle plugin): | Variant | App name | Package ID | | ------------- | ----------- | ---------------- | | `production` | Paseo | `sh.paseo` | | `development` | Paseo Debug | `sh.paseo.debug` | EAS profiles: `development`, `production`, and `production-apk` in `packages/app/eas.json`. `development` uses Android `debug`. ## Version codes `packages/app/native-release-version.js` is the single definition of native and F-Droid version-code math. Do not re-derive these numbers anywhere else — a drifted copy produces changelog files that match no published APK, and nothing fails loudly. The base version code comes from the package version: ```text major * 1_000_000 + minor * 1_000 + patch ``` Prerelease metadata is ignored, so `0.1.102-beta.1` and `0.1.102` both produce `1102`. The same value is used as the iOS `buildNumber` because `packages/app/eas.json` uses EAS's local app version source. Do not re-enable EAS remote version counters or Android `autoIncrement`; F-Droid and other source-based builders need the native build number to be visible in the repo. The formula reserves three digits each for minor and patch. If either reaches `1000`, change the formula before cutting that release. ## Prerequisites (local dev) Local Android builds run on macOS (or Linux) and need the Android toolchain, pinned in `.tool-versions` (`java 21`, `android-sdk 21.0`) and wired up by `.mise.toml` (which derives `ANDROID_HOME` and the command-line tool paths from the `android-sdk` entry). With [mise](https://mise.jdx.dev): ```bash mise install # java 21 + android-sdk 21.0 command-line tools ``` > **Pin a real `android-sdk` version, not `latest`.** The mise `android-sdk` plugin's `latest` resolved to the ancient `1.0` bundle, whose `sdkmanager` (3.6.0) predates the `emulator` package and fails with `Failed to find package emulator`. `21.0` ships a current `sdkmanager`. If you bump it, update only the version in `.tool-versions`; `.mise.toml` derives its paths from that tool entry. `mise install` only lays down the command-line tools. Install the rest and create an emulator. On Apple Silicon: ```bash sdkmanager --licenses sdkmanager "platform-tools" "emulator" "platforms;android-35" "build-tools;35.0.0" \ "system-images;android-35;google_apis;arm64-v8a" avdmanager create avd -n paseo -k "system-images;android-35;google_apis;arm64-v8a" -d pixel_7 emulator @paseo # start it; leave running ``` On an Intel Mac, use the `x86_64` system image: ```bash sdkmanager --licenses sdkmanager "platform-tools" "emulator" "platforms;android-35" "build-tools;35.0.0" \ "system-images;android-35;google_apis;x86_64" avdmanager create avd -n paseo -k "system-images;android-35;google_apis;x86_64" -d pixel_7 emulator @paseo # start it; leave running ``` Gradle auto-fetches the platform/build-tools it needs once licenses are accepted, so adjust `android-35` only if it asks for a different level. ## Local build + install The locked `expo-modules-core@57.0.23` needs the patch installed by `npm install`. It backports [Expo's Activity-result launcher fix](https://github.com/expo/expo/pull/49634): changing font size or another unhandled configuration can otherwise disable image selection until the app process restarts. Rebuild the native app after changing this patch; a Metro reload cannot update it. Remove the patch when the installed `expo-modules-core` includes the fix. Run its native regression tests from `packages/app/android` after prebuild: ```bash ./gradlew :expo-modules-core:testDebugUnitTest \ --tests expo.modules.kotlin.activityresult.AppContextActivityResultRegistryRecreationTest \ --no-daemon --max-workers=1 -Dorg.gradle.parallel=false ``` From repo root: ```bash npm run build:apk # Universal dogfood APK: 32/64-bit ARM and x86 npm run build:apk:arm64 # Smaller dogfood APK for ARM64 phones npm run dev:android # Build/install the debug app and start development npm run dev:ios # Build/install the iOS development app ``` `build:apk` writes `artifacts/paseo-dogfood-universal.apk`; `build:apk:arm64` writes `artifacts/paseo-dogfood-arm64.apk`. Neither command launches or installs on a device. Both enable `PASEO_WATCHDOG_BUILD=1`, the production React profiling renderer, and Android's shell-profileable flag. These builds keep the production package ID (`sh.paseo`) and release optimizations. Use this APK for personal dogfooding. Android system-trace spans require the separate `PASEO_PROFILE_BUILD=1` flag; watchdog recording does not send duplicate spans to that sink by default. Normal store/release workflows leave diagnostics disabled. The older `android`, `android:development`, and `ios` commands remain aliases for development. `android:production` still builds and installs a release through Expo; use `build:apk` when you need an artifact. `android:clear` removes the generated Android project. Run `npm run test:android --workspace=@getpaseo/app` to prebuild Android and run native module unit tests. The app CI job runs this command with the Android toolchain. ### Diagnostic logs without ADB In a dogfood build, open Android's Files app → Downloads → **Paseo diagnostics** and share all retained `.jsonl` files. No app screen, storage permission, or attached debugger is required. The recorder retains eight files of about 5 MiB each across reconnects and app restarts. Rotation replaces the oldest files, so collect them soon after reproducing a freeze. Uninstall/reinstall can leave older Downloads files that the new installation cannot manage. Each file identifies its build and session. Events include application-transport frame sizes and message/request IDs, connection transitions, parse/validation/dispatch spans, named React subtree render timings, and foreground JS heartbeat gaps. Payloads, passwords, and message contents are excluded; connection identifiers include host addresses. Each size has a unit: **bytes** when already available, otherwise **UTF-16 code units** for text. These are client transport observations, after relay decryption where applicable, not packet arrival times. The native recorder flags a heartbeat overdue by more than 500 ms (250 ms expected interval). A heartbeat gap bounds the unresponsive interval; it is not an exact blocked-stack duration. Backgrounding suspends detection. `js.stall.started` can be written while JS remains blocked; `js.stall.recovered` records the gap when JS resumes. Recovery can appear without a start event when JS resumes before the next native sampling tick. Process death leaves earlier files intact, but queued/unflushed records can be lost. A missing recovery event alone does not prove a crash. `react.render.slow` records subtree rendering taking at least 16 ms; one-second summaries include faster renders. Nested profiler timings overlap: don't add parent and child times. React's render measurements do not measure native layout/paint or the complete commit phase. `recorder.dropped` means the bounded queue overflowed; missing events in that interval must not be treated as absence of activity. Storage failure stops recording rather than blocking the app. For an ordinary release APK with system trace markers only: ```bash PASEO_PROFILE_BUILD=1 npm run android:production ``` Those markers emit only while a system trace records `sh.paseo` (`perfetto -a sh.paseo ...`); they do not produce Downloads files. ## Running on an emulator against a worktree daemon `npm run android` builds and installs the dev client, but two connections have to reach your Mac from inside the emulator — Metro (the JS bundle) and the Paseo daemon — and **the emulator does not share the host's loopback**: `localhost` inside the emulator is the emulator itself. Reach the host at `10.0.2.2` (the standard AVD's host alias) for both: ```bash REACT_NATIVE_PACKAGER_HOSTNAME=10.0.2.2 \ EXPO_PUBLIC_LOCAL_DAEMON=10.0.2.2:$PASEO_SERVICE_DAEMON_PORT \ npm run android ``` - **`REACT_NATIVE_PACKAGER_HOSTNAME=10.0.2.2`** — without it, Expo bakes your Mac's LAN IP into the dev client's Metro URL, which the emulator can't route to, and the app dies with `Failed to connect to /:8081` before any JS loads. - **`EXPO_PUBLIC_LOCAL_DAEMON=10.0.2.2:`** — the client's daemon endpoint (`packages/app/src/runtime/host-runtime.ts`); when unset it defaults to `localhost:6767`, the production daemon. Use `$PASEO_SERVICE_DAEMON_PORT` for a worktree daemon running as a Paseo service, or `6768` for a standalone `npm run dev:server`. It is inlined into the JS bundle at Metro bundle time, so set it on the build command and clear the Metro cache (`npx expo start -c`) if a change doesn't take. **Alternative — `adb reverse` + `localhost`** (if `10.0.2.2` misbehaves): ```bash adb reverse tcp:8081 tcp:8081 adb reverse tcp:$PASEO_SERVICE_DAEMON_PORT tcp:$PASEO_SERVICE_DAEMON_PORT REACT_NATIVE_PACKAGER_HOSTNAME=localhost \ EXPO_PUBLIC_LOCAL_DAEMON=localhost:$PASEO_SERVICE_DAEMON_PORT \ npm run android ``` This is the Android counterpart of the iOS local-simulator flow in [development.md](development.md): on iOS the simulator shares the Mac's loopback so `localhost:` works directly; on Android you need `10.0.2.2` or `adb reverse`. ## Inverted timeline selection Android focus and selection visibility requests must not reposition inverted timelines. The `modules/paseo-scroll` package keeps React Native's scroll manager interface and returns zero for child-reveal scroll calculations when the view's transform matrix inverts the vertical axis. React Native's Android list uses `scale: -1`, which decomposes into a 180-degree rotation with positive `scaleY`; checking the scale property alone misses it. Dragging and explicit scroll commands still work; non-inverted scroll views keep Android's default behavior. Register this package before React Native's core package through its Expo config plugin. Normal Android builds use the prebuilt `react-android` library, so patching Java under `node_modules` does not change the shipped scroll view. Keep this behavior in the app's compiled native module. ## F-Droid / source-only Android builds F-Droid builds should set `PASEO_FDROID_BUILD=1` when running Expo prebuild: ```bash cd packages/app PASEO_FDROID_BUILD=1 APP_VARIANT=production npx expo prebuild --platform android --clean --non-interactive cd android PASEO_FDROID_BUILD=1 ./gradlew assembleRelease --no-daemon --max-workers=1 -Dorg.gradle.parallel=false ``` The flag must be present for both prebuild and Gradle because Gradle starts Metro for the release bundle. Keep the source build serial and daemon-free as shown above: compiling every Expo module can exhaust memory when Gradle workers run in parallel. The profile enables source-built Expo modules, excludes the proprietary camera, Firebase notification, and Expo development-client native modules, disables Gradle dependency metadata, and substitutes JavaScript stubs for camera and notifications. The resulting app supports direct and pasted-link pairing but not QR scanning or push notifications. For a single-ABI APK, pass React Native's architecture property to Gradle: ```bash PASEO_FDROID_BUILD=1 ./gradlew assembleRelease \ -PreactNativeArchitectures=arm64-v8a \ --no-daemon --max-workers=1 -Dorg.gradle.parallel=false ``` Supported values are `armeabi-v7a`, `arm64-v8a`, `x86`, and `x86_64`. The F-Droid profile filters native libraries to that ABI and changes the APK version code to `baseVersionCode * 10 + abiSuffix`, where the suffixes are ordered `1` through `4` in that same sequence. F-Droid metadata should use four build blocks with `VercodeOperation` entries `10 * %c + 1` through `10 * %c + 4` and pass the matching `reactNativeArchitectures` value in each build command. Builds without a single architecture keep the base version code. Keep the excluded npm packages installed. Normal builds use them, while the F-Droid profile removes only their Android native modules and config plugins. Paseo always applies `expo-gradle-jvmargs` with `-Xmx4096m` and `-XX:MaxMetaspaceSize=1024m` so local Expo prebuilds have enough Gradle heap whether they use precompiled AARs or source-built Expo modules. The EAS `production-apk` profile uses the large Android resource class. Release builds compile the native ABIs and run Hermes bundling in the same Gradle invocation; the default worker can exhaust its remaining memory and kill Hermes with exit code 137 even when Gradle's own heap is correctly sized. ### F-Droid store metadata F-Droid reads the store listing from `fastlane/metadata/android//` **at the repo root**. This location provides the best compatibility with the F-Droid release process. ```text fastlane/metadata/android/ ├── en-US/ (F-Droid fallback locale, mandatory) │ ├── title.txt (<=50 chars) │ ├── short_description.txt (<=80 chars) │ ├── full_description.txt (<=4000 chars, limited HTML) │ ├── images/ │ │ ├── icon.png (512x512) │ │ ├── featureGraphic.png (1024x500) │ │ └── phoneScreenshots/ (1.png, 2.png, ...) │ └── changelogs/ (generated — see below) ├── ja/ └── zh-CN/ ``` Locale directories generally match `packages/app/src/i18n/locales.ts`, but note that `en` becomes `en-US`. F-Droid changelogs are generated from `CHANGELOG.md`. Run `npm run fdroid:changelogs`; `npm run fdroid:changelogs:check` verifies without writing. It is wired into the npm `version` lifecycle, so a release picks it up automatically and `git add -A` stages the result. One changelog must be generated per-ABI-split, so each version will create **four** identical version-coded entries. F-Droid caps changelogs at 500 characters, so the generator strips some content and adds a link to the full notes. Stable sync fails loudly if `CHANGELOG.md` has no entry for the version being cut. That is intentional — the release checklist requires the entry to be committed first, so an abort here means the checklist was skipped. Because the generator runs off the version in `package.json`, it must run **before** the tag is created: fdroidserver only reads metadata from the tag it builds, so the file for version N has to exist in the commit N points at. Beta releases are an explicit no-op: they do not create or rewrite F-Droid changelog files. Stable releases and promotions generate the four ABI entries from their final changelog. ### React version lockstep Keep `react` and `react-dom` pinned to the React version embedded by the current `react-native` release. React Native `0.81.x` embeds `react-native-renderer` `19.1.0`, so `packages/app` must use React `19.1.0`. Bumping React to a newer patch can build successfully but crash at JS startup on Android with `Incompatible React versions`, leaving the app on the native splash screen. ## Screenshots ```bash adb exec-out screencap -p > screenshot.png ``` ## Cloud build + submit (EAS) Stable tag pushes like `v0.1.0` trigger: - The EAS GitHub app on Expo servers, using `packages/app/.eas/workflows/release-mobile.yml` (iOS + Android production builds and distribution). - `.github/workflows/android-apk-release.yml` on GitHub Actions (APK asset on GitHub Release). iOS distributes the same build to external TestFlight testers and App Store review; see [Mobile builds (EAS)](release.md#mobile-builds-eas) for the review paths. Android auto-submits to the Play Store via EAS-managed credentials. Beta tags like `v0.1.1-beta.1` trigger the GitHub APK workflow and EAS `Release iOS Beta`. They publish a GitHub prerelease APK and distribute iOS through TestFlight without submitting to production stores. `android-v*` tags also trigger only the GitHub APK workflow — useful when you want to ship an APK without going through stores. The GitHub APK workflow supports `workflow_dispatch` with an existing `tag` input so you can rebuild without cutting a new tag. ### Useful commands ```bash cd packages/app # Recent builds npx eas build:list --limit 10 --non-interactive --json | jq '.[] | {platform, status, appVersion, gitCommitHash}' # Inspect a build (the printed `Logs` URL opens the build's Expo dashboard page, # which has a Submissions section showing the auto-submit to the Play Store). npx eas build:view ``` The Play Console (Internal testing → Production tracks) is the final confirmation that the binary reached the store. See [docs/release.md](release.md) for the full mobile-build babysitting flow. --- ### Architecture (`docs/architecture.md`) # Architecture Paseo is a client-server system for monitoring and controlling local AI coding agents. The daemon runs on your machine, manages agent processes, and streams their output in real time over WebSocket. Clients (mobile app, CLI, desktop app) connect to the daemon to observe and interact with agents. Your code never leaves your machine. Paseo is local-first. Daemon-owned outbound connections and routed API scope ownership are described in [Connected hosts](connected-hosts.md). ## System overview ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Mobile App │ │ CLI │ │ Desktop App │ │ (Expo) │ │ (Commander) │ │ (Electron) │ └──────┬───────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ WebSocket │ WebSocket │ Managed subprocess │ (direct or │ (direct) │ + WebSocket │ via relay) │ │ └───────────┬───────┴──────────────────┘ │ ┌──────▼──────┐ │ Daemon │ │ (Node.js) │ └──────┬──────┘ │ ┌────────────┼────────────┬────────────┬────────────┐ │ │ │ │ │ ┌─────▼─────┐ ┌───▼────┐ ┌──────▼─────┐ ┌────▼─────┐ ┌────▼────┐ │ Claude │ │ Codex │ │ Copilot │ │ OpenCode │ │ Pi │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ SDK │ │ Server │ │ ACP │ │ │ │ │ └───────────┘ └────────┘ └────────────┘ └──────────┘ └─────────┘ ``` ## Components at a glance - **Daemon:** Local server that spawns and manages agent processes and exposes the WebSocket API. - **App:** Cross-platform Expo client for iOS, Android, web, and the shared UI used by desktop. - **CLI:** Terminal interface for agent workflows that can also start and manage the daemon. - **Desktop app:** Electron wrapper around the web app that bundles and auto-manages its own daemon. - **Relay:** Optional encrypted bridge for remote access without opening ports directly. ## Packages ### `packages/server` — The daemon The heart of Paseo. A Node.js process that: - Listens for WebSocket connections from clients - Manages agent lifecycle (create, run, stop, resume, archive) - Streams agent output in real time via a timeline model - Provides agent-to-agent tools through a transport-neutral tool catalog, with MCP as one adapter - Optionally connects outbound to a relay for remote access - Optionally serves the browser web client from the same HTTP server (self-hosting guide: [public-docs/web-ui.md](../public-docs/web-ui.md)) All paths are under `packages/server/src/`. Desktop and CLI import server capabilities through explicit package subpaths such as `@getpaseo/server/daemon-control`, `/configuration`, and `/process`. The root export loads daemon bootstrap eagerly, even when a caller only uses a path or process helper. Keep process-management and configuration dependencies independent of bootstrap and WebSocket message schemas. Shared configuration schemas belong in protocol leaf modules; `messages` imports and re-exports them. This prevents every supervising process from retaining the daemon's runtime and wire-schema allocations. The server export tests guard these dependency trees with tree-shaking disabled to match unbundled production imports. Project identity is daemon-global rather than session-owned. After registry bootstrap, the daemon's project Git observer keeps one non-recursive watch on each lexically equivalent active project root and listens only for the root `.git` entry, with a slow rescan as a missed-event fallback. It runs for empty projects and without connected clients, then fans metadata changes through the WebSocket server to capability-aware sessions. It deliberately does not use the broad recursive working-tree watcher or the per-session Git observer: those are checkout/status mechanisms and intentionally do not retain non-Git directories. Workspace git and forge runtime data belongs to one daemon-level, directory-keyed store. Workspace descriptors, checkout diff subscriptions, and script metadata read the last known snapshot from that store, so reconnecting clients receive it before refresh completes. Refcounted git watches feed the store through snapshot-updated events; their lifetime controls refresh only. Session cleanup and workspace archive retain the data. Removing the final active workspace for a directory clears it. The store lives in memory and resets on daemon restart. **Key modules:** | Module | Responsibility | | ------------------------------- | ------------------------------------------------------------------------------ | | `server/bootstrap.ts` | Daemon initialization: HTTP server, WS server, agent manager, storage, relay | | `server/websocket-server.ts` | WebSocket connection management, hello handshake, binary frame routing | | `server/session.ts` | Per-client session state, timeline subscriptions, terminal operations | | `server/directory-sync/` | Daemon-global latest-state sequences for projects, workspaces, and agents | | `server/workspace-labels/` | Host-local label catalog, assignment mutations, and explicit subscriptions | | `server/agent/agent-manager.ts` | Agent lifecycle state machine, timeline tracking, subscriber management | | `server/agent/agent-storage.ts` | File-backed JSON persistence at `$PASEO_HOME/agents/` | | `server/agent/tools/` | Transport-neutral catalog for workspaces, agents, permissions, and automation | | `server/agent/mcp-server.ts` | Thin MCP adapter that registers the Paseo tool catalog with the MCP SDK | | `server/agent/providers/` | Provider adapters (see "Agent providers" below) | | `server/orchestration-skills/` | Bundled catalog, host selection, convergence, and skill-directory transactions | | `server/relay-transport.ts` | Outbound relay connection with E2E encryption | | `server/schedule/` | Cron-based scheduled agents | ### `packages/protocol` — Wire schemas and shared protocol types The source of truth for WebSocket messages, binary frame codecs, endpoint parsing, agent timeline types, provider config schemas, and other values shared by daemon and clients. Server, app, CLI, and `@getpaseo/client` all depend on this package; it does not depend on the server. ### `packages/client` — Daemon client library and SDK facade Owns the low-level daemon WebSocket driver plus the higher-level `PaseoClient` facade. App and CLI may import the low-level driver from `@getpaseo/client/internal/daemon-client` during migration, while new SDK-shaped code imports from `@getpaseo/client`. `PaseoApi` is the capability-only boundary over workspaces, agents, terminals, providers, and config. `PaseoClient` adds connection lifecycle. App plugin surfaces borrow an API over their selected host's client; plugin subprocesses use the same facade over a host-owned IPC transport. Protocol capability ownership and subscription lifetimes follow [the client contract](protocol-compatibility.md#client-capability-ownership). ### `packages/app` — Mobile + web client (Expo) Cross-platform React Native app that connects to one or more daemons. - Expo Router navigation (`/h/[serverId]/workspace/[workspaceId]`, `/h/[serverId]/agent/[agentId]`, etc.). The `workspaceId` URL segment is an opaque workspace id, not a directly meaningful filesystem path. - `HostRuntimeController` manages saved host connections, reconnection, and per-host runtime state. Direct TCP and relay connections use the ordinary client transport; desktop socket, pipe, and SSH connections cross one Electron-owned transport boundary. SSH only tunnels to an already-running daemon. - `runtime/replica-cache` is typed storage behind the directory and timeline owners. It never observes or mutates `SessionStore`. - `runtime/directory-sync` owns directory cache selection and network reconciliation. On demand it paints accepted rows for one host, then passes the persisted per-entity cursor through `project.list`, `fetch_workspaces`, and `fetch_agents`; the daemon returns each entity's latest projection when its sequence is newer, plus tombstones. - `workspace-labels` owns one sequenced catalog replica per connected host, the deterministic cross-host projection that surfaces spanning hosts use (the filter page, the manager), and the per-host resolution a workspace row's chips use. Two hosts may give one name different colors, so a row resolves against its own host's catalog and a merged answer would be wrong there. Catalogs never synchronize between hosts; assignment creates a missing definition only on the target host. On the daemon, catalog and assignment rewrites share a journaled commit boundary. Startup recovery completes that commit before workspace or catalog publication. - `SessionContext` wraps the daemon client for the active session - Composer UI and submit/draft behavior live in `packages/app/src/composer/`; screens and panels should integrate it from there instead of dropping composer internals into `components/`, `hooks/`, or `screens/workspace/` - Timeline reducers in `timeline/session-stream-reducers.ts` handle compaction, gap detection, sequence-based deduplication - Timeline sync correctness is documented in [docs/timeline-sync.md](timeline-sync.md): live streams are for immediacy, `fetch_agent_timeline_request` is authoritative, and catch-up is paged but complete. - Voice features: dictation (STT) and voice agent (realtime) Consumers request directory or timeline data without choosing memory, cache, or network. The owner publishes an accepted cache hit and then reconciles it over the existing network path. A miss or an invalid row uses that same path. Offline demand still publishes an accepted cache hit and defers network reconciliation. Cache loading is demand-driven: opening a chat reads its agent row and focused timeline row, plus the workspace and project rows needed by the route; opening a directory reads directory rows for that host and establishes its live subscription when connected. Accepted cached rows satisfy the same consumer-readiness projection as network rows. Host registry startup and host connection do not create directory demand or install replicas. The directory owner retains declared surface demand and re-establishes network reconciliation after reconnect; React does not track connection generations. Late cache reads cannot replace state already advanced by live or authoritative network data. Owners explicitly persist accepted commits; directory rows and their checkpoint share one storage transaction. See [data-model.md](data-model.md#replica-row-store) for the storage shape and [timeline-sync.md](timeline-sync.md#client-replica-lifetime) for timeline resume behavior. The three directory entity types have independent monotonic sequences and share one daemon generation. The daemon retains only the latest projection per entity and bounded tombstones, not an event log. A missing, expired, or previous-generation cursor receives a full snapshot. Projects are independent records; a project with no workspaces does not need a workspace placeholder. Workspace label definitions use a separate, explicitly subscribed sequence. The list request both fetches and grants live updates for that session. A current cursor receives an empty correlated catch-up response when nothing changed; idle sessions and unsubscribed sessions receive no label traffic. Workspace assignments stay on the workspace directory sequence. ### `packages/cli` — Command-line client Commander.js CLI with Docker-style commands. Common agent operations are also exposed at the top level (e.g. `paseo ls`, `paseo run`). - `paseo agent ls/run/import/attach/logs/stop/delete/send/inspect/wait/archive/reload/update/mode` - `paseo daemon start/run/stop/restart/status/reload/config/pair/set-password` - `paseo terminal ls/create/capture/send-keys/kill` - `paseo script ls/start/stop` - `paseo schedule create/ls/inspect/update/pause/resume/run-once/logs/delete` - `paseo heartbeat create/update/delete` - `paseo project create/ls/rename/delete` - `paseo workspace create/ls/rename/archive` - `paseo permit allow/deny/ls` - `paseo provider ls/models` - hidden legacy `paseo worktree create/ls/archive` compatibility alias - `paseo speech …` Communicates with the daemon via the same WebSocket protocol as the app. ### `packages/relay` — Relay transport and E2E encryption Enables remote access when the daemon is behind a firewall. - Updated peers negotiate a Noise `NK` session with per-record counters; peers on either side that predate it fall back to the legacy NaCl `box` construction. [docs/relay-endpoint-security.md](relay-endpoint-security.md) owns the mapping, negotiation, and the `daemon.relay.requireProtectedSecurity` flag - The relay is zero-knowledge — it routes encrypted bytes and cannot read content - Client and daemon channels with identical API (`openClientSecureChannel`, `openDaemonSecureChannel`) - Pairing via QR code transfers the daemon's public key to the client - New homes keep relay disabled until pairing consent. `DaemonConfigStore` persists the desired state, while the relay runtime starts or stops the outbound transport live; pairing reads that current state instead of a startup snapshot. - Optional E2EE capability negotiation preserves application frame kind: text plaintext uses base64 ciphertext text frames, while binary plaintext uses raw ciphertext binary frames; mixed-version peers remain base64-only - Self-hosted relays opt into TLS with `daemon.relay.useTls` or `PASEO_RELAY_USE_TLS=true`; the public (client-facing) TLS setting can be overridden independently via `daemon.relay.publicUseTls` or `PASEO_RELAY_PUBLIC_USE_TLS` The production relay server lives in [getpaseo/paseo-relay](https://github.com/getpaseo/paseo-relay). It is a distributed Elixir service. The Cloudflare relay implementation in this monorepo is retained as legacy code and is not deployed. See [SECURITY.md](../SECURITY.md) for the full threat model. ### Paseo Hub The optional Hub relationship is daemon-outbound and does not use the relay. Its connection, authorization, ownership, persistence, and lifecycle contract is documented in [hub.md](hub.md). ### `packages/desktop` — Desktop app (Electron) Electron wrapper for macOS, Linux, and Windows. - Can spawn the daemon as a managed subprocess - Native file access for workspace integration - Same WebSocket client as mobile app The desktop does not manage agent skills. It retains one compatibility reader for the old `skill-selection.json`, imports that preference into its managed local daemon, then deletes the old file after the daemon confirms persistence. **Multi-window (hybrid land-on model).** `createWindow()` in `main.ts` is reusable: `⌘⇧N`/File→New Window, relaunching the app (`second-instance`), and the sidebar "Open in new window" action each open a fresh `BrowserWindow`. Every window shows the full sidebar — there is no per-window project ownership or filtering. "Land on a project" is delivered by a per-`webContents` `PendingOpenProjectStore`: each window pulls its own pending project path on mount (`paseo:get-pending-open-project`) and runs the normal open-project flow, identical to a CLI `paseo ` launch. > **Window-state v1 limitation:** only the _first_ window of a session restores and persists saved geometry (size/position/maximized). Windows opened via ⌘⇧N / second-instance / "Open in new window" open at the default size, OS-cascaded, and do not persist — this avoids every window stacking on the same restored bounds and fighting over the single window-state store. Lifting this needs per-window state keys. > > **In-app browser profile.** Every browser guest uses one stable persistent Electron session, so cookies, authentication, cache, and site storage are shared across tabs, workspaces, and desktop windows and survive tab or app closure. Browser identity is independent of that storage partition: after every `did-attach`, the renderer explicitly registers its browser id, workspace id, and current guest `WebContents` id, and main accepts the registration only when that guest belongs to the calling renderer and the shared profile. Registration is intentionally repeated because reparenting a retained `` can replace its guest without replacing the DOM element. Settings > General > Clear browser data is the sole profile-deletion path; it clears the shared session and reloads live guests without deleting saved tabs or URLs. > > **In-app browser window opens.** Ordinary link opens, including Shift-clicked links, become Paseo workspace tabs. Script-created opens with popup features or a named window target and POST-backed opens remain secured Electron child windows in the shared browser profile, preserving `window.opener`, `postMessage`, named-window reuse, request bodies, and `window.close()` for OAuth, payment, and similar popup protocols. Unsupported URL schemes are denied before either path. > > **In-app browser ownership.** Each registered guest records its owning host window. The active browser is keyed by `(host window, workspace)`, and application-menu Reload / Force Reload resolve only within the window Electron supplies to the menu callback. A non-null active update must name a browser owned by that host; a null update clears only that host/workspace. Browser automation continues to target explicit browser ids returned by `browser_new_tab` or `browser_list_tabs`. > > **Browser keyboard boundary.** Guest pages receive renderer-published shortcuts first. `Cmd/Ctrl+L` and `Cmd/Ctrl+R` are explicit guest-shell reservations; ordinary Paseo shortcuts run only after the page declines them. The sandboxed guest preload runs in every frame so focused iframes use the same boundary, while Node integration remains disabled. Human guest input disables Electron's menu fallback for plain keys. Agent-generated keys use guest `sendInputEvent` with `skipIfUnhandled`, so an unhandled Enter stops at the guest instead of reaching the host composer. Main selects the preload; it exposes no APIs to guest pages. ```text Human key -> guest WebContents |-- Cmd/Ctrl+T/L/R ----------> reserved browser-shell action `-- page keydown |-- page prevents ------> page owns it `-- published shortcut -> guest preload -> IPC(browserId) -> Paseo resolver Agent browser_keypress -> guest sendInputEvent(skipIfUnhandled) |-- guest handles ------------> page owns it `-- guest does not handle ----> stop; never redispatch to the host window ``` ### `packages/website` — Marketing site TanStack Router + Cloudflare Workers. Serves paseo.sh. ## WebSocket protocol All clients speak the same WebSocket protocol over a single connection that mixes JSON text frames and a small binary framing for terminal streams. Schemas live in `packages/protocol/src/messages.ts`. **Handshake:** ``` Client → Server: WSHelloMessage { type: "hello", clientId, clientType: "mobile" | "browser" | "cli" | "mcp", protocolVersion, appVersion?, capabilities?: { voice?, pushNotifications?, ... }, } Server → Client: status message with payload { status: "server_info", serverId, hostname, version, capabilities?, features } ``` There is no dedicated welcome message; the server emits one initial `status.server_info` after accepting hello. Modern clients negotiate `owned_subscriptions` against `features.ownedSubscriptions`. Connecting or attaching a local listener creates no application-data demand. A list is a snapshot; adding `subscribe: {}` creates an independent server ID. The client correlates the initial reply by request ID, then routes updates by subscription ID. A logical Session can contain several physical sockets. Each socket owns its capabilities, subscriptions and ongoing operations; the final JSON/binary send boundary requires that source's request or subscription provenance. Domain modules own filtering, bootstrap and resource teardown. The shared ownership boundary only tracks source and lifetime. Releasing a subscription acknowledges its teardown; reconnect creates new server IDs for surviving client handles. See [protocol compatibility](protocol-compatibility.md) for the legacy boundary. **Top-level WS envelopes** are `hello`, `recording_state`, `ping`/`pong`, and `session` (which wraps the rich union of session messages). Client liveness checks use the top-level JSON `ping`/`pong` envelope, not a session RPC or RFC6455 control ping. Current clients ping every 10 seconds, beginning one interval after connecting. The first ping claims an application-ownership lease for that physical socket, all later inbound activity renews it, and the daemon forcibly terminates the socket if the lease expires. A legacy or raw socket that never sends an application ping never enters this lease and is not closed for omitting one. Session RPC timeouts are operation failures, not proof that the socket is dead. A subscription bootstrap timeout closes its source to clear any unknown server-owned registration; the failed handle is released before other surviving handles reconnect. Every physical send path enforces an 8 MiB outbound high-water mark, including JSON broadcasts, binary terminal frames, and the encrypted relay adapter's asynchronous queue. This sits above the terminal stream's 4 MiB soft backpressure threshold, leaving room for snapshot catch-up before the hard cutoff. JSON is serialized once per broadcast after sockets already at the limit are removed, then its exact byte length is checked for every remaining socket. A frame that would cross the limit is not sent; that physical socket is forcibly terminated without disturbing other sockets attached to the same logical session. Multiple tabs and simultaneous direct and relay paths may legitimately share a client id. Client session RPC waits default to 60s so slow relay or mobile networks do not turn a live but delayed daemon response into a false operation failure. Keep connect timeouts, app-level grace windows, explicit diagnostic latency probes, liveness ping timers, and genuinely long-running RPCs separate from this default. New session RPCs use dotted names with `.request` and `.response` suffixes, such as `checkout.forge.set_auto_merge.request` and `checkout.forge.set_auto_merge.response`. See [rpc-namespacing.md](rpc-namespacing.md) for the convention and migration rules for older flat RPC names. **Notable session message types:** - `agent_update` — Agent state changed (status, title, labels) - `agent_stream` — New timeline event from a running agent - `workspace_update`, `script_status_update`, `workspace_setup_progress` — Workspace state - `agent_permission_request` / `agent_permission_resolved` — Tool-call permission flow - `agent_deleted`, `agent_archived`, `agent_status`, `agent_list` - `checkout_status_update`, `checkout_diff_update`, and the full `checkout_*` request/response set for git operations Agent snapshots optionally carry the daemon-owned active turn identity, and turn lifecycle stream events optionally carry the same `turnId`. New clients use these fields when present and normalize an old daemon's status once at the directory boundary rather than maintaining a second activity model. - Terminal subscribe/input/capture commands - Voice/dictation streaming events (`dictation_stream_*`, `assistant_chunk`, `audio_output`, `transcription_result`) - Request/response pairs for fetch, list, create, etc., correlated by `requestId`; failures use `rpc_error` `directory_suggestions_request` is one daemon-owned filesystem search capability. The daemon configures the same `searchDirectoryEntries` engine with a root, output format, path-query policy, entry-kind filters, match mode, blank-query behavior, and hidden-directory traversal policy. A request without `cwd` searches the host home for absolute project paths; a request with `cwd` searches that workspace and returns relative entries. Clients may prepend their small host-scoped recent-project list for bare queries, but must not parse filesystem query syntax or re-filter a correlated daemon response. The legacy `directories` response field remains a projection of the typed `entries` list. **Binary frames (terminal stream protocol):** Terminal I/O is sent as binary WebSocket frames decoded by `decodeTerminalStreamFrame` in `shared/binary-frames/terminal.ts`. The layout is: - 1-byte opcode: `Output (0x01)`, `Input (0x02)`, `Resize (0x03)`, `Snapshot (0x04)` - 1-byte slot: terminal slot id - variable payload: bytes for output/input, JSON-encoded `{ rows, cols }` for resize, terminal snapshot for snapshot Terminal PTY size is last-interacting-client-wins. A client claims the PTY size only when its terminal viewport genuinely changes size or the user focuses/taps the terminal. Passive rendering work — attaching, restoring visibility, font settling, renderer refits, or just looking at a visible terminal — must not send a resize frame. The server does not broadcast resize ownership; the resized PTY redraws through normal output, and every attached client renders that output in its own local viewport. There is also a separate file-transfer binary frame format in the same directory, used for download/upload streams. File downloads keep the existing `FileBegin`/`FileChunk`/`FileEnd` framing and stream 256 KiB chunks from one stable file handle. Each transfer awaits completion of its own physical WebSocket send before reading the next chunk; it is scoped to the requesting physical socket and does not queue unrelated messages or transfers. ### Compatibility rules - WebSocket schemas are append-only. Add fields, do not remove fields, and never make optional fields required. - New wire enum values must be gated at serialization with `session.supports(CLIENT_CAPS.someCapability)`. - Capabilities belong to the physical source socket. `session.supports(...)` reads the requesting or observing source at the domain projection boundary; one socket must not borrow a sibling's capabilities. Example: adding a new enum value ```ts // 1. Add CLIENT_CAPS.newThing = "new_thing" // 2. Let new clients advertise it in WS hello // 3. Keep the shared producer schema strict // 4. Gate the new emitted value: session.supports(CLIENT_CAPS.newThing) ? "new_value" : "old_value" ``` ### Creation ownership Creation is owned by the daemon across socket lifetimes. A workspace request can include its initial agent and prompt. Workspace readiness is published before provider startup; the app keeps its existing disk-ready navigation and observes the remaining creation. Callbacks do not advance the workflow. Resource reservations in acknowledgement are identities, not ready workspace records. The creation journal (`server/creation/`) owns identity and execution for both legacy and modern creation RPCs. Requesting progress never selects a different journal. Existing agent receipts are imported at this boundary; message delivery receipts remain separate. It keeps cumulative milestones and permanent IDs under an operation kind and idempotency key. Reconnect subscribes to that key; retries join active work or reuse committed stages. A persisted resource alone cannot prove that a provider accepted its initial prompt. Interrupted side effects with no conclusive receipt return an unknown outcome instead of being repeated. Agent registration commits creation. Rejecting the first prompt is a turn error on that agent; reporting creation failure leaves an orphaned agent and invites another Create. Receipt replay must not resend the prompt. `packages/client/src/creation/` owns capability selection and legacy orchestration. Callers always pass the initial prompt to agent creation. On an older host, the client adapts keyed creation to the legacy create/send sequence; it cannot continue that sequence after the client process disappears. Explicitly requested IDs or receipts that an old host cannot honor produce an unsupported error. Keep these adapters inside the client package, as an exception to the default no-fallback feature policy. Creation executes through the existing Session capabilities. Connection-owned delivery controls observation only: detaching a socket or cleaning up its Session does not cancel accepted creation. Updates require an explicit subscription and go only to that socket; reconnect uses the shared subscription owner. Legacy consumers, including Hub, keep their existing response contract. ## Agent lifecycle The lifecycle states are defined in `shared/agent-lifecycle.ts`: ``` initializing → idle ⇄ running ↓ ↓ ↓ error ↓ closed ``` - `initializing` — provider session is being created - `idle` — has a live session, awaiting the next prompt - `running` — provider is currently producing a turn - `error` — last attempt failed; session is still attached - `closed` — terminal state, no live session `ManagedAgent` is a discriminated union over those lifecycle tags. Notes: - **AgentManager** is the source of truth for agent state and broadcasts updates to all subscribers - Timeline sequence allocation is append-only with epochs (each run starts a new epoch). The one permitted in-place enrichment adds a provider message id to the manager-owned row for an accepted prompt; it preserves the row's sequence, content, and timestamp. Storage uses sequence numbers for client-side dedup; the default fetch page is 200 items. - Timeline row `timestamp` values are canonical daemon-owned timestamps. Providers may supply original replay timestamps, but clients must not guess timestamp trust or hide time UI based on local clock heuristics. - Events stream to connected clients in real time; correctness is backed by authoritative timeline fetches and paged-to-completion catch-up. - Agent state persists to `$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json`. Timeline rows are runtime memory; provider history is the durable transcript authority and resumed agents rebuild from it. That storage path is derived from `cwd`, not from workspace id. ## Right-sidebar boundary: directory-backed vs workspace-owned Two workspaces can share the same `cwd` (e.g. a `directory` workspace and a `local_checkout` workspace on the same folder, or several workspaces opened against one checkout). Model B keeps these distinct: they share everything the directory determines, but nothing the workspace owns. The right-sidebar surfaces split cleanly along this line, and the split is enforced purely by **what each piece of state is keyed by**. **Directory-backed (shared by same-`cwd` workspaces) — keyed by `(serverId, cwd)`, never by `workspaceId`:** | Surface | Key | Source | | ----------------------- | -------------------------------------------------------- | ------------------------------------------------------- | | Git status | `checkoutStatusQueryKey(serverId, cwd)` | `packages/app/src/git/query-keys.ts` | | Git diff | `checkoutDiffQueryKey(serverId, cwd, mode, baseRef, ws)` | `packages/app/src/git/query-keys.ts` | | Forge change request | `checkoutPrStatusQueryKey(serverId, cwd)` | `packages/app/src/git/query-keys.ts` | | Change request timeline | `prPaneTimelineQueryKey({ serverId, cwd, prNumber })` | `packages/app/src/git/pull-request-panel/query-keys.ts` | | File preview content | `["workspaceFile", serverId, cwd, path]` | `packages/app/src/components/file-pane.tsx` | | File explorer listings | fetched via `listDirectory(workspaceRoot, path)` | `packages/app/src/hooks/use-file-explorer-actions.ts` | **Workspace-owned (independent per workspace) — keyed by `workspaceId` (falling back to `cwd` only when no `workspaceId` exists):** | State | Key builder / store | Source | | ---------------------------- | -------------------------------------------------- | ------------------------------------------------------------- | | Review draft comments | `buildReviewDraftKey` | `packages/app/src/review/store.ts` | | Working diff comparison | `workingDiffComparisonKey` (in-memory) | `packages/app/src/git/working-diff-comparison/state.ts` | | Composer attachments | `buildWorkspaceAttachmentScopeKey` | `packages/app/src/attachments/workspace-attachments-store.ts` | | File explorer nav/open state | `fileExplorer` map keyed `workspace:{workspaceId}` | `packages/app/src/hooks/use-file-explorer-actions.ts` | | File explorer expanded paths | `expandedPathsByWorkspace[workspaceStateKey]` | `packages/app/src/stores/panel-store/state.ts` | `diff-pane.tsx` is the canonical wiring site: it passes `{ serverId, cwd }` to the git queries and `{ serverId, workspaceId, cwd }` to the draft/comparison/attachment scope keys. **Do not "fix" the sharing away.** Re-keying a directory-backed query by `workspaceId` makes same-`cwd` workspaces diverge (two windows onto the same git tree showing different diffs). Re-keying owned state (drafts, expanded paths) by `cwd` makes them leak between distinct workspaces on the same folder. The `workspaceId`-keyed builders carry a `// workspaceId is opaque; do not parse this key back into a path.` comment — the opaque-id fallback to `cwd` exists only for old payloads without a `workspaceId`, not as a content-sharing mechanism. One deliberate non-violation: `AgentFileExplorerState.directories`/`files` cache directory listings inside the `workspaceId`-keyed explorer map. Same-`cwd` workspaces therefore keep duplicate caches, but they can never diverge — both fetch the identical directory via `listDirectory(workspaceRoot, …)`. This is duplication, not leakage, and is left as-is. ## Agent providers Each provider implements the `AgentClient` interface in `agent/agent-sdk-types.ts`. Provider implementations live in `agent/providers/`. The built-in, user-facing providers are Claude Code, Codex, Copilot, OpenCode, Pi, and OMP. Additional adapters exist in the same directory for ACP-compatible agents and internal use: | Provider | Wraps | Session format | | ------------------ | ------------------------------------ | -------------------------------------------------- | | Claude (`claude/`) | Anthropic Agent SDK | `~/.claude/projects/{cwd}/{session-id}.jsonl` | | Codex | Codex AppServer (`codex-app-server`) | `~/.codex/sessions/{date}/rollout-{ts}-{id}.jsonl` | | Copilot | GitHub Copilot via ACP | Provider-managed | | OpenCode | OpenCode server / CLI | Provider-managed | | Cursor | ACP wrapper (`acp-agent`) | Provider-managed | | Generic ACP | ACP wrapper | Provider-managed | | Pi | Local Pi RPC process | Provider-managed | | Mock load test | In-process fake | In-memory | All providers: - Handle their own authentication (Paseo does not manage API keys) - Support session resume via persistence handles - Map tool calls to a normalized `ToolCallDetail` type - Expose provider-specific modes (plan, default, full-access) Providers that can accept native tool definitions should set `supportsNativePaseoTools` and read `launchContext.paseoTools`. The daemon then passes the shared Paseo tool catalog directly and removes the internal Paseo MCP server from that provider launch config. Providers that only support MCP continue to receive the same tools through the MCP fallback at `/mcp/agents`. ## Data flow: running an agent 1. Client sends `CreateAgentRequestMessage` with config (prompt, cwd, provider, model, mode) 2. Session routes to `AgentManager.create()` 3. AgentManager creates a `ManagedAgent`, initializes provider session 4. Provider runs the agent → emits `AgentStreamEvent` items 5. Events append to the agent timeline, broadcast to all subscribed clients 6. Tool calls are normalized to `ToolCallDetail` (shell, read, edit, write, search, etc.) 7. Permission requests flow: agent → server → client → user decision → server → agent ## Storage `$PASEO_HOME` defaults to `~/.paseo`. The most important files: ``` $PASEO_HOME/ ├── agents/{cwd-with-dashes}/{agent-id}.json # Agent record ├── projects/projects.json # Project registry ├── projects/workspaces.json # Workspace registry ├── projects/icons/ # Custom project icon images ├── schedules/ # Scheduled-agent definitions and runs ├── config.json # Daemon config (mutable) ├── daemon-keypair.json # Daemon identity for relay/E2EE ├── push-tokens.json # Mobile push tokens ├── paseo.pid # Supervisor identity and published bound endpoint └── daemon.log # Daemon trace logs (rotated) ``` The supervisor alone publishes its ready worker's endpoint in `paseo.pid`, clears it before respawn, and fails if any worker exits before first readiness. CLI home selection trusts only that live record; config expresses desired state, never an endpoint fallback. POSIX home stop signals the captured supervisor without TCP. Windows graceful stop and ordinary RPCs trust the published endpoint. This metadata is not cryptographic listener ownership: edited endpoints, copied identities, PID reuse, and address takeover races remain outside that guarantee. A stale heartbeat never permits reclaiming a live lock. Worker restart retains supervisor arguments/environment and rereads the configuration file. Updating a package and observing its new worker version do not refresh the running supervisor code; the launcher owns full-process replacement. See [CLI lifecycle contracts](../public-docs/cli.md#daemon-management). ## Deployment models 1. **Local daemon** (default): `paseo daemon start` on `127.0.0.1:6767` 2. **Managed desktop**: Electron uses the server package’s local-instance lifecycle capability for sanitized launch, published readiness, and captured-PID stop. Only a matching `{pid, startedAt}` from a spawn in the current Desktop session authorizes automatic stop or binary replacement. Preexisting instances, including legacy `desktopManaged` records, are attach-only. Keep-running survivors attach in the next session. Explicit attached Stop requires a confirmation naming the captured home/PID. Ordinary Restart uses the worker RPC on every app platform. 3. **Remote + relay**: Daemon behind firewall, relay bridges with E2E encryption --- ### Browser Capture Harness (`docs/browser-capture-harness.md`) # Browser Capture Harness The desktop capture harness is the real-Electron verification path for browser screenshots. It validates the compositor behavior that unit tests cannot see: - the resident automation `` starts in the production parking state; - the parked guest remains paintable and has a copyable viewport frame; - a never-presented resident webview guest defaults to 1280x800 logical pixels; - multiple resident webviews are parked as an overlapping stack without per-capture stacking changes; - a newly attached resident webview whose first useful frame is delayed can be captured by retrying until the frame appears; - both viewport `capturePage` and full-page CDP screenshots return real pixels from the permanent production parking state; - parked guests remain capturable with Chromium background throttling enabled; - the real-Electron host-composer sentinel proves guest Enter cannot submit a focused host composer; - the automation group loads the compiled production keyboard boundary and guest preload, then proves that initial page window handlers get first refusal, unhandled shortcuts synchronously suppress editable browser defaults before crossing the host boundary, shortcuts marked unavailable in editable targets retain the browser field's native behavior, handlers registered after preload still get first refusal, focused iframes share the same boundary, digit wildcard shortcuts cross, and background automation stays in the guest. Run it with the repo Electron: ```bash npm run capture-harness --workspace=@getpaseo/desktop ``` Build the desktop main process before the automation group so its production guest preload is available: ```bash npm run build:main --workspace=@getpaseo/desktop PASEO_CAPTURE_HARNESS_GROUP=automation npm run capture-harness --workspace=@getpaseo/desktop ``` Run the shared browser profile fixture with: ```bash PASEO_CAPTURE_HARNESS_GROUP=browser-profile npm run capture-harness --workspace=@getpaseo/desktop ``` On macOS, test native titlebar dragging after scrolling with: ```bash PASEO_CAPTURE_HARNESS_GROUP=titlebar-drag npm run capture-harness --workspace=@getpaseo/desktop ``` This group needs Xcode Command Line Tools and Accessibility permission for the terminal running it. It sends real mouse input to its test window and checks window movement, including button clicks and a portal over the titlebar. Leave the mouse idle during this group. It reads the app's production CSS and writes screenshots and window bounds to the output directory. The browser profile group runs two Electron processes in sequence. It verifies that each renderer-side `did-attach` identity maps to the correct main-process guest, that two live tabs share cookies and local storage through one persistent session, and that the data is still present after the first Electron process exits and the second starts. The automation group uses a real guest webview to verify the page-side ref contract: ARIA-like snapshot text includes headings, static text, and controls; refs survive `pushState` when the element still matches; same-URL rerenders stale old refs; and a file-input ref can be resolved to a CDP backend node id for upload. It also verifies page-context evaluation, including passing a resolved ref element as the function argument. Keyboard containment runs last because the host-composer sentinel intentionally leaves native focus in the host. It reuses an existing fixture button: adding a test-only control changes the inline fixture geometry exercised by the earlier actionability checks. On macOS the harness process must set `app.setActivationPolicy("accessory")` and hide the Dock icon before creating any window. `showInactive()` only prevents window focus; a normal Electron app launch can still activate the app and steal focus. Harness windows are then created hidden, positioned in a screen corner, skipped from the taskbar where Electron supports it, and revealed with `showInactive()` from `ready-to-show`. Do not replace this with `show()`, `focus()`, or `app.focus()`: the compositor only needs visible inactive windows, and harness runs must not steal focus from the person using the machine. The harness writes PNG evidence and `results.json` to: ```text packages/desktop/capture-harness/out/ ``` A passing run prints `PASS` lines for the production P1 default-throttling parking state, including fresh, settled, 75-second soak, multi-tab, viewport, and full-page checks. The PNG sizes may be device-pixel scaled; on a Retina display the 1280x800 logical viewport is usually saved as 2560x1600. The existing `npm run test:e2e:browser-tabs --workspace=@getpaseo/desktop` journey verifies that a hidden window stops guest animation, captures fresh viewport pixels, and resumes animation after restoring the window. Its artifacts include the screenshot and animation measurements. Full-page content correctness remains separately tracked in [the full-page repetition bug](https://github.com/getpaseo/paseo/issues/3196). ## Mechanism Electron captures copy from the guest web contents' compositor surface. A resident webview parked with `display:none`, offscreen coordinates, or `opacity:0` can lose its copyable surface. Each production webview keeps one permanent body-level surface. Presenting or parking changes that surface's geometry without reparenting the webview. The parking state uses `left:0`, `top:0`, `width:1px`, `height:1px`, `overflow:hidden`, `opacity:1`, and `pointer-events:none`. The webview stays at its resolved logical viewport, defaulting to 1280x800 before first presentation, with `display:inline-flex` at `left:0`, `top:0`. Presentation resolves responsive guests to the pane's exact pixel dimensions after the surface has visible bounds. Do not apply percentage guest sizing against the parked surface: Electron exposes the 1x1 parking geometry as a real guest resize before expanding it again. The permanent browser host and `overlay-root` are explicit sibling paint planes. The browser plane stays below the overlay plane regardless of body insertion order; menus keep their relative layering inside `overlay-root`. Activating a presented browser also focuses its registered guest `WebContents` in main so macOS assigns keyboard first-responder ownership to the page. There is no renderer prep/restore handshake or lifetime background-throttling override. Screenshot capture temporarily enables frame production inside the shared serialized queue, restores the previous throttling policy on success or failure, and retains a 5-second capture budget. The browser tool takes one viewport frame through Electron's frame subscription and releases the subscription on completion or cancellation. A resized resident guest can produce fresh pixels while `capturePage()` leaves its surface-copy request pending; waiting for animation frames or retrying the copy does not repair that state. Full-page screenshots retain the CDP path with layout metrics and screenshot clip. --- ### Coding Standards (`docs/coding-standards.md`) # Coding Standards The core instinct: AI-generated code hedges — it covers every case, layers over instead of cutting in, scatters uncertainty everywhere, wraps in case. A senior engineer commits — to a shape, a boundary, a name, a happy path, a type — and lets everything else fall into place. Every rule below catches a different form of indecision. For testing rules, see [testing.md](testing.md). ## Core principles - **Zero complexity budget** — every abstraction must justify itself with a specific, current benefit. - **YAGNI** — build features and abstractions only when needed. A function called once is indirection, not abstraction. - **No "while I'm at it" cleanups** — make the change you came for. Drive-by edits hide in the diff. - **Functional and declarative** over object-oriented. - **`function` declarations** over arrow function assignments. - **`interface`** over `type` when both work. - **No `index.ts` barrel files** that only re-export — they create indirection and circular-dep risk. Import from the source. ## Shell scripts - Bash scripts always use `#!/usr/bin/env bash`. Never hard-code `/bin/bash` or `/usr/bin/bash`; those paths are not portable to environments such as NixOS. ## Comments and noise - Delete any comment where removing it loses zero information. Comments explain _why_, not _what_. - No tutorial comments explaining language features (`// Use destructuring to...`). - No decorative section dividers (`// ===== Helpers =====`). Use files and modules to organize, not ASCII art. - No hedging comments (`// might need to revisit`, `// should work for most cases`). If you're unsure, investigate. - No commented-out code. Git remembers. - No `console.log` / `debugger` left behind. No `TODO: implement` stubs — if it needs to exist, write it. ## Confidence: commit to a shape - Validate at boundaries (network, IPC, user input, file I/O), trust types internally. After the parse, the value is what its type says. - Every `?.` and `??` past the validation boundary is unconfident code — either the boundary should resolve it, or the type should reflect reality. - No defensive checks for conditions the type system already rules out (`if (!agent) return` on a non-nullable parameter). - No `try/catch` "just in case." If you can't say what you're catching and why, don't catch. - Optionality is a design decision, not a migration shortcut. Distinct valid states → discriminated union. Intentionally empty → explicit `null`. Keep optionality at real boundaries. ## Types - No `any`. No `as` casts to bypass errors. No `@ts-ignore` / `@ts-expect-error`. Narrow with `if` / schema validation; let the compiler check harder, not less. - If a Zod schema exists, the TypeScript type is `z.infer`. Never hand-write a parallel type. - One canonical type per concept. Layer-specific views are `Pick` / `Omit`, not duplicated fields. - Name multi-property object shapes — no inline `Array<{ ... }>` or `Promise<{ ... }>` in signatures, returns, or generic args. - Use string literal unions, not raw `string`, when the value is one of a known set. Catches typos at compile time. - Object parameters past the obvious-name threshold: 3+ args, any boolean arg, any optional arg → object. `(thing, true, false, true)` is unreadable at the call site. - Make impossible states impossible — discriminated unions over `{ isLoading; error?; data? }` bags. ## Errors - Throw typed error classes that carry the fields a caller would want to read. Plain `Error("Provider X not found")` collapses structured info into a string. - Catch blocks branch on `instanceof` for what they can handle; rethrow the rest. No `catch (e) { return null }`. - Separate user-facing copy from log/debug strings — don't make one string serve telemetry, logs, and the UI. - Fail explicitly. If the caller asked for X and X isn't available, throw — don't silently substitute Y. - Every fallible user action owns explicit pending, success, and failure UI. Console logs and unverified platform alerts do not satisfy this contract. See [testing.md](testing.md#fallible-user-actions). - A capability advertised to a client means the current runtime can perform the action, not merely that its RPC handler exists. If an unavailable action needs explanatory UI, send the runtime fact or reason separately and keep the server-side refusal fail-closed. ## Density - Nested ternaries are forbidden. A single ternary is fine only when both branches are a single identifier or trivial access (`x ? a : b`). - Boolean expressions with 2+ clauses or mixed concerns → name the conditions. - Object literals assemble pre-computed values; don't pack branching and lookups into property positions. - Operations wrapping operations (`Object.fromEntries(arr.filter(...).map(...))`, `Math.max(...xs.map(...))`) → break into named intermediates. - Max 3 levels of nesting (callbacks, JSX, control flow). Above that, extract. ## Structure and modules - A directory is a module, not a namespace. One intentional public surface; internal files stay internal. - Path is part of the name — prefer `provider/registry.ts` over `provider/provider-registry.ts`. If the filename has to do double duty, deepen the path. - Filenames ending in `-utils`, `-helpers`, `-manager`, `-handler`, `-controller`, `-formatter`, `-builder` are a smell — the path didn't carry enough domain. - Boundary returns answer the caller's question (`getActiveAgents()`), not "here's my storage" (`getAgents().filter(...)` repeated everywhere). - One adapter means a hypothetical seam; two adapters means a real one. Don't define a port until something actually varies across it. - Pass-through modules fail the deletion test — if removing the module makes callers go straight to what they wanted, delete it. - Centralize policy. The same discriminator (`plan`, `provider`, `kind`, `status`) branched in 3+ files → policy table, not another `else if` per case. - New features get a home before implementation. A feature smeared across 5 shared files is the same slop as a flat-peer namespace. - Don't drop new files at the nearest root just because placement is unclear — say so and ask. ## Refactoring is a bolt-on test - A change should look like a thoughtful edit to existing code, not a new layer next to it. New coordinator wrapping a coordinator, new flag bypassing the normal path, new helper duplicating an existing selector — stop and reshape instead. - Refactors preserve behavior by default. No removing features to simplify code without explicit approval. - Have a verification plan _before_ refactoring — name the invariants, confirm a test holds them, write one if not. See [testing.md](testing.md). - Migrate all callers and remove old paths in the same refactor. No fallback behavior unless explicitly designed. ## React - `useEffect` is for synchronizing with external systems (DOM, network, timers, subscriptions). Not for transforming React state. Derived state → compute in render or `useMemo`. - No effect cascades — chains of effects setting state that triggers more effects almost always want React Query or a reducer. - `useRef` is for DOM refs and non-rendering identities (timer IDs, AbortController, latest-callback caches). If the value affects what renders next, it's state — model it explicitly with `useReducer` and a discriminated union. - Server state goes through React Query. Manual `useState` + `useEffect` + `isLoading` + `error` for fetched data is always worse. - Components render and dispatch — they don't compute transitions. Two-plus interacting `useState`s → extract a reducer. - Never define components inside other components. Module-scope only. - Subscribe narrowly: select primitives from stores, pass `status` not `agent`, use `useShallow` / deep-equal when returning derived arrays/objects. - Collection rows do not independently subscribe to a high-frequency global store. The collection owner selects structurally shared indexes once, derives a keyed row model with `useMemo`, and passes entries to rows. This keeps retained hidden collections current without running one selector per row on every store update. - Equality functions prevent React renders; they do not prevent selector callbacks from running. A selector attached to a hot store must be O(1) when its relevant source references have not changed. - Retained native panels use `RetainedPanel`. If an existing gesture/layout wrapper must own visibility, wrap its contents in `RetainedPanelActivity` instead. Keep keyed panel roots in a stable sibling order, include the newly active panel in the same render, centralize subscriptions, and gate genuine effects through `useRetainedPanelActive`. Follow the [native ownership constraints and chat suspension boundary](mobile-panels.md) when stopping hidden rendering. - Infinite animations are subscriptions. Start them only while their retained panel is active, and cancel a shared clock when its final active consumer leaves. Synchronized animations use one clock per animation family and feed active instances through local shared values; retained hidden instances stay mounted but unsubscribed. Match state updates to the actual visual cadence; do not run every style worklet at 60 fps when the rendered value changes only a few times per second. - Stable references for props that cross `memo` boundaries or feed dependency arrays. Static literals at module scope `as const`; derived with `useMemo`; handlers with `useCallback` only when there's a memoized beneficiary. - Use stable ids for `key`, never array index for reorderable/filterable lists. - Context for stable values (theme, auth). Store with selectors for state that changes. ### Retained panel measurements Inactive retained panels use `display: none`, so DOM and layout APIs report zero width and height. A non-positive measurement means the surface is not rendered; it is never a valid compact layout. - Suspend geometry-derived updates while either measured dimension is non-positive. Preserve the last valid state until the surface reports positive geometry again. - Enforce the rule at the measurement boundary shared by every trigger. Guarding only an `onLayout` or `ResizeObserver` callback still lets effects, content changes, and imperative remeasurement publish hidden geometry. - Test the hide-and-reveal path through a real retained surface. Settled assertions do not catch stale geometry painted during the first returned frames. ## Naming - Names describe meaning, not mechanics. `submitForm` over `handleOnClickButtonSubmit`. `running` over `filteredArrayOfRunningAgents`. - The right length is the shortest unambiguous in context. Inside `AgentManager`, methods are `start`, `stop`, `list`. - Match the surrounding code's vocabulary. If the codebase uses `getX`, don't introduce `fetchX` / `retrieveX` for the same shape. - Don't leak implementation into names — `getAgent`, not `queryPostgresForAgent`. If swapping the impl would force a rename, the name is wrong. - Booleans read as yes/no questions: `isX`, `hasX`, `canX`. Avoid negative booleans (`isNotConnected`). - `data`, `result`, `info`, `manager`, `temp` are smells — say what the thing _is_. --- ### Connected Hosts (`docs/connected-hosts.md`) # Connected hosts A saved host belongs to the daemon that stores it. The app's saved connections remain a separate list. Connect A to B through `paseo --host A host` or `paseo.hosts`. Consumers select B by its learned `serverId`; management uses the stable `registrationId` created before B is reachable. ## Ownership and authority Credentials live in A's `hosts.json`, written atomically with mode `0600` on POSIX systems. Discovery returns a safe target description. Replacement inputs never come back through a read API. Keep this file private when collecting diagnostics or backing up daemon state. The authenticated producer owns its source key. Repeating an unchanged add returns the saved entry, including a user's disabled state. Changed input requires an explicit update. Display labels and access can be changed by users with `tunnel.manage`; connection and metadata changes require the producer or `access.manage`. Removing a producer-managed entry allows that producer to add it again. Disabling retains the opt-out. Each enabled registration owns one physical daemon link, shared by status monitoring and every routed API scope. Each scope owns an isolated virtual session on B. A derives its identity from the admitted origin session, producer, and logical SDK scope. B admits virtual sessions under the actual physical link principal, then intersects forwarded caller grants with that link's current authority. Changing or resuming a parent's grants closes its existing channels; reconnect re-admits demand with current authority. A routed API cannot select a second hop, and saving a host grants no reverse access. A producer that registers a host through a routed API is qualified on B as `route:::`, with each component percent-encoded. This namespace belongs to the authenticated link principal. An ordinary direct B consumer does not become that producer by supplying a source key. The optional `server_info.sourceId` reports this producer identity separately from the authenticated admission principal. Trusted server plugins retain the authority of their runtime; they are not sandboxed by this feature. ## Delegating agents Agent MCP discovers destination IDs with `list_hosts`. `create_workspace`, `list_workspaces`, `create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity`, and `list_agents` accept `serverId`; omission selects the calling daemon. Remote creation requires a destination workspace and explicit provider/model. Caller filesystem defaults apply only on the calling daemon. Prompting a remote child acknowledges acceptance and uses the existing idle wait for finish notifications. Remote agent lists have no caller-directory default; pass `cwd` to filter them. The parent’s Subagents track shows qualified children across connected hosts. Opening a child uses the ordinary conversation on the destination's session. The runtime selects among that host's connection candidates, including direct connections and routes discovered through another daemon. Adding a direct connection to a discovered host adds another candidate. If no candidate connects, the destination workspace keeps its existing disconnected or reconnecting behavior. Finish notifications use the existing idle wait, including a pending initial run or an already idle child. They name the server and agent. A daemon restart or route loss ends an outstanding notification wait; inspect or wait for the child again rather than resending its prompt. Concurrent prompts gain no additional turn attribution or delivery guarantee. ## Connections and recovery The shared Node connector owns the target grammar and each connection attempt, including a fresh SSH process. SSH reaches an already running daemon. The shared client connection lifecycle owns physical reconnect and keepalive; the registry retains configuration, identity acceptance, and recovery status. Unreachable registrations remain saved. Identity is pinned when discovered. Self and duplicate registrations remain inspectable; a changed destination requires explicit identity replacement. Both daemons advertise `connectedHosts`; the shared link additionally requires `hostMultiplexing`. A completes capability and pinned-identity checks on each physical recovery before admitting channels. There is no local fallback. An older daemon continues to serve existing local operations; requesting this feature gives update guidance. Disposing a routed API releases its observations and session. It does not remove the saved host or affect sibling API scopes. Disposing the origin cascades to its derived scopes. Observations restore through the usual owned-subscription contract. The ordinary client queues new requests while connecting within its existing deadline and rejects requests while disconnected. Connection loss clears old waiters and queued sends. Submitted requests with no response fail with `DaemonConnectionError` (`DAEMON_CONNECTION_LOST`), optional `outcome: "unknown"` and known `serverId`. Inspect the destination before retrying a mutation. Ordinary non-recoverable mutations are not automatically replayed. Existing acknowledged/idempotent creation recovery retains its request identity and resumes through the ordinary creation lifecycle. Multiplexing changes only the transport: ordinary permission RPC codes pass through unchanged, and connection/recovery behavior matches direct clients. Text session envelopes carry a channel identifier. Binary routing adds an opcode, a bounded UTF-8 channel identifier, and the original terminal or file-transfer bytes. It never converts those bytes to base64 JSON. The existing direct binary opcodes and 100 MiB message limit remain unchanged; routed payloads reserve space for the routing header inside that limit. Relay encryption retains its own existing frame limit. Host links cap saved registrations, simultaneous channels, handshake lifetime, frames, physical output, and aggregate queued bytes. Capacity checks use the actual escaped outer JSON or binary frame size. Awaitable output completes when the physical send completes. An overflowing channel closes without closing siblings or the saved link. Routed sessions release resources on disconnect; subscription demand is rebuilt by its owning client on reconnect. See the [SDK reference](../public-docs/sdk/reference.md#clienthosts), [CLI reference](../public-docs/cli.md#connected-hosts), and [plugin reference](../public-docs/plugins/reference.md#connected-hosts). --- ### Custom Providers (`docs/custom-providers.md`) # Custom Provider Configuration Paseo supports configuring custom agent providers through `config.json` (located at `$PASEO_HOME/config.json`, typically `~/.paseo/config.json`). You can extend built-in providers with different API backends, add ACP-compatible agents, set custom binaries, disable providers, and create multiple profiles for the same underlying provider. Provider definitions live under `agents.providers` in config.json: ```json { "version": 1, "agents": { "providers": { "provider-id": { ... } } } } ``` Provider IDs must be lowercase alphanumeric with hyphens (`/^[a-z][a-z0-9-]*$/`). Each provider catalog refresh waits up to 2 minutes. If a provider loads many plugins or a large agent catalog during startup, raise the limit in milliseconds: ```json { "agents": { "catalogRefreshTimeoutMs": 180000 } } ``` The limit applies independently to every provider refresh and covers availability plus the entire catalog probe. `PASEO_PROVIDER_REFRESH_TIMEOUT_MS` sets it when the config field is absent. ## Provider options Set provider defaults in `agents.providers..options`. At agent creation, use `providerOptions` on the wire or `config.options` in the SDK. Both are opaque `Record` values: the provider owns validation and application. Claude, Codex, and OpenCode reject unknown keys with a key-specific creation error. Providers without option handling ignore the record. The daemon deep-merges the agent's options over the provider defaults at each session launch or resume. Plain objects merge recursively; arrays, scalars, and `null` replace the base value. Only the agent's own options are persisted, so edits to provider defaults apply on the next launch or resume. A profile inherits its base provider's options unless it sets its own options record. ```json { "agents": { "providers": { "codex": { "options": { "sandbox_mode": "read-only", "approval_policy": "never" } } } } } ``` See the [SDK provider options guide](../public-docs/sdk/provider-options.md) for per-agent examples and provider-specific keys. --- ## Table of Contents - [Extending a built-in provider](#extending-a-built-in-provider) - [Z.AI (Zhipu) coding plan](#zai-zhipu-coding-plan) - [Alibaba Cloud (Qwen) coding plan](#alibaba-cloud-qwen-coding-plan) - [Codex with a custom OpenAI-compatible endpoint](#codex-with-a-custom-openai-compatible-endpoint) - [Multiple profiles for the same provider](#multiple-profiles-for-the-same-provider) - [Custom binary for a provider](#custom-binary-for-a-provider) - [Disabling a provider](#disabling-a-provider) - [ACP providers](#acp-providers) - [Provider override reference](#provider-override-reference) --- ## Extending a built-in provider Use `extends` to create a new provider entry that inherits from a built-in provider (claude, codex, copilot, opencode, pi, omp). The new provider gets its own entry in the provider list, with its own label, environment, and model definitions. ```json { "agents": { "providers": { "my-claude": { "extends": "claude", "label": "My Claude", "description": "Claude with custom API endpoint", "env": { "ANTHROPIC_API_KEY": "sk-ant-...", "ANTHROPIC_BASE_URL": "https://my-proxy.example.com/v1" } } } } } ``` Required fields for custom providers: - `extends` — which built-in provider to inherit from (or `"acp"`) - `label` — display name in the UI See [Codex with a custom OpenAI-compatible endpoint](#codex-with-a-custom-openai-compatible-endpoint) below for the dedicated Codex example. --- ## Z.AI (Zhipu) coding plan [Z.AI](https://z.ai) is a Chinese AI company (Zhipu AI) that offers an Anthropic-compatible API endpoint. Their GLM Coding Plan provides flat-rate access to GLM models through Claude Code's Anthropic API protocol. These are **not** Anthropic Claude models — they are Zhipu's own GLM models exposed through an Anthropic-compatible API. ### Setup 1. Register at [z.ai](https://z.ai) and subscribe to a coding plan 2. Create an API key from the Z.AI dashboard 3. Add a provider entry in config.json: ```json { "agents": { "providers": { "zai": { "extends": "claude", "label": "ZAI", "env": { "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", "API_TIMEOUT_MS": "3000000" }, "disallowedTools": ["WebSearch"], "models": [ { "id": "glm-4.5-air", "label": "GLM 4.5 Air" }, { "id": "glm-5-turbo", "label": "GLM 5 Turbo", "isDefault": true }, { "id": "glm-5.1", "label": "GLM 5.1" } ] } } } } ``` ### Available models | Model | Tier | | ------------- | ------------------- | | `glm-5.1` | Advanced (flagship) | | `glm-5-turbo` | Advanced | | `glm-4.7` | Standard | | `glm-4.5-air` | Lightweight | ### Notes - `ANTHROPIC_AUTH_TOKEN` is used instead of `ANTHROPIC_API_KEY` — this is the z.ai API key - The `API_TIMEOUT_MS` env var extends the request timeout (z.ai can be slower than direct Anthropic) - If you get auth errors, run `/logout` inside Claude Code before switching to the z.ai provider - Web search (`WebSearch` tool) is an Anthropic-only server-side feature — third-party endpoints don't support it. Add `"disallowedTools": ["WebSearch"]` to avoid errors. - Automated setup is also available: `npx @z_ai/coding-helper` - Official docs: [docs.z.ai/devpack/tool/claude](https://docs.z.ai/devpack/tool/claude) --- ## Alibaba Cloud (Qwen) coding plan [Alibaba Cloud Model Studio](https://www.alibabacloud.com/en/campaign/ai-scene-coding) offers a coding plan that routes Claude Code requests to Qwen models through an Anthropic-compatible API. Like z.ai, these are **not** Anthropic Claude models. ### Setup 1. Go to the [Coding Plan page](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=globalset#/efm/coding_plan) on Alibaba Cloud Model Studio (Singapore region) 2. Subscribe to the Pro plan ($50/month) 3. Obtain your plan-specific API key (format: `sk-sp-xxxxx`) — this is different from a standard Model Studio key 4. Add a provider entry in config.json: ```json { "agents": { "providers": { "qwen": { "extends": "claude", "label": "Qwen (Alibaba)", "env": { "ANTHROPIC_AUTH_TOKEN": "sk-sp-", "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic" }, "disallowedTools": ["WebSearch"], "models": [ { "id": "qwen3.5-plus", "label": "Qwen 3.5 Plus", "isDefault": true }, { "id": "qwen3-coder-next", "label": "Qwen 3 Coder Next" }, { "id": "kimi-k2.5", "label": "Kimi K2.5" } ] } } } } ``` ### API endpoints | Mode | Base URL | | ------------------------------- | ----------------------------------------------------------- | | Coding plan (subscription) | `https://coding-intl.dashscope.aliyuncs.com/apps/anthropic` | | Pay-as-you-go (no subscription) | `https://dashscope-intl.aliyuncs.com/apps/anthropic` | For pay-as-you-go, use `ANTHROPIC_API_KEY` with a standard Model Studio key (`sk-xxxxx`) instead of `ANTHROPIC_AUTH_TOKEN`. ### Available models **Recommended for coding plan:** | Model | Notes | | ------------------ | --------------------------- | | `qwen3.5-plus` | Vision capable, recommended | | `qwen3-coder-next` | Optimized for coding | | `kimi-k2.5` | Vision capable | | `glm-5` | Zhipu GLM | | `MiniMax-M3` | MiniMax | **Additional models (pay-as-you-go):** `qwen3-max`, `qwen3.5-flash`, `qwen3-coder-plus`, `qwen3-coder-flash`, `qwen3-vl-plus`, `qwen3-vl-flash` ### Notes - API keys must be created in the **Singapore region** - The coding plan is for personal use only in interactive coding tools - Web search (`WebSearch` tool) is an Anthropic-only server-side feature — third-party endpoints don't support it. Add `"disallowedTools": ["WebSearch"]` to avoid errors. - Official docs: [alibabacloud.com/help/en/model-studio/claude-code-coding-plan](https://www.alibabacloud.com/help/en/model-studio/claude-code-coding-plan) --- ## Codex with a custom OpenAI-compatible endpoint Codex talks to OpenAI's Responses API by default. Custom providers that extend `"codex"` can point Codex at any OpenAI-compatible endpoint (OpenRouter, LiteLLM, vLLM, llama.cpp server, an internal gateway, etc.) by setting `OPENAI_BASE_URL` and `OPENAI_API_KEY` in the provider `env`. Paseo passes those variables through to the Codex app-server process **and** maps them into Codex's thread config under `model_provider` / `model_providers`, because Codex reads provider routing from config rather than from `OPENAI_BASE_URL` alone. ### Setup ```json { "agents": { "providers": { "my-codex": { "extends": "codex", "label": "My Codex", "description": "Codex via custom OpenAI-compatible endpoint", "env": { "OPENAI_API_KEY": "sk-...", "OPENAI_BASE_URL": "https://custom-relay.example.com" }, "models": [{ "id": "custom-model", "label": "Custom Model", "isDefault": true }] } } } } ``` ### What Paseo wires up Under the hood, for each custom Codex provider Paseo injects this into Codex's config: ```toml model_provider = "my-codex" [model_providers.my-codex] name = "My Codex" base_url = "https://custom-relay.example.com/v1" wire_api = "responses" env_key = "OPENAI_API_KEY" requires_openai_auth = false ``` - `base_url` — taken from `OPENAI_BASE_URL`. If it does not already end in `/v1`, Paseo appends `/v1`. Trailing slashes are stripped. - `wire_api` — always `"responses"` (OpenAI Responses API protocol). - `env_key` — set to `"OPENAI_API_KEY"` when that env var is present and non-empty, so Codex reads the key from the same env var Paseo passes through. - `requires_openai_auth` — forced to `false` when `OPENAI_API_KEY` is provided, so Codex skips its built-in OpenAI login flow. ### Notes - The endpoint must speak the OpenAI **Responses API**, not just chat completions. Many gateways (OpenRouter, LiteLLM) support both — pick the Responses-compatible route. - Set `models` explicitly. Custom endpoints expose their own model IDs (`anthropic/claude-opus-4-7`, `qwen/qwen3-coder`, `local/llama`, etc.), and Paseo does not discover them automatically for Codex. - To run multiple endpoints side-by-side, define multiple entries that each extend `"codex"` with different IDs, labels, and env. Each appears as its own provider in the app. - If you only want to override the binary (e.g. a nightly Codex build) without changing the endpoint, omit `OPENAI_BASE_URL` and use `command` instead — see [Custom binary for a provider](#custom-binary-for-a-provider). --- ## Multiple profiles for the same provider You can create multiple entries that extend the same built-in provider. Each gets its own entry in the provider list with independent credentials, models, and environment. "Profile" here means a provider alias, and it is not an **Agent profile** — that is a named bundle of provider, model, mode, thinking option and features, stored under `daemon.agentProfiles`. See [glossary.md](glossary.md) for all four senses of the word. Example: two different Anthropic accounts as separate profiles: ```json { "agents": { "providers": { "claude-work": { "extends": "claude", "label": "Claude (Work)", "description": "Work Anthropic account", "env": { "ANTHROPIC_API_KEY": "sk-ant-work-..." } }, "claude-personal": { "extends": "claude", "label": "Claude (Personal)", "description": "Personal Anthropic account", "env": { "ANTHROPIC_API_KEY": "sk-ant-personal-..." } } } } } ``` Each profile appears as a separate provider in the Paseo app. You can select which one to use when launching an agent. You can also combine profiles with model overrides to pin specific models per profile: ```json { "agents": { "providers": { "claude-fast": { "extends": "claude", "label": "Claude (Fast)", "models": [{ "id": "claude-sonnet-4-6", "label": "Sonnet 4.6", "isDefault": true }] }, "claude-smart": { "extends": "claude", "label": "Claude (Smart)", "models": [{ "id": "claude-opus-4-6", "label": "Opus 4.6", "isDefault": true }] } } } } ``` --- ## Custom binary for a provider Override the command used to launch any provider with the `command` field. This is an array where the first element is the binary and the rest are arguments. ### Override a built-in provider's binary ```json { "agents": { "providers": { "claude": { "command": ["/opt/claude-nightly/claude"] } } } } ``` ### Use a custom wrapper script ```json { "agents": { "providers": { "claude": { "command": ["/usr/local/bin/my-claude-wrapper", "--verbose"] } } } } ``` ### Custom binary on a derived provider ```json { "agents": { "providers": { "my-codex": { "extends": "codex", "label": "Codex (Custom Build)", "command": ["/home/user/codex-dev/target/release/codex"] } } } } ``` The `command` array completely replaces the default command for that provider. The binary must exist on the system — Paseo checks for its availability and will mark the provider as unavailable if not found. ### OMP profiles and Pi-compatible forks OMP ships as a first-class built-in provider option. It is disabled by default; enable it with: ```json { "agents": { "providers": { "omp": { "enabled": true } } } } ``` Custom OMP profiles should extend `omp`. They inherit the OMP adapter's `rpc-ui` approvals, native Paseo host tools, provider-managed subagents, and import behavior: ```json { "agents": { "providers": { "omp-work": { "extends": "omp", "label": "Oh My Pi (Work)", "command": ["omp"], "env": { "XDG_CONFIG_HOME": "~/.config/omp-work", "XDG_STATE_HOME": "~/.local/state/omp-work" }, "options": { "sessionDir": "~/.local/state/omp-work/omp/agent/sessions", "rpcTimeoutMs": 60000, "smolModel": "openai/gpt-5-mini", "slowModel": "anthropic/claude-opus-4-1", "planModel": "openai/o3" } } } } } ``` `options.sessionDir` is used only for importing sessions that were started outside Paseo. If `command` or XDG env vars move OMP's state directory, set `options.sessionDir` to the resulting OMP JSONL session directory; launching and resuming still go through the configured command. OMP waits 20 seconds for its initial `ready` frame and 60 seconds for later control-plane RPCs by default. `options.rpcTimeoutMs` overrides both deadlines. For other providers that keep Pi's `--mode rpc` API but write sessions somewhere else, extend `pi`, replace the command, and provide the JSONL session directory: ```json { "agents": { "providers": { "my-pi-fork": { "extends": "pi", "label": "My Pi Fork", "command": ["my-pi-fork"], "options": { "sessionDir": "~/.my-pi-fork/sessions", "rpcTimeoutMs": 60000 } } } } } ``` This session directory is also import-only. Launching and resuming still go through the configured command, so this example resumes with `my-pi-fork --mode rpc --session `. `options.rpcTimeoutMs` overrides the 60-second Pi control-plane RPC deadline. --- ## Disabling a provider Set `enabled: false` to hide a provider from the provider list. The provider will not appear in the app or CLI. ```json { "agents": { "providers": { "copilot": { "enabled": false }, "codex": { "enabled": false } } } } ``` This works for both built-in and custom providers. To re-enable, set `enabled: true` or remove the `enabled` field entirely. Most providers are enabled by default; OMP is intentionally disabled by default and requires `enabled: true`. --- ## ACP providers The [Agent Client Protocol (ACP)](https://agentclientprotocol.com) is an open standard for communication between editors and AI coding agents — think LSP but for AI agents. Any agent that supports ACP can be added to Paseo as a custom provider. ACP agents communicate over JSON-RPC 2.0 on stdio. Paseo spawns the agent process and talks to it through stdin/stdout. Paseo also ships an in-app ACP provider catalog for common agents, including CodeWhale, Cursor, DeepAgents, DimCode, Gemini CLI, Hermes, Qwen Code, and Kimi Code. Most catalog entries create the same `extends: "acp"` provider config shown below. Hoplite activates its [bundled provider](plugins.md#built-in-plugins) instead. ### Adding a generic ACP provider Set `extends: "acp"` and provide a `command`: ```json { "agents": { "providers": { "my-agent": { "extends": "acp", "label": "My Agent", "command": ["my-agent-binary", "--acp"], "env": { "MY_API_KEY": "..." } } } } } ``` Required fields for ACP providers: - `extends: "acp"` - `label` - `command` — the command to spawn the agent process (must support ACP over stdio) Paseo tools such as subagent creation come from the shared internal tool catalog. ACP providers receive those tools through the MCP fallback by default because ACP exposes `mcpServers`, not Paseo's native tool catalog. Some ACP adapters cannot create sessions when `mcpServers` is non-empty. Disable injected MCP for those providers with `options.supportsMcpServers: false`: ```json { "agents": { "providers": { "my-agent": { "extends": "acp", "label": "My Agent", "command": ["my-agent", "acp"], "options": { "supportsMcpServers": false } } } } } ``` ACP agents execute filesystem operations in their own environment by default, while terminal operations run through Paseo on the host. To customize which operations Paseo handles, configure client capabilities in provider options: ```json { "agents": { "providers": { "container-agent": { "extends": "acp", "label": "Container Agent", "command": ["container-agent", "acp"], "options": { "clientCapabilities": { "fs": { "readTextFile": false, "writeTextFile": false }, "terminal": false } } } } } } ``` When an agent runs in a container or remote environment that manages its own terminal, set `terminal: false` to keep command execution inside the agent container. When delegating filesystem operations to Paseo (`fs.readTextFile: true` or `fs.writeTextFile: true`), ensure the agent and Paseo share equivalent absolute workspace paths. ### Generic ACP diagnostics Paseo diagnostics for `extends: "acp"` providers report the configured command, resolved launcher binary, version output, ACP `initialize`, ACP `session/new`, model count, modes, and final status. For package-runner commands such as `npx -y @google/gemini-cli --acp`, the version probe keeps the package spec and runs `npx -y @google/gemini-cli --version`. This diagnoses the actual agent package instead of only proving that `npx` exists. ACP probes use short timeouts and browser-suppression environment variables so agents that enter an auth/browser flow fail as a diagnostic error instead of hanging the provider screen. ### Example: Google Gemini CLI [Gemini CLI](https://github.com/google-gemini/gemini-cli) supports ACP via the `--acp` flag. 1. Install: `npm install @google/gemini-cli` or see [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) 2. Authenticate with Google (Gemini CLI handles its own auth) 3. Add to config.json: ```json { "agents": { "providers": { "gemini": { "extends": "acp", "label": "Google Gemini", "command": ["gemini", "--acp"] } } } } ``` Ref: [Gemini CLI ACP mode docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/acp-mode.md) ### Example: Hermes (Nous Research) [Hermes](https://github.com/NousResearch/hermes-agent) is an open-source coding agent by Nous Research with persistent memory and multi-provider LLM support. It supports ACP via the `acp` subcommand. 1. Install: `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash` 2. Install ACP support: `pip install -e '.[acp]'` 3. Configure Hermes credentials in `~/.hermes/` 4. Add to config.json: ```json { "agents": { "providers": { "hermes": { "extends": "acp", "label": "Hermes", "description": "Nous Research self-improving AI agent", "command": ["hermes", "acp"] } } } } ``` Ref: [Hermes ACP docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp) ### How ACP providers work in Paseo When you launch an agent with an ACP provider: 1. Paseo spawns the process using the configured `command` 2. Sends an `initialize` JSON-RPC request over stdin 3. The agent responds with its capabilities, available modes, and models 4. Paseo creates a session and sends prompts through the ACP protocol 5. The agent streams responses, tool calls, and permission requests back over stdout Every ACP provider exposes an **Auto Accept** toggle. Enable it per session to let Paseo approve ACP permission requests without surfacing each prompt. If the provider sends no allow option, Paseo leaves the request for you to answer. Unattended agents enable Auto Accept unless you explicitly disable it. Models and modes are discovered dynamically at runtime from the agent process. If you want to override the model list (e.g., to curate which models appear in the UI), use the `models` field: ```json { "agents": { "providers": { "my-agent": { "extends": "acp", "label": "My Agent", "command": ["my-agent", "--acp"], "models": [ { "id": "fast-model", "label": "Fast", "isDefault": true }, { "id": "smart-model", "label": "Smart" } ] } } } } ``` Profile models (defined in config.json) completely replace runtime-discovered models when present. If you want to keep runtime-discovered models and add or relabel a few entries, use `additionalModels` instead. Example: add an experimental model while keeping every model the provider discovers at runtime: ```json { "agents": { "providers": { "my-agent": { "extends": "acp", "label": "My Agent", "command": ["my-agent", "--acp"], "additionalModels": [ { "id": "experimental-model", "label": "Experimental", "isDefault": true } ] } } } } ``` Example: relabel a discovered model without replacing the full list: ```json { "agents": { "providers": { "my-agent": { "extends": "acp", "label": "My Agent", "command": ["my-agent", "--acp"], "additionalModels": [{ "id": "provider/model-id", "label": "My Preferred Label" }] } } } } ``` When an `additionalModels` entry has the same `id` as a discovered model, it updates that model in place. --- ## Provider override reference Every entry under `agents.providers` accepts these fields: | Field | Type | Required | Description | | ------------------ | ------------------------- | ----------------- | ------------------------------------------------------------------ | | `extends` | `string` | Yes (custom only) | Built-in provider ID to inherit from, or `"acp"` | | `label` | `string` | Yes (custom only) | Display name in the UI | | `description` | `string` | No | Short description shown in the UI | | `command` | `string[]` | Yes (ACP only) | Command to spawn the agent process | | `env` | `Record` | No | Environment variables to set for the agent process | | `options` | `Record` | No | Provider-specific options such as `supportsMcpServers: false` | | `models` | `ProviderProfileModel[]` | No | Static model list (overrides runtime discovery) | | `additionalModels` | `ProviderProfileModel[]` | No | Static model additions (merged with runtime discovery or `models`) | | `disallowedTools` | `string[]` | No | Tool names to disable for this provider (e.g. `["WebSearch"]`) | | `enabled` | `boolean` | No | Set to `false` to hide the provider (default: `true`) | | `order` | `number` | No | Sort order in the provider list | ### Model definition Each entry in the `models` array: | Field | Type | Required | Description | | ----------------- | ------------------ | -------- | ------------------------------------- | | `id` | `string` | Yes | Model identifier sent to the provider | | `label` | `string` | Yes | Display name in the UI | | `description` | `string` | No | Short description | | `isDefault` | `boolean` | No | Mark as the default model selection | | `thinkingOptions` | `ThinkingOption[]` | No | Available thinking/reasoning levels | ### Thinking option | Field | Type | Required | Description | | ------------- | --------- | -------- | ----------------------------------- | | `id` | `string` | Yes | Thinking option identifier | | `label` | `string` | Yes | Display name | | `description` | `string` | No | Short description | | `isDefault` | `boolean` | No | Mark as the default thinking option | ### Claude settings.json model discovery The built-in `claude` provider appends concrete model IDs from `~/.claude/settings.json` to its first-party Claude model list. Paseo reads the top-level `model` field and these `env` keys: `ANTHROPIC_MODEL`, `ANTHROPIC_SMALL_FAST_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. This lets users who already configured Claude Code for Bedrock, OpenRouter, ollama, Z.AI, or another Anthropic-compatible gateway select the exact model ID in Paseo. Explicit model IDs are passed unchanged to Claude Code, even when the same string is a compatibility alias for a built-in model. When `agents.providers.claude.models` is set it **replaces** both the hardcoded first-party Claude list and any settings.json-discovered entries; use `agents.providers.claude.additionalModels` to keep the first-party list and append curated entries on top. ### Gotcha: `extends: "claude"` with third-party endpoints When a custom provider extends `"claude"` but points `ANTHROPIC_BASE_URL` at a non-Anthropic API (Z.AI, Alibaba/Qwen, proxies), the Claude Agent SDK may try to use Anthropic-only server-side tools like `WebSearch`. Third-party APIs don't support these tools, causing errors. Use `disallowedTools` to disable unsupported tools: ```json { "agents": { "providers": { "my-proxy": { "extends": "claude", "label": "My Proxy", "env": { "ANTHROPIC_BASE_URL": "https://my-proxy.example.com/v1" }, "disallowedTools": ["WebSearch"] } } } } ``` ### Valid `extends` values Built-in providers: `claude`, `codex`, `copilot`, `opencode`, `pi`, `omp` Special value: `acp` — creates a generic ACP provider (requires `command`) ### Full example A config.json with multiple custom providers: ```json { "version": 1, "agents": { "providers": { "copilot": { "enabled": false }, "zai": { "extends": "claude", "label": "ZAI", "env": { "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", "API_TIMEOUT_MS": "3000000" }, "disallowedTools": ["WebSearch"], "models": [ { "id": "glm-4.5-air", "label": "GLM 4.5 Air" }, { "id": "glm-5-turbo", "label": "GLM 5 Turbo", "isDefault": true }, { "id": "glm-5.1", "label": "GLM 5.1" } ] }, "qwen": { "extends": "claude", "label": "Qwen (Alibaba)", "env": { "ANTHROPIC_AUTH_TOKEN": "sk-sp-", "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic" }, "disallowedTools": ["WebSearch"], "models": [ { "id": "qwen3.5-plus", "label": "Qwen 3.5 Plus", "isDefault": true }, { "id": "qwen3-coder-next", "label": "Qwen 3 Coder Next" } ] }, "gemini": { "extends": "acp", "label": "Google Gemini", "command": ["gemini", "--acp"] }, "hermes": { "extends": "acp", "label": "Hermes", "command": ["hermes", "acp"] } } } } ``` --- ### Data Model (`docs/data-model.md`) # Data Model ## Project identity Projects are allocated for the exact root selected by the caller, normalized lexically with `path.resolve` (never `realpath`). New project IDs are opaque `prj_<16 hex>` values. Existing remote-shaped or path-shaped IDs are retained as readable compatibility records and are never rekeyed. An active exact root is idempotent; archived-only matches do not resurrect an old project. Workspace `projectId` is stable membership: reconciliation may update git-derived kind and branch metadata, but never rehomes a workspace or changes a project's root, ID, or default name. `projectKey` is a persisted, opaque equivalence key used only to group the same logical project across hosts. It is separate from the host-local `projectId`; today's producer prefers a normalized Git remote and otherwise uses the local project root. Consumers never derive it from live Git. Creation persists it with the project, and normal boot reconciliation fills it for older records where the field is absent—there is no migration. `kind` and `projectKey` are mutable metadata, not identity. Workspace reconciliation watches active project roots and updates those fields and `updatedAt` when Git facts change, preserving the project's ID, root path, names, and workspace foreign keys. Attached workspaces are independently refreshed from their own cwd, so an explicit project root never implies a workspace checkout. Empty projects are observed too. The workspace registry model defines placement once: initial directory/worktree construction, mutable reconciliation fields, and the persisted-to-wire checkout projection. Its update policy preserves `displayName` and `baseBranch`. `WorkspaceProvisioningService` owns the corresponding registry writes, so directory opens, agent imports, and worktree creation all enter through that service instead of constructing records independently. The workspace record is then the durable placement authority: `cwd` is the exact execution directory, while `worktreeRoot` is the backing checkout root. They intentionally differ for an exact subproject inside a worktree. Archive, restore, branch auto-name, and descriptor flows consume those persisted facts rather than rediscovering ownership from a directory that may already be gone. Reconciliation may refresh mutable placement facts, but never changes `projectId`, `cwd`, `displayName`, or `baseBranch`. Workspace archive runs lifecycle teardown from the exact `cwd` but removes only the backing `worktreeRoot` after its last active reference disappears. Worktree recovery recreates that backing checkout from `mainRepoRoot`, then restores the relative path from `worktreeRoot` to `cwd`. Paseo uses **file-based JSON persistence** instead of a traditional database. All data is validated at runtime with Zod schemas. Most stores write atomically (write to temp file, then rename); a few still use plain `writeFile` — see each section. There is no schema-versioning/migration framework — schemas rely on optional fields with defaults for forward compatibility, with a small amount of inline normalization in `persisted-config.ts` for legacy provider/speech entries. All server-side stores live under `$PASEO_HOME` (defaults to `~/.paseo`). ## Store Surface Rules Store APIs own persistence atomicity and should not make services coordinate raw reads and writes. A good store method maps cleanly to one SQL statement or one SQL transaction, even when the current implementation is JSON files. If a caller needs a queue, lock, read-merge-write loop, or uniqueness race workaround, that behavior belongs behind the store surface. --- ## Directory layout ``` $PASEO_HOME/ ├── config.json # Daemon configuration ├── server-id # Stable daemon identifier (plain text, "srv_") ├── daemon-keypair.json # E2EE keypair for relay (mode 0600) ├── paseo.pid # Daemon PID lock file ├── local-credential # Per-run local client credential (mode 0600) ├── daemon.log # Default log file (path configurable) ├── agents/ │ └── {sanitized-cwd}/ │ └── {agentId}.json # One file per agent ├── schedules/ │ └── {scheduleId}.json # One file per schedule ├── projects/ │ ├── projects.json # Project registry │ ├── workspaces.json # Workspace registry │ ├── workspace-labels.json # Shared host-local label catalog │ ├── workspace-labels.transaction.json # Recoverable catalog/assignment compound commit │ └── icons/ # Host-local custom project icon images ├── runtime/ │ └── managed-processes/ │ └── {recordId}.json # Helper processes owned by Paseo; reconciled on daemon bootstrap ├── plugins/ │ ├── sources.json # Managed kind and Git acquisition remote │ └── {pluginId}/{uuid}/ # Git checkout or npm package/lockfile/dependency tree └── push-tokens.json # Expo push notification tokens ``` The `agents/{sanitized-cwd}/` directory name is derived from the agent's `cwd` by stripping the filesystem root and replacing path separators with `-` (Windows drive letters become a `C-` style prefix). Persistent server stores write atomically by writing a temp file in the target directory and then renaming it into place. --- ## 1. Agent Record **Path:** `$PASEO_HOME/agents/{project-dir}/{agentId}.json` Each agent is stored as a separate JSON file, grouped by project directory. | Field | Type | Description | | -------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | UUID, primary key | | `provider` | `string` | Agent provider (`"claude"`, `"codex"`, `"opencode"`, etc.) | | `cwd` | `string` | Working directory the agent operates in | | `workspaceId` | `string?` | Owning workspace id — the single source of ownership. Every agent is stamped with one at create time; legacy cwd-only records are backfilled once by `migrations/backfill-workspace-id.migration.ts` (the only place a cwd→id mapping exists). Runtime code never infers ownership or status from cwd: status is computed per `workspaceId`, and same-cwd siblings are independent. | | `createdAt` | `string` (ISO 8601) | Creation timestamp | | `updatedAt` | `string` (ISO 8601) | Last update timestamp | | `lastActivityAt` | `string?` (ISO 8601) | Last activity timestamp | | `lastUserMessageAt` | `string?` (ISO 8601) | Last user message timestamp | | `title` | `string?` | User-visible title | | `labels` | `Record` | Key-value labels (default `{}`). Paseo uses `paseo.parent-agent-id` for parentage and client-scoped `paseo.open-agent-tab.*` labels while managed subagent tabs are open — see [agent-lifecycle.md](./agent-lifecycle.md) | | `lastStatus` | `AgentStatus` | One of: `"initializing"`, `"idle"`, `"running"`, `"error"`, `"closed"`. `closed` means the record is resumable but has no live provider runtime; archive remains represented separately by `archivedAt`. | | `lastModeId` | `string?` | Last active mode ID | | `config` | `SerializableConfig?` | Agent session configuration (see below) | | `runtimeInfo` | `RuntimeInfo?` | Live runtime state (see below) | | `features` | `AgentFeature[]?` | Provider-reported features (toggles/selects) | | `persistence` | `PersistenceHandle?` | Handle for resuming sessions | | `lastError` | `string?` (nullable) | Last error message, if any | | `requiresAttention` | `boolean?` | Whether the agent needs user attention | | `attentionReason` | `"finished" \| "error" \| "permission"?` | Why attention is needed | | `attentionTimestamp` | `string?` (ISO 8601) | When attention was flagged | | `internal` | `boolean?` | Whether this is a system-internal agent | | `archivedAt` | `string?` (ISO 8601) | Soft-delete timestamp | ### Nested: SerializableConfig | Field | Type | Description | | ------------------ | -------------------------- | ---------------------------- | | `title` | `string?` | Configured title | | `modeId` | `string?` | Configured mode | | `model` | `string?` | Configured model | | `thinkingOptionId` | `string?` | Thinking/reasoning level | | `featureValues` | `Record?` | Feature preference overrides | | `extra` | `Record?` | Provider-specific config | | `systemPrompt` | `string?` | Custom system prompt | | `mcpServers` | `Record?` | MCP server configurations | ### Nested: RuntimeInfo | Field | Type | Description | | ------------------ | -------------------------- | ------------------------------ | | `provider` | `string` | Active provider | | `sessionId` | `string?` | Active session ID | | `model` | `string?` | Active model | | `thinkingOptionId` | `string?` | Active thinking option | | `modeId` | `string?` | Active mode | | `extra` | `Record?` | Provider-specific runtime data | ### Nested: PersistenceHandle | Field | Type | Description | | -------------- | ---------------------- | --------------------------------------------------------------------- | | `provider` | `string` | Provider that owns the session | | `sessionId` | `string` | Session ID for resumption | | `nativeHandle` | `any?` | Provider-specific handle (Codex thread ID, Claude resume token, etc.) | | `metadata` | `Record?` | Extra metadata | ### Nested: AgentFeature (discriminated union on `type`) **Toggle:** | Field | Type | | ------------- | ---------- | | `type` | `"toggle"` | | `id` | `string` | | `label` | `string` | | `description` | `string?` | | `tooltip` | `string?` | | `icon` | `string?` | | `value` | `boolean` | **Select:** | Field | Type | | ------------- | --------------------- | | `type` | `"select"` | | `id` | `string` | | `label` | `string` | | `description` | `string?` | | `tooltip` | `string?` | | `icon` | `string?` | | `value` | `string \| null` | | `options` | `AgentSelectOption[]` | --- ## Runtime-only Terminal Sessions Terminals are live daemon state, not persisted JSON records. A terminal carries a `workspaceId` while it is running; workspace-scoped terminal lists include only terminals with the matching `workspaceId`. Legacy live terminals without an owner remain visible to unscoped terminal reads but contribute to no workspace status. Terminal activity contributes to the workspace status bucket **per `workspaceId`**: a working terminal drives `running` onto the workspace it carries only. Same-`cwd` siblings are untouched; terminal visibility is likewise `workspaceId`-scoped. --- ## 2. Daemon Configuration **Path:** `$PASEO_HOME/config.json` Single file, validated with `PersistedConfigSchema`. `agents.skills.selection` is the daemon host's orchestration-skill preference. Missing means `{ mode: "all" }`. Installed state is not persisted; the daemon derives it from the shared `~/.agents/skills` and Claude skill directories and keeps config plus filesystem convergence behind one serialized owner. Codex discovers the shared directory. Updates retire unchanged files from Paseo-managed copies in `~/.codex/skills`, preserving user edits and untracked files. `paseo reload` reads and validates this file once inside the daemon. That snapshot drives resolution, classification, application, and reload bookkeeping. `DaemonConfigStore` owns applying runtime-safe fields and their removal/default semantics; session handlers and the CLI only relay the structured result. Normal config patches persist only the requested fields, so launch overrides and resolved defaults never leak into the file. Startup-only fields remain compared with the daemon's launch snapshot so a mixed edit can apply its live subset and still name the paths that require restart. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` All fields are optional with sensible defaults. Managed plugins appear as directory sources in `config.json`; it owns the active path and enabled state. `plugins/sources.json` is written atomically and stores only managed kind and the Git acquisition remote. Installed revision, package/subdirectory identity and ownership root come from retained artifacts and the fixed managed layout; [managed source ownership](plugins.md#managed-source-ownership) explains their authority. An update prepares a new directory before replacing the active path and removing the previous version. Old record fields are accepted at the store boundary and ignored; there is no startup migration or persistent update policy. ### Profile lists `terminalProfiles` and `agentProfiles` are both whole-list fields: a config patch replaces the array, never merges entries, so a client sends the complete next list on every add, edit, reorder and remove. List order is the display order. Absent and empty mean different things for terminal profiles — omitting the key falls back to `DEFAULT_TERMINAL_PROFILES`, while `[]` means the user removed them all. Agent profiles have no defaults, so both mean none. `PersistedConfigSchema` parses strictly, so a daemon that predates a field drops it on write rather than storing something it cannot describe. That is why the client gates the agent profiles UI on `server_info.features.agentProfiles` instead of letting a save appear to succeed against an older daemon. ### Agent provider Paseo tools `agents.providers` is keyed by the exact provider ID used to launch the agent. The built-in IDs are `claude`, `codex`, `copilot`, `opencode`, `pi`, and `omp`. Custom provider IDs are their literal configuration keys, such as `my-claude` or `zai`, not the provider named by `extends`. Each entry may include a Paseo-tool policy: ```json { "agents": { "providers": { "my-claude": { "extends": "claude", "label": "My Claude", "paseoTools": { "enabled": true, "disabledTools": ["browser_evaluate"] } } } } } ``` Absent `paseoTools`, or absent fields within it, means Paseo tools are enabled and all tools are allowed. `enabled: false` disables the provider's Paseo catalog; `disabledTools` lists exact tool IDs to omit. The policy covers the core and browser catalog, not the voice-only `speak` tool. Browser tools also require `daemon.browserTools.enabled` and a connected browser host. This policy controls the catalog presented to an agent. It is not an authorization boundary for agents that can access the host through a shell. `daemon.mcp.injectIntoAgents` is the global override. When it is `false`, no provider receives Paseo tools; otherwise the provider policy applies. Provider and global policy are resolved when a session is created, resumed, imported, or reloaded, so configuration changes affect the next session rather than an already-running one. `agents.metadataGeneration.providers` selects the models for daemon-side metadata tasks: commit messages, PR text, branch names, and generated titles. An empty list is Automatic; a non-empty list is Manual and only those models are tried. See [public-docs/metadata-generation.md](../public-docs/metadata-generation.md#how-a-model-is-chosen). ### Git process limits Git process limits are global to one daemon. The start-rate limit defaults to `64` processes per second, and the concurrency limit defaults to `8`: ```json { "daemon": { "git": { "maxProcessesPerSecond": 64, "maxProcessConcurrency": 8 } } } ``` `maxProcessesPerSecond` limits Git process starts in any one-second interval. The allowance can start as a burst; it does not wait for earlier processes to exit. `maxProcessConcurrency` limits the number of Git processes that have started but not exited. Every Git command uses both limits, including initial workspace reads, filesystem-triggered refreshes, background checks, and explicit requests. Environment variables override `config.json`: | Environment variable | Setting | | ------------------------------------ | ------------------------ | | `PASEO_GIT_MAX_PROCESSES_PER_SECOND` | `maxProcessesPerSecond` | | `PASEO_GIT_MAX_PROCESS_CONCURRENCY` | `maxProcessConcurrency` | | `PASEO_GIT_CONCURRENCY` | Legacy concurrency alias | `PASEO_GIT_MAX_PROCESS_CONCURRENCY` wins when it and the legacy alias are both set. Run `paseo reload` after changing `config.json`. Environment changes require a daemon restart; the launch environment remains authoritative during reload. Local speech model ids are intentionally narrow: STT uses `parakeet-tdt-0.6b-v2-int8`, TTS uses `kokoro-en-v0_19`, and turn detection uses the bundled Silero VAD model. Set these to select OpenAI instead of local speech: | Env var | Applies to | | ------------------------------ | ------------------------------- | | `PASEO_VOICE_STT_PROVIDER` | Voice mode STT provider | | `PASEO_DICTATION_STT_PROVIDER` | Composer dictation STT provider | | `PASEO_VOICE_TTS_PROVIDER` | Voice mode TTS provider | OpenAI speech can be configured under `providers.openai`. STT and TTS resolve independently, so they can point at different endpoints: ```json { "providers": { "openai": { "stt": { "apiKey": "sk-...", "baseUrl": "https://stt.example.com/v1" }, "tts": { "apiKey": "sk-...", "baseUrl": "https://api.openai.com/v1" } } } } ``` `providers.openai.stt` is used for both composer dictation and voice mode speech-to-text; `providers.openai.tts` is used for voice mode text-to-speech. The equivalent env vars are `OPENAI_STT_API_KEY`/`OPENAI_STT_BASE_URL` and `OPENAI_TTS_API_KEY`/`OPENAI_TTS_BASE_URL`. Each feature falls back to `providers.openai.apiKey`/`providers.openai.baseUrl`, then `OPENAI_API_KEY`/`OPENAI_BASE_URL`, when its own fields are unset. These settings apply only to Paseo OpenAI speech features, not to Codex or other OpenAI-backed tools. Paseo uses these paths under the configured OpenAI base URL: - dictation STT: `/v1/audio/transcriptions` - voice mode STT: `/v1/audio/transcriptions` - voice mode TTS: `/v1/audio/speech` --- ## 3. Schedule **Path:** `$PASEO_HOME/schedules/{id}.json` One file per schedule. ID is 8 hex characters. | Field | Type | Description | | ----------- | ------------------------------------- | -------------------------------- | | `id` | `string` | 8-char hex ID | | `name` | `string?` | Human-readable name | | `prompt` | `string` | The prompt to send | | `cadence` | `ScheduleCadence` | Timing (see below) | | `target` | `ScheduleTarget` | What to run (see below) | | `status` | `"active" \| "paused" \| "completed"` | Current state | | `createdAt` | `string` (ISO 8601) | | | `updatedAt` | `string` (ISO 8601) | | | `nextRunAt` | `string?` (ISO 8601) | Next scheduled execution | | `lastRunAt` | `string?` (ISO 8601) | Last execution time | | `pausedAt` | `string?` (ISO 8601) | When paused | | `expiresAt` | `string?` (ISO 8601) | Auto-expire time | | `maxRuns` | `number?` | Max executions before completing | | `runs` | `ScheduleRun[]` | Execution history | ### Nested: ScheduleCadence (discriminated union on `type`) - `{ type: "cron", expression: string, timezone?: string }` — canonical cadence for new writes; absent `timezone` means UTC - `{ type: "every", everyMs: number }` — legacy rolling interval, still readable and executable during the compatibility window ### Nested: ScheduleTarget (discriminated union on `type`) - `{ type: "agent", agentId: string }` — send to existing agent - `{ type: "new-agent", config: { provider, cwd, modeId?, model?, thinkingOptionId?, title?, providerOptions?, featureValues?, systemPrompt?, mcpServers? } }` — create a new agent ### Nested: ScheduleRun | Field | Type | Description | | -------------- | -------------------------------------- | ----------------------- | | `id` | `string` | Run ID | | `scheduledFor` | `string` (ISO 8601) | Intended execution time | | `startedAt` | `string` (ISO 8601) | | | `endedAt` | `string?` (ISO 8601) | | | `status` | `"running" \| "succeeded" \| "failed"` | | | `agentId` | `string?` (UUID) | Agent used for this run | | `output` | `string?` | Agent output text | | `error` | `string?` | Error message if failed | --- ## 4. Project Registry **Path:** `$PASEO_HOME/projects/projects.json` Array of project records. | Field | Type | Description | | -------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `projectId` | `string` | Host-local primary key; new records use opaque `prj_<16 hex>` IDs | | `projectKey` | `string \| null` | Persisted opaque cross-host grouping key; reconciliation backfills absent values | | `rootPath` | `string` | Exact lexically normalized selected root; never realpathed | | `kind` | `"git" \| "non_git"` | Mutable Git observation about `rootPath`, never a membership key | | `displayName` | `string` | Selected-root basename, stable across remote and Git changes | | `customName` | `string \| null` | User-set override layered over `displayName`. Null means "use the derived name". | | `customIconRevision` | `string \| null` | Identifies the host-local custom icon stored under `projects/icons/`. Null means the icon is discovered by scanning the project directory. | | `createdAt` | `string` (ISO 8601) | | | `updatedAt` | `string` (ISO 8601) | | | `archivedAt` | `string \| null` (ISO 8601) | Soft-delete timestamp; required nullable | Uploading a file and pasting a website or image URL are two ways of _acquiring_ the same custom icon. The client fetches URL imports and sends their bytes through the upload RPC. The daemon never receives or fetches the URL; it validates the uploaded bytes, stores them, and records a new `customIconRevision`. Going back to automatic deletes the stored image, as does removing the project. Active exact roots are idempotent using lexical platform-equivalence semantics. Existing legacy remote-shaped and path-shaped IDs remain readable, including duplicate roots; reconciliation never merges them, transfers names, archives them, or moves workspace foreign keys. An explicit workspace `projectId` is authoritative when it names an active project, regardless of cwd containment. Archived-only exact-root records are not resurrected by explicit add/open; a fresh opaque project is allocated instead. Agent restore is separate and restores the agent's existing workspace together with its owning project. --- ## 5. Workspace Registry **Path:** `$PASEO_HOME/projects/workspaces.json` Array of workspace records. A workspace is a specific working directory within a project. | Field | Type | Description | | ------------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspaceId` | `string` | Opaque stable identifier (`wks_`), generated independently of the directory. MUST NOT be treated as a path; compare by exact equality. Use the `cwd` field for directory access. | | `projectId` | `string` | FK to Project.projectId; the workspace's stable project membership | | `cwd` | `string` | Exact execution directory selected for agents, files, scripts, and setup | | `kind` | `"local_checkout" \| "worktree" \| "directory"` | Mutable checkout classification | | `displayName` | `string` | The human name (the generated/derived title). Decoupled from `branch` by construction. | | `title` | `string \| null` | User-set name override layered over `displayName`. Null means "use `displayName`". | | `branch` | `string \| null` | The current Git branch for git-backed workspaces. Separate from `displayName`/`title`; a background branch refresh never rewrites the name. | | `worktreeRoot` | `string \| null` | Backing checkout/worktree root. May differ from `cwd` for exact subprojects and remains persisted after the worktree is deleted so restore can reproduce the placement. | | `baseBranch` | `string \| null` | Comparison base retained across archive and restore. Branch-off creation stores the resolved ref; legacy and PR-checkout records hold a bare name. Null means no recorded base. | | `isPaseoOwnedWorktree` | `boolean` | Whether Paseo owns and may remove/recreate the backing `worktreeRoot` | | `mainRepoRoot` | `string \| null` | Main repository root for worktree checkouts, independent of both exact `cwd` and backing `worktreeRoot` | | `createdAt` | `string` (ISO 8601) | | | `updatedAt` | `string` (ISO 8601) | | | `archivedAt` | `string \| null` (ISO 8601) | Soft-delete; required nullable | | `autoArchivedChangeRequestUrl` | `string \| null` | Change request whose merged state triggered auto-archive. Restore replaces it with the current merged change request, when present, so repeated snapshots cannot archive the workspace again. | | `labels` | `string[]?` | Normalized display names assigned from this host's shared label catalog. Missing means unlabelled. | | `pinnedAt` | `string \| null` (ISO 8601) | Pinned-to-top-of-sidebar timestamp; null means "not pinned" | | `untrustedSource` | `{ kind: "change_request", forge, number, headRepository }?` | Provenance captured when a cross-repository change request creates the workspace. Missing means repository automation is allowed; explicit setup removes the field. | > **Opaque-ID invariant:** `workspaceId` is opaque identity, never a filesystem path. Filesystem and git operations take `cwd`/`workspaceDirectory` only — never the id. A compatibility-only first-materialization bootstrap still groups pre-registry agent records by path and Git remote so existing installs retain their legacy records. That grouping never runs against a live registry, and its keys are not runtime project or workspace identity. ### Workspace label catalog **Path:** `$PASEO_HOME/projects/workspace-labels.json` The catalog is shared by every workspace on one host. A definition contains a display name and one of the ten identity colour names (`WORKSPACE_LABEL_COLORS` in `packages/protocol/src/workspace-labels.ts`); trimmed, collapsed, case-insensitive name identity is unique within that file. Definitions have no portable ID or principal owner and remain after their last assignment. Editing a label takes a new name, a new colour, or both in one commit, so the two fields cannot land half-applied. Workspaces store label names, so a rename and a delete rewrite workspace assignments through one serialized compound commit while a recolour is catalog-only; a rename onto a name the host already has is refused rather than merged. A prepared `workspace-labels.transaction.json` contains both before and after images. The daemon writes the catalog and workspace files, then atomically changes the transaction to committed; that phase change is the durable commit point. Recovery rolls prepared transactions back before either directory is served. A committed marker proves both data files were already written, so recovery only loads the current catalog and retries marker cleanup; it never reapplies stale workspace after-images over later registry mutations. A request rejected before the commit point therefore cannot take effect after restart. If the live daemon cannot determine or restore the durable state, the workspace registry freezes every write and later label mutations fail with `workspace_label_storage_uncertain` until daemon restart performs recovery. Reads remain available, but may reflect the last acknowledged cache until restart. Workspace directory and catalog updates publish only after the commit point; publication failure does not roll durable state back. `projectId` is still a real FK: workspace records should have a matching project record. Read-only history surfaces tolerate transient orphaned workspaces by omitting those rows so one bad FK cannot blank the whole History screen, but mutation paths should repair or remove the orphaned state rather than treating it as valid. --- ## 6. Push Token Store **Path:** `$PASEO_HOME/push-tokens.json` ```json { "tokens": ["ExponentPushToken[...]", ...] } ``` Simple set of Expo push notification tokens. Loaded with permissive parsing (filters non-string entries). Persisted with atomic temp-file rename. --- ## 7. Daemon meta files These small files are not validated as full Zod schemas but are persisted under `$PASEO_HOME` for daemon identity and runtime coordination. | Path | Format | Notes | | --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `server-id` | Plain text, e.g. `srv_` | Stable per-`$PASEO_HOME` daemon ID. Overridable via `PASEO_SERVER_ID` env. | | `daemon-keypair.json` | `{ v: 2, publicKeyB64, secretKeyB64 }` (libsodium box keypair) | E2EE relay identity. Written with mode `0600`. Regenerated if file is unreadable. | | `paseo.pid` | JSON `{ pid, startedAt, ... }` | PID lock; prevents two daemons sharing one `$PASEO_HOME`. | | `local-credential` | 32 random bytes encoded as base64url text | Rotated before each listen and deleted on shutdown; mode `0600`. | | `daemon.log` | Pino log output | Default location; path/rotation configurable via `log.file` in `config.json`. | --- ## Client-side stores (App) These live in React Native `AsyncStorage` or browser `IndexedDB`, not on the daemon filesystem. ### Keying convention: directory-backed vs workspace-owned Right-sidebar client state splits on whether it is determined by the directory or owned by the workspace (two workspaces can share one `cwd`). The split is enforced by the cache key, so changing a key changes the sharing semantics — see [architecture.md](architecture.md#right-sidebar-boundary-directory-backed-vs-workspace-owned) for the full table. - **Directory-backed** (shared by same-`cwd` workspaces): keyed by `(serverId, cwd)`. Git status/diff, GitHub PR status, PR timeline, file preview content. These are TanStack Query caches, not persisted stores. - **Workspace-owned** (independent per workspace): keyed by `workspaceId`, with `cwd` used only as a fallback when no `workspaceId` is present. Review draft comments (`@paseo:review-draft-store`), diff-mode overrides (in-memory), workspace composer attachments, and file-explorer nav/expand state. The `workspaceId` part of these keys is **opaque** — never parse it back into a path. ### Replica row store The durable client replica uses IndexedDB on browser/Electron and expo-sqlite on native. Rows use the compound key `(serverId, kind, id)`; kinds are `agent`, `workspace`, `project`, `timeline`, and `checkpoint`. Directory entities have individual rows, timelines use the agent id, and the checkpoint uses the singleton id. The store is a typed persistence boundary. It returns values to directory and timeline owners and accepts their explicit commits; it never reads or writes UI state. Reads are scoped to the requested host, kinds, and ids. Opening a cached workspace uses exact workspace and project keys rather than a directory scan. One invalid row is deleted and returned as a miss without affecting other rows. An invalid directory row and its affected checkpoint cursor are repaired in one transaction, so a later launch cannot accept a checkpoint for a partial baseline. Directory changes and their checkpoint are also applied in one transaction. Reads wait for accepted changes to reach storage, then retry only when a requested row changes during the read. Unrelated agent streams do not invalidate the read. Directory baseline replacements and host removal or renaming still invalidate the affected reads. The cache is capped at 32 MiB and evicts whole hosts in least-recently-written order. Budget bookkeeping may scan opaque row sizes during a deferred write, never during host registry startup or before a requested cache row can paint. The row store is not encrypted. A cached timeline can contain source code, prompts, and tool output; encrypted-at-rest storage is a separate security decision. ### Draft Store **AsyncStorage key:** `paseo-drafts` (version 2) ```typescript { drafts: Record, createModalDraft: DraftRecord | null } ``` ### Attachment Store (Web) **IndexedDB database:** `paseo-attachment-bytes`, object store: `attachments` Stores binary attachment blobs keyed by attachment ID. ### AttachmentMetadata | Field | Type | Description | | ------------- | --------- | ------------------------------ | | `id` | `string` | Unique attachment ID | | `mimeType` | `string` | MIME type | | `storageType` | `string` | Storage backend identifier | | `storageKey` | `string` | Key within the storage backend | | `createdAt` | `number` | Epoch ms | | `fileName` | `string?` | Original filename | | `byteSize` | `number?` | Size in bytes | --- ### Design (`docs/design.md`) # Design Tokens — every color, font size, weight, spacing step, radius, icon size — live in `packages/app/src/styles/theme.ts`. --- ## 1. Character Paseo is minimal, spacious, quiet, confident. Whitespace is deliberate. Nothing crowds, nothing decorates, nothing apologizes. A row, a label, a control. That is the bar. The app is calm so the user's work is not. Every visual decision serves either _act on this_ or _understand this_ — never _look at this_. Consistency comes from component reuse, not from hand-matching styles across surfaces. A row in the projects list, a row in settings, and a row in a modal are the same component, not three implementations that happen to look alike. When two surfaces do the same semantic thing in two different ways, one of them is wrong. --- ## 2. Component reuse A semantic element used in three or more places is a primitive. One of a kind is a screen. Primitives live in `packages/app/src/components/ui/` and `packages/app/src/components/headers/`. Card and row layout live in `packages/app/src/styles/settings.ts`. Section structure lives in `packages/app/src/screens/settings/settings-section.tsx`. A pressable styled to look like a button is wrong; the button is `