@puddle-code/cli 0.3.13 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/CHANGELOG.md +4 -8
  2. package/README.md +31 -19
  3. package/dist/host-control.mjs +2005 -158
  4. package/dist/index.js +4478 -1106
  5. package/dist/install.sh +401 -40
  6. package/dist/public/assets/App-CB0Bm55u.js +9 -0
  7. package/dist/public/assets/{CompilationCommandForm-Bzt5OaiJ.js → CompilationCommandForm-vv5bglnl.js} +1 -1
  8. package/dist/public/assets/Dashboard-BQd42kix.js +1 -0
  9. package/dist/public/assets/{EditorTabClose-xasqNn4b.js → EditorTabClose-D3LwFFHd.js} +1 -1
  10. package/dist/public/assets/{LazyTerminal-B2eXi-NW.js → LazyTerminal-CfuC3bjp.js} +2 -2
  11. package/dist/public/assets/{ModelRefcount-Dfulry9I.js → ModelRefcount-DtJdNeW7.js} +1 -1
  12. package/dist/public/assets/NewProjectDialog-DYn30yon.js +1 -0
  13. package/dist/public/assets/{NotebookWidget-D2ddZny7.js → NotebookWidget-BntkgqbM.js} +1 -1
  14. package/dist/public/assets/PaneEditorBody-ChNwAz96.js +284 -0
  15. package/dist/public/assets/PdfViewer-DYmz05py.js +2 -0
  16. package/dist/public/assets/ReleaseNotesDialog-D2kA6oIr.js +1 -0
  17. package/dist/public/assets/SettingsDialog-BWWWn7I0.js +8 -0
  18. package/dist/public/assets/{Terminal-C56yFFee.js → Terminal-BQHSZc8Q.js} +21 -21
  19. package/dist/public/assets/Workspace-DVTqrQNf.js +20 -0
  20. package/dist/public/assets/api-BOuyloUi.js +1 -0
  21. package/dist/public/assets/auth-olLlgxc3.js +64 -0
  22. package/dist/public/assets/{buffer-store-JDgXuYJp.js → buffer-store-BWLcD39y.js} +1 -1
  23. package/dist/public/assets/{button-BgeBH2Uc.js → button-9AVMLaMQ.js} +1 -1
  24. package/dist/public/assets/{context-CwZ4epwz.js → context-C3-WejyN.js} +1 -1
  25. package/dist/public/assets/{forward-link-C-8Xn8gf.js → forward-link-DMvLf0Xw.js} +1 -1
  26. package/dist/public/assets/{hotkeys-DOpJ1a7g.js → hotkeys-Cu0t6sbz.js} +1 -1
  27. package/dist/public/assets/index--5A6_BeN.css +2 -0
  28. package/dist/public/assets/{index-B_fYaxIG.js → index-BUAoYe1o.js} +3 -3
  29. package/dist/public/assets/markdown-CMSzQtLp.js +8 -0
  30. package/dist/public/assets/markdown-it-CWoG9_Dn.js +13 -0
  31. package/dist/public/assets/{markdown-mermaid-BVt1aqNY.js → markdown-mermaid-BCXEEB98.js} +1 -1
  32. package/dist/public/assets/media-refresh-store-BplHZVs4.js +1 -0
  33. package/dist/public/assets/notification-delivery-CDWhS_kj.js +1 -0
  34. package/dist/public/assets/protocol-support-CsLR9u7d.js +1 -0
  35. package/dist/public/assets/queue-BlrQxHDl.js +3 -0
  36. package/dist/public/assets/scroll-restoration-CwXbvZvT.js +1 -0
  37. package/dist/public/assets/selection-actions-B2XIuCoH.js +1 -0
  38. package/dist/public/assets/{session-order-SN_zG4Us.js → session-order-unCbOqgk.js} +1 -1
  39. package/dist/public/assets/{switch-iVuj74VW.js → switch-DVo2TkMf.js} +1 -1
  40. package/dist/public/assets/use-ui-state-i7N5-9dI.js +1 -0
  41. package/dist/public/assets/view-state-store-Cy9sQJoZ.js +1 -0
  42. package/dist/public/assets/ws-BX1iQbeP.js +1 -0
  43. package/dist/public/index.html +3 -3
  44. package/dist/pudl.js +2025 -212
  45. package/package.json +1 -1
  46. package/dist/public/assets/App-Dtn-lPJX.js +0 -2
  47. package/dist/public/assets/Dashboard-D6cwjmKX.js +0 -1
  48. package/dist/public/assets/NewProjectDialog-DTZfXXpH.js +0 -1
  49. package/dist/public/assets/PaneEditorBody-DM3RxU9y.js +0 -303
  50. package/dist/public/assets/PdfViewer-BR_qnX0w.js +0 -2
  51. package/dist/public/assets/SettingsDialog-DK_xpwwR.js +0 -8
  52. package/dist/public/assets/Workspace-DJGOiast.js +0 -20
  53. package/dist/public/assets/api-CfmzEbQ_.js +0 -1
  54. package/dist/public/assets/auth-CIb9G2C5.js +0 -64
  55. package/dist/public/assets/errors-DTaodZDR.js +0 -1
  56. package/dist/public/assets/index-ChK3zzci.css +0 -2
  57. package/dist/public/assets/media-refresh-store-DDvrEM5K.js +0 -1
  58. package/dist/public/assets/notification-delivery-DhFtFhEH.js +0 -1
  59. package/dist/public/assets/protocol-support-BGk73LFk.js +0 -1
  60. package/dist/public/assets/scroll-restoration-xYrqc2k4.js +0 -1
  61. package/dist/public/assets/selection-actions--OSfjvlG.js +0 -1
  62. package/dist/public/assets/use-ui-state-DEsKtleW.js +0 -1
  63. package/dist/public/assets/ws-CspBmo8M.js +0 -1
package/CHANGELOG.md CHANGED
@@ -4,14 +4,10 @@ Archived release changelog. Governance lives in CLAUDE.md §"Changelog disciplin
4
4
 
5
5
  # Changelog
6
6
 
7
- ## [0.3.13] — 2026-11-02
8
-
9
- ### Added
10
-
11
- - Default inactive bulk terminal logs to three-day retention, preserving archived restoration, replay tails, snapshots and shell history; expose the host setting in protocol 25.6.
12
- - Warn about low host storage and inodes, report persistence failures, and block new sessions/worktrees at critical capacity (protocol 25.5, local/SSH diagnostics).
7
+ ## [0.4.1] — 2026-11-04
13
8
 
14
9
  ### Fixed
15
10
 
16
- - Keep live terminals connected when log writes or SQLite persistence run out of space; bound unsaved history, retry runtime observations and recover without replaying user actions.
17
- - Keep host/configuration reads available without rewriting configuration.
11
+ - Fix notebook fixture package inheritance when using isolated Python environments.
12
+ - Reap detached runtime fixtures in Linux archive jobs.
13
+ - Record CI fixture regression results for the persistent-runtime acceptance suite.
package/README.md CHANGED
@@ -9,7 +9,7 @@ Puddle is an open-source, multi-account coding agent orchestrator with first-cla
9
9
  puddle launch <user>@<host>
10
10
  ```
11
11
 
12
- Puddle manages parallel agents anywhere you SSH into, insulates agents in dedicated worktrees, and keeps your agents alive across disconnects and restarts.
12
+ Puddle manages parallel agents on local and SSH hosts, isolates work in dedicated worktrees, and retains conversations and workspace state across reconnects. Independently supervised runtimes in the 0.4.0 architecture preserve live processes across daemon replacement; hosts with limited session lifetimes have narrower guarantees below.
13
13
 
14
14
  <p align="center">
15
15
  <picture>
@@ -75,10 +75,12 @@ puddle launch
75
75
 
76
76
  This installs the Puddle daemon under `~/.puddle` and serves the GUI at `http://localhost:7433`.
77
77
 
78
- Ctrl-C normally closes only the GUI while agent sessions keep running. On an SSH host that reaps
79
- detached processes, Puddle instead keeps the daemon attached to the cockpit; closing it interrupts
80
- live processes. The next `puddle launch` restarts the daemon from the host's persistent state and,
81
- when auto-resume is enabled (the default), restores the interrupted sessions.
78
+ Ctrl-C normally closes only the GUI while independently supervised runtimes keep running.
79
+ Some SSH hosts require a cockpit-held daemon. Closing that cockpit stops the daemon and
80
+ detaches its independent owners; host policy may retain or reap those host-session runtimes.
81
+ Reconnection adopts survivors and restores interrupted sessions according to the host's
82
+ auto-resume setting. These limited hosts do not support managed updates without a usable
83
+ service manager.
82
84
 
83
85
  The [deployed app](docs/mobile-access.md#host-the-installer) serves `/install.sh`
84
86
  as the single public installer. Install daemon and desktop components through
@@ -88,14 +90,18 @@ GitHub Releases.
88
90
 
89
91
  **Managing components:**
90
92
 
91
- The CLI installs, upgrades, and removes all three components — daemon, desktop app, and itself — with optional versions and SSH targets:
93
+ The CLI manages the daemon, runtime software, desktop app and itself, with optional versions and SSH targets:
92
94
 
93
95
  ```sh
94
96
  puddle upgrade # everything installed → the newest release
95
97
  puddle install daemon@v0.0.32 user@host # pin a host's daemon to a version
98
+ puddle upgrade runtime user@host # select the default build for future runtimes
99
+ puddle updates user@host # inspect the host's current update operation
96
100
  puddle remove daemon # uninstall; your data stays unless you --purge
97
101
  ```
98
102
 
103
+ Runtime install/upgrade requires a running daemon with host-update support (application protocol 25.7+) and an available user service manager. Existing runtimes retain their pinned build. `puddle updates --operation <id> --cancel` abandons an exact preparation before dispatch; accepted work is observed without replay.
104
+
99
105
  **Desktop app (optional):**
100
106
 
101
107
  The same cockpit also ships as a standalone desktop app — identical UI and engine, plus a File → "Connect to SSH Host…" menu for remote hosts. Install it with `puddle install desktop` (macOS arm64 or Linux x64). Once installed, it runs independently of the CLI.
@@ -109,7 +115,7 @@ auth prompts unless you use a key).
109
115
 
110
116
  ## How it works
111
117
 
112
- - **The Puddle daemon works anywhere you can SSH into.** It is installed on your host during every fresh connect, relaying information across SSH to your local GUI. The daemon is the parent of every agent process, keeping sessions running when your laptop sleeps, the window closes, or the SSH connection drops. Puddle also maintains a stateful memory of your conversations to survive machine reboots.
118
+ - **Puddle separates host management from live execution.** First connection installs a missing daemon on a supported local or SSH host. In the 0.4.0 architecture, `puddled` manages worktrees and application state, while one independent `puddler` per runtime owns agent and shell PTYs and provider sidecars. Supervised owners survive daemon replacement and cockpit disconnects. After machine reboot, saved conversations can resume according to host settings; live process state does not survive reboot. Hosts without a usable service manager retain the limited host-session fallback described above.
113
119
  - **Puddle orchestrates parallel isolated agents** each working in a unique git worktree and branch. You can choose the branch and worktree during session creation.
114
120
  - **Puddle's lightweight GUI** allows you to track agent progress, session usage, and active worktrees.
115
121
  - **Puddle's philosophy is that any good developer must stay grounded in their code.** Puddle natively integrates live terminals, file editing in Monaco, git commit grahps, diff views, and opens worktrees in your favourite IDE.
@@ -118,36 +124,42 @@ auth prompts unless you use a key).
118
124
  ```
119
125
  client machine host machine (local or remote)
120
126
  ┌──────────────────────────────┐ ┌───────────────────────────────────┐
121
- │ browser ── localhost:7433 │ │ puddled (systemd user service) │
127
+ │ browser ── localhost:7433 │ │ puddled │
122
128
  │ │ │ local: │ ├─ REST + WS API │
123
- │ puddle CLI ◄─┘ │ direct │ ├─ PTY manager │
124
- │ ├─ static web UI assets │───────►│ ├─ git worktree manager │
125
- │ └─ /api + /ws proxy │ remote:│ ├─ per-agent adapters │
126
- └──────────────────────────────┘ ssh -L │ └─ SQLite + append-only logs │
129
+ │ puddle CLI ◄───┘ │ direct │ ├─ runtime controller │
130
+ │ ├─ static web UI assets │───────►│ ├─ worktrees + SQLite │
131
+ │ └─ /api + /ws proxy │ remote:│ └─ daemon-owned execution │
132
+ └──────────────────────────────┘ ssh -L └───────────────────────────────────┘
133
+ │ private IPC
134
+ ┌───────────────────────────────────┐
135
+ │ puddler (one owner per runtime) │
136
+ │ PTYs, sidecars, output, journal │
127
137
  └───────────────────────────────────┘
128
138
  ```
129
139
 
130
- The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI (`puddle upgrade cli` refreshes the cockpit for every host); the daemon only has to update when the versioned protocol breaks, and the launcher asks for approval before updating it. The prompt shows the host, both protocols and how many live sessions the restart interrupts; declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
140
+ The CLI serves the UI at a stable local origin and reverse-proxies the API to the daemon, directly in local mode, through the tunnel in SSH mode. The daemon is headless and host-agnostic on `127.0.0.1:7434`. UI updates ship with the CLI. Compatible cockpit and daemon releases may differ; the launcher requires approval when an older application protocol is incompatible. Explicit daemon/runtime updates also use the CLI or supporting cockpit Host settings. Review distinguishes unaffected independent runtimes from work requiring interruption; first upgrades from daemon-owned sessions report their interruption count. Declining leaves the daemon running. `--no-upgrade` refuses before prompting, and non-interactive launches require an explicit `puddle upgrade daemon [user@host]` first. Short-lived host connection leases, separate browser authorisation and exact cockpit Host/Origin checks guard local access. Launch invitations are single-use; browser login survives cockpit restarts, while forwarded applications use a separate loopback origin. After upgrading from the old token flow, run `puddle launch` once to authorise existing tabs.
131
141
 
132
142
  Everything lives under `~/.puddle` on the host, installed without sudo — and `puddle remove daemon` takes it apart again.
133
143
 
134
144
  ## Development & teardown
135
145
 
136
- **One daemon, many clients.** There is a single local daemon per machine, living under `~/.puddle` and run by one supervised service (launchd's `dev.puddle.puddled` on macOS, systemd's `puddled` on Linux). The global `puddle` and a repo-run `node packages/cli/dist/index.js` are **both just clients** that talk to — and, when needed, install — that same daemon. They never run side by side, and there is no separate "dev daemon" alongside a "production daemon".
146
+ **One daemon, many clients.** There is a single local daemon per machine, living under `~/.puddle` and run by one supervised service (launchd's `dev.puddle.puddled` on macOS, systemd's `puddled` on Linux). The global `puddle` and a repo-run `node packages/cli/dist/index.js` are **both just clients** that talk to — and, when needed, install — that same daemon. Multiple clients can share that daemon; there is no automatically separate "dev daemon" alongside a "production daemon".
137
147
 
138
148
  **Dev build vs. production.** The standalone installer or `npm i -g @puddle-code/cli` is the production path — its `puddle` fetches and upgrades the daemon from this repo's GitHub Releases. To exercise uncommitted changes, build and run from the repo:
139
149
 
140
150
  ```sh
141
151
  pnpm build && pnpm build:tarball
142
- node packages/cli/dist/index.js launch --tarball dist-release/puddled-v*.tar.gz --foreground
152
+ node packages/cli/dist/index.js upgrade daemon@X.Y.Z --tarball dist-release/puddled-vX.Y.Z-PLATFORM-ARCH.tar.gz
153
+ node packages/cli/dist/index.js launch --foreground
143
154
  ```
144
155
 
145
- `--tarball` sets the install _source_ only, and is consulted **only when the CLI actually installs the daemon** — when none is running, the daemon is stopped, or a protocol-major upgrade fires. If a compatible daemon (same protocol major) is already up, `launch` just serves the cockpit against it and **the tarball is ignored** (even a newer app version — nothing compares app versions). So to load a fresh dev build over a running daemon you must **stop it first** (see _Kill_ below), then re-run `launch --tarball …`. `--foreground` keeps the cockpit attached (`launch <user>@<host> --tarball …` is the remote form). Both clients share one `~/.puddle` daemon and cockpit registry, so `puddle list` / `puddle kill` see either — don't point both at the same host at once. (Never launch the daemon from inside a coding-agent shell: it inherits the agent's env and breaks conversation resume — use a plain terminal.)
156
+ Replace `X.Y.Z`, `PLATFORM` and `ARCH` with the version and target printed by `build:tarball`; keep the generated `.sha256` file beside the archive. Add `user@host` after the component for an SSH target. A modern stopped installation starts its selected service before an explicit upgrade; `launch --tarball` alone does not replace that selected build. A compatible running daemon also ignores the launch tarball. To select the same archive for future runtime launches, use `upgrade runtime@X.Y.Z --tarball …`; existing owners remain pinned until explicitly restarted. First installation and approved legacy transitions still use the embedded bootstrap. Both clients share the host's daemon and cockpit registry. Never launch the daemon from inside a coding-agent shell: it inherits the agent's environment and can break conversation resume; use a plain terminal.
146
157
 
147
158
  **Kill.** `puddle kill --all` (or Ctrl-C in a `--foreground` run) normally stops the local cockpit
148
159
  UI only; a supervised daemon and its sessions keep running. When launch reported that it is keeping
149
- the daemon attached over SSH, killing that cockpit cleanly interrupts its processes instead; the
150
- next launch reconciles them from `~/.puddle` and auto-resumes them when that host setting is enabled.
160
+ the daemon attached over SSH, killing that cockpit stops the daemon. Host-session owners may
161
+ survive or be reaped by host policy; the next launch adopts survivors and reconciles ended
162
+ owners according to the host auto-resume setting.
151
163
  A supervised daemon is auto-restarting
152
164
  (launchd `KeepAlive`, systemd `Restart=always`), so a plain `kill <pid>` bounces straight back — stop
153
165
  it through its supervisor:
@@ -158,7 +170,7 @@ systemctl --user disable --now puddled # Linux (systemd user unit)
158
170
  kill "$(cat ~/.puddle/puddled.pid)" # nohup fallback (no supervisor)
159
171
  ```
160
172
 
161
- **Restore the production daemon.** When you're done testing, `puddle remove daemon` (answer no to the purge question — your profiles, sessions, and worktrees stay), then run the production `puddle launch`, which refetches the daemon from GitHub Releases. (Removal is what forces the refetch: the installer skips a version whose files are already present, so a dev build sharing the release's version number would otherwise stay put.)
173
+ **Restore published software.** Use a compatible CLI to explicitly upgrade to a chosen compatible published version: `puddle upgrade daemon@X.Y.Z` (and `puddle upgrade runtime@X.Y.Z` for future runtimes). Replace `X.Y.Z` with that release; compatibility and recovery checks still apply. Removing and reinstalling a modern daemon can restore its retained service and selected generation, so it is not a way to force a download. Existing runtime processes keep their pinned build until explicitly restarted.
162
174
 
163
175
  **Uninstall.** Removing the CLI alone leaves the daemon installed and running — a full teardown is:
164
176