@dashup/connector 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# Desktop connector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run beside the editor on each computer, including the PC whose Zed window connects to a development machine over SSH. Dashup retains that saved SSH relationship; it does not start a replacement SSH session.
+
+With Node 24:
+
+```sh
+npx @dashup/connector pair
+```
+
+From a checkout, use pnpm 10.34.5 from the workspace root and `pnpm --filter @dashup/connector dashup` in place of `dashup`:
+
+```sh
+pnpm install
+pnpm exec turbo build --filter=@dashup/connector...
+```
+
+The published package bundles the workspace code, and CI publishes it when the package version is new. Screen and input need the native helper from `packages/desktop`, which the package does not include.
+
+`dashup pair` walks through pairing in the terminal: it shows a QR code that expires in five minutes, waits for a phone to scan it under Pair a computer, and offers to keep Dashup running in the background. The first phone adds the computer to its account, so the walkthrough names that account and shares nothing until you confirm it. Later codes pair more phones on the same account without asking, including through a connector that is already running. A phone that scans an expired code gets a pairing the computer revokes, because it never kept that key. Pairing needs a terminal: without one, an unpaired computer exits and says so. It uses `https://api.dashup.com`; for a local API, add `--api http://localhost:3000`. A physical phone needs a reachable HTTPS API. To run a paired connector in the foreground, use `dashup watch`.
+
+## Existing projects and alerts
+
+```sh
+pnpm --filter @dashup/connector dashup doctor
+pnpm --filter @dashup/connector dashup projects
+pnpm --filter @dashup/connector dashup alert --project PROJECT_ID --title "Dashup is connected"
+```
+
+The connector automatically reads existing Claude Code, Codex, and OpenCode conversations alongside Zed workspaces and VS Code chat history. It honors the harness's existing data directory, authentication, and native session IDs. Native stores are opened read-only; discovery never launches an agent, creates or resumes a conversation, or changes editor settings. Opening the same supported harness session through Zed and its native history uses one Dashup thread when their actual session identities match. Matching directory names alone never merges local and SSH projects.
+
+A thread's time is its last conversation message in the agent's own history; editor bookkeeping such as Zed's sidebar restamps never moves it. Subagent sessions (OpenCode children, Codex spawned agents) carry their parent thread. Tool calls are joined with their results into one step with status, duration and, for file edits, a unified diff. Saved history has unknown live status and read-only controls. File changes publish project metadata; only an approval, a question, an error or a finished turn sends an alert. A workspace becomes a project once it has a conversation. After every change the connector publishes its overview: every project, and the conversations Home shows (anything that needs the person or is working, then the newest 20). The phone renders Home from the overview alone and decodes a project's full snapshot only when a page opens it. Only a scan that read every source retires a project it published earlier and left off. Each phone read request reads a thread's native history once and publishes a snapshot of separately encrypted message fragments to the database. The phone reads bounded latest and earlier pages; realtime thread updates carry only summary and approval metadata. Native history remains the source, and an incomplete upload never replaces the previous published snapshot. Native live interfaces provide actual status and pending choices. Tool integrations can also queue explicit encrypted alerts with `alert`.
+
+Project paths, SSH details, thread content, approvals, and alerts are encrypted separately for every paired phone. The encrypted outbox survives a connector restart. Parcae handles realtime delivery and reconnect; replay counters are saved before commands execute. Revoking a pairing stops its viewer and discards its connector key and queued content.
+
+The phone watches small connection sequence records and fetches encrypted relay pages in order. New clients negotiate paged history before fetching relays; SQL excludes legacy full-transcript envelopes before loading ciphertext. The separate history API returns at most 30 encrypted records and 256 KiB per page, including a hard individual record limit. Large native outputs become authenticated continuation records. History cursors are independent of command replay counters.
+
+Each history read stages a new encrypted database snapshot and publishes it only after every bounded batch is stored. Failed uploads leave the previous complete snapshot readable; a cursor from a superseded snapshot asks the phone to load the latest page. Metadata updates do not import or relay the full history. An oversized non-history update is rejected before entering the durable outbox, so later alerts remain deliverable.
+
+## Existing live sessions
+
+Dashup discovers existing local OpenCode listeners, Codex control sockets, and VS Code Agent Host endpoints. These connections remain local; their tokens are never sent to Parcae or the phone. Native endpoints are checked for local ownership or loopback access, and redirects and remote endpoint URLs are rejected.
+
+- **OpenCode:** the existing TUI/server supplies conversations, live events, prompts, native tool permissions, and supported single-choice questions. A reply targets the original session ID and preserves its latest native agent, model, and variant. Dashup does not run `opencode serve` or create another session.
+- **Codex:** the existing control socket supplies already-loaded threads. Replies require a recognized native server and a thread that is still loaded and idle immediately before sending. Dashup never calls `thread/start`, `thread/resume`, or `session/load`. Approval controls appear only for native requests routed to this connection; approvals owned by another client may remain available only in the original UI.
+- **VS Code:** Microsoft's official AHP client subscribes to existing host sessions and chats. Native choices are retained, and delivery is acknowledged by the host. Older extension-host chats without an accessible Agent Host remain saved history. AHP chat IDs are namespaced rather than guessed to equal CLI thread IDs. Non-file remote AHP workspace URIs are not presented as local execution environments.
+- **Claude Code:** existing transcripts are readable without starting Claude. Direct control of an ordinary foreground Claude process is not advertised when it exposes no supported attach interface.
+
+Native listener discovery supports the host's available process/socket interfaces. File and socket formats are versioned implementation boundaries; unavailable or unfamiliar interfaces leave history readable and controls disabled. Existing editor and agent processes continue independently when the Dashup connector disconnects. The PC's saved SSH relationship is retained; reading it does not grant access to a remote machine's CLI store.
+
+The [existing Zed/Codex session proof](INTEGRATION_PROOF.md) records native queued-reply delivery and both observer and connector restarts against an unchanged original process. A separate product **Queue reply** adapter is implemented for local Linux Codex 0.160.1 packaged binaries, including private-stdio owners. It requires the exact native thread's owned writer lock, rollout file, queue database, process start time and executable version. A matching directory or copied transcript does not grant queue access. This source implementation has not yet been built or exercised; the earlier proof is not validation of this adapter.
+
+Only an explicit Queue reply starts a temporary official app-server helper to initialize and call `thread/queue/add` in that same native home. It does not start, resume or load an agent thread. A durable local intent records the caller-supplied native client-message ID before dispatch. Interrupted acknowledgement leaves the request unconfirmed and prevents automatic resubmission, including after connector restart. Known acceptance is retained if the item leaves the queue; disappearance is not delivery.
+
+Delivery requires that exact typed client-message ID in the original thread's native history database. A response receipt requires a later native assistant item in the same turn; it does not mean the agent finished. Receipts remain encrypted through the ordinary Dashup relay. History is read on request; the phone asks again while a thread is open and its session changes. Native approvals owned by the private-stdio process remain unsupported and require its original UI or Screen. Queue text never substitutes for a native approval.
+
+Stop interrupts the running turn through each live interface: OpenCode's session abort, Codex `turn/interrupt`, the AHP client's turn cancellation, and ACP `session/cancel`. It refuses when nothing is running and expires with other commands after 60 seconds, so a late stop cannot end a newer turn.
+
+Live discovery is bounded to 100 sessions per endpoint. OpenCode supplies the latest 200 messages; the VS Code host supplies its current chat snapshot. Paged history prefers the native saved store when available and otherwise uses the existing live snapshot. Approvals whose actual commands or file contents cannot be previewed require Screen review; rejection remains available when the native protocol supports it.
+
+## Optional ACP wrapper
+
+The default history and native-host path needs no wrapper or editor configuration. For an explicitly configured external ACP agent, use the connector as the editor's stdio wrapper; it uses the official ACP SDK's protocol contracts:
+
+```sh
+node /absolute/path/to/dashup/apps/connector/dist/index.js acp -- /absolute/path/to/original-agent ORIGINAL_ARGUMENTS
+```
+
+Set the editor's existing agent command to Node, with the arguments above. Start the connector first and launch the agent through that editor configuration. The proxy starts the original command once and forwards the editor's own ACP stream. Phone messages and approval choices go to that same process and session. Only native approval choices are offered, including native file scope when the agent provides it. The proxy does not create another session when opening a phone thread.
+
+The wrapper and connector must run on the same execution host. For SSH projects, confirm where that particular external agent runs before configuring its command; [Zed treats external-agent runtime and authentication as agent-owned](https://zed.dev/docs/ai/external-agents#remote-projects). Pair the development machine separately if it owns the wrapper process. Reading the PC's saved SSH project does not attach to a remote agent process.
+
+The wrapper cannot retroactively capture an already-running stdio stream. Saved history is not a live session handle. Zed's built-in agent and providers without a supported native attach interface remain read-only in Dashup; use Screen for their native controls. If the connector restarts, the original wrapped agent continues, but this optional wrapper currently needs relaunching to restore its observer connection.
+
+## Screen and input
+
+Build the native WebRTC helper on the computer, following [desktop build requirements](../../packages/desktop/README.md), then enable access locally:
+
+```sh
+pnpm --filter @dashup/desktop build
+pnpm --filter @dashup/connector dashup permissions --screen
+pnpm --filter @dashup/connector dashup permissions --screen --control
+```
+
+Run `permissions` without flags to disable access. Video and input use a WebRTC peer connection; SDP, ICE candidates, and DTLS fingerprints travel inside paired-device encrypted envelopes. Only one screen session is active at a time. The relay does not carry decoded frames. Set `DASHUP_DESKTOP_BIN` if the helper lives outside its workspace build path.
+
+macOS requires Screen Recording and Accessibility permission. Windows uses the signed-in desktop session. Linux input needs `xdotool` on X11 or a configured `ydotool` daemon on Wayland; capture support depends on the native helper and desktop environment. `doctor` reports available tooling, not OS permission grants. Configure `TURN_URLS` and `TURN_SECRET` on the API and the matching coturn shared secret for networks requiring a relay; the API issues one-hour credentials. Without TURN, connectivity depends on the devices' network reachability.
+
+## Start at login
+
+Answering yes to the walkthrough's background question, or running `dashup install` on a paired computer, registers a macOS LaunchAgent, Windows Startup entry, or Linux user systemd service and starts it, taking over from any connector already running for that state file. The service runs `watch` with the state file it was paired with (`DASHUP_CONFIG`). Linux requires a user systemd session. Under npx or pnpm dlx, whose caches can be cleared, the service runs a copy of that install kept in `app/` beside the state file; a checkout or global install runs in place. The Node executable must stay at its installed location. Signed desktop installers are not included.
+
+Remove startup with `launchctl unload ~/Library/LaunchAgents/com.dashup.connector.plist` and delete that file on macOS; delete `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\Dashup.vbs` on Windows; or run `systemctl --user disable --now dashup.service` and delete `~/.config/systemd/user/dashup.service` on Linux. `dashup stop` leaves the service stopped until the next sign-in; a crash restarts it.
+
+## Local state and checks
+
+`~/.dashup/connector.json` holds this computer's secret, pairing keys, encrypted outbox, and replay counters. It is written atomically with private Unix permissions; it is not currently protected by an OS credential vault. Do not share or copy it to another connector. `DASHUP_CONFIG` selects a separate state file. `DASHUP_ZED_DATA` and `DASHUP_VSCODE_DATA` select custom editor data directories. Native history discovery honors `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, and XDG paths. The selected conversation is parsed locally on demand; Dashup does not create another plaintext transcript database.
+
+For isolated development fixtures, `DASHUP_LIVE_DISCOVERY=0` disables automatic process discovery. Explicit `DASHUP_OPENCODE_ENDPOINT`, `DASHUP_CODEX_SOCKET`, and `DASHUP_AHP_DATA` overrides allow local test endpoints without modifying editor configuration. They are not required for ordinary discovery.
+
+```sh
+pnpm --filter @dashup/connector test
+pnpm --filter @dashup/connector check-types
+pnpm --filter @dashup/connector build
+TEST_API_URL=http://127.0.0.1:3049 pnpm --filter @dashup/connector test:workflow
+```
+
+The workflow test needs a running isolated Dashup API and database. It creates disposable accounts and verifies pairing, encrypted project/alert delivery over Parcae realtime, native history and session identity, replacement approvals, command replay protection, capability removal on disconnect, reattachment, and revocation. Unit fixtures exercise real native file formats, HTTP/SSE, Unix WebSockets, and the official AHP client. Actual editor UI compatibility, macOS/Windows startup, production push credentials, and cross-network TURN deployment require their respective hosts and credentials.