@pi-chamber/web 1.0.8-rc.1 → 1.0.8-rc.3
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.
- package/dist/assets/{AgentsSurface-BmHImX8m.js → AgentsSurface-wsW9VCRp.js} +1 -1
- package/dist/assets/{ChoicesArtifact-C71fGOm2.js → ChoicesArtifact-EwCf4Yxu.js} +1 -1
- package/dist/assets/{DiagramView-BZQxoiZu.js → DiagramView-BX6N99cQ.js} +1 -1
- package/dist/assets/{DiffView-C70pbgk-.js → DiffView-CI0eSnPP.js} +1 -1
- package/dist/assets/{FileSaveConflictDialog-Cu8c3gBV.js → FileSaveConflictDialog-GLj2W7VE.js} +1 -1
- package/dist/assets/{FilesView-nFJYEdRw.js → FilesView-CI0tfZQL.js} +1 -1
- package/dist/assets/{GitHubDetailScaffold-Jvv_tgbl.js → GitHubDetailScaffold-B85tZ9m7.js} +1 -1
- package/dist/assets/{GitHubLinkPicker-BXD2ODRi.js → GitHubLinkPicker-Y6AuNiGl.js} +1 -1
- package/dist/assets/{GitHubListPrimitives-BWI706F0.js → GitHubListPrimitives-BJHBud6i.js} +1 -1
- package/dist/assets/{GitView-MIDG5RYW.js → GitView-DueE69kW.js} +5 -5
- package/dist/assets/{IssuesSurface-uNlozeu0.js → IssuesSurface-Cg-xkdIu.js} +3 -3
- package/dist/assets/{JsonTreeView-CSLsTriz.js → JsonTreeView-Cvg6lc40.js} +1 -1
- package/dist/assets/{MarkdownRendererImpl-Cs-7BfWi.js → MarkdownRendererImpl-DExPx-QM.js} +1 -1
- package/dist/assets/{PatchDiff-axbsnbTJ.js → PatchDiff-_c3HZ34I.js} +1 -1
- package/dist/assets/{PierreDiffViewer-lwn6w_5w.js → PierreDiffViewer-CZnaqO-_.js} +1 -1
- package/dist/assets/{PullRequestsSurface-o_AXDjbO.js → PullRequestsSurface-C9AYPiwo.js} +2 -2
- package/dist/assets/{SessionSwitcherContent-C4CMlcbv.js → SessionSwitcherContent-DOpnN-8S.js} +1 -1
- package/dist/assets/{SessionSwitcherDropdown-DCBVuCoo.js → SessionSwitcherDropdown-CmHMPZ69.js} +2 -2
- package/dist/assets/{SessionUnreadDot-DyeIrsro.js → SessionUnreadDot-CZCQ4t1J.js} +1 -1
- package/dist/assets/SettingsView-D5PO5M3z.js +11 -0
- package/dist/assets/{SettingsWindow-Cb4st5y5.js → SettingsWindow-DXV5UOE8.js} +1 -1
- package/dist/assets/{SubagentsArtifact-BzeMEoFP.js → SubagentsArtifact-CO1ZiI1x.js} +1 -1
- package/dist/assets/{ToolOutputDialog-BP2mOWdV.js → ToolOutputDialog-GOwNLj-y.js} +1 -1
- package/dist/assets/{ToolPartDiffPreview-D49XBR9b.js → ToolPartDiffPreview-BoaiZji6.js} +1 -1
- package/dist/assets/{VirtualizedFileDiff-CLgDONEQ.js → VirtualizedFileDiff-Chq1X8nw.js} +1 -1
- package/dist/assets/VisualFrame-u7aRcX7O.js +22 -0
- package/dist/assets/VisualsArtifact-D9vPjihW.js +1 -0
- package/dist/assets/{collapsible-BeyKtQGB.js → collapsible-BjpDEohv.js} +1 -1
- package/dist/assets/{computeVirtualFileMetrics-DmO6H8u6.js → computeVirtualFileMetrics-DmPCxbok.js} +1 -1
- package/dist/assets/{contextFileOpenGuard-DOK251YW.js → contextFileOpenGuard-CukNcUeY.js} +1 -1
- package/dist/assets/{fileTreeStatus-CnzR7kxA.js → fileTreeStatus-CDyfNPYO.js} +1 -1
- package/dist/assets/{gitStatusPredicates-4kPg2t6j.js → gitStatusPredicates-uI7Y7L5k.js} +1 -1
- package/dist/assets/{githubLink-QvaLfNNT.js → githubLink-B9Mxac4R.js} +1 -1
- package/dist/assets/{index-DMX9wT1Z.js → index-BWq2ibCw.js} +1 -1
- package/dist/assets/index-BxKPJ9uG.js +11 -0
- package/dist/assets/index-C5JgjS20.css +1 -0
- package/dist/assets/{main-BirYxac2.js → main-CWfC-9xT.js} +4 -4
- package/dist/assets/{main-BW9J3Y72.js → main-ckQ0ciIN.js} +2 -2
- package/dist/assets/{markdownCore-CxmcPur8.js → markdownCore-p2q2Kxwo.js} +1 -1
- package/dist/assets/{miniChat-BRB11eEs.js → miniChat-x2TrwRYA.js} +2 -2
- package/dist/assets/{mobile-DJZYYCuB.js → mobile-B0x2G8h1.js} +2 -2
- package/dist/assets/{nativeFileSave-B6QpoPRn.js → nativeFileSave-D542OJlG.js} +1 -1
- package/dist/assets/{pi-session-focus-preference-PWoh3LNA.js → pi-session-focus-preference-Q_RZUCnt.js} +1 -1
- package/dist/assets/{renderDiffWithHighlighter-C48T6YFJ.js → renderDiffWithHighlighter-CSFGSknx.js} +1 -1
- package/dist/assets/{renderElectronMiniChatApp-N-BQdJl0.js → renderElectronMiniChatApp-CFIdesZT.js} +2 -2
- package/dist/assets/{renderFileWithHighlighter-8Kt2MyTN.js → renderFileWithHighlighter-C5JE0mRX.js} +1 -1
- package/dist/assets/renderMobileApp-B1ybjcGM.js +11 -0
- package/dist/assets/runtimeEndpointReset-DyZSKCYM.js +66 -0
- package/dist/assets/{runtimeSurface-kIEoYsPP.js → runtimeSurface-BR_dhe7_.js} +1 -1
- package/dist/assets/{selection-BTEdLRVK.js → selection-CfOpW4rA.js} +1 -1
- package/dist/assets/useAppFontEffects-COMvkffC.js +226 -0
- package/dist/assets/{useGitHubRemoteSearch-DIBHNu8r.js → useGitHubRemoteSearch-M1AE2YuX.js} +1 -1
- package/dist/assets/{useSwitcherItems-DfLbfX37.js → useSwitcherItems-D0i2BYYP.js} +1 -1
- package/dist/assets/{web-components-C_DsTJis.js → web-components-wOQkOurQ.js} +1 -1
- package/dist/index.html +4 -4
- package/dist/mini-chat.html +3 -3
- package/dist/mobile.html +3 -3
- package/package.json +1 -1
- package/plugins/featured.json +12 -0
- package/plugins/subagents/package.json +1 -1
- package/plugins/visuals/extension.js +8 -5
- package/plugins/visuals/package.json +1 -1
- package/server/index.js +90 -27
- package/server/lib/git/DOCUMENTATION.md +4 -0
- package/server/lib/git/service.js +70 -5
- package/server/lib/git/service.test.js +179 -0
- package/server/lib/github/DOCUMENTATION.md +2 -0
- package/server/lib/marketplace/DOCUMENTATION.md +95 -0
- package/server/lib/marketplace/featured.js +176 -0
- package/server/lib/marketplace/featured.test.js +207 -0
- package/server/lib/marketplace/npm-registry.js +255 -0
- package/server/lib/marketplace/npm-registry.test.js +227 -0
- package/server/lib/marketplace/routes.js +64 -0
- package/server/lib/marketplace/routes.test.js +119 -0
- package/server/lib/marketplace/service.js +225 -0
- package/server/lib/marketplace/service.test.js +174 -0
- package/server/lib/notifications/DOCUMENTATION.md +10 -4
- package/server/lib/notifications/pi-notification-watcher.js +92 -33
- package/server/lib/notifications/pi-notification-watcher.test.js +79 -0
- package/server/lib/open-url/DOCUMENTATION.md +1 -0
- package/server/lib/pi/merged-event-stream.js +316 -0
- package/server/lib/pi/merged-event-stream.test.js +95 -0
- package/server/lib/pi/routes-daemon-pool.test.js +348 -0
- package/server/lib/pi/routes-merged-events.test.js +327 -0
- package/server/lib/pi/routes-sandbox.test.js +1684 -0
- package/server/lib/pi/routes.js +491 -90
- package/server/lib/pi/routes.test.js +87 -2
- package/server/lib/pi/sandbox/DOCUMENTATION.md +68 -0
- package/server/lib/pi/sandbox/launcher.js +122 -0
- package/server/lib/pi/sandbox/launcher.test.js +91 -0
- package/server/lib/pi/sandbox/nono-launcher.js +455 -0
- package/server/lib/pi/sandbox/nono-launcher.test.js +371 -0
- package/server/lib/pi/sandbox/nono-profile-macos.json +20 -0
- package/server/lib/pi/sandbox/nono-profile-wsl2.json +21 -0
- package/server/lib/pi/sandbox/nono-profile.json +22 -0
- package/server/lib/pi/sandbox/project-sandbox-manager.js +1461 -0
- package/server/lib/pi/sandbox/project-sandbox-setting.js +166 -0
- package/server/lib/pi/sandbox/project-sandbox.js +207 -0
- package/server/lib/pi/sandbox/sandbox-routes.js +110 -0
- package/server/lib/pi/sandbox/sandboxed-folders.js +100 -0
- package/server/lib/pi/sandbox/sandboxed-folders.test.js +65 -0
- package/server/lib/pi/sandbox/trust-ask.js +135 -0
- package/server/lib/pi/sandbox/trust-ask.test.js +54 -0
- package/server/lib/pi/sandbox/worktree-ids.js +96 -0
- package/server/lib/pi/sandbox/worktree-ids.test.js +73 -0
- package/server/lib/pi/session-daemon/DOCUMENTATION.md +26 -6
- package/server/lib/pi/session-daemon/daemon-pool.js +157 -0
- package/server/lib/pi/session-daemon/daemon-process.js +10 -1
- package/server/lib/pi/session-daemon/extension-config.js +206 -23
- package/server/lib/pi/session-daemon/extension-config.test.js +180 -0
- package/server/lib/pi/session-daemon/session-daemon-read-persisted.test.js +167 -0
- package/server/lib/pi/session-daemon/session-daemon.js +368 -56
- package/server/lib/pi/session-daemon/session-daemon.test.js +227 -0
- package/server/lib/pi/session-daemon/session-idle-residency.test.js +98 -1
- package/server/lib/pi/session-daemon/session-jsonl.js +49 -10
- package/server/lib/pi/session-daemon/session-jsonl.test.js +11 -0
- package/server/lib/pi/session-daemon/session-lease.js +93 -15
- package/server/lib/pi/session-daemon/session-lease.test.js +107 -1
- package/server/lib/pi/session-daemon/supervisor-launcher-stop.test.js +295 -0
- package/server/lib/pi/session-daemon/supervisor-sandbox-nono.e2e.test.js +301 -0
- package/server/lib/pi/session-daemon/supervisor-sandbox.test.js +444 -0
- package/server/lib/pi/session-daemon/supervisor.js +386 -35
- package/server/lib/pi/session-daemon/supervisor.test.js +28 -0
- package/server/lib/pi/ui-settings-store.js +90 -3
- package/server/lib/pi/ui-settings-store.test.js +118 -0
- package/server/lib/plugins/DOCUMENTATION.md +17 -5
- package/server/lib/plugins/daemon-sync.js +16 -6
- package/server/lib/plugins/daemon-sync.test.js +12 -0
- package/server/lib/plugins/impact.test.js +2 -1
- package/server/lib/plugins/manifest.js +25 -0
- package/server/lib/plugins/manifest.test.js +9 -0
- package/server/lib/plugins/routes.test.js +28 -0
- package/server/lib/plugins/service.js +24 -2
- package/server/lib/server/cross-process-lock.js +28 -3
- package/server/lib/wallpaper/DOCUMENTATION.md +25 -0
- package/server/lib/wallpaper/routes.js +63 -0
- package/server/lib/wallpaper/routes.test.js +109 -0
- package/server/lib/wallpaper/store.js +87 -0
- package/dist/assets/SettingsView-BHBpt2Um.js +0 -7
- package/dist/assets/VisualFrame-CJrAvWSo.js +0 -22
- package/dist/assets/VisualsArtifact-DqLGgU-Q.js +0 -1
- package/dist/assets/index-B2v0_mez.js +0 -11
- package/dist/assets/index-D3F4JrPN.css +0 -1
- package/dist/assets/renderMobileApp-B7cT7m5b.js +0 -11
- package/dist/assets/runtimeEndpointReset-BC6yGnxN.js +0 -62
- package/dist/assets/useAppFontEffects-EcTZ_I_I.js +0 -225
|
@@ -10,14 +10,17 @@ This module is the Pi-owned session-daemon foundation. A detached local daemon p
|
|
|
10
10
|
- `extension-bridge.js` owns extension UI bindings, pending dialog lifecycle, normalized status/widget/panel/app state, snapshot projection, and extension event publication. `session-daemon.js` supplies runtime lookup, publication, redaction, and directory dependencies through its narrow factory interface.
|
|
11
11
|
- `open-request.js` owns Open request URL validation and session attribution for the `openUrl.publish` command. Intake, the `$BROWSER` handler, and delivery live in `../../open-url/` (see its `DOCUMENTATION.md`).
|
|
12
12
|
- `builtin-extensions.js` owns the list of Pi built-in extensions PiChamber loads (`codemode`, `tool-search`, `mcp`) and the list it skips on purpose (`llama.cpp`). Pi ships these inside the SDK package and only the Pi CLI loads them by itself, so the daemon passes them through `resourceLoaderOptions.extensionFactories` with the same `builtin: true` and `replaceable: true` flags the CLI uses. They load as `builtin:<name>`. `-builtin:<name>` in the Pi `extensions` setting disables one. Pi leaves one out when an installed extension registers the same tool, command, or flag, so a third-party MCP extension that registers `/mcp` takes over and Pi does not read `mcp.json`. MCP servers come from `mcp.json` in the agent directory and `.pi/mcp.json` in a trusted project. Each resident session runtime starts its own servers on `session_start` and stops them on `session_shutdown`, which every runtime disposal path emits. The MCP extension resolves `mcp.json`, `mcp-auth.json`, and `mcp.log` through the SDK's process-wide agent directory, so `daemon-process.js` sets `PI_CODING_AGENT_DIR` to the daemon's `--agent-dir` when one is given. Code that creates a daemon in-process with a custom `agentDir` must set that variable itself. `codemode` and `tool_search` are registered inactive. The MCP extension activates `codemode` for servers with the default `codemode` exposure and `tool_search` for `deferred` servers; `defaultTools` can activate them without MCP. Tool rows follow Pi's design: a `direct` MCP tool is an ordinary row rendered by its own `renderCall` and `renderResult`, `tool_search` is an ordinary row with the default display, and a `codemode` call is one row whose rendered result lists the nested calls with their status while the script runs. Nested calls stay out of the row list because their events carry `parentToolCallId`. The bridge reports `mode: 'tui'` by default (see `extension-ui-mode.js`), so `/mcp` opens Pi's interactive MCP manager through `ctx.ui.custom()` (see `extension-custom-host.js`), and `/mcp login <server>` signs in inside that manager; `/mcp logout <server>` and `/mcp reconnect <server>` act directly. The MCP extension is created with an `openUrl` that does nothing: Pi would open the authorization URL in a browser on the daemon host, which is often not the device in use and may have no display. The manager draws the URL as an OSC 8 hyperlink, which the browser renders as a link. PiChamber has no MCP settings screen.
|
|
13
|
-
- `extension-config.js` owns what `pi config`, `pi list`, and `pi remove` do for Pi extensions. Skills, prompts, and themes are not listed yet; the write functions already handle every resource type so adding them is additive. It uses the SDK's `DefaultPackageManager` and `SettingsManager` in-process and never runs the `pi` CLI. `list(target, replacements?)` takes the optional replacement facts from `extension-replacements.js` and adds `replaced`: `[{ kind: 'plugin' | 'builtin', id, registers?: { kind: 'tool' | 'command' | 'flag', name }, by?: { id?, name } }]`. A plugin entry's `id` is the PiChamber plugin id; a built-in entry's `id` is that built-in's item id in the same answer's `extensions` array (a built-in with no listed item is left out). `by.id` is the winning extension's item id when it is listed; otherwise `by` has only a path-free `name`. The field is present, possibly empty, only when a live runtime answered, and absent means unknown. Winner and built-in file paths are mapped to ids inside this module and never leave it.
|
|
14
|
-
- Commands (private IPC): `extensions.config.list { directory? }`; `extensions.config.set { directory?, id, scope: 'global', enabled }` or `{ directory, id, scope: 'project', state: 'inherit' | 'load' | 'unload' }`, or `{ directory, id, scope: 'project', enabled }`, which the service turns into `inherit` when the project would get that value anyway and into `load` or `unload` otherwise, against the settings it reads under the lock (a client's copy of the global value can be stale); `extensions.packages.remove { directory?, id }`. Public routes: `GET /api/pi/extensions/config?directory=`, `PUT /api/pi/extensions/config/:id`, `DELETE /api/pi/extensions/packages/:id?directory=` in `../routes.js`, each with strict input checks and a whitelist projection.
|
|
13
|
+
- `extension-config.js` owns what `pi config`, `pi list`, `pi install npm:<name>`, `pi update`, and `pi remove` do for Pi extensions. Skills, prompts, and themes are not listed yet; the write functions already handle every resource type so adding them is additive. It uses the SDK's `DefaultPackageManager` and `SettingsManager` in-process and never runs the `pi` CLI. `list(target, replacements?)` takes the optional replacement facts from `extension-replacements.js` and adds `replaced`: `[{ kind: 'plugin' | 'builtin', id, registers?: { kind: 'tool' | 'command' | 'flag', name }, by?: { id?, name } }]`. A plugin entry's `id` is the PiChamber plugin id; a built-in entry's `id` is that built-in's item id in the same answer's `extensions` array (a built-in with no listed item is left out). `by.id` is the winning extension's item id when it is listed; otherwise `by` has only a path-free `name`. The field is present, possibly empty, only when a live runtime answered, and absent means unknown. Winner and built-in file paths are mapped to ids inside this module and never leave it.
|
|
14
|
+
- Commands (private IPC): `extensions.config.list { directory? }`; `extensions.config.set { directory?, id, scope: 'global', enabled }` or `{ directory, id, scope: 'project', state: 'inherit' | 'load' | 'unload' }`, or `{ directory, id, scope: 'project', enabled }`, which the service turns into `inherit` when the project would get that value anyway and into `load` or `unload` otherwise, against the settings it reads under the lock (a client's copy of the global value can be stale); `extensions.packages.remove { directory?, id }`; `extensions.packages.install { directory?, name, scope: 'user' | 'project' }`; `extensions.packages.update { directory?, id }`. Public routes: `GET /api/pi/extensions/config?directory=`, `PUT /api/pi/extensions/config/:id`, `DELETE /api/pi/extensions/packages/:id?directory=`, `POST /api/pi/extensions/packages` (body `{ name, scope, directory? }`, exact keys, `directory` required for `project`), and `POST /api/pi/extensions/packages/:id/update?directory=` in `../routes.js`, each with strict input checks and a whitelist projection. Install and update answer like remove (fresh list, `deferred: true` when runtime recreation was deferred); install adds `installedId`, the new package's list id. The routes ask the supervisor for a 10-minute IPC timeout (`requestDaemon(command, payload, { timeoutMs })`) instead of the 30 s default. HTTP status: `PACKAGE_ALREADY_INSTALLED` and `PACKAGE_PINNED` are 409, `PACKAGE_INSTALL_FAILED` and `PACKAGE_UPDATE_FAILED` are 502, other service errors 400; bodies carry only `{ error: { code } }`, never npm or git text.
|
|
15
|
+
- Package entries carry `{ id, source, scope, kind, installed, filtered }` and, when known, `name` and `version` from the installed package's own `package.json` (read through Pi's `installedPath`, at most 256 KB, any error ignored, the path never sent), `pichamber: true` when that `package.json` has a `pichamber` object with a numeric `apiVersion`, and `pinned: true` for an npm source written with an exact version (`npm:foo@1.2.3`), which Pi never updates. The route projection drops a malformed value instead of failing the list.
|
|
16
|
+
- Install takes a bare npm name only (npm's naming rules, at most 214 characters, no version, no git, URL, or local source; anything else is `INVALID_ARGUMENT`) and installs `npm:<name>`. Project scope needs a trusted directory (`PROJECT_UNTRUSTED`). The same npm identity already configured in that scope is `PACKAGE_ALREADY_INSTALLED`, checked before the download and again under the lock. Update takes a configured npm or git package by list id; a local package is `INVALID_ARGUMENT` and a pinned npm source `PACKAGE_PINNED`. npm or git failures become `PACKAGE_INSTALL_FAILED` / `PACKAGE_UPDATE_FAILED` with `sanitizeErrorMessage` text inside the daemon.
|
|
17
|
+
- Locking: npm can run for minutes, so neither the download nor `pi update` holds the shared Pi config lock (other writers time out after 5 s) or the resource mutation queue. They run in the daemon's own install queue (`serializePackageInstall`, one at a time per daemon; separate daemons are not serialized against each other). When a queued install or update starts it reads the target again (`resolveTarget`), so trust revoked while it waited stops it before npm runs; update also looks the package up again. Install then takes the resource mutation queue and the shared lock, re-reads trust, and writes `addSourceToSettings` through a fresh settings manager. When that write fails the installed files stay (as with Pi's own `installAndPersist`) and the answer is `PI_SETTINGS_INVALID`. Both then recreate resident runtimes and answer with the fresh list inside the resource mutation queue.
|
|
15
18
|
- Listing builds two views like `pi config`: a global view resolved with `projectTrusted: false`, and, when a directory is given and trusted, a project view. Trust follows Pi's `resolveProjectTrusted`: a saved decision wins; with none, a project with nothing that needs trust is trusted (`resolveDirectory` has already saved trust for a folder that has project resources), so in practice only a denied project is untrusted. Built-ins offered are `LOADED_BUILTIN_EXTENSIONS` (never `llama.cpp`). Listing never installs: it calls `resolve(() => 'skip')`, so a missing package shows `installed: false`. A package Pi could not resolve goes into `installFailures` and the rest still list. A project entry with `autoload: false` for a package the user also has is Pi's record of that project's overrides, not a second package, so it is left out of `packages` and its extensions stay under the user's package. An untrusted directory answers the global view with `project: { available: true, trusted: false }`.
|
|
16
19
|
- No server path leaves the daemon. Ids are sha256 base64url over resource type, declaring scope, and the canonical path or `builtin:<name>` (packages: scope and Pi's package identity). An item the global view lists keeps the same id in the project view. Names follow `pi config`: the built-in name, `parent/file` when the parent folder is not `extensions`, else the file name. Package sources are npm and git sources as written with URL userinfo removed, and the folder name only for a local package. Error text is stripped of paths and credentials and capped at 300 characters.
|
|
17
20
|
- Writes reimplement Pi's private toggle logic (`config-selector.js`) as pure functions over a settings manager: in global scope only user-scope items toggle (`+`/`-` entries, package filters in object form); in project scope each item takes `inherit`, `load`, or `unload`, inherited files are named by absolute path, built-ins by `builtin:<name>`, and a user package gets an `autoload: false` project entry that is removed again when it has no filter left. `BUILTIN_PATH_PREFIX` is a local constant pinned by a test. Recheck these functions on every SDK upgrade.
|
|
18
21
|
- Every write re-resolves and rejects an unknown id (`RESOURCE_NOT_FOUND`), runs in the resource mutation queue under the shared Pi config lock, reads trust inside the lock (`PROJECT_UNTRUSTED` for project scope in an untrusted project, `INVALID_ARGUMENT` without a directory), and fails with `PI_SETTINGS_INVALID` when settings cannot be read or flushed. Removal calls only Pi's `removeAndPersist` (PiChamber deletes no path; local packages keep their files). A local package's source is passed as an absolute path, resolved against the folder its settings file is in, because `removeAndPersist` reads a relative source as typed in the daemon's working directory while settings keep it relative to the settings folder: `PACKAGE_REMOVE_FAILED` when npm or git fails, `PACKAGE_NOT_CONFIGURED` when settings had no entry, and `PI_SETTINGS_INVALID` when the files are gone but the settings write failed, which is never reported as success. After a write, resident runtimes are recreated through `scheduleRuntimeRecreation` (it recreates every resident runtime, for either scope); the answer is the fresh list plus `deferred: true` when a busy session delays that.
|
|
19
22
|
- `plugin-host.js` owns PiChamber plugins in the daemon (the server side is `../../plugins/`). The private, server-only `plugins.configure` command (`{ plugins: [{ id, entry, replaceable?, state: { global, projects, sessions? } }] }`, enabled plugins only) replaces the configured set. The host validates the payload (`INVALID_ARGUMENT`), imports each module only from under `packages/web/plugins/` (checked with realpath), and reports `{ plugins: [{ id, loaded, error? }], enabledChanged, deferred }`. One plugin that fails to import is left out and logged; the others still load. When the loaded set changes, the daemon calls `scheduleRuntimeRecreation()`, which is all or nothing: while any session in any folder is streaming, compacting, taking an input, or running a user shell command (`!cmd`), nothing is recreated and the answer is `deferred: true`; the change applies when that work ends, so a running turn or command is never cut. Recreation then disposes every resident runtime and recreates only the active one. The other sessions reopen from their files when next opened or prompted, and until then have no extension statuses, widgets, or composer controls; open drafts are discarded; a dialog or `custom()` surface left open is cancelled, as on a daemon restart. A composer control whose command the recreated runtime no longer registers answers `CONTROL_UNAVAILABLE` and never reaches the model as a prompt. A state-only change calls the `pichamber.onStateChange` listeners of live runtimes without recreation. Each loaded plugin becomes an `extensionFactories` entry after Pi's built-ins, in `createPiSessionRuntime` (through the `pluginExtensionFactories` runtime hook) and in `createFreshPromptServices`: `{ name: 'pichamber:<id>', replaceable, factory }`, listed by Pi as `<inline:pichamber:<id>>`. The factory calls the module's default export as `(pi, pichamber)` with `pichamber = { id, ui, state(directory, sessionId?), onStateChange(listener) -> unsubscribe }` (`ui` is the same `pichamber.ui` that `globalThis.pichamber` holds); `state` resolves `{ ...global, ...projects[directory], ...sessions[sessionId] }` (a session's own values are composer switches; up to 4096 sessions per plugin), and a runtime's listeners are dropped at its `session_shutdown`. The daemon never reads plugin state or the enabled set from disk, so a sandboxed daemon needs no grant for PiChamber's data folder. Until the server configures it, the daemon loads no plugins. The server pushes before the first request to each daemon process it has not configured (keyed by `streamEpoch`; see `../../plugins/DOCUMENTATION.md`). Each plugin factory runs for every runtime, also for a plugin Pi then drops as replaced, so the wrapper hands the factory a Proxy of Pi's extension API that notes the names passed to `registerTool`, `registerCommand`, and `registerFlag` (everything else forwards untouched). `registeredNames()` returns plugin id to `['tool:x', 'command:y', 'flag:z']` and `configuredIds()` lists the configured plugins; a plugin's names are forgotten when it leaves the configured set or its entry changes.
|
|
20
|
-
- `extension-replacements.js` finds what Pi left out of a live runtime. Pi drops a `replaceable` extension (PiChamber plugins and the `builtin:mcp`, `builtin:codemode`, and `builtin:tool-search` built-ins) when a non-replaceable one registers the same tool, command, or flag (`omitReplacedExtensions`), and keeps no record for plugins. A plugin counts as replaced when it is configured, its `<inline:pichamber:<id>>` path is not among the runtime's loaded extensions, and a loaded non-replaceable extension has one of the names the plugin registered (tools first, then commands, then flags); a missing plugin that shares no name is not reported, since it failed for another reason. A built-in counts as replaced when Pi's `warnings` hold an entry whose `path` is `builtin:<name>`; package and install warnings use other paths. Pi names the winner only inside that warning's text, so the optional `registers` and `by` details are parsed from it and left out when the text does not match. `extensions.config.list`, `extensions.config.set`, and `extensions.packages.remove` call it through `liveExtensionReplacements` in `session-daemon.js`, which never starts a runtime and never resolves a directory for it: it uses a non-draft runtime resident in the requested directory (the active directory when the request names none, and no other folder), and answers unknown (no `replaced`) when none is resident or when a runtime recreation is still queued, because that runtime predates the new configuration. Recheck the logic and the warning text against `omitReplacedExtensions` on every SDK upgrade.
|
|
23
|
+
- `extension-replacements.js` finds what Pi left out of a live runtime. Pi drops a `replaceable` extension (PiChamber plugins and the `builtin:mcp`, `builtin:codemode`, and `builtin:tool-search` built-ins) when a non-replaceable one registers the same tool, command, or flag (`omitReplacedExtensions`), and keeps no record for plugins. A plugin counts as replaced when it is configured, its `<inline:pichamber:<id>>` path is not among the runtime's loaded extensions, and a loaded non-replaceable extension has one of the names the plugin registered (tools first, then commands, then flags); a missing plugin that shares no name is not reported, since it failed for another reason. A built-in counts as replaced when Pi's `warnings` hold an entry whose `path` is `builtin:<name>`; package and install warnings use other paths. Pi names the winner only inside that warning's text, so the optional `registers` and `by` details are parsed from it and left out when the text does not match. `extensions.config.list`, `extensions.config.set`, and `extensions.packages.install/update/remove` call it through `liveExtensionReplacements` in `session-daemon.js`, which never starts a runtime and never resolves a directory for it: it uses a non-draft runtime resident in the requested directory (the active directory when the request names none, and no other folder), and answers unknown (no `replaced`) when none is resident or when a runtime recreation is still queued, because that runtime predates the new configuration. Recheck the logic and the warning text against `omitReplacedExtensions` on every SDK upgrade.
|
|
21
24
|
- `extension-name.js` owns path-free extension display names for `extensions.list` and the `source` of runtime `extension.error` events. A single-file extension is named after its file; an `index` entry point is named after its nearest non-generic directory, or the package root for package extensions. Neither surface ever carries a server path.
|
|
22
25
|
- `extension-tool-render.js` owns daemon-side rendering for Pi extension tools that define `renderCall` or `renderResult`. Built-in tools are excluded so PiChamber retains native tool card rendering. Global Pi TUI theme symbols are installed once without overriding an existing theme. Partial updates render both the collapsed and expanded result slots (the browser draws the expanded slot only when a row is expanded), are throttled at 250ms with a trailing timer and component `invalidate()` trigger, the latest live render of a running tool is kept and included in session detail so a client opening mid-run sees the working state, settled results are rendered only for messages a history page selects (never for the whole branch) and memoized per toolResult message for history replay, and rendered ANSI lines are bounded to 100 columns, ≤200 lines, and ≤2000 characters per line. Its exported `renderComponentLines` helper carries those same bounds for message renders.
|
|
23
26
|
- PiChamber's own dialog calls live on `pichamber.ui`, not on Pi's `ctx.ui`, so a method Pi adds later cannot be shadowed by ours (`pichamber-ui.js`). `pichamber.ui.choose(ctx, title, choices, opts)`, `.form(ctx, title, fields, opts)` and `.openUrl(ctx, url)` each take the tool or handler `ctx` first; a missing or foreign `ctx` (no PiChamber session behind it) rejects with a `TypeError`, never throws synchronously. The working implementations hang on the session's ui context under a `Symbol.for('pichamber.ui')` key, which cannot collide with a name Pi adds and survives Pi's runner copying the ui context with an object spread; `pichamber.ui.x(ctx, ...)` reads them from `ctx.ui`, so no session lookup is needed. Plugins get the same `ui` on their handle (`plugin-host.js`); ordinary extensions get `globalThis.pichamber` (`{ version, ui }`, frozen), set next to the `__PICHAMBER__` marker, which stays as released. `ctx.ui.form` and `ctx.ui.openUrl`, released in 1.0.4 and 1.0.6, are removed, and `ctx.ui.choose` never existed: `ctx.ui` holds only what Pi defines. Plain Pi has no `pichamber`, so an extension checks for it and falls back to `select`.
|
|
@@ -47,20 +50,24 @@ This module is the Pi-owned session-daemon foundation. A detached local daemon p
|
|
|
47
50
|
- `session-jsonl.js` validates cwd-scoped Pi JSONL before discovery. List, create, and daemon startup require a valid session header per file; they do not read whole transcripts. `sessions.list` uses `listPiSessionJsonlDirectory` (header, first user prompt, latest `session_info` anywhere in the file). Each daemon owns a per-file metadata cache (`createPiSessionJsonlListCache`) keyed by path and validated by dev/ino + size + mtime: an unchanged file costs one `stat`, a file that grew in place is scanned only from the last complete newline, and a shrunk, replaced, or rewritten file is rescanned. Scans stream in 256KB chunks and only `JSON.parse` lines whose raw bytes contain `"session_info"` (or `"user"` until the first prompt is found). Pi semantics apply: the latest `session_info` wins, and an empty or whitespace name is an explicit clear. Entries for files no longer in the directory are pruned on each list. Files in one directory are listed with at most eight concurrent reads; one unreadable or header-malformed file still fails that directory. Full-file validation remains on open of a specific session so a malformed body still fails that chat. Pi's SDK list is not the production list path because it scans every line of every log. `sessions.list` and `sessions.delete` accept a folder that no longer exists (a removed worktree or temporary folder still has sessions in the store, which auto-archive and the sidebar must reach). Deletion finds such a session after a daemon restart too (`findPersistedSession` with `allowRemovedDirectory`), never records the removed folder as a known project, and engine-owned deletes resolve the same way (`resolveSessionStoreDirectory` in the engine router); the path must still be absolute, and an existing path that is not a folder (a file, or a foreign Windows path such as `C:/Users/...` on Linux, which is not absolute there) is rejected with `INVALID_ARGUMENT`. Opening or creating a session still requires the folder to exist. Directory names match Pi's SessionManager encoding, including Windows drive letters and Git Bash/MSYS/Cygwin/WSL `/c/...` paths so PiChamber and the Pi CLI share the same JSONL sessions.
|
|
48
51
|
- `supervisor.js` accepts an optional `onDaemonReady({ health, request })` hook that runs after every successful health probe (before each request, subscription, and health answer) with a request function bound to that verified daemon; its errors are swallowed so it can never fail the caller. The plugin push uses it.
|
|
49
52
|
- `supervisor.js` resolves server-only overrides, creates the credential, serializes start/reuse/stop through an owner-only lock, validates daemon identity through `runtime.health`, forwards server-owned commands only after that identity check, and starts or stops the detached process. Reuse requires the ready-state sidecar `entrypoint` to match this checkout's `daemon-process.js`; a healthy same-profile daemon with a different entrypoint is claimed and then shut down through authenticated IPC so local `bun run dev` cannot keep answering `getSession` without the live-turn overlay. When the parent is Electron, the child is spawned with `ELECTRON_RUN_AS_NODE=1` so packaged Windows/macOS/Linux apps run the daemon as Node instead of a hidden second Electron GUI process. A daemon spawn failure (synchronous throw or the child's async 'error' event, e.g. when the executable vanished) is captured, never left as an uncaught 'error' event, ends the readiness wait early, and surfaces as code-only `DAEMON_SPAWN_FAILED` without the executable path.
|
|
53
|
+
- `../sandbox/` owns project sandboxes (launcher seam, nono launcher and profile, setting, manager, routes, OAuth, trust reset); see `../sandbox/DOCUMENTATION.md`. `createSandboxedPiSessionDaemonSupervisor` in `supervisor.js` starts the unchanged daemon command through a launcher (see "Sandbox launchers" below).
|
|
54
|
+
- `daemon-pool.js` (`createPiDaemonPool`) holds the session daemons this server talks to: the main daemon (the supervisor's runtime, read through `getMainRuntime` at call time) plus project daemons registered by key (`register(key, { runtime, directories })` / `unregister(key, runtime?)`; with `runtime` it unregisters only if that runtime is still the one registered, so a late drain finish never removes a replacement). An entry may own no directories (`directories: []`): a retired daemon stays registered that way while its sessions drain, so it keeps its place in the merged event stream. A project daemon owns its project root and worktree roots and every folder inside them; the longest matching root wins and a sibling such as `/work/ab` never matches `/work/a`. Anything no project daemon owns, and any missing or relative directory, belongs to the main daemon. `setDraining(directory, keys)` names daemons that still run some of a folder's sessions while a switch drains; `drainingFor(directory)` returns them as `{ key, runtime }` (never the owner). `live()` lists every daemon, main first, skipping a project daemon whose runtime reports `isLive() === false` (a registered sandbox daemon that has not started or was stopped idle), and `onChange` fires on register, replace, and unregister. `publicDaemonStreamId(key)` is the opaque id clients see for a daemon: `main` for the main daemon, otherwise a 16-character hash of the key, so pool keys and project paths never reach a client. `streamFor(directory)` returns the owner's public id, or undefined for the main daemon. `announceMove(sessionId, directory)` tells every open event stream that a session changed daemons (`onMove` listens); whoever moves a session between daemons calls it. The composition root registers one entry per sandboxed project (`../sandbox/project-sandbox-manager.js`); with no sandboxed project the pool holds only the main daemon and every request goes where it went before.
|
|
50
55
|
- `../server/server-profile.js` derives one stable daemon profile per server: installed web is `web-p<port>`, development web is `web-dev-p<port>`, installed desktop is `desktop`, and development desktop is `desktop-dev`. `PICHAMBER_SERVER_PROFILE` overrides the derivation with a hashed `custom-<hash>` key so raw input never becomes a path, while preserving whether the launcher is a development build for stale-code replacement. The profile key is stable across restarts; the server instance id is a fresh UUID per launch. Development launchers (`scripts/dev-web-hmr.mjs`, `scripts/dev-web-full.mjs`, `cross-env` in the `dev:server` scripts, `PICHAMBER_ELECTRON_DEV`) explicitly mark themselves so stopping development can never terminate the installed daemon.
|
|
51
56
|
- `../server/cross-process-lock.js` serializes critical sections across servers sharing one data directory (exclusive create, owner nonce, dead-pid steal, bounded wait). It backs the daemon operation lock pattern and every shared read-modify-write store below.
|
|
52
|
-
- `session-lease.js` owns exclusive cross-daemon residency of one Pi session, keyed by canonical agent directory, cwd, and session id under `<agentDir>/.pichamber/locks/sessions/`. The lease is acquired before a resident `AgentSessionRuntime` is created and released after idle disposal, deletion, replacement, or daemon shutdown. Opening or deleting a session leased by another live daemon returns `SESSION_IN_USE` (HTTP 409) while the session stays visible in listings; different sessions remain fully concurrent. Lease files from different `PICHAMBER_DATA_DIR` values still coordinate because they live under the shared agent directory.
|
|
57
|
+
- `session-lease.js` owns exclusive cross-daemon residency of one Pi session, keyed by canonical agent directory, cwd, and session id under `<agentDir>/.pichamber/locks/sessions/`. The lease is acquired before a resident `AgentSessionRuntime` is created and released after idle disposal, deletion, replacement, or daemon shutdown. Opening or deleting a session leased by another live daemon returns `SESSION_IN_USE` (HTTP 409) while the session stays visible in listings; different sessions remain fully concurrent. Lease files from different `PICHAMBER_DATA_DIR` values still coordinate because they live under the shared agent directory. A sandbox daemon (`leaseScope`, from `--lease-scope`) keeps its leases in `<agentDir>/.pichamber/locks/sandbox-sessions/<scope>/` instead and sees no other; a daemon without a scope also checks every scope folder for the session before it takes it. Files in those folders are read without following symlinks or waiting on FIFOs and only up to 8 KiB, and leases are written through a random-named temp file created exclusively (see `../sandbox/DOCUMENTATION.md`, Session leases). Inside one daemon, taking and letting go of a session's lease run one at a time per session, and the retry of a failed release (`sessions.release`) does nothing when the session has taken its lease again since; it reports that session as pending, not released.
|
|
53
58
|
- `../session-shelf-store.js` holds sidebar snooze only (`snoozedUntil` / `snoozedAt`) in `<dataDir>/pi/session-shelf.json`; `POST /api/pi/sessions/:id/shelf` accepts only a snooze patch and answers `{ entry }`. Files written before Archive replaced Settle migrate on first read or write under the shelf lock: a `settled` mark becomes an archive at its `settledAt` (an existing archive time is kept) and an `active` mark is dropped. The archive file is written first through `archive-store.js` `archiveMissing`; if that write fails, the migration retries on the next read or write. Until it succeeds, reads return the snooze-only view and snooze writes still go through, with every unmigrated settled mark written back unchanged. A send (`clearForActivity`) or a delete (`remove`) also drops that session's settled mark, so the retried migration never archives a session the user just used. Older clients that still send `settled: 'settled'` archive the session; `'active'` and `null` are no-ops. The older-client mapping is removed one release later.
|
|
54
59
|
- Unarchive on send: an accepted (202) prompt, steer, follow-up, or bash request clears the session's snooze and its archive mark (`bringBackForActivity` in `routes.js`), so a session you return to rejoins the active list. A failed write there is logged and the request still answers 202.
|
|
55
60
|
- Archive changes reach every device: after the archive route, the older-client `settled: 'settled'` shelf write, or an unarchive on send saves the mark, `routes.js` asks the daemon to publish it (`archive.publish`, private, server-only, `{ sessionId, archived, directory? }`; without a directory the daemon uses the resident session's cwd). The daemon publishes `session.archive` (`{ archived }`) on that session's stream, which every subscriber receives. It is a signal, not state: a client whose catalog row disagrees re-lists that folder (coalesced per folder), and the archive store stays the authority. The request is fire-and-forget; a failure (such as an older daemon) only logs, and devices catch up on their next list.
|
|
56
61
|
- Retention settings migration (`ui-settings-store.js`): `sessionAutoArchiveAfterDays` and `sessionAutoDeleteAfterDays` are portable integers 0 to 365 (0 is off). When either is missing or invalid in `settings.json`, the store decides both once, under the read lock, before any write: a new install (no allowlisted field in `settings.json` and no local field in `runtime-state.json`) gets 7 and 0; an existing install maps the old fields (off or missing to 0 and 0, on with archive N to N and 0, on with delete N to N and 30; a missing action means archive, a missing or invalid N means 30, clamped 1 to 365). The old fields (`autoDeleteEnabled`, `autoDeleteAfterDays`, `sessionRetentionAction`, `sidebarAutoSettleAfterDays`) stay allowlisted but unread until a later release removes them. The passes themselves run in the client (`useSessionAutoCleanup`); there is no server-side auto-archive.
|
|
57
62
|
- `../routes.js` registers authenticated public adapters before the generic proxy. It exposes only whitelisted runtime, project, session, provider-auth/configuration, settings, resource, small-model utility, and SSE event shapes; no browser response contains daemon paths, credentials, PIDs, headers, or socket framing. Session actions are path-selected, so an identity supplied in a request body cannot redirect a mutation. `POST /api/pi/sessions` projects the created detail through the same session-detail projector as `GET /api/pi/sessions/:id`, so extension items appended from `session_start`, the `streamEpoch` stamp, and extension UI snapshot state are returned rather than rejected; only a malformed detail is `DAEMON_PROTOCOL_MISMATCH`. `archive-store.js` persists PiChamber-only opaque session archive metadata atomically beneath the PiChamber data root and never edits Pi JSONL. `settings-store.js` keeps PiChamber new-session defaults separate from Pi settings.json. `/api/pi/small-model/generate` reads that sidecar and runs a bounded in-memory no-tools Pi session, so utility generation creates no visible or persisted session and exposes no model or credential details. `GET /api/pi/settings` copies leftover UI/desktop `defaultModel` / small / walkthrough strings into that sidecar when those sidecar fields are unset, then Sessions settings is the only editor. Sidecar `defaultThinkingByModel` is the per-model thinking map (`provider/model` keys). A stored global `defaultThinking` with a default model is copied onto that map key and dropped; global thinking without a default model remains a clamp-only fallback. `ui-settings-store.js` owns portable PiChamber preferences at data-root `settings.json` and host, device, and secret-bearing values at `runtime-state.json`. `/api/pi/ui-settings` merges both views for existing clients and splits writes through explicit field allowlists. It migrates an unscoped flat file once; after the portable scope marker exists, local fields found in `settings.json` are ignored rather than applied to the host. The route is not available through removed `/api/config/*` aliases. `session-folders-store.js` validates and atomically persists the restored sidebar's folder snapshot at `/api/pi/session-folders`; a missing snapshot is distinct from an empty one. `session-shelf-store.js` persists PiChamber-only sidebar shelf state (a snooze wake time and its start) per session id at data-root `pi/session-shelf.json`, read through `GET /api/pi/session-shelf` and changed through `POST /api/pi/sessions/:id/shelf`, which checks that the session exists like archive does. Archive replaced Settle: a shelf file that still holds `settled` marks is migrated once under the shelf lock, archiving hand-settled sessions at their `settledAt` (already archived sessions keep their time) and dropping the settled fields. The archive file is written first; if that write fails, reads still answer with the snooze state, snooze writes still go through with every unmigrated settled mark written back unchanged, and the next read or write retries. Until one release later the shelf route maps `settled: 'settled'` from an older client to an archive and accepts `'active'` and `null` as no-ops. A prompt, steer, follow-up, or `!` command the daemon accepts clears that session's snooze and unarchives it, and deleting a session removes its entry; a failed shelf or archive write after a successful send only logs and the send still answers `202`. The sending client clears `archived` optimistically. Every archive change, including this unarchive, is then published as `session.archive` (see Archive changes reach every device above); a client also re-lists the folder when it sees a send's user message or `session.bash` event for a session it holds as archived, which covers a failed publish. A malformed file is `SESSION_SHELF_INVALID`, never an empty shelf. `custom-themes.js` serves validated custom-theme candidates from `/api/pi/themes` with per-file partial-failure isolation. `model-config-store.js` atomically updates Pi's credential-blind `models.json`; literal keys continue through Pi auth and headers are write-only. `providers.config.get` returns `config: null` for a provider that is not in `models.json` (built-in catalog entries) and fails only when that file is present but malformed.
|
|
63
|
+
- Daemon routing in `../routes.js` (`registerPiRuntimeRoutes({ daemonPool })`; without a pool it wraps `getPiSessionDaemonRuntime` as the main daemon). Session- and directory-scoped commands (session actions, `sessions.create` by `cwd`, `sessions.list`, `sessions.rename`, `sessions.sendReceipt`, `resources.list`, `extensions.list/respond`, the archive and shelf membership lists, `archive.publish`) go to `forDirectory(directory)`; the daemon payload is unchanged. While any project is sandboxed, session commands, rename and send receipts route by the project whose session folder stores the session's transcript, or its header `cwd` when no sandboxed project stores it (`sessionDaemonDirectory`), not by the client's folder; client-named folders are spelled canonically first and a non-absolute one is refused (`../sandbox/DOCUMENTATION.md`, Routing): a daemon finds a session by id wherever it lives, so a wrong or missing folder would let the main daemon run a sandboxed project's agent unsandboxed. The client's folder applies only to a session not yet written to disk. Directory-less commands (`runtime.health`, `projects.*`, `providers.*` including login and logout, `engines.list`, `settings.*`, `extensions.palette`) and resource writes (`resources.update`, `resources.prompts.*`) always go to the main daemon, because they write Pi's own config and credentials, which a project daemon may only read. `/api/pi/events` merges every live daemon (see `../merged-event-stream.js` below). Every response that carries a project daemon's state is tagged with that daemon's `stream` id: session detail, create, navigate, fork and clone, messages, and the list. Clients check such a response's `streamEpoch` against that stream, not the main one. `sessions.pendingInput` fans out to every live daemon. The top-level `sequence` and `streamEpoch` are the main daemon's, and its entries carry no `stream`. A project daemon's entries carry its `stream`, and its position is under `streams[stream] = { sequence, streamEpoch }`. A failed or malformed daemon is skipped and the response gains `incomplete: true` (clients then set the listed entries but clear no absent row). If the main daemon failed, the top-level `sequence` and `streamEpoch` are absent. Only when every daemon fails does the route fail. `sessions.list` for a folder is the owner's list. Each draining daemon's list for the same folder only fills in `live` and `inputState` on owner rows that lack them, matched by session id. Such a row also gets that daemon's `stream` (`main` for the main daemon) and `streamEpoch`, so clients order it in that daemon's sequence space. A failed draining daemon leaves those rows unknown. A failed owner fails the list. The all-sessions list (no folder) is the main daemon's, with `live` and `inputState` filled the same way from every live project daemon's list.
|
|
64
|
+
- `../merged-event-stream.js` (`subscribeMergedPiEvents`) is the `/api/pi/events` subscription across the pool. The main daemon is subscribed exactly as before: same options, unchanged frames, its resume position still `fromSequence` + `streamEpoch`. Its failure still ends the connection. Each project daemon is subscribed alongside it. Its frames gain `stream` (its public id) and `cursor`. The cursor is opaque base64url JSON (`{ v: 1, d: { [stream]: [epoch, sequence] } }`) covering every project daemon, never the main one. A client sends its newest accepted cursor back as `?cursor=`. Each project daemon then resumes from its entry, and a daemon whose lifetime changed answers with a resync snapshot. `decodePiEventCursor` bounds the cursor (4096 characters, 64 streams), and a malformed one is a 400. A cursor sent to a daemon without `events.streamEpoch` is a protocol mismatch. Only the affected daemon's sessions resync. A daemon registered mid-stream is subscribed without a position (snapshot baseline). A replaced runtime (restart) is resubscribed from its old position, so the new process resyncs. A removed daemon is unsubscribed and dropped from the cursor. A project daemon whose subscription fails is dropped and retried alone with backoff (500 ms doubling to 30 s) while it stays registered, without ending the connection. Each connection remembers which daemon last delivered each session (bounded to 4096 sessions). A frame for a session from a different daemon, a daemon detaching, or `pool.announceMove` emits a server-made `session.moved` frame (`sequence: 0`, no `streamEpoch` or `stream`) before anything from the new owner. Clients drop that session's live state and refetch it.
|
|
58
65
|
- `../event-stream.js` owns the `/api/pi/events` SSE connection lifecycle so `../routes.js` stays a thin adapter. Per connection it installs cleanup before `subscribe` is awaited (a client that leaves during the opening window cannot leak a daemon subscription; a late subscription is closed exactly once), funnels client disconnect, subscription error, and server shutdown through one idempotent cleanup, hands an `AbortSignal` through the supervisor to the private IPC subscriber, never writes a named heartbeat or a late frame to a dead response, and byte-bounds the response socket buffer (`res.writableLength`, default 8 MiB, aligned with the daemon replay budget) with the bound enforced BEFORE each write so no single frame overshoots it. A client that stops reading is disconnected recoverably — the stream ends and the client reconnects from its last accepted sequence for replay or an authoritative snapshot, so no event is silently removed from an otherwise contiguous stream, but frames still buffered when the disconnect fires are not promised as delivered; the reconnect replay is the delivery guarantee — while a healthy client's connection stays independent of the slow one. Every teardown is bounded: a `write()` that returns false starts a drain deadline (default 5s) that ends even a quiet never-draining client, and after `res.end()` a terminate deadline (default 5s) destroys the response, because `end()` alone only queues the FIN behind unflushed data and would otherwise leave a stalled socket open forever and hang server shutdown/close. The response `'error'` guard stays attached for the response's lifetime (idempotent; cleanup can complete while data is still in flight and a late unhandled `'error'` would crash the process). The registry tracks live connections so `registerPiRuntimeRoutes` can expose `closeEventStreams()` for server shutdown, ending active and still-opening streams (and their daemon subscriptions) before the HTTP server closes. The IPC subscriber removes its abort listener and destroys the opening or active daemon socket on cancellation.
|
|
59
66
|
- `*.test.js` uses temporary cwd, agent, data, and runtime directories; it never loads a developer's Pi home, credentials, or sessions. On Windows the private endpoint is a named pipe, not a `.sock` file, and POSIX mode-bit assertions are skipped.
|
|
60
67
|
|
|
61
68
|
## Protocol and security invariants
|
|
62
69
|
|
|
63
|
-
- Each profile owns its daemon artifacts: `<dataDir>/pi/daemons/<profileKey>/` holds the credential, `daemon-state.json`, and `operation.lock
|
|
70
|
+
- Each profile owns its daemon artifacts: `<dataDir>/pi/daemons/<profileKey>/` holds the credential, `daemon-state.json`, and `operation.lock` (a sandbox daemon's lock, launcher record and credential are in `<dataDir>/pi/launchers/<profileKey>/` instead; see "Sandbox launchers"); the endpoint is `<runtimeDir>/pi-daemons/<profileKey>/daemon.sock` (or `$XDG_RUNTIME_DIR` equivalent); per-profile logs append to `<dataDir>/logs/pi-daemon-<profileKey>.log`. The state sidecar records `profileKey`, `serverInstanceId`, `serverPid`, `daemonId`, `runtime`, and `buildId` alongside pid, endpoint, and entrypoint. A pre-profile legacy daemon is never adopted, unlinked, or signaled; only its dead pid record is best-effort removed.
|
|
64
71
|
- The endpoint is a Unix domain socket on POSIX or a Windows named pipe. TCP endpoints are rejected. Listeners and clients connect with IPC `path` options so Windows `\\.\pipe\pichamber-pi-session-daemon-<owner-key>-<profileKey>` works the same as a POSIX socket path. `PICHAMBER_PI_SESSION_DAEMON_ENDPOINT` still overrides the socket path, but the credential, state, and lock stay per-profile: a profile never adopts, unlinks, or signals an endpoint it cannot authenticate and identify as its own, and the conflict surfaces as `DAEMON_ENDPOINT_UNVERIFIED`.
|
|
65
72
|
- POSIX socket parent directories are mode `0700`; the socket is created mode `0600`. An existing endpoint fails startup rather than being unlinked without daemon-identity verification. Windows named-pipe ACLs are not yet equivalent owner-only OS permissions; credential authentication remains mandatory.
|
|
66
73
|
- The daemon credential and non-secret state sidecars are mode `0600`; their per-profile parent directory and the operation lock serialize start/reuse/stop. Exclusive lock create writes the owner pid in the same step. A leftover empty or malformed lock, a dead owner pid, or Windows `EPERM`/`EACCES` on exclusive create is retried and stolen after a short freshness window instead of failing as `DAEMON_LOCK_UNAVAILABLE`. Sidecar `chmod` failures on Windows are ignored after the file exists so readiness is still recorded. Health identity includes the daemon PID, profile key, and daemon id, and all three must match the state sidecar before the supervisor reuses a process. Reuse also requires the ready-state `entrypoint` to equal this host's `daemon-process.js`; a missing or different path is not identity-compatible and is replaced after a claim.
|
|
@@ -69,7 +76,7 @@ This module is the Pi-owned session-daemon foundation. A detached local daemon p
|
|
|
69
76
|
- The public health route deliberately whitelists its response fields (state, protocol version, capability names, and the opaque public `streamEpoch`). It never returns a daemon endpoint, credential, PID, cwd, agent directory, or transcript data. Public transcript and event projections preserve daemon-redacted assistant error messages so the UI can distinguish provider/runtime failures instead of reducing every failure to `ASSISTANT_ERROR`.
|
|
70
77
|
- A client must send an `authenticate` frame carrying the host-private daemon credential before it can issue a request. Credentials are never logged or returned.
|
|
71
78
|
- Frames are LF-delimited JSON. One frame has a 16 MiB maximum. Complete frames are parsed before the client bounds the remaining incomplete frame. Invalid JSON reports `MALFORMED_DAEMON_RESPONSE`; an oversized response reports `DAEMON_RESPONSE_TOO_LARGE`. A malformed, oversized, unauthenticated, or invalid request closes the connection.
|
|
72
|
-
- The private core commands are `runtime.health`, `projects.list/select`, `providers.list/config.get/models.set/models.add/status/login/login.respond/login.status/logout`, `settings.get/set`, `resources.list/update/prompts.create/prompts.update/prompts.delete`, `extensions.list/respond/palette`, `extensions.config.list/set`, `extensions.packages.remove` (see `extension-config.js` above), `plugins.configure` (see `plugin-host.js` above), and session list/pendingInput/create/discardDraft/open/messages/rename/delete/tree/navigate/fork/clone/prompt/steer/followUp/sendReceipt/abort/model/thinking/compact operations. `sessions.pendingInput` takes no arguments, is never session-scoped or routed to engines, and returns `{ sessions: [{ sessionId, directory, pending }], sequence, streamEpoch }` for sessions with a non-null summary; `runtime.health` advertises it. Resource lists use opaque IDs and never disclose server paths. Only top-level Pi prompt templates and applicable AGENTS.md sources are editable; package/path resources and skills are browse-only. Prompt-template mutations resolve against the caller's explicit effective directory, reject stale and cross-directory opaque IDs, enforce project trust for project prompts, serialize create/update/delete operations, preserve existing files on validation or write failure, atomically reserve new destinations without overwriting concurrent writers, use temporary-file persistence with cleanup, preserve unknown frontmatter fields (for example `argument-hint`) when editing description or content, and for rename validate the destination name and scope, reject collisions, write the destination atomically, remove the source only after success, and roll back the destination when source removal fails. A committed prompt mutation never disposes a session runtime: affected idle sessions use Pi's identity-preserving `session.reload()`, while streaming, compacting, and extension-command sessions finish first and reload at their next safe lifecycle edge. Global prompts refresh every resident runtime; project prompts refresh only runtimes in that directory. Mutation responses merge freshly discovered editable prompts from transient per-mutation services (never retained; Pi 0.84.1 exposes no dispose on AgentSessionServices/ModelRuntime/ResourceLoader/SettingsManager — file reads plus a cleared create-time timeout, no watchers/intervals/listeners, so dropping the reference lets GC reclaim it) with live package/path/extension resources so the Settings page reflects the committed file even while runtime activation is deferred. `providers.refresh` touches only live runtimes plus the requested directory's runtime (started when it is not resident); the returned catalog comes from that directory's runtime via `providers.list`. Concurrent refreshes share one task per resolved directory, never across directories; refreshes for different directories run one after another so their temporary catalog keys never interleave. Generic non-prompt resource writes share the serialized resource-mutation queue and commit through an atomic replace even while a session is active. The daemon returns `deferred: true` and recreates resident runtimes after they become idle; a new session reads the committed file immediately. If immediate recreation fails after a committed write, the response still reports deferred activation and the daemon keeps the recreation queued for a later safe edge. Project trust changes are persisted in Pi trust.json and use the same deferred runtime recreation; project-local extensions load through Pi's own trust flow once trust is resolved. Provider login submits API keys only across authenticated private IPC or brokers Pi's OAuth/device/manual-code interaction, passing the same `getDeviceId` login option as the Pi CLI (backed by the runtime `SettingsManager.getOrCreateDeviceId()`) because flows such as Sign in with ChatGPT reject logins without a stable installation ID. A failed attempt projects Pi's error message (with its causes, URL query strings stripped so a pasted callback never echoes an authorization code, capped at 500 characters) beside the stable `PROVIDER_AUTH_REQUIRED` code; public projections contain only opaque login IDs, prompts, URLs/device codes, model catalog/configuration, and stable states, never credentials or write-only headers. `providers.models.set` atomically persists Pi's `models.json`; a busy runtime returns `deferred: true` and is rehydrated after all active sessions are idle, while a new session sees the catalog immediately. `providers.models.add` appends one model (`id` required; optional `name`, `reasoning`, `thinkingLevelMap`, `input`, `contextWindow`, and `maxTokens`) atomically without replacing the provider. The model configuration store owns normalization and validation. The daemon rejects duplicate or unavailable live models, seeds a missing file provider only from authoritative live metadata when safely representable, rejects extension registrations with an explicit `models` array, and uses the same deferred recreation as `providers.models.set`. A successful recreation publishes a provider-catalog invalidation so connected settings views load the new authoritative catalog. Provider edits preserve unexposed existing model metadata server-side while public projections remain credential-blind. `providers.list` projects only catalog and authentication-status metadata, including Pi-supported `thinkingLevels` (`null` map entries hidden, `xhigh`/`max` opt-in). Session thinking overrides are clamped to the live model's supported levels. `sessions.list` checks each cwd JSONL header (not the full transcript) so a project with large session logs cannot spend tens of seconds on startup. SDK `SessionManager.list` is not used for that path; `listPiSessionJsonlDirectory` returns cached or incrementally scanned header, first-prompt, and name fields. For a row whose runtime is resident, the list uses `sessionManager.getSessionName()` instead of the disk name, so unflushed renames and clears show immediately. Unpersisted resident sessions are listed too, except the fresh empty session a runtime starts with when it is started only to answer a folder's catalogs (`providers.list`, `resources.list`, `extensions.list`, runtime recreation) with no JSONL to reopen: nobody asked for it, so it stays out of listings until it holds a non-`custom` message (a user prompt, an assistant reply, or anything else that is not an extension's custom message) or a name, since what an extension adds at `session_start` lands in every such session, otherwise every folder switch would add an untitled "Awaiting first prompt" row. Each listed row whose runtime is resident in this daemon (including unpersisted resident sessions) carries `live: { lifecycle, sequence, retry?, runStartedAt?, serverNow }`, sampled synchronously with the current event `sequence` from the same retry/streaming/run-start state as snapshots; rows without a resident runtime carry no `live`, which clients treat as unknown rather than idle. Every Pi row additionally carries `inputState: { pending, sequence }` from the pending-input index (`pending` is `null` when authoritatively nothing is pending, stamped with the same observed sequence as `live`), so every device learns blocked sessions without opening them. Concurrent lists of the same directory share one in-flight result. Concurrent `sessions.open` of the same id share one in-flight runtime create; a duplicate that finishes later disposes itself and returns the registered runtime instead of `SESSION_RUNTIME_CONFLICT`. Full-file JSONL validation stays on open of a chosen session. The browser explicitly selects an existing user-chosen project directory before listing it; the daemon's startup cwd is an internal fallback, not a user-visible default project. Unnamed persisted sessions use their first prompt as a readable list title when available. `sessions.open`, `getSession`, navigate, fork, and clone project the live session's model and thinking level onto the session record, because that is what the next prompt runs on; Pi itself restores both from the branch when it reopens a chat. The last assistant `provider`/`model`/`thinkingLevel` only fills in when the live session reports none. It is not a substitute: after a revert, a failed turn, or a switch nobody has prompted on yet it names a model the session has left, and a client that compared its composer against it would skip the switch and keep sending on the old model. `sessions.open`, navigate, fork, and clone return a tail page bounded by both projected-message count and serialized bytes. `sessions.messages` reads older pages with an opaque before-cursor. A page that starts inside a tool loop repeats the owning user message as a grouping anchor; browser merging deduplicates that overlap. Persisted tool results are indexed across the active branch before paging, so a paged assistant tool call still receives its matching final result. Session selection validates a persisted JSONL path before Pi opens it; inactive mutations are never directed by a browser-supplied path. `sessions.open` first checks a caller-supplied directory through its bounded header list, so an ordinary project-scoped open neither walks every directory in the agent store nor adopts a same-id session from another directory. Directory-less deep links resolve by Pi's `timestamp_<id>.jsonl` filename before broader SDK-list and header-scan fallbacks. Directory-wide JSONL checks on list/create/startup are header-only; full-file validation stays on open of a chosen transcript. Attachment paths originate in the server-local upload map and cross only private IPC into Pi's tool context. Pi may persist or echo those paths in its authoritative JSONL transcript, so every public projection redacts them recursively: session titles/previews, user and assistant text/thinking, tool arguments, errors, snapshots, and live message events never expose the server-local path. Persisted projection first checks for the attachment marker, then redacts matching tokens with a delimiter scan whose work stays linear for large encoded strings and tool payloads. The daemon maps Pi message lifecycle, deltas, tools, queue changes, model/thinking, compaction, interruption state, and session title updates (`session.updated` on create-with-title, first prompt, and rename). Like the Pi CLI, the daemon never persists an auto-title: on the first conversation prompt of an unnamed session it publishes the derived title live without appending `session_info`, and lists derive the same title from the first user prompt. Renames of a resident session call Pi's `session.setSessionName`, which appends `session_info` and emits `session_info_changed` to listeners and extensions; the subscriber publishes the single `session.updated`. Non-resident renames open the file and append, as Pi's session picker does, and publish directly. `session.updated` with `title: ''` means Pi cleared the name; clients fall back to the title derived from the first prompt, and older clients ignore empty titles to canonical events. Session deletion publishes an explicit `session.deleted` event; archive and directory moves keep the id and never publish it. Pi `model_select`, `thinking_level_changed`, and `session_info_changed` events are authoritative for model, thinking, and session-name changes made by extensions, the TUI, or another client. Each thinking change publishes exactly one `session.thinking` with the effective (clamped) level: `applyThinking` publishes only when Pi will not (the level did not change, or the runtime is not yet subscribed during create). The bridge observes Pi provider registration and label writes because Pi 0.84.1 emits no corresponding session events: provider mutations publish a catalog invalidation, and label mutations invalidate the bounded session-tree projection. `ctx.reload()` clears old extension UI state, reloads Pi resources, and invalidates provider/resource/command catalogs. `ctx.shutdown()` disposes only the requesting idle session runtime after its command or turn settles; it never stops the shared daemon or unrelated sessions. Compaction events preserve Pi's manual/threshold/overflow reason, active/retrying/terminal phase, retry timing, redacted failure, compact-and-retry intent, and pre/post token estimates. The latest state is included in `getSession` and reconnect snapshots; after daemon restart, the latest persisted Pi `CompactionEntry` restores completed feedback without treating history as live work. Tool events carry redacted input arguments, cumulative partial-output snapshots, final output, error text, renderer metadata (edit diffs, truncation notes), and server start/end timestamps plus a `serverNow` sample so clients with different clocks can normalize elapsed time. Nested tool execution events carrying a non-empty `parentToolCallId` are skipped because Pi records nested calls on the parent tool result and omits them from transcript messages. Active and recently completed tool parts retain their start timestamps in the daemon's bounded in-memory timing cache, so `getSession` hydration keeps timers consistent across clients and browser reloads until the daemon restarts. Pi loads skills with the ordinary `read` tool. The daemon matches those read paths against the active runtime's authoritative `resourceLoader.getSkills()` catalog and adds path-free `metadata.pichamber.skill.name` for live events, hydrated history, and reconnect snapshots. PiChamber uses that metadata for its compact Skill row and Settings navigation; an arbitrary file named `SKILL.md` remains a normal read. Persisted `toolResult` entries merge into their assistant `toolCall` parts as output/error/end time so hydrated sessions render complete tool cards; tool-result entries never surface as standalone messages. Assistant message projections and start events carry the owning user-message id so the restored turn renderer can group and display replies; all assistant entries in a tool loop and every retry/compaction continuation remain attached to the latest user turn until `agent_settled` closes the run. Assistant message projections also pass through Pi's per-turn `Usage` (input, output, cacheRead, cacheWrite, totalTokens, and the same five numeric cost fields). The daemon sanitizes the raw payload through `projectUsage` before publication: every numeric must be finite and non-negative, the whole object is omitted when any field is missing or wrong type, and unknown keys are never copied. The `assistant.message.end` event carries the same sanitized usage so the last turn updates without waiting for a full `getSession` refetch. The public route whitelist re-applies the same sanitizer on each projection so a stale or malformed payload from a different daemon version cannot surface as `NaN` or `Infinity` in the reducer.- Live `message_start` events use daemon-generated browser message IDs because Pi has not appended the corresponding session entry yet. Pi agent-core emits streaming assistant starts as shallow copies, not as the finalized object it later persists. At `message_end`, `message-entry-aliases.js` therefore rebinds the synthetic ID to the finalized event object, then maps that object by identity to Pi's appended entry in a microtask. `sessions.navigate` and `sessions.fork` resolve the mapping after stripping any part suffix. Alias keys include cwd and session ID, survive idle runtime disposal of persisted sessions, and clear on explicit session deletion, confirmed ephemeral expiration (which publishes `session.deleted`), or daemon shutdown. Hydrated message projections continue to use the Pi entry ID directly.
|
|
79
|
+
- The private core commands are `runtime.health` (its result includes `residentSessions`, the count of live and starting runtimes, which the sandbox manager reads for idle stop), `projects.list/select`, `providers.list/hosts/config.get/models.set/models.add/status/login/login.respond/login.status/logout` (`providers.hosts` returns the sorted, lowercase hosts of signed-in providers' model base URLs, skipping loopback and IP literals, for sandbox network grants; it and `providers.oauth.refresh` take an optional `exclude` list of absolute folders, use a resident runtime outside them, and never start a runtime inside one, so the main daemon does not load a sandboxed project's extensions), `settings.get/set`, `sessions.release` (`{ directories }`, 1–64 absolute folders: disposes every idle resident runtime in them now and marks each busy one to dispose at its next idle edge with no grace delay; returns `{ released, pending, streamEpoch }` as session ids, for the sandbox manager's drain; a session whose lease could not be released stays `pending` and the release is retried on the next call, so another daemon never opens it while the lease is held), `providers.oauth.refresh` (`{ minValidityMs }`, 0–24 h: for each signed-in OAuth provider, Pi's `getAuth(id, { minOAuthValidityMs })` refreshes a token that expires sooner, under Pi's own credential lock; returns `{ checked, failed }` as provider ids, never tokens), `resources.list/update/prompts.create/prompts.update/prompts.delete`, `extensions.list/respond/palette`, `extensions.config.list/set`, `extensions.packages.install/update/remove` (see `extension-config.js` above), `plugins.configure` (see `plugin-host.js` above), and session list/pendingInput/create/discardDraft/open/messages/rename/delete/tree/navigate/fork/clone/prompt/steer/followUp/sendReceipt/abort/model/thinking/compact operations. `sessions.pendingInput` takes no arguments, is never session-scoped or routed to engines, and returns `{ sessions: [{ sessionId, directory, pending }], sequence, streamEpoch }` for sessions with a non-null summary; `runtime.health` advertises it. Resource lists use opaque IDs and never disclose server paths. Only top-level Pi prompt templates and applicable AGENTS.md sources are editable; package/path resources and skills are browse-only. Prompt-template mutations resolve against the caller's explicit effective directory, reject stale and cross-directory opaque IDs, enforce project trust for project prompts, serialize create/update/delete operations, preserve existing files on validation or write failure, atomically reserve new destinations without overwriting concurrent writers, use temporary-file persistence with cleanup, preserve unknown frontmatter fields (for example `argument-hint`) when editing description or content, and for rename validate the destination name and scope, reject collisions, write the destination atomically, remove the source only after success, and roll back the destination when source removal fails. A committed prompt mutation never disposes a session runtime: affected idle sessions use Pi's identity-preserving `session.reload()`, while streaming, compacting, and extension-command sessions finish first and reload at their next safe lifecycle edge. Global prompts refresh every resident runtime; project prompts refresh only runtimes in that directory. Mutation responses merge freshly discovered editable prompts from transient per-mutation services (never retained; Pi 0.84.1 exposes no dispose on AgentSessionServices/ModelRuntime/ResourceLoader/SettingsManager — file reads plus a cleared create-time timeout, no watchers/intervals/listeners, so dropping the reference lets GC reclaim it) with live package/path/extension resources so the Settings page reflects the committed file even while runtime activation is deferred. `providers.refresh` touches only live runtimes plus the requested directory's runtime (started when it is not resident); the returned catalog comes from that directory's runtime via `providers.list`. Concurrent refreshes share one task per resolved directory, never across directories; refreshes for different directories run one after another so their temporary catalog keys never interleave. Generic non-prompt resource writes share the serialized resource-mutation queue and commit through an atomic replace even while a session is active. The daemon returns `deferred: true` and recreates resident runtimes after they become idle; a new session reads the committed file immediately. If immediate recreation fails after a committed write, the response still reports deferred activation and the daemon keeps the recreation queued for a later safe edge. Project trust changes are persisted in Pi trust.json and use the same deferred runtime recreation; project-local extensions load through Pi's own trust flow once trust is resolved. Provider login submits API keys only across authenticated private IPC or brokers Pi's OAuth/device/manual-code interaction, passing the same `getDeviceId` login option as the Pi CLI (backed by the runtime `SettingsManager.getOrCreateDeviceId()`) because flows such as Sign in with ChatGPT reject logins without a stable installation ID. A failed attempt projects Pi's error message (with its causes, URL query strings stripped so a pasted callback never echoes an authorization code, capped at 500 characters) beside the stable `PROVIDER_AUTH_REQUIRED` code; public projections contain only opaque login IDs, prompts, URLs/device codes, model catalog/configuration, and stable states, never credentials or write-only headers. `providers.models.set` atomically persists Pi's `models.json`; a busy runtime returns `deferred: true` and is rehydrated after all active sessions are idle, while a new session sees the catalog immediately. `providers.models.add` appends one model (`id` required; optional `name`, `reasoning`, `thinkingLevelMap`, `input`, `contextWindow`, and `maxTokens`) atomically without replacing the provider. The model configuration store owns normalization and validation. The daemon rejects duplicate or unavailable live models, seeds a missing file provider only from authoritative live metadata when safely representable, rejects extension registrations with an explicit `models` array, and uses the same deferred recreation as `providers.models.set`. A successful recreation publishes a provider-catalog invalidation so connected settings views load the new authoritative catalog. Provider edits preserve unexposed existing model metadata server-side while public projections remain credential-blind. `providers.list` projects only catalog and authentication-status metadata, including Pi-supported `thinkingLevels` (`null` map entries hidden, `xhigh`/`max` opt-in). Session thinking overrides are clamped to the live model's supported levels. `sessions.list` checks each cwd JSONL header (not the full transcript) so a project with large session logs cannot spend tens of seconds on startup. SDK `SessionManager.list` is not used for that path; `listPiSessionJsonlDirectory` returns cached or incrementally scanned header, first-prompt, and name fields. For a row whose runtime is resident, the list uses `sessionManager.getSessionName()` instead of the disk name, so unflushed renames and clears show immediately. Unpersisted resident sessions are listed too, except the fresh empty session a runtime starts with when it is started only to answer a folder's catalogs (`providers.list`, `resources.list`, `extensions.list`, runtime recreation) with no JSONL to reopen: nobody asked for it, so it stays out of listings until it holds a non-`custom` message (a user prompt, an assistant reply, or anything else that is not an extension's custom message) or a name, since what an extension adds at `session_start` lands in every such session, otherwise every folder switch would add an untitled "Awaiting first prompt" row. Each listed row whose runtime is resident in this daemon (including unpersisted resident sessions) carries `live: { lifecycle, sequence, retry?, runStartedAt?, serverNow }`, sampled synchronously with the current event `sequence` from the same retry/streaming/run-start state as snapshots; rows without a resident runtime carry no `live`, which clients treat as unknown rather than idle. Every Pi row additionally carries `inputState: { pending, sequence }` from the pending-input index (`pending` is `null` when authoritatively nothing is pending, stamped with the same observed sequence as `live`), so every device learns blocked sessions without opening them. Concurrent lists of the same directory share one in-flight result. Concurrent `sessions.open` of the same id share one in-flight runtime create; a duplicate that finishes later disposes itself and returns the registered runtime instead of `SESSION_RUNTIME_CONFLICT`. Full-file JSONL validation stays on open of a chosen session. The browser explicitly selects an existing user-chosen project directory before listing it; the daemon's startup cwd is an internal fallback, not a user-visible default project. Unnamed persisted sessions use their first prompt as a readable list title when available. `sessions.open`, `getSession`, navigate, fork, and clone project the live session's model and thinking level onto the session record, because that is what the next prompt runs on; Pi itself restores both from the branch when it reopens a chat. The last assistant `provider`/`model`/`thinkingLevel` only fills in when the live session reports none. It is not a substitute: after a revert, a failed turn, or a switch nobody has prompted on yet it names a model the session has left, and a client that compared its composer against it would skip the switch and keep sending on the old model. `sessions.open`, navigate, fork, and clone return a tail page bounded by both projected-message count and serialized bytes. `sessions.messages` reads older pages with an opaque before-cursor. A page that starts inside a tool loop repeats the owning user message as a grouping anchor; browser merging deduplicates that overlap. Persisted tool results are indexed across the active branch before paging, so a paged assistant tool call still receives its matching final result. Session selection validates a persisted JSONL path before Pi opens it; inactive mutations are never directed by a browser-supplied path. `sessions.open` first checks a caller-supplied directory through its bounded header list, so an ordinary project-scoped open neither walks every directory in the agent store nor adopts a same-id session from another directory. Directory-less deep links resolve by Pi's `timestamp_<id>.jsonl` filename before broader SDK-list and header-scan fallbacks. Directory-wide JSONL checks on list/create/startup are header-only; full-file validation stays on open of a chosen transcript. Attachment paths originate in the server-local upload map and cross only private IPC into Pi's tool context. Pi may persist or echo those paths in its authoritative JSONL transcript, so every public projection redacts them recursively: session titles/previews, user and assistant text/thinking, tool arguments, errors, snapshots, and live message events never expose the server-local path. Persisted projection first checks for the attachment marker, then redacts matching tokens with a delimiter scan whose work stays linear for large encoded strings and tool payloads. The daemon maps Pi message lifecycle, deltas, tools, queue changes, model/thinking, compaction, interruption state, and session title updates (`session.updated` on create-with-title, first prompt, and rename). Like the Pi CLI, the daemon never persists an auto-title: on the first conversation prompt of an unnamed session it publishes the derived title live without appending `session_info`, and lists derive the same title from the first user prompt. Renames of a resident session call Pi's `session.setSessionName`, which appends `session_info` and emits `session_info_changed` to listeners and extensions; the subscriber publishes the single `session.updated`. Non-resident renames open the file and append, as Pi's session picker does, and publish directly. `session.updated` with `title: ''` means Pi cleared the name; clients fall back to the title derived from the first prompt, and older clients ignore empty titles to canonical events. Session deletion publishes an explicit `session.deleted` event; archive and directory moves keep the id and never publish it. Pi `model_select`, `thinking_level_changed`, and `session_info_changed` events are authoritative for model, thinking, and session-name changes made by extensions, the TUI, or another client. Each thinking change publishes exactly one `session.thinking` with the effective (clamped) level: `applyThinking` publishes only when Pi will not (the level did not change, or the runtime is not yet subscribed during create). The bridge observes Pi provider registration and label writes because Pi 0.84.1 emits no corresponding session events: provider mutations publish a catalog invalidation, and label mutations invalidate the bounded session-tree projection. `ctx.reload()` clears old extension UI state, reloads Pi resources, and invalidates provider/resource/command catalogs. `ctx.shutdown()` disposes only the requesting idle session runtime after its command or turn settles; it never stops the shared daemon or unrelated sessions. Compaction events preserve Pi's manual/threshold/overflow reason, active/retrying/terminal phase, retry timing, redacted failure, compact-and-retry intent, and pre/post token estimates. The latest state is included in `getSession` and reconnect snapshots; after daemon restart, the latest persisted Pi `CompactionEntry` restores completed feedback without treating history as live work. Tool events carry redacted input arguments, cumulative partial-output snapshots, final output, error text, renderer metadata (edit diffs, truncation notes), and server start/end timestamps plus a `serverNow` sample so clients with different clocks can normalize elapsed time. Nested tool execution events carrying a non-empty `parentToolCallId` are skipped because Pi records nested calls on the parent tool result and omits them from transcript messages. Active and recently completed tool parts retain their start timestamps in the daemon's bounded in-memory timing cache, so `getSession` hydration keeps timers consistent across clients and browser reloads until the daemon restarts. Pi loads skills with the ordinary `read` tool. The daemon matches those read paths against the active runtime's authoritative `resourceLoader.getSkills()` catalog and adds path-free `metadata.pichamber.skill.name` for live events, hydrated history, and reconnect snapshots. PiChamber uses that metadata for its compact Skill row and Settings navigation; an arbitrary file named `SKILL.md` remains a normal read. Persisted `toolResult` entries merge into their assistant `toolCall` parts as output/error/end time so hydrated sessions render complete tool cards; tool-result entries never surface as standalone messages. Assistant message projections and start events carry the owning user-message id so the restored turn renderer can group and display replies; all assistant entries in a tool loop and every retry/compaction continuation remain attached to the latest user turn until `agent_settled` closes the run. Assistant message projections also pass through Pi's per-turn `Usage` (input, output, cacheRead, cacheWrite, totalTokens, and the same five numeric cost fields). The daemon sanitizes the raw payload through `projectUsage` before publication: every numeric must be finite and non-negative, the whole object is omitted when any field is missing or wrong type, and unknown keys are never copied. The `assistant.message.end` event carries the same sanitized usage so the last turn updates without waiting for a full `getSession` refetch. The public route whitelist re-applies the same sanitizer on each projection so a stale or malformed payload from a different daemon version cannot surface as `NaN` or `Infinity` in the reducer.- Live `message_start` events use daemon-generated browser message IDs because Pi has not appended the corresponding session entry yet. Pi agent-core emits streaming assistant starts as shallow copies, not as the finalized object it later persists. At `message_end`, `message-entry-aliases.js` therefore rebinds the synthetic ID to the finalized event object, then maps that object by identity to Pi's appended entry in a microtask. `sessions.navigate` and `sessions.fork` resolve the mapping after stripping any part suffix. Alias keys include cwd and session ID, survive idle runtime disposal of persisted sessions, and clear on explicit session deletion, confirmed ephemeral expiration (which publishes `session.deleted`), or daemon shutdown. Hydrated message projections continue to use the Pi entry ID directly.
|
|
73
80
|
- Each event and reconnect snapshot has a monotonic sequence. Replay is capability-negotiated: the subscriber stamps its cursor with the `streamEpoch` it was established under, a marker-less cursor fails as `DAEMON_PROTOCOL_MISMATCH`, and a cursor from a retired epoch resyncs from a snapshot instead of replaying — even when this daemon's sequence numerically overtook the old cursor, replaying from it would silently skip the head of the new space. Every event, snapshot, and health result carries an opaque random `streamEpoch` regenerated on every daemon process start (never derived from daemon id, profile key, pid, or any private identity); `runtime.health` advertises the `events.streamEpoch` capability, session reads stamp it so clients can reject stale-epoch responses, and a snapshot published because the cursor could not be replayed is additionally stamped `resync: true` as a recovery baseline. A reconnect replays the retained contiguous suffix after its cursor when available, otherwise it receives an authoritative `session.snapshot`; unavailable runtimes are not represented as empty sessions. The suffix lives in `session-replay.js` and is bounded by both count (1,024 events) and encoded wire bytes (8 MiB): eviction removes whole oldest events first and never truncates content, each event is serialized once and the cached line is reused for live broadcast and replay, and live delivery stays full-fidelity even for events too large to retain. The byte budget counts encoded wire bytes, not heap, and snapshots assign sequence numbers without replay insertion so numeric gaps from private snapshots are intentional. A single oversized event clears the retained suffix without being retained, an empty ring never replays, and a cursor beyond the latest sequence resynchronizes from a snapshot; contiguity is judged on the global suffix while delivery stays session-filtered, so a filtered client never replays through a gap. A missed suffix recovers through `session.snapshot` plus `sessions.open` hydrate, which re-reads persisted entries for tool finals and lifecycle.
|
|
74
81
|
- Prompt, steer, and follow-up requests acknowledge acceptance only after the Pi SDK preflight signal (`session.prompt` with `preflightResult(disposition)` where `disposition` is `'started'`, `'queued'`, or `'handled'`); the daemon owns the still-running turn promise and publishes any asynchronous rejection as `session.error`. A preflight rejection (`session.prompt` promise rejecting without calling `preflightResult`) propagates as the request rejection so dedup never caches it as accepted and the operation id stays reusable. Plain text uses prompt() with expandPromptTemplates:false and source:extension plus images; slash input keeps source:rpc. Pi can emit the live user-message start before that message is branch-readable, so the daemon queues each accepted prompt's path-free file metadata per delivery kind (`prompt`/`steer`/`followUp`) and adds it to the matching user start. SDK `queue_update` shrink is the authoritative owner of the next user start (steering drains before followUp regardless of send order); direct starts emit no shrink and fall back to oldest-by-generation. Requested `steer`/`followUp` always travels as SDK `streamingBehavior` (ignored while idle) so an idle arrival that races another sender still queues. Retention is decided at resolution from the SDK preflight disposition: `'queued'` keeps the metadata, `'handled'` and registered extension commands never do, and `'started'` keeps it only while the session is still streaming; only queued resolutions keep metadata until their per-delivery start, all other completions clean a still-pending entry (an extension command that never emits a user start). The browser can render the attachment footer immediately without exposing bytes or server paths, while later hydration remains authoritative. An extension command may resolve without starting an agent turn, so completion of its non-streaming prompt promise publishes the idle lifecycle boundary that Pi does not emit as `agent_settled`. Pi notifies extensions of model switches (`model_select`) but not session subscribers, so that same completion edge also reconciles a changed live model into `session.model` before the idle boundary; thinking already emits `thinking_level_changed` to subscribers and needs no reconciliation. A registered extension invocation is not used for automatic first-prompt naming: an extension-only empty session remains unnamed unless the extension names it, and the first later conversation prompt supplies the derived title. Classification uses the active Pi runtime's registered extension commands, not a browser claim. Manual compact requests likewise acknowledge startup instead of holding the public/private request open for the summarization call; the daemon-owned promise reports its outcome through `session.compaction`. A second compact request while Pi is compacting fails as `SESSION_BUSY`, and optional `/compact` instructions pass to `AgentSession.compact(customInstructions)`. A later prompt on the same session invalidates an older send rejection so it cannot error the new turn. If the rejected send left Pi streaming, the daemon aborts it. Steer/follow-up against an idle session starts a new prompt instead of `SESSION_NOT_RUNNING`. A registered extension command running without an agent turn (waiting on `custom()`, a dialog, or its own work) keeps the session busy, as Pi's interactive mode holds input until the command returns: the daemon publishes `session.lifecycle: busy` with `command: '/name'` when it dispatches, snapshots, `getSession`, and list live status report the same, and prompt, steer, and follow-up fail as `SESSION_BUSY` until it returns, because the SDK would start a second run beside the command (steering only queues behind a streaming turn). While the command's own agent turn streams, input behaves normally; when that turn settles and the command still runs, the busy frame with `command` is published again instead of idle, and the settled turn neither completes a requested shutdown nor re-arms idle disposal. A command that returns or throws publishes idle from its own settlement, whatever the send generation (a steer into the command's turn moves it on), unless a turn still streams, whose `agent_settled` then publishes idle. `!cmd` (`sessions.bash`) and `sessions.compact` are refused the same way. The busy check runs again after the model and attachment awaits, so two clients cannot both start beside a command. Command detection follows Pi's `_tryExecuteExtensionCommand`: the text (with appended attachment notes) must start with `/`, and the name up to the first space must match a registered `invocationName` exactly. Agent and compaction completion are never held behind the 30-second public/private request budgets. Pi retryable provider failures remain live: an `agent_end` with `willRetry` does not publish terminal `session.error`, and `auto_retry_start` projects Pi's attempt, next-attempt time, and redacted error text through `session.lifecycle: retry`. Retry metadata is retained in reconnect and `getSession` snapshots until the next `agent_start` begins the attempt. `agent_settled` remains the authoritative idle boundary after retry success, exhaustion, or cancellation and clears the run's user/assistant ownership.
|
|
75
82
|
- Send-intent deduplication (`send-operation-registry.js`) owns the authoritative execution boundary for prompt/steer/followUp: the client labels each intent with a stable `operationId` and the health-verified `streamEpoch`, the daemon claims `kind + sessionId + operationId + streamEpoch` BEFORE Pi activation, and an identical same-epoch retry returns the original acceptance receipt (`{ accepted, messageId, deduplicated: true }`) without invoking Pi again. A concurrent duplicate of a still-pending intent shares the original outcome; the same full key with a different payload (text, model, thinking, message id, or attachments) fails as `OPERATION_PAYLOAD_MISMATCH` (HTTP 409). An intent from another daemon lifetime fails as `STALE_STREAM_EPOCH` (HTTP 409) before Pi or attachment-consumption side effects. The same id on a different kind or session is a different intent and executes independently, never a mismatch. Only acceptances are retained: request-path rejections happen before Pi runs (nothing executed, id reusable) while pending duplicates still share the original rejection, and every claim settles so pending duplicates never hang. Retention is bounded: receipts expire after `sendOperationTtlMs` (default ten minutes) and at most 1,024 accepted receipts are retained (oldest evicted to a bounded expired tombstone); pending claims are bounded separately (256 entries, never expired while active, new distinct pending past the bound fails as `SESSION_BUSY`). An expired or evicted id reports `expired` and a retry with the same id fails as `OPERATION_EXPIRED` (HTTP 410), never an automatic re-execution — callers must use a new operation id. `sessions.sendReceipt` is the exact read-only receipt lookup for an uncertain send: it requires the full `kind + sessionId + operationId + streamEpoch` identity; a missing epoch returns `unknown`, never invokes Pi, and returns `accepted` (retained receipt), `pending`, `expired` (seen but retention gone, outcome unknown, never assume success), or `unknown` (never seen in this retention window, tombstone pressure, post-restart, or rejected before Pi ran). The registry is in-memory per daemon process with bounded tombstones (`expired` degrades to `unknown` under pressure): there is no lifetime receipt guarantee, only within the retention window. A restart loses receipts, but the replacement daemon rejects the retired epoch instead of replaying the old intent. Receipt lookup and replay protection remain separate read-only contracts.
|
|
@@ -90,6 +97,19 @@ An engine implements `id` (lowercase alphanumeric/hyphen, never `'pi'`), optiona
|
|
|
90
97
|
|
|
91
98
|
Routing is ownership-first: a command in the engine command set (open/messages/rename/delete/tree/navigate/fork/clone/prompt/steer/followUp/abort/setModel/setThinking/compact) with an explicit `sessionId` dispatches to the first owning engine in registration order and skips the Pi idle guard entirely; unowned sessions fall through unchanged, and Pi's default-to-active-session fallback never selects an engine. `extensions.draft` on an engine-owned session fails as `ENGINE_UNSUPPORTED_OPERATION` without touching Pi. Draft sessions are Pi-native: a `sessions.create` with `draft: true` or `draftSessionId` that would route to an engine fails as `ENGINE_UNSUPPORTED_OPERATION` and creates nothing; `sessions.discardDraft` is never routed. Creation targets an engine via explicit `engine` (`'pi'` forces Pi, unknown ids fail as `INVALID_ARGUMENT` even with zero engines) or via an owned `model.providerId`, stamping `session.engine` on the detail. An engine without a `sessions.create` handler cannot be a create target: an explicit id fails as `ENGINE_UNSUPPORTED_OPERATION` while provider routing skips it and falls back to Pi. Prompt-family commands run through the same send-dedup boundary, so operation ids, receipts, `STALE_STREAM_EPOCH`, and `OPERATION_PAYLOAD_MISMATCH` behave identically and `sessions.sendReceipt` works unchanged; a result without a `messageId` fails as `MALFORMED_DAEMON_RESPONSE`. `engines.list` returns `{ engines: [{ id, label, commands }] }` (`{ engines: [] }` with zero engines) and `runtime.health` advertises `engines.list`; `GET /api/pi/engines` projects the same shape through a whitelisting projector and maps daemon errors without returning an empty list. Listings append engine rows (tagged `session.engine`, directory forced) after Pi rows and engine providers after Pi providers, skipping id collisions (a collision marks that engine failed); `incompleteEngines` names failed engines and appears only when non-empty. Failure is never empty success: a throwing, timed-out (10s default), or malformed engine listing drops all that engine's rows, and the current browser catalog does not yet act on `incompleteEngines`, so a UI that renders engine sessions must treat such a listing as non-authoritative for those engines before relying on destructive cleanup. Each listing call receives an AbortSignal aborted when its per-engine timeout fires, and concurrent `listSessions` calls for one directory (plus concurrent `listProviders` calls) share one in-flight result that clears on settle; failures are never cached. All engine output (event payloads, detail/command results, list and provider rows, snapshot fields) is redacted in core with `redactAttachmentValues`, so an echoed server-local attachment path never reaches the wire; the registry and router refuse to build without a redactor. Snapshots for engine sessions come from sync `engine.snapshot()` framed with daemon-owned sequence/`lastSequence`/epoch/`sessionId`/`directory` using the snapshot's own absolute directory; a throw logs and writes nothing, and a non-object/undefined/missing-directory result returns nothing, like an unavailable Pi session. Registry creation awaits factories in order (a throwing factory is logged and skipped; a duplicate/invalid id/label/shape disposes already-created engines and throws `INVALID_ENGINE`), ownership-check throws count as not owned, and `stop()` disposes every engine (AggregateError on failure, mirroring the runtime registry) without blocking remaining teardown. Logging records only engine id, short event name, and stable error code, never messages, payloads, credentials, or paths. Extension, resource, settings, and provider-auth commands stay Pi-only. Pending-input contract: engines MAY carry `inputState: { pending }` on list rows, snapshot fields, and detail results, where `pending` is `{ count, kind, since }` (`count` an integer 1..99, `kind` `'input'` or `'approval'` with `'approval'` marking a permission-style request, `since` epoch ms of the oldest open request) or `null` when authoritatively nothing is pending; a missing or malformed value falls back to the daemon index without failing the row. Engines MUST publish `session.input { pending }` on every pending-input transition for live updates: the daemon normalizes the summary, folds it into the pending-input index (hosted requests win when both exist), republishes it canonically as `{ pending, serverNow }`, rejects a malformed summary as `INVALID_ARGUMENT`, and rejects a summary for a session the publishing engine does not own as `INVALID_ARGUMENT` without applying it (a throwing ownership check counts as not owned); an engine `session.deleted` also clears that engine's index state. Engine notifications are live-only: engines publish `extension.notify { message, level }` through the host wrapper; the daemon normalizes the level (`'info'` unless `'warning'`/`'error'`), caps the message at 2000 characters, and publishes through the usual redaction. An empty message is a silent no-op. Nothing is stored, so engine snapshots and details carry no notice history. `session-engine-router.js` owns the dispatch, create targeting, merges, snapshot payloads, publish wrapper, and `engines.list` description behind dependency injection; `session-daemon.js` keeps one-guard call sites.
|
|
92
99
|
|
|
100
|
+
## Sandbox launchers
|
|
101
|
+
|
|
102
|
+
A sandboxed project runs its sessions in a separate daemon started through a launcher (#242). `../sandbox/` owns everything else about it, documented in `../sandbox/DOCUMENTATION.md`: the launcher seam, the nono launcher and profile, the per-project setting, the manager, its routes, switching, staleness, OAuth, and trust reset. This section covers the daemon side. Only Pi session daemons (the agent) run in the sandbox. PiChamber's own Git panel, terminal, browser and GitHub features, and worktree hooks and start commands, run outside it with the user's access, so git config, hooks or filters an agent writes into the repo can run when the user or the Git panel runs git. This is a known, accepted trade-off. With no sandboxed project, `createPiSessionDaemonSupervisor` without `launch` spawns exactly the command it always did.
|
|
103
|
+
|
|
104
|
+
- Identity and profile key. `identity` hashes the launcher id, its probed version, the hash of its policy file, the grants, and the network. The sandbox daemon's profile key is `<server profile key>-sbx-<project key>-<identity>`, where the project key is a hash of the project root. A change to any input starts a new daemon; the same inputs reuse the running one through the normal reuse path. The daemon's own profile folder (read-write) and runtime folder (socket bind) derive from that key, so the supervisor adds them to the grants after hashing. The runtime folder is named `sbx-<first 16 hex of sha256(profile key)>` rather than the full key, so the socket path fits macOS's shorter address limit.
|
|
105
|
+
- Liveness and stop. The sandbox can write the daemon's profile folder, so its state sidecar and `runtime.health` answer can be forged. The supervisor never signals a pid from them, and reads the sidecar only as a small regular file (no symlink, no FIFO). The credential it sends on every request is kept in the launcher folder, which the sandbox can read one file of and write nothing in; the daemon's environment carries none of the server's own `PICHAMBER_*` variables but the data and agent folders. Known limit: after a server crash, a sandbox daemon whose grants then change (a worktree added, a host changed) has a different profile key, so the next server never finds its record and it keeps running with its old grants until it exits; a graceful shutdown stops every daemon. After spawning a launcher daemon, it records the launcher's `child.pid` with an identity (Linux: start time from `/proc/<pid>/stat`, zombies count as gone; macOS: `ps` state and start time, one-second resolution; elsewhere none, so no record) and the owning `serverInstanceId` in `<dataDir>/pi/launchers/<profileKey>/launcher.json`. The operation lock for a launcher daemon is `operation.lock` in that folder. No sandbox grant covers it, and the daemon never touches the lock. If the record cannot be written, the launcher gets SIGTERM and the start fails with `DAEMON_LAUNCHER_RECORD_FAILED`. A claim on reuse rewrites the record's owner. Stop with a record: the record's owner must be this server instance (otherwise `DAEMON_OWNERSHIP_MISMATCH`). The supervisor then asks for `runtime.shutdown` where the sidecar allows it; a missing, forged or refused answer does not block the stop. It sends SIGTERM to the recorded pid only while its identity still matches, waits for that process to exit (`DAEMON_STOP_TIMEOUT` otherwise), and removes the record. A pid now held by another process is not signaled. Stop without a record (a daemon started before records existed) signals nothing and only waits for the sidecar pid to exit. Under `nono run` (0.82.0), the launcher is nono's supervisor process. It forwards SIGTERM to the daemon and exits after it. The daemon stays in nono's process group, because it has no terminal and nono makes no new session for it. The group is not signaled: the daemon would get SIGTERM twice, and its one-shot handler would let the second kill it mid-shutdown. On Linux nono's network-mediated path also sets `PR_SET_PDEATHSIG` (SIGKILL) on the daemon; its plain fork path does not, so a SIGKILL to nono there would orphan the daemon. Sidecar pids are still read for liveness only, where a lie hurts nothing but that sandbox's own availability: refusing a start (`DAEMON_UNAVAILABLE`), the stale-endpoint check (which unlinks only the socket inside its own runtime folder), stale-sidecar removal in its own profile folder, and the `runtime.health` identity match. A start also refuses while a recorded launcher is still running. The start-timeout signal goes to the `child.pid` just spawned. Test: `supervisor-launcher-stop.test.js`.
|
|
106
|
+
- Fail closed. `createSandboxedPiSessionDaemonSupervisor` probes first. When the launcher cannot sandbox, it throws `SANDBOX_UNAVAILABLE` with the probe's `reason` and spawns nothing. It also refuses `SANDBOX_ENDPOINT_TOO_LONG` when the sandbox socket path would not fit a Unix socket address (107 usable bytes on Linux, 103 on macOS), because the daemon's listen would fail with `EINVAL` and exit without a state sidecar. A grant or network that fails validation, or a launcher `prepare` error, surfaces as that error's code and spawns nothing. The shared `PICHAMBER_PI_SESSION_DAEMON_ENDPOINT` override never applies to a sandbox daemon.
|
|
107
|
+
- Tests. `../sandbox/nono-launcher.test.js` maps a fake nono's answers to each probe code. `supervisor-sandbox.test.js` injects `spawn` and asserts the exact nono command, flags, environment, profile file, shadow links, profile-key reuse and change, refusals, and fail-closed probe. `supervisor-sandbox-nono.e2e.test.js` runs a real turn whose bash tool checks what it can touch under real nono; it skips itself when the nono probe fails (Linux CI and the development container have no Landlock), so run it on a Landlock machine before a release. `.github/workflows/sandbox-macos.yml` runs it on macOS with `PICHAMBER_REQUIRE_NONO_E2E=1`, which turns the skip into a failure.
|
|
108
|
+
- Session leases across the boundary. A lease file name hashes the agent folder, the cwd, and the session id. A sandbox daemon's `--agent-dir` is the shadow, so the supervisor also passes `--lease-agent-dir <real agent folder>` (`prepareProjectSandbox` returns it as `leaseAgentDir`) and `createSessionDaemon({ leaseAgentDir })` keys leases on it. The main daemon and a sandbox daemon then compute the same lease file and exclude each other on one session.
|
|
109
|
+
- Events. A sandbox daemon joins the merged `/api/pi/events` stream when it starts (the manager re-registers it, so the pool's `onChange` subscribes it) and leaves when it stops idle or is turned off; its frames carry its `stream` id. A session read routed by its transcript is stamped with the stream of the daemon that served it, not the request's (absent) directory.
|
|
110
|
+
- Sandboxed folders (`createSessionDaemon({ isSandboxedDirectory })`, default: none). `daemon-process.js` sets it from `--sandboxed-folders-file`, which the supervisor passes only to a daemon started without a launcher (the main daemon). Every runtime creation (`startRuntime`, `sessions.open` of a persisted session, `sessions.create`) refuses such a folder with `DIRECTORY_SANDBOXED`. `defaultDirectory()` replaces the active folder with one outside every sandbox while the active folder is sandboxed, and catalog reads that name a sandboxed folder use the same folder (`outsideSandbox`). See `../sandbox/DOCUMENTATION.md`. Test: `session-daemon.test.js` ("never starts a runtime in a folder a sandbox daemon owns").
|
|
111
|
+
- Read-only reads (`sessions.readPersisted`). Given `sessionId` and an optional `directory`, `before`, and `limit`, the daemon finds the session's JSONL like `sessions.open` does and parses it with Pi's `parseSessionEntries` into `SessionManager.inMemory` (no persistence). It then projects messages and pages exactly like `sessions.open` / `sessions.messages`. It starts no Pi runtime, extension, or tool, takes no lease, and writes nothing, including no trust decision for the folder it reads from. Pi's file loader can append a newline to repair a file; this path does not use it. The result is `readOnly: true`, idle, `isStreaming: false`, and `lastSequence: -1`, with no `streamEpoch`, `inputState`, extension state, or bash executions. The sandbox manager uses it on the main daemon while a project's sandbox cannot start. Test: `session-daemon-read-persisted.test.js`.
|
|
112
|
+
|
|
93
113
|
## Deliberate limits
|
|
94
114
|
|
|
95
115
|
This module defines the authenticated session API boundary consumed by the Pi-native session UI. Session leases coordinate PiChamber daemons only: the standalone `pi` CLI runs its own foreground runtime and does not honor these leases, so concurrently editing the same session through PiChamber and `pi` remains unsupported until Pi provides compatible upstream locking. Resource configuration and richer attachment extraction remain owned by their dedicated workstreams. The session event stream is SSE over the existing authenticated runtime transport; WebSocket callers fall back to it, preserving direct and relay behavior without a second daemon listener. The public route emits named heartbeat events so native `EventSource` clients can detect a silent foreground connection, reconnect, and resume from their last accepted sequence.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
|
|
4
|
+
export const MAIN_DAEMON_KEY = 'main';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Public, opaque id of a daemon's event stream. Pool keys may be server
|
|
8
|
+
* paths, which never leave the server; a project daemon's id is a stable
|
|
9
|
+
* 16-character hash so a resume cursor stays valid across PiChamber
|
|
10
|
+
* restarts. The main daemon's id is `main`: frames and responses from it
|
|
11
|
+
* carry no id at all, and `main` only appears where a value from the main
|
|
12
|
+
* daemon sits inside a project daemon's response (a draining list row).
|
|
13
|
+
*/
|
|
14
|
+
export const publicDaemonStreamId = (key) => (key === MAIN_DAEMON_KEY ? MAIN_DAEMON_KEY : hashDaemonKey(key));
|
|
15
|
+
|
|
16
|
+
const hashDaemonKey = (key) => createHash('sha256').update(`pichamber-daemon:${key}`).digest('base64url').slice(0, 16);
|
|
17
|
+
|
|
18
|
+
const normalizeDirectory = (directory) => (
|
|
19
|
+
typeof directory === 'string' && directory.length > 0 && path.isAbsolute(directory)
|
|
20
|
+
? path.resolve(directory)
|
|
21
|
+
: null
|
|
22
|
+
);
|
|
23
|
+
|
|
24
|
+
const contains = (root, directory) => directory === root
|
|
25
|
+
|| directory.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The session daemons this server talks to: the main daemon (the
|
|
29
|
+
* supervisor's runtime, always present once started) plus zero or more
|
|
30
|
+
* project daemons, each keyed by project and owning that project's root and
|
|
31
|
+
* worktree roots. Routes ask the pool which daemon owns a directory;
|
|
32
|
+
* anything outside every project daemon belongs to the main daemon.
|
|
33
|
+
*
|
|
34
|
+
* Draining: while a project switches daemons, the old daemon keeps live
|
|
35
|
+
* state for sessions still finishing a turn there. `setDraining` names the
|
|
36
|
+
* daemons whose live state is merged into that directory's session list.
|
|
37
|
+
*/
|
|
38
|
+
export const createPiDaemonPool = ({ getMainRuntime }) => {
|
|
39
|
+
const projects = new Map();
|
|
40
|
+
const draining = new Map();
|
|
41
|
+
const listeners = new Set();
|
|
42
|
+
const moveListeners = new Set();
|
|
43
|
+
|
|
44
|
+
const notify = () => {
|
|
45
|
+
for (const listener of [...listeners]) {
|
|
46
|
+
try {
|
|
47
|
+
listener();
|
|
48
|
+
} catch (error) {
|
|
49
|
+
console.warn('[pi] daemon pool listener failed', error?.code ?? error);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
const runtimeFor = (key) => (key === MAIN_DAEMON_KEY ? getMainRuntime() ?? null : projects.get(key)?.runtime ?? null);
|
|
55
|
+
|
|
56
|
+
const ownerKey = (directory) => {
|
|
57
|
+
const normalized = normalizeDirectory(directory);
|
|
58
|
+
if (!normalized) return MAIN_DAEMON_KEY;
|
|
59
|
+
let best = null;
|
|
60
|
+
let bestLength = -1;
|
|
61
|
+
for (const [key, entry] of projects) {
|
|
62
|
+
for (const root of entry.directories) {
|
|
63
|
+
if (root.length > bestLength && contains(root, normalized)) {
|
|
64
|
+
best = key;
|
|
65
|
+
bestLength = root.length;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
return best ?? MAIN_DAEMON_KEY;
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
return {
|
|
73
|
+
/** The main daemon's runtime, or null before it exists. */
|
|
74
|
+
main: () => getMainRuntime() ?? null,
|
|
75
|
+
/** The runtime owning `directory` (project root or worktree root, or any
|
|
76
|
+
* folder inside one); the main daemon when no project daemon owns it. */
|
|
77
|
+
forDirectory: (directory) => runtimeFor(ownerKey(directory)),
|
|
78
|
+
/** Daemons (`{ key, runtime }`) whose live state merges into
|
|
79
|
+
* `directory`'s session list while a switch drains. Never includes the
|
|
80
|
+
* owner. */
|
|
81
|
+
drainingFor: (directory) => {
|
|
82
|
+
const owner = ownerKey(directory);
|
|
83
|
+
const normalized = normalizeDirectory(directory);
|
|
84
|
+
if (!normalized) return [];
|
|
85
|
+
const keys = new Set();
|
|
86
|
+
for (const [root, rootKeys] of draining) {
|
|
87
|
+
if (!contains(root, normalized)) continue;
|
|
88
|
+
for (const key of rootKeys) if (key !== owner) keys.add(key);
|
|
89
|
+
}
|
|
90
|
+
return [...keys].map((key) => ({ key, runtime: runtimeFor(key) })).filter((item) => item.runtime);
|
|
91
|
+
},
|
|
92
|
+
/** Public stream id of the daemon owning `directory`, or undefined for
|
|
93
|
+
* the main daemon (whose responses and frames carry none). */
|
|
94
|
+
streamFor: (directory) => {
|
|
95
|
+
const key = ownerKey(directory);
|
|
96
|
+
return key === MAIN_DAEMON_KEY ? undefined : publicDaemonStreamId(key);
|
|
97
|
+
},
|
|
98
|
+
/** Every daemon that is running, main first. */
|
|
99
|
+
live: () => {
|
|
100
|
+
const result = [];
|
|
101
|
+
const main = getMainRuntime();
|
|
102
|
+
if (main) result.push({ key: MAIN_DAEMON_KEY, runtime: main });
|
|
103
|
+
// A project runtime whose daemon is not running (`isLive()` false)
|
|
104
|
+
// is left out: fan-out never starts a daemon.
|
|
105
|
+
for (const [key, entry] of projects) {
|
|
106
|
+
if (entry.runtime.isLive?.() === false) continue;
|
|
107
|
+
result.push({ key, runtime: entry.runtime });
|
|
108
|
+
}
|
|
109
|
+
return result;
|
|
110
|
+
},
|
|
111
|
+
register: (key, { runtime, directories }) => {
|
|
112
|
+
if (typeof key !== 'string' || key.length === 0 || key === MAIN_DAEMON_KEY) throw new TypeError('Invalid daemon key');
|
|
113
|
+
if (!runtime || typeof runtime.request !== 'function') throw new TypeError('Invalid daemon runtime');
|
|
114
|
+
// An empty list owns nothing: a daemon kept only to finish sessions
|
|
115
|
+
// while a switch drains (see `setDraining`).
|
|
116
|
+
const roots = (directories ?? []).map(normalizeDirectory);
|
|
117
|
+
if (roots.some((root) => root === null)) throw new TypeError('Invalid daemon directories');
|
|
118
|
+
projects.set(key, { runtime, directories: roots });
|
|
119
|
+
notify();
|
|
120
|
+
},
|
|
121
|
+
/** Remove `key`; with `runtime`, only while the key still holds it. */
|
|
122
|
+
unregister: (key, runtime) => {
|
|
123
|
+
if (runtime && projects.get(key)?.runtime !== runtime) return;
|
|
124
|
+
if (projects.delete(key)) notify();
|
|
125
|
+
},
|
|
126
|
+
/** Name the daemons still holding live sessions for `directory`; an
|
|
127
|
+
* empty list ends the drain. */
|
|
128
|
+
setDraining: (directory, keys) => {
|
|
129
|
+
const normalized = normalizeDirectory(directory);
|
|
130
|
+
if (!normalized) throw new TypeError('Invalid directory');
|
|
131
|
+
if (!Array.isArray(keys) || keys.length === 0) draining.delete(normalized);
|
|
132
|
+
else draining.set(normalized, [...new Set(keys)]);
|
|
133
|
+
},
|
|
134
|
+
/** Tell event stream subscribers that a session's live owner changed
|
|
135
|
+
* (for example a switch disposed it in one daemon), so clients refetch
|
|
136
|
+
* it from its new owner. */
|
|
137
|
+
announceMove: (sessionId, directory) => {
|
|
138
|
+
if (typeof sessionId !== 'string' || sessionId.length === 0 || !normalizeDirectory(directory)) return;
|
|
139
|
+
for (const listener of [...moveListeners]) {
|
|
140
|
+
try {
|
|
141
|
+
listener(sessionId, directory);
|
|
142
|
+
} catch (error) {
|
|
143
|
+
console.warn('[pi] daemon pool move listener failed', error?.code ?? error);
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
},
|
|
147
|
+
onMove: (listener) => {
|
|
148
|
+
moveListeners.add(listener);
|
|
149
|
+
return () => moveListeners.delete(listener);
|
|
150
|
+
},
|
|
151
|
+
/** Called when a daemon is registered, replaced, or unregistered. */
|
|
152
|
+
onChange: (listener) => {
|
|
153
|
+
listeners.add(listener);
|
|
154
|
+
return () => listeners.delete(listener);
|
|
155
|
+
},
|
|
156
|
+
};
|
|
157
|
+
};
|
|
@@ -4,6 +4,7 @@ import { dirname } from 'node:path';
|
|
|
4
4
|
import { fileURLToPath } from 'node:url';
|
|
5
5
|
|
|
6
6
|
import { createSessionDaemon } from './session-daemon.js';
|
|
7
|
+
import { createSandboxedFoldersReader } from '../sandbox/sandboxed-folders.js';
|
|
7
8
|
import { ensureOpenUrlBrowser, watchOpenUrlBrowser } from '../../open-url/browser-env.js';
|
|
8
9
|
import { sessionEngineFactories } from './engines/index.js';
|
|
9
10
|
|
|
@@ -19,6 +20,8 @@ const credentialFile = argument('--credential-file');
|
|
|
19
20
|
const stateFile = argument('--state-file');
|
|
20
21
|
const cwd = argument('--cwd');
|
|
21
22
|
const agentDir = argument('--agent-dir');
|
|
23
|
+
const leaseAgentDir = argument('--lease-agent-dir');
|
|
24
|
+
const leaseScope = argument('--lease-scope');
|
|
22
25
|
const profileKey = argument('--profile-key');
|
|
23
26
|
const serverInstanceId = argument('--server-instance-id');
|
|
24
27
|
const serverPid = Number(argument('--server-pid'));
|
|
@@ -26,6 +29,7 @@ const daemonId = argument('--daemon-id');
|
|
|
26
29
|
const daemonRuntime = argument('--runtime');
|
|
27
30
|
const buildId = argument('--build-id');
|
|
28
31
|
const openUrlSocket = argument('--open-url-socket');
|
|
32
|
+
const sandboxedFoldersFile = argument('--sandboxed-folders-file');
|
|
29
33
|
const startedAt = new Date().toISOString();
|
|
30
34
|
|
|
31
35
|
// Pi's built-in MCP extension resolves mcp.json, mcp-auth.json, and mcp.log
|
|
@@ -117,7 +121,7 @@ if (!endpoint || !credentialFile || !stateFile || !cwd || !profileKey || !server
|
|
|
117
121
|
// open the way they did before. The watchdog reinstalls the launcher if its
|
|
118
122
|
// directory is cleaned away while the daemon runs.
|
|
119
123
|
if (openUrlSocket) {
|
|
120
|
-
const openUrlOptions = { socketPath: openUrlSocket, privateDir: dirname(
|
|
124
|
+
const openUrlOptions = { socketPath: openUrlSocket, privateDir: dirname(stateFile), tmpdir: os.tmpdir() };
|
|
121
125
|
await ensureOpenUrlBrowser(openUrlOptions);
|
|
122
126
|
watchOpenUrlBrowser(openUrlOptions);
|
|
123
127
|
}
|
|
@@ -128,6 +132,8 @@ if (!endpoint || !credentialFile || !stateFile || !cwd || !profileKey || !server
|
|
|
128
132
|
credential,
|
|
129
133
|
cwd,
|
|
130
134
|
...(agentDir ? { agentDir } : {}),
|
|
135
|
+
...(leaseAgentDir ? { leaseAgentDir } : {}),
|
|
136
|
+
...(leaseScope ? { leaseScope } : {}),
|
|
131
137
|
engines: sessionEngineFactories,
|
|
132
138
|
profileKey,
|
|
133
139
|
serverInstanceId,
|
|
@@ -136,6 +142,9 @@ if (!endpoint || !credentialFile || !stateFile || !cwd || !profileKey || !server
|
|
|
136
142
|
daemonRuntime: daemonRuntime || 'web',
|
|
137
143
|
buildId: buildId || 'unknown',
|
|
138
144
|
healthMetadata: { daemonPid: process.pid },
|
|
145
|
+
// Only the main daemon is started with the list of folders that
|
|
146
|
+
// sandbox daemons own; it never starts a runtime in one.
|
|
147
|
+
...(sandboxedFoldersFile ? { isSandboxedDirectory: createSandboxedFoldersReader({ file: sandboxedFoldersFile }) } : {}),
|
|
139
148
|
onOwnershipClaim: ({ serverInstanceId: nextServerInstanceId, serverPid: nextServerPid }) => writeReadyState({
|
|
140
149
|
ownerServerInstanceId: nextServerInstanceId,
|
|
141
150
|
ownerServerPid: nextServerPid,
|