pi-pocket 0.25.0 → 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 (85) hide show
  1. package/AGENTS.md +2 -0
  2. package/README.md +5 -3
  3. package/docs/architecture.md +21 -0
  4. package/docs/design/design-mode.md +108 -0
  5. package/docs/design/notes-a.md +106 -0
  6. package/docs/design/notes-b.md +123 -0
  7. package/docs/design/notes-c.md +92 -0
  8. package/docs/design/notes-d.md +78 -0
  9. package/docs/design/release-notes-design.md +46 -0
  10. package/docs/extensions/browser-modules.md +2 -0
  11. package/docs/extensions/policies/api-stability.md +2 -0
  12. package/docs/extensions/reference/api-versions.md +1 -0
  13. package/docs/extensions/reference/host.md +1 -1
  14. package/docs/extensions/reference/limits.md +4 -0
  15. package/docs/extensions/reference/names.md +2 -2
  16. package/docs/extensions/reference/pocket.md +38 -0
  17. package/docs/features.md +19 -5
  18. package/docs/map.md +75 -54
  19. package/docs/release-notes.md +1 -1
  20. package/docs/self-editing.md +1 -1
  21. package/docs/systemd.md +1 -1
  22. package/npm-shrinkwrap.json +2 -2
  23. package/package.json +1 -1
  24. package/src/launcher/main.ts +20 -9
  25. package/src/server/app.ts +113 -4
  26. package/src/server/background.ts +3 -3
  27. package/src/server/cache-keeper.ts +605 -0
  28. package/src/server/compaction.ts +68 -15
  29. package/src/server/design/bundle.ts +65 -0
  30. package/src/server/design/export.ts +118 -0
  31. package/src/server/design/files.ts +49 -0
  32. package/src/server/design/guide.ts +56 -0
  33. package/src/server/design/index.ts +232 -0
  34. package/src/server/design/pptx.ts +304 -0
  35. package/src/server/design/render.ts +593 -0
  36. package/src/server/design/system.ts +248 -0
  37. package/src/server/docs.ts +55 -0
  38. package/src/server/extensions/artifacts.ts +202 -18
  39. package/src/server/extensions/design/canvas.js +304 -0
  40. package/src/server/extensions/design/comments.js +15 -0
  41. package/src/server/extensions/design/data.js +263 -0
  42. package/src/server/extensions/design/devices.js +70 -0
  43. package/src/server/extensions/design/docks.js +647 -0
  44. package/src/server/extensions/design/edits.js +37 -0
  45. package/src/server/extensions/design/index.js +326 -0
  46. package/src/server/extensions/design/messages.js +92 -0
  47. package/src/server/extensions/design/parts.js +160 -0
  48. package/src/server/extensions/design/state.js +146 -0
  49. package/src/server/extensions/design/style.css +1332 -0
  50. package/src/server/extensions/design/tweaks.js +161 -0
  51. package/src/server/extensions/design/views.js +375 -0
  52. package/src/server/extensions/design/workspace.js +723 -0
  53. package/src/server/extensions/design.ts +620 -0
  54. package/src/server/extensions/plan.ts +11 -9
  55. package/src/server/extensions/prompt.ts +11 -3
  56. package/src/server/extensions/subagents.ts +7 -1
  57. package/src/server/extensions/updates/index.js +16 -6
  58. package/src/server/extensions/updates.ts +2 -2
  59. package/src/server/http/artifact-assets.ts +216 -0
  60. package/src/server/http/artifact-inspect.ts +1281 -0
  61. package/src/server/http/artifacts.ts +89 -14
  62. package/src/server/http/conversation-routes.ts +46 -1
  63. package/src/server/http.ts +12 -4
  64. package/src/server/main.ts +4 -0
  65. package/src/server/npm-install.ts +82 -0
  66. package/src/server/npm-update.ts +100 -0
  67. package/src/server/reload.ts +5 -0
  68. package/src/server/room.ts +2 -0
  69. package/src/server/spend.ts +73 -9
  70. package/src/server/update-state.ts +257 -8
  71. package/src/server/updates.ts +268 -33
  72. package/src/server/zip.ts +163 -0
  73. package/types/pocket.d.ts +32 -0
  74. package/web/activity-fold.js +28 -0
  75. package/web/artifact-bridge.js +506 -82
  76. package/web/extension-ui.js +21 -1
  77. package/web/pip.js +46 -9
  78. package/web/sessions.js +1 -1
  79. package/web/sheets/appearance.js +10 -0
  80. package/web/sheets/viewers.js +26 -1
  81. package/web/style.css +11 -0
  82. package/web/taps.js +26 -0
  83. package/web/theme.js +6 -0
  84. package/web/transcript.js +19 -10
  85. package/src/server/http/public.ts +0 -30
package/src/server/app.ts CHANGED
@@ -53,6 +53,7 @@ import { Commands } from "./commands.ts";
53
53
  import { LinkedSessions } from "./linked-sessions.ts";
54
54
  import { APP_ROOT, ConfigStore, modulesWith, type User } from "./config.ts";
55
55
  import {
56
+ ArtifactAssetDoc,
56
57
  ArtifactBodyDoc,
57
58
  type ArtifactMeta,
58
59
  ArtifactsDoc,
@@ -67,6 +68,7 @@ import {
67
68
  MemoryDoc,
68
69
  type SessionMeta,
69
70
  SessionsDoc,
71
+ SpendDoc,
70
72
  type SubagentRecord,
71
73
  SubagentsDoc,
72
74
  TurnsDoc,
@@ -104,6 +106,7 @@ import { loadPromptTemplates, type PromptTemplate, type SkillCommand } from "./p
104
106
  import { BASE_THEME, Themes } from "./themes.ts";
105
107
  import { THEME_ID } from "./themes/format.ts";
106
108
  import { LimitGate, type LimitTuning } from "./limit-gate.ts";
109
+ import { CacheKeeper } from "./cache-keeper.ts";
107
110
  import { measureModelStreams } from "./timing.ts";
108
111
  import { Providers } from "./providers.ts";
109
112
  import { PushStore } from "./push.ts";
@@ -300,6 +303,8 @@ export class PocketApp {
300
303
  readonly providers = new Providers(this);
301
304
  /** Model requests that hit a limit wait for it to clear, then go on (`limit-gate.ts`). */
302
305
  readonly limits: LimitGate;
306
+ /** Keeps the prompt cache warm while a run waits on a tool call (`cache-keeper.ts`). */
307
+ readonly cacheKeeper: CacheKeeper;
303
308
  readonly schedules = new Schedules(this);
304
309
  /** Commands Pi runs in the background, watched until they end (`background.ts`). */
305
310
  readonly background = new BackgroundTasks(this);
@@ -413,6 +418,7 @@ export class PocketApp {
413
418
  supervised: options.supervised && options.restart !== undefined,
414
419
  // The launcher says so when it goes back to the version before a new one that does not start.
415
420
  rollback: process.env.PI_POCKET_ROLLBACK === "1",
421
+ npmRollback: process.env.PI_POCKET_NPM_ROLLBACK === "1",
416
422
  restart: () => options.restart?.(),
417
423
  quiesce: (paused) => this.pauseReloads(paused),
418
424
  busy: () => this.#busy.size,
@@ -425,6 +431,34 @@ export class PocketApp {
425
431
  this.config = new ConfigStore(options.dataDir);
426
432
  this.#lockFile = join(options.dataDir, "harness.lock");
427
433
  this.#log = options.log ?? ((line) => console.log(line));
434
+ this.cacheKeeper = new CacheKeeper({
435
+ log: (line) => this.#log(line),
436
+ conversationOf: (sessionId) => this.#conversationOfSession(sessionId),
437
+ isRunning: (conversationId) => this.#busy.has(conversationId as ConversationId),
438
+ accountFor: (conversationId) => {
439
+ const id = conversationId as ConversationId;
440
+ const payer = this.spend.payer(id);
441
+
442
+ return {
443
+ check: () => {
444
+ const person = this.config.userById(payer);
445
+
446
+ if (person === undefined || !this.#busy.has(id)) {
447
+ return false;
448
+ }
449
+
450
+ try {
451
+ this.spend.check(person, id);
452
+
453
+ return true;
454
+ } catch {
455
+ return false;
456
+ }
457
+ },
458
+ recordUsage: (message) => this.spend.recordModelUsage(id, payer, message),
459
+ };
460
+ },
461
+ });
428
462
  this.limits = new LimitGate({
429
463
  hours: () => this.config.limitWaitHours,
430
464
  epoch: (provider) => this.providers.signInEpoch(provider),
@@ -678,12 +712,16 @@ export class PocketApp {
678
712
  }
679
713
 
680
714
  this.models = await ModelRuntime.create();
715
+ // Innermost: observe the adapter payload only after the caller and all extension shapers finish.
716
+ this.cacheKeeper.installPayloadObserver(this.models);
681
717
  installRequestShaping(this.models, this.#shapers, this.#log);
682
718
  this.providers.modelRefresh.watch(this.models);
683
719
  this.#configureModels?.(this.models);
684
720
  measureModelStreams(this.models);
685
721
  // Outside the timing wrapper: each attempt is timed on its own, not the wait before it.
686
722
  this.limits.install(this.models);
723
+ // Outermost: it sees each real request finish, and replays it through the wrappers below.
724
+ this.cacheKeeper.install(this.models);
687
725
  await this.models.getAvailable().catch(() => []);
688
726
 
689
727
  const registry = createRegistry();
@@ -952,6 +990,20 @@ export class PocketApp {
952
990
  /** Every commit, as Pi Durable publishes it: what the app keeps in memory follows it, and so do the open views. */
953
991
  #committed(publication: CommitPublication): void {
954
992
  let sessionsChanged = false;
993
+ let alreadyPaid = false;
994
+
995
+ // Auxiliary requests pay their captured person in the same commit as usage, in either document order.
996
+ // A commit with both documents must pay every usage change. Normal spend counts never change UsageDoc.
997
+ for (const change of publication.changes) {
998
+ if (
999
+ change.type === "document" &&
1000
+ change.record.kind === SpendDoc.definition.kind &&
1001
+ change.value !== null
1002
+ ) {
1003
+ this.spend.countedChanged(change.value as { people: Record<string, number> });
1004
+ alreadyPaid = true;
1005
+ }
1006
+ }
955
1007
 
956
1008
  // Usage in a commit is from the work that was going on before it: it is counted before a message the same
957
1009
  // commit places changes whom Pi works for.
@@ -961,7 +1013,11 @@ export class PocketApp {
961
1013
  change.record.kind === UsageDoc.definition.kind &&
962
1014
  change.conversationId !== undefined
963
1015
  ) {
964
- this.spend.usageChanged(change.conversationId, change.value as UsageState | null);
1016
+ this.spend.usageChanged(
1017
+ change.conversationId,
1018
+ change.value as UsageState | null,
1019
+ alreadyPaid,
1020
+ );
965
1021
 
966
1022
  // A team's top session with a limit shows the team's spend: it follows a linked session's too.
967
1023
  const root = this.rootOf(change.conversationId);
@@ -1090,6 +1146,8 @@ export class PocketApp {
1090
1146
 
1091
1147
  if (!busy) {
1092
1148
  this.spend.runEnded(id);
1149
+ // No request follows the last tool call of a run that ended or was stopped (PiP's runs too).
1150
+ this.cacheKeeper.runEnded(Number(id));
1093
1151
  this.pipCompaction.runEnded(id);
1094
1152
 
1095
1153
  if (this.#sessions[String(id)] !== undefined) {
@@ -1912,13 +1970,19 @@ export class PocketApp {
1912
1970
  return true;
1913
1971
  }
1914
1972
 
1915
- /** Count the commands a session runs in the background, starting ones too. True when the count changed. */
1973
+ /**
1974
+ * Count the commands a session runs in the background, starting ones too. While their extension is off no watch
1975
+ * settles a task whose process died, so only a task with a live process counts. True when the count changed.
1976
+ */
1916
1977
  #noteBackground(
1917
1978
  id: ConversationId,
1918
1979
  doc: { items: Record<string, BackgroundTask> } | null | undefined,
1919
1980
  ): boolean {
1981
+ const watched = this.background.running;
1920
1982
  const running = Object.values(doc?.items ?? {}).filter(
1921
- (item) => item.status === "running" || item.status === "starting",
1983
+ (item) =>
1984
+ (item.status === "running" || item.status === "starting") &&
1985
+ (watched || this.background.alive(id, item)),
1922
1986
  ).length;
1923
1987
 
1924
1988
  if (running === (this.#background.get(id) ?? 0)) {
@@ -2683,7 +2747,7 @@ export class PocketApp {
2683
2747
  }
2684
2748
  }
2685
2749
 
2686
- async artifactBody(id: ConversationId, artifact: string, version: number | undefined) {
2750
+ async artifactBody(id: ConversationId, artifact: string, version?: number) {
2687
2751
  const index = await this.harness.snapshot(ArtifactsDoc, id, context);
2688
2752
  // Its own entries only: `__proto__` and the like name no artifact.
2689
2753
  const meta =
@@ -2718,6 +2782,50 @@ export class PocketApp {
2718
2782
  return { meta, version: chosen.version, content: body.content };
2719
2783
  }
2720
2784
 
2785
+ /** One manifest asset. Missing names must not load the rest of a potentially large bundle. */
2786
+ async artifactAsset(id: ConversationId, artifact: string, version: number, name: string) {
2787
+ const found = await this.artifactBody(id, artifact, version);
2788
+ const manifest = found.meta.versions.find((each) => each.version === found.version)!.assets;
2789
+ const asset =
2790
+ manifest !== undefined && Object.hasOwn(manifest, name) ? manifest[name] : undefined;
2791
+
2792
+ if (asset === undefined) {
2793
+ throw new HttpError(404, "No such asset");
2794
+ }
2795
+
2796
+ const stored = await this.harness.snapshot(ArtifactAssetDoc, asset.hash, context);
2797
+
2798
+ if (stored === undefined) {
2799
+ throw new HttpError(404, "Artifact asset is missing");
2800
+ }
2801
+
2802
+ return {
2803
+ name,
2804
+ type: asset.type,
2805
+ bytes: Buffer.from(stored.base64, "base64"),
2806
+ title: found.meta.title,
2807
+ };
2808
+ }
2809
+
2810
+ /** A complete bundle for rendering and export. Callers must check conversation access first. */
2811
+ async artifactBundle(id: ConversationId, artifact: string, version?: number) {
2812
+ const found = await this.artifactBody(id, artifact, version);
2813
+ const manifest = found.meta.versions.find((each) => each.version === found.version)!.assets;
2814
+ const assets = await Promise.all(
2815
+ Object.entries(manifest ?? {}).map(async ([name, asset]) => {
2816
+ const stored = await this.harness.snapshot(ArtifactAssetDoc, asset.hash, context);
2817
+
2818
+ if (stored === undefined) {
2819
+ throw new HttpError(404, "Artifact asset is missing");
2820
+ }
2821
+
2822
+ return { name, type: asset.type, bytes: Buffer.from(stored.base64, "base64") };
2823
+ }),
2824
+ );
2825
+
2826
+ return { ...found, assets };
2827
+ }
2828
+
2721
2829
  /** The folder a conversation works in. */
2722
2830
  cwdOf(id: ConversationId): string {
2723
2831
  return this.#agents.get(id)?.cwd ?? this.#sessions[String(id)]?.cwd ?? this.defaultCwd;
@@ -3408,6 +3516,7 @@ export class PocketApp {
3408
3516
  clearTimeout(this.#sessionsTimer);
3409
3517
  this.alerts.close();
3410
3518
  this.themes.close();
3519
+ await this.cacheKeeper.close();
3411
3520
  this.spend.close();
3412
3521
  this.limits.close();
3413
3522
  this.background.close();
@@ -269,7 +269,7 @@ function kill(pid: number, name: NodeJS.Signals): void {
269
269
 
270
270
  // ─── Words ──────────────────────────────────────────────────────────────────
271
271
 
272
- /** A length of time in words: 45s, 3m 12s, 2h 5m. */
272
+ /** A length of time in words: 45s, 3m 12s, 3m 05s, 2h 05m. */
273
273
  export function duration(ms: number): string {
274
274
  const seconds = Math.max(0, Math.round(ms / 1000));
275
275
 
@@ -278,10 +278,10 @@ export function duration(ms: number): string {
278
278
  }
279
279
 
280
280
  if (seconds < 3600) {
281
- return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
281
+ return `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, "0")}s`;
282
282
  }
283
283
 
284
- return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
284
+ return `${Math.floor(seconds / 3600)}h ${String(Math.floor(seconds / 60) % 60).padStart(2, "0")}m`;
285
285
  }
286
286
 
287
287
  /** How a task ended, in words, with what it left running. */