pi-pocket 0.0.0-stage → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (369) hide show
  1. package/AGENTS.md +14 -0
  2. package/CONTRIBUTING.md +22 -0
  3. package/LICENSE +21 -0
  4. package/README.md +119 -2
  5. package/SECURITY.md +23 -0
  6. package/bin/pi-pocket.js +27 -0
  7. package/bin/strip-types.js +62 -0
  8. package/contrib/systemd/pi-pocket@.service +38 -0
  9. package/docs/architecture.md +306 -0
  10. package/docs/customizing.md +134 -0
  11. package/docs/design/design-mode.md +108 -0
  12. package/docs/design/docs-site.md +183 -0
  13. package/docs/design/notes-a.md +106 -0
  14. package/docs/design/notes-b.md +123 -0
  15. package/docs/design/notes-c.md +92 -0
  16. package/docs/design/notes-d.md +78 -0
  17. package/docs/design/rate-limit-wait.md +204 -0
  18. package/docs/design/release-notes-design.md +46 -0
  19. package/docs/design/theming.md +256 -0
  20. package/docs/docker.md +93 -0
  21. package/docs/examples/clock.ts +100 -0
  22. package/docs/examples/my-words.ts +39 -0
  23. package/docs/examples/no-force-push.ts +38 -0
  24. package/docs/examples/read-page.ts +86 -0
  25. package/docs/examples/server-status.js +106 -0
  26. package/docs/examples/server-status.ts +35 -0
  27. package/docs/extensions/app.md +37 -0
  28. package/docs/extensions/browser-modules.md +228 -0
  29. package/docs/extensions/built-in.md +23 -0
  30. package/docs/extensions/cleanups.md +33 -0
  31. package/docs/extensions/commands.md +85 -0
  32. package/docs/extensions/events.md +47 -0
  33. package/docs/extensions/first-extension.md +109 -0
  34. package/docs/extensions/hooks.md +52 -0
  35. package/docs/extensions/host.md +59 -0
  36. package/docs/extensions/linked-sessions.md +78 -0
  37. package/docs/extensions/modules.md +50 -0
  38. package/docs/extensions/people-values.md +186 -0
  39. package/docs/extensions/policies/api-stability.md +288 -0
  40. package/docs/extensions/policies/core-or-extension.md +135 -0
  41. package/docs/extensions/policies/gallery-review.md +154 -0
  42. package/docs/extensions/policies/index.md +24 -0
  43. package/docs/extensions/policies/security-model.md +183 -0
  44. package/docs/extensions/prompt-sections.md +39 -0
  45. package/docs/extensions/public-pages.md +91 -0
  46. package/docs/extensions/publishing.md +73 -0
  47. package/docs/extensions/reference/api-versions.md +87 -0
  48. package/docs/extensions/reference/command-context.md +147 -0
  49. package/docs/extensions/reference/gallery-entry.md +351 -0
  50. package/docs/extensions/reference/glossary.md +326 -0
  51. package/docs/extensions/reference/host.md +692 -0
  52. package/docs/extensions/reference/limits.md +184 -0
  53. package/docs/extensions/reference/names.md +65 -0
  54. package/docs/extensions/reference/pocket.md +1361 -0
  55. package/docs/extensions/reference/theme-surface.md +257 -0
  56. package/docs/extensions/reference/types.md +140 -0
  57. package/docs/extensions/reference/web.md +539 -0
  58. package/docs/extensions/routes.md +106 -0
  59. package/docs/extensions/services-settings.md +118 -0
  60. package/docs/extensions/testing.md +98 -0
  61. package/docs/extensions/themes.md +208 -0
  62. package/docs/extensions/tool-calls.md +42 -0
  63. package/docs/extensions/tools.md +96 -0
  64. package/docs/extensions.md +114 -0
  65. package/docs/features.md +128 -0
  66. package/docs/index.md +56 -0
  67. package/docs/map.md +288 -0
  68. package/docs/release-notes.md +84 -0
  69. package/docs/self-editing.md +84 -0
  70. package/docs/showcase-0.12.1.png +0 -0
  71. package/docs/systemd.md +113 -0
  72. package/npm-shrinkwrap.json +3162 -0
  73. package/package.json +83 -5
  74. package/src/launcher/access.ts +354 -0
  75. package/src/launcher/main.ts +918 -0
  76. package/src/launcher/options.ts +101 -0
  77. package/src/launcher/term.ts +227 -0
  78. package/src/server/alerts.ts +278 -0
  79. package/src/server/anthropic-shape.ts +133 -0
  80. package/src/server/app-events.ts +114 -0
  81. package/src/server/app.ts +3627 -0
  82. package/src/server/artifact-state.ts +153 -0
  83. package/src/server/attribution.ts +278 -0
  84. package/src/server/auth.ts +193 -0
  85. package/src/server/background.ts +1524 -0
  86. package/src/server/branches.ts +243 -0
  87. package/src/server/browser/cdp.ts +275 -0
  88. package/src/server/browser/discovery.ts +203 -0
  89. package/src/server/browser/keys.ts +135 -0
  90. package/src/server/browser/local-servers.ts +124 -0
  91. package/src/server/browser/page-scripts.ts +289 -0
  92. package/src/server/browser/page.ts +1458 -0
  93. package/src/server/browser/urls.ts +140 -0
  94. package/src/server/browser/viewport.ts +73 -0
  95. package/src/server/browser.ts +434 -0
  96. package/src/server/cache-keeper.ts +605 -0
  97. package/src/server/changes.ts +508 -0
  98. package/src/server/collab.ts +573 -0
  99. package/src/server/commands.ts +2322 -0
  100. package/src/server/compaction.ts +108 -0
  101. package/src/server/config.ts +515 -0
  102. package/src/server/design/bundle.ts +65 -0
  103. package/src/server/design/export.ts +118 -0
  104. package/src/server/design/files.ts +49 -0
  105. package/src/server/design/guide.ts +56 -0
  106. package/src/server/design/index.ts +232 -0
  107. package/src/server/design/pptx.ts +304 -0
  108. package/src/server/design/render.ts +593 -0
  109. package/src/server/design/system.ts +248 -0
  110. package/src/server/docs.ts +922 -0
  111. package/src/server/entry-format.ts +66 -0
  112. package/src/server/errors.ts +33 -0
  113. package/src/server/export.ts +202 -0
  114. package/src/server/extension-commands.ts +497 -0
  115. package/src/server/extension-document-compat.ts +32 -0
  116. package/src/server/extension-document-imports.ts +114 -0
  117. package/src/server/extension-points.ts +283 -0
  118. package/src/server/extension-request.ts +132 -0
  119. package/src/server/extension-settings.ts +301 -0
  120. package/src/server/extension-web.ts +1455 -0
  121. package/src/server/extensions/agent-teams.js +29 -0
  122. package/src/server/extensions/agent-teams.ts +206 -0
  123. package/src/server/extensions/anthropic-subscription.ts +18 -0
  124. package/src/server/extensions/artifacts.ts +603 -0
  125. package/src/server/extensions/ask-someone/index.js +500 -0
  126. package/src/server/extensions/ask-someone/style.css +110 -0
  127. package/src/server/extensions/ask-someone.ts +571 -0
  128. package/src/server/extensions/background.ts +184 -0
  129. package/src/server/extensions/browser.ts +477 -0
  130. package/src/server/extensions/codemode.ts +430 -0
  131. package/src/server/extensions/design/canvas.js +304 -0
  132. package/src/server/extensions/design/comments.js +15 -0
  133. package/src/server/extensions/design/data.js +263 -0
  134. package/src/server/extensions/design/devices.js +70 -0
  135. package/src/server/extensions/design/docks.js +647 -0
  136. package/src/server/extensions/design/edits.js +37 -0
  137. package/src/server/extensions/design/index.js +326 -0
  138. package/src/server/extensions/design/messages.js +92 -0
  139. package/src/server/extensions/design/parts.js +160 -0
  140. package/src/server/extensions/design/state.js +146 -0
  141. package/src/server/extensions/design/style.css +1332 -0
  142. package/src/server/extensions/design/tweaks.js +161 -0
  143. package/src/server/extensions/design/views.js +375 -0
  144. package/src/server/extensions/design/workspace.js +723 -0
  145. package/src/server/extensions/design.ts +620 -0
  146. package/src/server/extensions/gallery.ts +154 -0
  147. package/src/server/extensions/goals.ts +103 -0
  148. package/src/server/extensions/guard.ts +80 -0
  149. package/src/server/extensions/memory.ts +183 -0
  150. package/src/server/extensions/pip.ts +714 -0
  151. package/src/server/extensions/plan.ts +345 -0
  152. package/src/server/extensions/prompt.ts +134 -0
  153. package/src/server/extensions/schedules.ts +164 -0
  154. package/src/server/extensions/session-tags/index.js +511 -0
  155. package/src/server/extensions/session-tags/style.css +150 -0
  156. package/src/server/extensions/session-tags.ts +165 -0
  157. package/src/server/extensions/subagents.ts +1087 -0
  158. package/src/server/extensions/triggers.ts +104 -0
  159. package/src/server/extensions/updates/index.js +429 -0
  160. package/src/server/extensions/updates/style.css +120 -0
  161. package/src/server/extensions/updates.ts +177 -0
  162. package/src/server/fence.ts +49 -0
  163. package/src/server/files.ts +343 -0
  164. package/src/server/folder-favorites.ts +76 -0
  165. package/src/server/gallery/diff.ts +202 -0
  166. package/src/server/gallery/entry.ts +930 -0
  167. package/src/server/gallery/fetch.ts +131 -0
  168. package/src/server/gallery/files.ts +364 -0
  169. package/src/server/gallery/share.ts +495 -0
  170. package/src/server/gallery/themes.ts +247 -0
  171. package/src/server/gallery.ts +1478 -0
  172. package/src/server/git.ts +57 -0
  173. package/src/server/github.ts +396 -0
  174. package/src/server/goals.ts +198 -0
  175. package/src/server/hidden.ts +470 -0
  176. package/src/server/hooks.ts +677 -0
  177. package/src/server/host.ts +707 -0
  178. package/src/server/http/api.ts +858 -0
  179. package/src/server/http/artifact-assets.ts +216 -0
  180. package/src/server/http/artifact-inspect.ts +1281 -0
  181. package/src/server/http/artifacts.ts +347 -0
  182. package/src/server/http/assets.ts +412 -0
  183. package/src/server/http/browser-routes.ts +210 -0
  184. package/src/server/http/compress.ts +108 -0
  185. package/src/server/http/conversation-routes.ts +757 -0
  186. package/src/server/http/events.ts +405 -0
  187. package/src/server/http/extension-routes.ts +234 -0
  188. package/src/server/http/hook-routes.ts +93 -0
  189. package/src/server/http/io.ts +205 -0
  190. package/src/server/http/link-routes.ts +342 -0
  191. package/src/server/http/push-routes.ts +95 -0
  192. package/src/server/http/sign-in.ts +183 -0
  193. package/src/server/http/theme-routes.ts +86 -0
  194. package/src/server/http.ts +152 -0
  195. package/src/server/lancet.ts +424 -0
  196. package/src/server/limit-gate.ts +1333 -0
  197. package/src/server/limits.ts +489 -0
  198. package/src/server/linked-sessions.ts +942 -0
  199. package/src/server/lock.ts +275 -0
  200. package/src/server/main.ts +279 -0
  201. package/src/server/memory.ts +719 -0
  202. package/src/server/model-facts.ts +60 -0
  203. package/src/server/model-names.ts +337 -0
  204. package/src/server/model-refresh.ts +256 -0
  205. package/src/server/models.ts +196 -0
  206. package/src/server/net.ts +54 -0
  207. package/src/server/npm-install.ts +82 -0
  208. package/src/server/npm-update.ts +100 -0
  209. package/src/server/omarchy.ts +114 -0
  210. package/src/server/paths.ts +28 -0
  211. package/src/server/pi-sessions.ts +556 -0
  212. package/src/server/pip-compact.ts +595 -0
  213. package/src/server/pip.ts +1732 -0
  214. package/src/server/project-model.ts +114 -0
  215. package/src/server/projection.ts +1055 -0
  216. package/src/server/prompts.ts +264 -0
  217. package/src/server/providers.ts +423 -0
  218. package/src/server/public-fetch.ts +443 -0
  219. package/src/server/public-links.ts +239 -0
  220. package/src/server/push.ts +503 -0
  221. package/src/server/reload.ts +1154 -0
  222. package/src/server/repo-watches.ts +842 -0
  223. package/src/server/requests.ts +26 -0
  224. package/src/server/resend.ts +191 -0
  225. package/src/server/reveal.ts +104 -0
  226. package/src/server/room.ts +1132 -0
  227. package/src/server/running.ts +243 -0
  228. package/src/server/schedules.ts +400 -0
  229. package/src/server/share.ts +245 -0
  230. package/src/server/shell.ts +365 -0
  231. package/src/server/skills.ts +259 -0
  232. package/src/server/spend.ts +528 -0
  233. package/src/server/subagent-runs.ts +21 -0
  234. package/src/server/themes/css.ts +592 -0
  235. package/src/server/themes/format.ts +166 -0
  236. package/src/server/themes/reserved.ts +39 -0
  237. package/src/server/themes.ts +1211 -0
  238. package/src/server/timing.ts +98 -0
  239. package/src/server/titles.ts +168 -0
  240. package/src/server/transcripts.ts +208 -0
  241. package/src/server/update-state.ts +963 -0
  242. package/src/server/updates.ts +1371 -0
  243. package/src/server/versions.ts +47 -0
  244. package/src/server/watches.ts +1108 -0
  245. package/src/server/when.ts +403 -0
  246. package/src/server/workspace.ts +507 -0
  247. package/src/server/worktrees.ts +203 -0
  248. package/src/server/zip.ts +163 -0
  249. package/types/pocket.d.ts +2725 -0
  250. package/web/activity-fold.js +28 -0
  251. package/web/agent-now.js +37 -0
  252. package/web/agent-tile.js +79 -0
  253. package/web/app.js +964 -0
  254. package/web/apple-touch-icon.png +0 -0
  255. package/web/artifact-bridge.js +656 -0
  256. package/web/avatar.js +87 -0
  257. package/web/back.js +554 -0
  258. package/web/box-keys.js +216 -0
  259. package/web/browser-panel.js +1097 -0
  260. package/web/browser.js +68 -0
  261. package/web/calls.js +119 -0
  262. package/web/chat.js +919 -0
  263. package/web/clock.js +34 -0
  264. package/web/commands.js +578 -0
  265. package/web/composer.js +2003 -0
  266. package/web/diff-parse.js +672 -0
  267. package/web/diff.js +1646 -0
  268. package/web/dock.js +299 -0
  269. package/web/extension-ui.js +2734 -0
  270. package/web/files-panel.js +772 -0
  271. package/web/files.js +368 -0
  272. package/web/fonts/FiraCode-OFL.txt +93 -0
  273. package/web/fonts/FiraCode-VF.woff2 +0 -0
  274. package/web/fonts/Geist-OFL.txt +92 -0
  275. package/web/fonts/Geist.woff2 +0 -0
  276. package/web/fonts/IBMPlexMono-OFL.txt +92 -0
  277. package/web/fonts/IBMPlexMono-Variable-Italic.woff2 +0 -0
  278. package/web/fonts/IBMPlexMono-Variable.woff2 +0 -0
  279. package/web/fonts/Inter-OFL.txt +92 -0
  280. package/web/fonts/InterVariable-Italic.woff2 +0 -0
  281. package/web/fonts/InterVariable.woff2 +0 -0
  282. package/web/fonts/Iosevka-Bold.woff2 +0 -0
  283. package/web/fonts/Iosevka-BoldItalic.woff2 +0 -0
  284. package/web/fonts/Iosevka-Italic.woff2 +0 -0
  285. package/web/fonts/Iosevka-OFL.txt +110 -0
  286. package/web/fonts/Iosevka-Regular.woff2 +0 -0
  287. package/web/fonts/Iosevka-SemiBold.woff2 +0 -0
  288. package/web/fonts/Iosevka-SemiBoldItalic.woff2 +0 -0
  289. package/web/fonts/JetBrainsMono-Italic.woff2 +0 -0
  290. package/web/fonts/JetBrainsMono.woff2 +0 -0
  291. package/web/fonts/NerdFonts-LICENSE.txt +21 -0
  292. package/web/fonts/NerdFonts-README.txt +67 -0
  293. package/web/fonts/NerdFontsSymbolsMono.woff2 +0 -0
  294. package/web/fonts/OFL.txt +93 -0
  295. package/web/fonts/SOURCES.md +69 -0
  296. package/web/gestures.js +610 -0
  297. package/web/highlight.js +480 -0
  298. package/web/history.js +70 -0
  299. package/web/home.js +169 -0
  300. package/web/icon-192.png +0 -0
  301. package/web/icon-512.png +0 -0
  302. package/web/icon-maskable-512.png +0 -0
  303. package/web/icon.svg +16 -0
  304. package/web/index.html +123 -0
  305. package/web/launcher.js +1293 -0
  306. package/web/linked-sessions.js +55 -0
  307. package/web/live.js +39 -0
  308. package/web/manifest.webmanifest +32 -0
  309. package/web/model-refresh.js +73 -0
  310. package/web/notify.js +251 -0
  311. package/web/peeks.js +915 -0
  312. package/web/pip-attachments.js +182 -0
  313. package/web/pip-window.js +141 -0
  314. package/web/pip.js +1217 -0
  315. package/web/rich.js +403 -0
  316. package/web/run-frame.js +106 -0
  317. package/web/safe-mode.js +71 -0
  318. package/web/seen.js +137 -0
  319. package/web/session-tree.js +117 -0
  320. package/web/sessions.js +1944 -0
  321. package/web/share.js +126 -0
  322. package/web/sheets/appearance.js +820 -0
  323. package/web/sheets/branch.js +353 -0
  324. package/web/sheets/extensions.js +750 -0
  325. package/web/sheets/file.js +306 -0
  326. package/web/sheets/find.js +250 -0
  327. package/web/sheets/folder.js +680 -0
  328. package/web/sheets/gallery.js +1720 -0
  329. package/web/sheets/hooks.js +350 -0
  330. package/web/sheets/memory.js +531 -0
  331. package/web/sheets/menu.js +580 -0
  332. package/web/sheets/message.js +220 -0
  333. package/web/sheets/model.js +412 -0
  334. package/web/sheets/people.js +409 -0
  335. package/web/sheets/pi-sessions.js +264 -0
  336. package/web/sheets/providers.js +525 -0
  337. package/web/sheets/running.js +130 -0
  338. package/web/sheets/schedules.js +71 -0
  339. package/web/sheets/session.js +60 -0
  340. package/web/sheets/shortcuts.js +101 -0
  341. package/web/sheets/spend.js +150 -0
  342. package/web/sheets/text.js +53 -0
  343. package/web/sheets/viewers.js +363 -0
  344. package/web/sheets/worktree.js +50 -0
  345. package/web/sheets.js +395 -0
  346. package/web/signin.js +57 -0
  347. package/web/slots.js +208 -0
  348. package/web/store.js +1731 -0
  349. package/web/style.css +17562 -0
  350. package/web/subagents-board.js +879 -0
  351. package/web/subagents.js +273 -0
  352. package/web/sw.js +169 -0
  353. package/web/taps.js +26 -0
  354. package/web/theme-surface.d.ts +4 -0
  355. package/web/theme-surface.js +243 -0
  356. package/web/theme.js +833 -0
  357. package/web/themes/lantern/colors.toml +25 -0
  358. package/web/themes/lantern/direction.css +60 -0
  359. package/web/themes/lantern/frame.css +254 -0
  360. package/web/themes/lantern/theme.css +10 -0
  361. package/web/themes/lantern/theme.json +7 -0
  362. package/web/themes/pocket/theme.css +189 -0
  363. package/web/themes/pocket/theme.json +6 -0
  364. package/web/themes.js +556 -0
  365. package/web/transcript.js +3224 -0
  366. package/web/trust.js +295 -0
  367. package/web/turns.js +507 -0
  368. package/web/ui.js +1906 -0
  369. package/web/voice.js +345 -0
package/AGENTS.md ADDED
@@ -0,0 +1,14 @@
1
+ # Working on Pi Pocket
2
+
3
+ In an npm install (inside `node_modules`), read only: to change Pi Pocket, clone the repository.
4
+
5
+ Pi Pocket is often edited from inside itself, while it runs. [docs/map.md](docs/map.md) says where things are, and [docs/architecture.md](docs/architecture.md) what they rely on. [docs/self-editing.md](docs/self-editing.md) has the whole of what follows, including how to check a change on a throwaway copy (`node test/serve.ts`); [docs/index.md](docs/index.md) lists every guide. Keep editing safe:
6
+
7
+ - `web/**` changes reload every open browser right away. Keep the app loadable after each save: a syntax error blanks the screen for everyone, including you. Check with `node --check web/<file>.js` after editing.
8
+ - `src/server/extensions/*.ts` changes are reinstalled into the running server. A file that fails to load keeps its previous version and reports the error. Each module default-exports `(host, web) => Extension | Extension[] | void`, possibly async (`web` adds routes and a browser module to the app: [docs/extensions/app.md](docs/extensions/app.md)). Start each module with a `/** … */` comment: its first sentence is the description in the app's Extensions sheet, where the owner can turn modules off (a module that is off is not loaded, even when edited).
9
+ - Other `src/server/**` changes need a restart (menu → Restart server). Running work resumes after it, but a tool call cut off mid-run that is not replay-safe comes back as interrupted. Do not restart while your own tool call is running; finish the edit, run `npm run check` and `npm test`, then ask the user to restart.
10
+ - The owner's drop-in extensions in `~/.pi-pocket/extensions/` load the same way, after the built-in ones, and stay off until the owner turns them on. A `node_modules` link there lets them import Pi Pocket's packages.
11
+ - Document kinds in `src/server/docs.ts` are stored data. Do not rename them, or change their scope, history, or fork settings: Pi Durable checks those against what is stored.
12
+ - The server is plain TypeScript run by Node's type stripping: only erasable syntax (no enums, no parameter properties, no namespaces). Imports use `.ts` extensions.
13
+ - Code style is Prettier (`.prettierrc.json`: 4 spaces, 100 columns) plus ESLint's layout rules (`eslint.config.js`): braces on every `if` and loop, and a blank line after declarations, around blocks, and before `return` and `throw`. Run `npm run format` after editing. Prettier leaves the markup in `html` templates alone, so lay it out by hand the same way: 4 spaces per level, and a tag that runs past 100 columns gets one attribute per line and its children on their own lines. In htm a line break is not a space: break only where there is no space, or between tags, never inside running text.
14
+ - Run `npm run check`, `npm run lint`, and `npm test` after server changes.
@@ -0,0 +1,22 @@
1
+ # Contributing to Pi Pocket
2
+
3
+ Thank you for your help. This page tells how to send a change.
4
+
5
+ ## Before you start
6
+
7
+ - Read the [policies](docs/extensions/policies/index.md). They tell what belongs in core and what belongs in an extension, which interfaces are public, and how they change.
8
+ - For a large change, open an issue first. Tell what you want to change, and why.
9
+ - If an extension cannot do what you need, ask for an extension point ([how](docs/extensions/policies/core-or-extension.md#ask-for-a-new-extension-point)).
10
+ - To report a security problem, do not open an issue. Read [SECURITY.md](SECURITY.md).
11
+
12
+ ## Make the change
13
+
14
+ - [AGENTS.md](AGENTS.md) and [docs/self-editing.md](docs/self-editing.md) tell how to work on the code. [docs/map.md](docs/map.md) tells where things are.
15
+ - Add one small test for each real risk that the change brings. The test must fail before the change.
16
+ - Run `npm run format`, `npm run check`, `npm run lint`, and `npm test`.
17
+
18
+ ## Send it
19
+
20
+ - Open a pull request with a short title, and a brief note: what changed, why, and what you tested.
21
+ - Maintainers merge with a merge commit, so your commits keep your name.
22
+ - A release pull request's description is the release notes: [docs/release-notes.md](docs/release-notes.md) tells how to write them.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tanner Middleton
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,120 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # Pi Pocket
4
+
5
+ **Your Pi coding agent, in your pocket.**
6
+
7
+ A durable, multiplayer, mobile-first web app for Pi agents, built on [Pi Durable](https://earendil.com/posts/pi-durable/).<br>
8
+ Runs on your own machine or directly on your phone. No cloud VM.
9
+
10
+ [![Release](https://img.shields.io/github/v/release/TannerMidd/pi-pocket?color=7aa2f7)](https://github.com/TannerMidd/pi-pocket/releases)
11
+ [![Node.js 22.19+](https://img.shields.io/badge/node-%E2%89%A5%2022.19-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
12
+ [![MIT license](https://img.shields.io/badge/license-MIT-ff9e64)](LICENSE)
13
+
14
+ [Website](https://tannermidd.github.io/pi-pocket/) · [Quick start](#quick-start) · [Feature tour](docs/features.md) · [Docs](https://tannermidd.github.io/pi-pocket/docs/)
15
+
16
+ <img src="docs/showcase-0.12.1.png" alt="Pi Pocket in the Tokyo Night theme, on a desktop and a phone. On the desktop, the session list beside a conversation where Pi has fixed a sign-in redirect loop, its edits and a passing run of 48 tests folded into a timeline. On the phone, the same session after a teammate, Alex, asks for the push: Lancet Guard waits for approval before git push." width="100%">
17
+
18
+ </div>
19
+
20
+ ## Highlights
21
+
22
+ - **Durable.** Every model call, tool call, and subagent is stored as it happens. Restart the server mid-run, and the work continues.
23
+ - **Multiplayer.** Share a live session with presence, a side chat Pi does not see, invites, and roles.
24
+ - **Made for phones.** Push notifications, dictation, sharing into Pi from other apps, and a home-screen app.
25
+ - **PiP.** An assistant that starts, follows, and reports on your other sessions, and watches GitHub for you.
26
+ - **Your models.** Pi's own providers, sign-ins, skills, and prompt templates, with the model chosen per session.
27
+ - **Live-editable.** No build step. Pi can change Pi Pocket while it runs, and you can add your own extensions.
28
+
29
+ The [feature tour](docs/features.md) covers everything else, from plan mode and peek tiles to the built-in browser.
30
+
31
+ ## Quick start
32
+
33
+ Requires Node.js 22.19 or newer. Runs on Linux, macOS, Windows, and Android (Termux); Linux is the most tested. Sign in to a provider with Pi first (`pi`, then `/login`), or later from the app's Providers sheet.
34
+
35
+ ```bash
36
+ npm install -g pi-pocket
37
+ pi-pocket
38
+ ```
39
+
40
+ Newer npm may print "install-scripts ... not yet covered by allowScripts" for `@google/genai` and `protobufjs`, which come from Pi's model library. The warning is expected: Pi Pocket needs neither script. `npm config set allow-scripts=@google/genai,protobufjs --location=user` quiets it by letting both run, which does no harm.
41
+
42
+ Or try it with `npx pi-pocket`. To change Pi Pocket's code, run a git checkout instead:
43
+
44
+ ```bash
45
+ git clone https://github.com/TannerMidd/pi-pocket.git
46
+ cd pi-pocket
47
+ npm install
48
+ npm start
49
+ ```
50
+
51
+ The launcher asks how your devices should connect, then prints a sign-in link and a QR code. The link is the owner's key: keep it private. `--rotate-token` replaces it and signs out every device that used it.
52
+
53
+ While it runs: **q** quit · **r** restart server · **a** change access · **o** open in browser · **s** show QR code.
54
+
55
+ **Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 upgrades the database one way, so going back needs the backup.
56
+
57
+ ### Other ways to run it
58
+
59
+ - **Docker or Podman:** `docker compose up -d --build`. See [docs/docker.md](docs/docker.md).
60
+ - **Nix:** `nix run github:TannerMidd/pi-pocket`, or the NixOS module `services.pi-pocket.enable = true;` ([nix/module.nix](nix/module.nix)).
61
+ - **Android (Termux):**
62
+
63
+ ```bash
64
+ pkg update && pkg upgrade && pkg install nodejs git
65
+ npm install -g --ignore-scripts @earendil-works/pi-coding-agent
66
+ pi # /login, then quit
67
+ git clone https://github.com/TannerMidd/pi-pocket.git
68
+ cd pi-pocket && npm install --ignore-scripts && termux-wake-lock && npm start
69
+ ```
70
+
71
+ Lancet Guard may not load on Android. If it is on but fails, start with `PI_POCKET_GUARD=off`.
72
+
73
+ ## Remote access
74
+
75
+ Choose a mode in the launcher, or pass `--access`:
76
+
77
+ | Mode | Who can connect | Notes |
78
+ | ------------ | -------------------- | -------------------------------------------------------- |
79
+ | `local` | This machine | `127.0.0.1`; bring your own tunnel to port 8787 |
80
+ | `lan` | Your local network | Plain http |
81
+ | `cloudflare` | Anyone with the link | Free https quick tunnel, no account; needs `cloudflared` |
82
+ | `tailscale` | Your tailnet | Tailscale address only |
83
+
84
+ Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)).
85
+
86
+ > [!WARNING]
87
+ > Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Pi Pocket's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. [SECURITY.md](SECURITY.md) says what is protected and what is not.
88
+
89
+ ## Documentation
90
+
91
+ - [Feature tour](docs/features.md): every feature, in full.
92
+ - [Docs site](https://tannermidd.github.io/pi-pocket/docs/): customizing Pi without code, and writing extensions.
93
+ - [Engineering](https://tannermidd.github.io/pi-pocket/engineering.html) and [code map](docs/map.md): how Pi Pocket is built.
94
+
95
+ ## Development
96
+
97
+ ```bash
98
+ npm run check # type-check
99
+ npm test # server tests with a scripted model
100
+ npm run format # ESLint's layout fixes, then Prettier
101
+ npm run lint # check the layout rules
102
+ ```
103
+
104
+ `web/` changes reload every open browser, and extensions reload into the running server. `node test/serve.ts` runs a throwaway copy to check a change on. [AGENTS.md](AGENTS.md) covers editing Pi Pocket safely from inside itself, and [CONTRIBUTING.md](CONTRIBUTING.md) how to send a change.
105
+
106
+ ## Limitations
107
+
108
+ - Pi Durable is experimental, and its API can change between releases. Versions are pinned in `package.json`.
109
+ - Only one server process can use the database at a time.
110
+ - Pi's own extensions are not supported. Pi Pocket runs its own, on Pi Durable.
111
+ - A git worktree keeps a session's files apart; it is not a sandbox.
112
+ - The built-in browser needs Chromium, Chrome, Brave, or Edge on the server. It is tested on Linux and macOS.
113
+
114
+ The [full list](docs/features.md#limitations) has the details.
115
+
116
+ ## Credits and license
117
+
118
+ Inspired by [Mario Zechner's demo](https://x.com/badlogicgames/status/2106452296087302173) of his own Pi app. Pi Pocket is an independent project, not affiliated with Earendil. The bundled fonts keep their own licenses, which are beside them in [web/fonts/](web/fonts/).
119
+
120
+ [MIT](LICENSE). To report a security problem, see [SECURITY.md](SECURITY.md).
package/SECURITY.md ADDED
@@ -0,0 +1,23 @@
1
+ # Security
2
+
3
+ ## Reporting a problem
4
+
5
+ Please report security problems privately through GitHub: on this repository, open **Security → Report a vulnerability**. Do not open a public issue. Include what you found, how to reproduce it, and what an attacker gains.
6
+
7
+ ## What Pi Pocket protects, and what it does not
8
+
9
+ Pi Pocket runs a coding agent that executes commands on the machine it runs on, as the user who started it.
10
+
11
+ - **Signing in.** The owner's sign-in link is the key to the server. Invites are one-time links that expire after 15 minutes, or an hour, a day, or a week when whoever makes one picks that; the longer one lasts, the longer a link that leaks can be used. Their codes are stored hashed. An owner invite, which only the owner can make, always lasts 15 minutes and gives the device that opens it the owner token itself, and with it full control; starting with `--rotate-token` signs out every device that has it and ends owner invites not yet used. Tokens are random, stored hashed, and kept in an `HttpOnly` cookie. The cookie is host-only (it has no `Domain`), so each address needs its own sign-in: `127.0.0.1` and `localhost` are different hosts to a browser, and a device signed in at one is not signed in at the other.
12
+ - **Viewers** can read, react, and chat. They cannot make Pi do anything.
13
+ - **Anyone who can steer can do what you can.** Through Pi, they reach your files, Pi Pocket's settings and tokens, and its code. An invite to one session limits what someone sees in the app, not what Pi can reach. Neither do git worktrees or spend limits: a worktree keeps a session's files apart, and a run is stopped only after the request that crosses its limit.
14
+ - **Approvals.** Lancet Guard approvals can come from anyone who can steer, including the person who asked, unless the owner turns on "Approvals need someone else" (Menu → Extensions); then, when nobody is known to have asked, only the owner can allow. A notification offers Allow only for a call that fits on one short line; anything longer opens the app first. Since 0.22.0, an extension can ask a question on the same kind of card (a sign-in, a code): only the person Pi works for fills it in, what they type goes to that extension and never to Pi or the transcript, and its notification has no Allow. Values an extension hides show as `[label]` in command output, tool results, and messages to Pi; that keeps them out by accident, not from a command or a model that leaks them on purpose. A "Done when" check command runs after every answer without asking, so with Lancet Guard on it must be one the guard allows outright.
15
+ - **The built-in browser** reaches what this machine reaches: `localhost`, your network, and the internet. Anyone who can steer can use it from the Browser panel, and Pi from its `browser` tool; Lancet Guard does not check either, and pages can hold whatever they show. The addresses people open show in the session's chat. Its pages run in Chromium on the server, not in your browser, so they cannot reach the app or its cookies. Only the owner opens files from the address bar or sees which servers run on the machine. If steering guests should not reach your network, turn Browser off in Menu → Extensions.
16
+ - **Models** are a person's to choose. Pi starts subagents only on their session's model, or on models the owner allowed (Providers → Models for subagents); PiP passes a model only when its person named it; titles and summaries use the session's own model. Subagents on another model, and PiP, ask a model's sign-in afresh first and use none whose sign-in expired; a session's own run, a subagent on its model, titles, and summaries just try the model, and a run that fails on an expired sign-in marks it. This guards spending against Pi's choices, not against a person: anyone who can steer can pick a session's model, and Pi, which runs commands, can reach Pi's sign-ins and Pi Pocket's files like anything else on the machine.
17
+ - **Linked sessions** (Agent Teams, off until the owner turns it on) widen what prompt injection can reach. A session that read something hostile (a page, a file, an issue) can pass it on to the other sessions of its team in a message, and a message makes Pi work in the target for the person Pi worked for in the sender, with that person's access, in a session where other people may have written. Pi is told to take a linked session's message as a request, not as an order from a person, and to do nothing destructive or with credentials only because one asks; that is guidance to the model, not a boundary. A message is fenced, and a team stops at the starting session's spend limit. Since 0.19.0, no count of messages or sessions stops a team, so set a session budget for a session that starts one; a link gives no access to a session someone cannot already see.
18
+ - **Plan mode** keeps Pi to planning; it is not a boundary. Programs that people configured to run on their own, such as a git diff driver, run as they would for anyone.
19
+ - **Drop-in extensions** in `~/.pi-pocket/extensions/` run inside the server with the owner's rights. They stay off until the owner turns them on. One with a browser module also runs code in the app's own page, with the rights of whoever's tab loads it: the owner's alone unless the module opens it to others (never to someone invited to one session). The page's content security policy keeps that code from loading scripts and styles from another site or fetching from one, but code in the page could still send data out in other ways (navigating the page elsewhere, for one): turn on only browser modules you trust, as with the server part. What a module's route throws with `web.error` reaches everyone who may use that route as it is; anything else it throws, only the owner reads. Every file of a web type (`.js`, `.mjs`, `.css`, `.json`, images, and `.woff2` fonts) in a browser module's folder can be read by everyone the module is for. A module's conversation command is offered to everyone who can steer that session, people invited to only that session included, and its handler runs with the owner's rights: treat its arguments as untrusted, and check who runs it. A global command is the owner's alone.
20
+ - **The extension gallery** (Menu → Extensions → Find extensions) installs drop-ins other people wrote, so what it installs has the owner's rights once turned on. It reads its index strictly, downloads only over https from each entry's pinned commit, refuses a file whose SHA-256 differs from the entry's, keeps file names inside the drop-in folder, and installs everything off; updates are never automatic. The index's checks and its maintainers' review lower the risk, but do not remove it: read the code (or ask Pi to review it) before you turn one on. Only the owner can use the gallery. A theme from the gallery is CSS, fonts, and images that the owner chooses to install. Pi Pocket checks it as every theme folder before it is in place, so it cannot load anything from other servers, nor the app's own addresses, and it runs no code. It can still hide or relabel parts of the app, approvals too: install only themes you trust.
21
+ - **Replies are untrusted.** Anything Pi reads can steer what it writes, so the app page loads nothing from other sites, and replies cannot contain forms, scripts, or styling. Artifacts run in a sandbox with no access to the app. An HTML block in a reply is previewed in a frame of its own with its scripts off and a policy that loads nothing, not even from the app; tapping **Run** runs it as an artifact runs, with scripts and the network but no access to the app, so a page Pi was steered into writing could then send what it shows elsewhere. SVG blocks show as images, which run nothing. A shared artifact (`/pub/<token>`) is the same sandboxed page, for anyone with the link and no sign-in: the token is the whole of the access, so treat the address as a secret until it is ended, and remember that the page can reach the network, as an artifact in the app can. Since 0.22.0, an extension module can show public pages too (`/l/<token>`): each link closes at its time (30 days at most) or after its answers, the page runs no script in an opaque origin, so whoever opens it while signed in lends it nothing, and Menu → Extensions says which modules have them.
22
+
23
+ Problems within these limits are bugs we want to hear about: for example, a viewer making Pi act, a session-scoped person seeing another session, or a reply reaching the app's cookies or API.
@@ -0,0 +1,27 @@
1
+ #!/usr/bin/env node
2
+ // Pi Pocket's launcher entry. It checks the Node version, then runs src/launcher/main.ts (Node strips its types, with
3
+ // help from strip-types.js in an npm install): pick how devices reach the server, then run it, restart it when the app
4
+ // asks (exit code 75, or SIGUSR2) or after a crash, and keep any tunnel up across restarts. Work in flight survives
5
+ // restarts: the durable harness resumes it.
6
+ const [major, minor] = process.versions.node.split(".").map(Number);
7
+
8
+ if (major < 22 || (major === 22 && minor < 19)) {
9
+ console.error(`Pi Pocket needs Node.js 22.19 or newer (found ${process.versions.node}).`);
10
+ process.exit(1);
11
+ }
12
+
13
+ // The first release of each line with the October 21, 2026 security fixes (TLS hostname checks, Brotli,
14
+ // dns.resolve). Older ones still run, with a warning; a line not listed here gets none.
15
+ const patched = { 22: [23, 4], 24: [22, 1], 26: [12, 1] };
16
+ const patch = Number(process.versions.node.split(".")[2]);
17
+ const fixed = patched[major];
18
+
19
+ if (fixed && (minor < fixed[0] || (minor === fixed[0] && patch < fixed[1]))) {
20
+ console.warn(
21
+ `Node.js ${process.versions.node} lacks security fixes: update to ${major}.${fixed.join(".")} or newer.`,
22
+ );
23
+ }
24
+
25
+ // From an npm install, Node needs help to run TypeScript: strip-types.js gives it.
26
+ await import("./strip-types.js");
27
+ await import("../src/launcher/main.ts");
@@ -0,0 +1,62 @@
1
+ // Lets Node run Pi Pocket's TypeScript from an npm install. Node strips types itself, but never from a file under a
2
+ // node_modules folder, which is where npm puts Pi Pocket. Imported before any of Pi Pocket's code (by
3
+ // bin/pi-pocket.js, and with `--import` in the server the launcher starts), it strips the types of Pi Pocket's own
4
+ // .ts files there with Node's own stripper, and leaves every other file to Node. In a git checkout it does nothing.
5
+ import { readFileSync } from "node:fs";
6
+ import { registerHooks, stripTypeScriptTypes } from "node:module";
7
+ import { sep } from "node:path";
8
+ import { fileURLToPath } from "node:url";
9
+
10
+ /** Pi Pocket's folder, as a URL that ends in `/`. */
11
+ const ROOT = new URL("..", import.meta.url).href;
12
+
13
+ /** Whether Pi Pocket runs from a node_modules folder, where Node does not strip types. */
14
+ export const needed = fileURLToPath(ROOT).split(sep).includes("node_modules");
15
+
16
+ /** Node's stripper, without the warning that it is experimental above the launcher's panel at every start. */
17
+ function strip(source) {
18
+ const warn = process.emitWarning;
19
+
20
+ process.emitWarning = (warning, ...rest) => {
21
+ if (!String(warning).includes("stripTypeScriptTypes")) {
22
+ warn.call(process, warning, ...rest);
23
+ }
24
+ };
25
+
26
+ try {
27
+ return stripTypeScriptTypes(source);
28
+ } finally {
29
+ process.emitWarning = warn;
30
+ }
31
+ }
32
+
33
+ /** One of Pi Pocket's own TypeScript files (not one of a package inside it), as a file path; else undefined. */
34
+ function ownTypeScript(url) {
35
+ const bare = url.split(/[?#]/)[0];
36
+
37
+ if (!bare.startsWith(ROOT) || !/\.m?ts$/.test(bare)) {
38
+ return undefined;
39
+ }
40
+
41
+ return bare.slice(ROOT.length).split("/").includes("node_modules")
42
+ ? undefined
43
+ : fileURLToPath(bare);
44
+ }
45
+
46
+ if (needed) {
47
+ registerHooks({
48
+ load(url, context, nextLoad) {
49
+ const file = ownTypeScript(url);
50
+
51
+ if (file === undefined) {
52
+ return nextLoad(url, context);
53
+ }
54
+
55
+ return {
56
+ format: "module",
57
+ source: strip(readFileSync(file, "utf8")),
58
+ shortCircuit: true,
59
+ };
60
+ },
61
+ });
62
+ }
@@ -0,0 +1,38 @@
1
+ # Pi Pocket as a systemd template unit. The instance name is the access mode; see docs/systemd.md.
2
+
3
+ [Unit]
4
+ Description=Pi Pocket (%i access)
5
+ Documentation=https://github.com/TannerMidd/pi-pocket/blob/main/docs/systemd.md
6
+ Wants=network-online.target
7
+ After=network-online.target tailscaled.service
8
+
9
+ [Service]
10
+ Type=simple
11
+ User=pi-pocket
12
+ Group=pi-pocket
13
+
14
+ Environment=POCKET_HOME=/opt/pi-pocket
15
+ Environment=HOME=/var/lib/pi-pocket
16
+ Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
17
+ EnvironmentFile=-/etc/pi-pocket.env
18
+
19
+ WorkingDirectory=/srv/pi-pocket
20
+
21
+ # %i is the access mode: local, lan, cloudflare, tailscale, or tailscale-serve.
22
+ ExecStart=/usr/bin/env node ${POCKET_HOME}/bin/pi-pocket.js --access %i --port 8787 --data /var/lib/pi-pocket --cwd /srv/pi-pocket
23
+
24
+ Restart=on-failure
25
+ RestartSec=5
26
+ KillMode=mixed
27
+ TimeoutStopSec=20
28
+
29
+ StateDirectory=pi-pocket
30
+ StateDirectoryMode=0700
31
+ UMask=0077
32
+ LimitNOFILE=65536
33
+
34
+ NoNewPrivileges=yes
35
+ PrivateTmp=yes
36
+
37
+ [Install]
38
+ WantedBy=multi-user.target