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
@@ -0,0 +1,248 @@
1
+ /**
2
+ * The project's design system (stream D of design mode): a Markdown file at `<session folder>/.pi/design-system.md`
3
+ * that Pi writes after it reads the codebase or the brand files the person points at, and that guide.ts puts into the
4
+ * prompt before Pi makes a design. The `design_system` tool reads and writes that file.
5
+ *
6
+ * The file is bounded UTF-8 text. A write never follows a symlink to the file itself and replaces it atomically: the
7
+ * new bytes go to a temporary file next to it, and a rename puts them in place. A read never follows a symlink either.
8
+ */
9
+ import { randomUUID } from "node:crypto";
10
+ import {
11
+ closeSync,
12
+ constants,
13
+ fstatSync,
14
+ lstatSync,
15
+ mkdirSync,
16
+ openSync,
17
+ readSync,
18
+ renameSync,
19
+ rmSync,
20
+ writeFileSync,
21
+ } from "node:fs";
22
+ import { join } from "node:path";
23
+ import { Type } from "@earendil-works/pi-ai";
24
+ import { defineTool, type ToolRegistration } from "@earendil-works/pi-durable";
25
+
26
+ /** The file's path, in the session's working directory. */
27
+ export const SYSTEM_FILE = join(".pi", "design-system.md");
28
+
29
+ /** The file's size limit, in bytes: tokens and rules stay short enough to sit in a prompt. */
30
+ export const MAX_BYTES = 16_384;
31
+
32
+ const file = (cwd: string) => join(cwd, SYSTEM_FILE);
33
+
34
+ function systemDirectory(cwd: string): boolean {
35
+ try {
36
+ const info = lstatSync(join(cwd, ".pi"));
37
+
38
+ if (!info.isDirectory() || info.isSymbolicLink()) {
39
+ throw new Error("The project's .pi folder must be a directory, not a symlink.");
40
+ }
41
+
42
+ return true;
43
+ } catch (error) {
44
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
45
+ return false;
46
+ }
47
+
48
+ throw error;
49
+ }
50
+ }
51
+
52
+ /**
53
+ * Where `end` leaves a whole UTF-8 sequence after it: it walks back over continuation bytes and then a lead byte whose
54
+ * sequence the kept bytes complete. Text cut this way has no replacement character at its last character.
55
+ */
56
+ export function utf8Cut(bytes: Buffer, end: number): number {
57
+ let back = 0;
58
+
59
+ if (end <= 0) {
60
+ return 0;
61
+ }
62
+
63
+ while (back < 3 && end - back - 1 >= 0 && (bytes[end - back - 1]! & 0xc0) === 0x80) {
64
+ back++;
65
+ }
66
+
67
+ const at = end - back - 1;
68
+
69
+ // Only continuation bytes on the way back: the start of the text is one broken sequence, so keep none of it.
70
+ if (at < 0) {
71
+ return 0;
72
+ }
73
+
74
+ const lead = bytes[at]!;
75
+ const need = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
76
+
77
+ return need <= back + 1 ? end : at;
78
+ }
79
+
80
+ /** The bounded text of bytes: at most `max` bytes, cut without a broken character at the end. */
81
+ export function boundedText(bytes: Buffer, max: number): { text: string; truncated: boolean } {
82
+ const kept = bytes.length > max ? utf8Cut(bytes, max) : bytes.length;
83
+
84
+ return {
85
+ text: bytes.subarray(0, Math.max(0, kept)).toString("utf8"),
86
+ truncated: bytes.length > kept,
87
+ };
88
+ }
89
+
90
+ /** The file's text, bounded, or undefined when there is no file. It never follows a symlink to the file. */
91
+ export function readDesignSystemText(
92
+ cwd: string,
93
+ ): { text: string; truncated: boolean } | undefined {
94
+ if (!systemDirectory(cwd)) {
95
+ return undefined;
96
+ }
97
+
98
+ const path = file(cwd);
99
+ let stats;
100
+
101
+ try {
102
+ stats = lstatSync(path);
103
+ } catch (error) {
104
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
105
+ return undefined;
106
+ }
107
+
108
+ throw error;
109
+ }
110
+
111
+ if (!stats.isFile()) {
112
+ throw new Error(
113
+ `${SYSTEM_FILE} must be a regular file, not a directory, device, or symlink.`,
114
+ );
115
+ }
116
+
117
+ // O_NOFOLLOW closes the window between the lstat and this open, where a symlink could appear.
118
+ const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
119
+
120
+ try {
121
+ if (!fstatSync(fd).isFile()) {
122
+ throw new Error(`${SYSTEM_FILE} must be a regular file.`);
123
+ }
124
+
125
+ // Read at most the limit, so a stray large file is no more work than a bounded one.
126
+ const head = Buffer.alloc(MAX_BYTES + 4);
127
+ let size = 0;
128
+
129
+ while (size < head.length) {
130
+ const read = readSync(fd, head, size, head.length - size, null);
131
+
132
+ if (read <= 0) {
133
+ break;
134
+ }
135
+
136
+ size += read;
137
+ }
138
+
139
+ if (size === 0) {
140
+ return { text: "", truncated: false };
141
+ }
142
+
143
+ return boundedText(head.subarray(0, size), MAX_BYTES);
144
+ } finally {
145
+ closeSync(fd);
146
+ }
147
+ }
148
+
149
+ /** Replaces the file with `content`, atomically, and returns its size in bytes. */
150
+ export function writeDesignSystemText(cwd: string, content: string): number {
151
+ const bytes = Buffer.from(content, "utf8");
152
+
153
+ if (bytes.length > MAX_BYTES) {
154
+ throw new Error(
155
+ `The design system is bounded text: ${MAX_BYTES} bytes at most (16 KB); the text is ${bytes.length}. Cut the design system down, or move components and rules into separate project files that the design system names.`,
156
+ );
157
+ }
158
+
159
+ if (!systemDirectory(cwd)) {
160
+ mkdirSync(join(cwd, ".pi"), { recursive: true });
161
+ }
162
+
163
+ systemDirectory(cwd);
164
+ // A fresh name each time: only this write's temporary file, and none of an earlier one under the same name.
165
+ const temp = join(cwd, ".pi", `.${randomUUID()}.tmp`);
166
+
167
+ try {
168
+ writeFileSync(temp, bytes, { flag: "wx" });
169
+ // A rename replaces the final name whole on one file system: if the target was a symlink, the file takes its
170
+ // place and no write ever follows the link.
171
+ renameSync(temp, file(cwd));
172
+ } finally {
173
+ // The rename already removed it; a failed call may have left it there.
174
+ rmSync(temp, { force: true });
175
+ }
176
+
177
+ return bytes.length;
178
+ }
179
+
180
+ /** The `design_system` tool: read the file, or replace it with `content`. */
181
+ export function designSystemTool(): ToolRegistration {
182
+ return defineTool({
183
+ name: "design_system",
184
+ description: `The project's design system: ${SYSTEM_FILE} in the session's folder, with the design tokens as a fenced JSON block, then the components and rules for new designs. Use read before you make or change a design; use write (content replaces the file) after you read the codebase or the brand files the person points at.`,
185
+ parameters: Type.Object({
186
+ action: Type.Union([Type.Literal("read"), Type.Literal("write")], {
187
+ description: "read the file, or write over it",
188
+ }),
189
+ content: Type.Optional(
190
+ Type.String({
191
+ description: `write: the new file, up to ${MAX_BYTES} bytes`,
192
+ }),
193
+ ),
194
+ }),
195
+ // Not read-only: write changes the session's files. Not replay-safe either, on purpose: a call that a restart
196
+ // stopped comes back interrupted instead of running and writing twice.
197
+ execute: async (args, api, context) => {
198
+ const { cwd } = await api.agent(context);
199
+
200
+ if (cwd === undefined) {
201
+ throw new Error(
202
+ "This session has no working directory, so the design system has no place.",
203
+ );
204
+ }
205
+
206
+ if (args.action === "write") {
207
+ if (args.content === undefined) {
208
+ throw new Error("write needs the new design system in content.");
209
+ }
210
+
211
+ const size = writeDesignSystemText(cwd, args.content);
212
+
213
+ return {
214
+ output: [
215
+ {
216
+ type: "text" as const,
217
+ text: `Wrote ${SYSTEM_FILE} (${size} bytes). The next design request reads it.`,
218
+ },
219
+ ],
220
+ };
221
+ }
222
+
223
+ const read = readDesignSystemText(cwd);
224
+
225
+ if (read === undefined) {
226
+ return {
227
+ output: [
228
+ {
229
+ type: "text" as const,
230
+ text: `There is no ${SYSTEM_FILE} in this session yet. Read the codebase or the brand files the person points at, then write the design system: the design tokens as a fenced JSON block, then the components and rules for new designs.`,
231
+ },
232
+ ],
233
+ };
234
+ }
235
+
236
+ const size = Math.min(Buffer.byteLength(read.text, "utf8"), MAX_BYTES);
237
+
238
+ return {
239
+ output: [
240
+ {
241
+ type: "text" as const,
242
+ text: `Read ${SYSTEM_FILE} (${size} bytes${read.truncated ? `, cut at the ${MAX_BYTES}-byte limit` : ""}): the design system.\n\n${read.text}`,
243
+ },
244
+ ],
245
+ };
246
+ },
247
+ });
248
+ }
@@ -133,6 +133,8 @@ export const AuthorsDoc = defineDoc<{
133
133
 
134
134
  export type ArtifactType = "html" | "markdown" | "svg";
135
135
 
136
+ export type ArtifactAsset = { hash: string; size: number; type: string };
137
+
136
138
  export type ArtifactVersion = {
137
139
  version: number;
138
140
  /** The tool task that wrote it; a replayed call finds its version instead of writing another. */
@@ -149,11 +151,15 @@ export type ArtifactVersion = {
149
151
  * artifact, and would change every version's page).
150
152
  */
151
153
  inline?: true;
154
+ /** Bundle paths map to immutable, content-addressed bytes. */
155
+ assets?: Record<string, ArtifactAsset>;
152
156
  };
153
157
 
154
158
  export type ArtifactMeta = {
155
159
  title: string;
156
160
  type: ArtifactType;
161
+ group?: string;
162
+ kind?: "page" | "deck";
157
163
  versions: ArtifactVersion[];
158
164
  };
159
165
 
@@ -180,6 +186,16 @@ export const ArtifactBodyDoc = defineDocFamily<{ content: string }, { content: s
180
186
  initial: (seed) => ({ content: seed.content }),
181
187
  });
182
188
 
189
+ /** Immutable asset bytes, shared across conversations and keyed by their SHA-256 hash. */
190
+ export const ArtifactAssetDoc = defineDocFamily<{ base64: string }, { base64: string }>({
191
+ kind: "pocket.artifact-asset",
192
+ version: 1,
193
+ ...rebased,
194
+ family: true,
195
+ scope: "session",
196
+ initial: (seed) => ({ base64: seed.base64 }),
197
+ });
198
+
183
199
  /** What one person saved for one artifact (`artifact-state.ts`): a JSON value, the page's schema label, and when. */
184
200
  export type ArtifactStateValue = { value: JsonValue; schema?: string; at: number };
185
201
 
@@ -865,3 +881,42 @@ export const RepoWatchesDoc = defineDoc<{ items: Record<string, RepoWatch> }>({
865
881
  scope: "session",
866
882
  initial: () => ({ items: {} }),
867
883
  });
884
+
885
+ /** One comment on a design, pinned to an element of one version (`extensions/design.ts`). */
886
+ export type DesignComment = {
887
+ id: string;
888
+ /** The artifact version it was made on. */
889
+ version: number;
890
+ /** The element it points at, as the page's inspector described it: shape-checked and cut to size by the server. */
891
+ target: JsonValue;
892
+ text: string;
893
+ /** Who wrote it, by id and by name when they did (the name is kept if the person is removed). */
894
+ by: string;
895
+ byName: string;
896
+ at: number;
897
+ /** Set when someone marked it done. */
898
+ resolved?: { by: string; at: number };
899
+ };
900
+
901
+ /** What a conversation keeps for one design artifact. */
902
+ export type DesignItem = {
903
+ comments: DesignComment[];
904
+ /** Each person's tweak values for it, by person id: the knobs of the page's manifest and what was set. */
905
+ tweaks?: Record<string, { values: Record<string, string | number | boolean>; at: number }>;
906
+ /** Versions that "Go back to this one" made, by version: the version whose content they copy. */
907
+ restores?: Record<string, number>;
908
+ };
909
+
910
+ /**
911
+ * The Design workspace's own data (`extensions/design.ts`), by artifact id: shared comments, each person's tweaks, and
912
+ * which versions were restored from which. A fork starts with the current values, as its artifacts do.
913
+ */
914
+ export const DesignCommentsDoc = defineDoc<{ items: Record<string, DesignItem> }>({
915
+ kind: "pocket.design-comments",
916
+ version: 1,
917
+ ...rebased,
918
+ scope: "conversation",
919
+ history: "latest",
920
+ fork: "current",
921
+ initial: () => ({ items: {} }),
922
+ });
@@ -4,6 +4,7 @@
4
4
  * version. The index and the bodies are durable documents committed together with
5
5
  * the call, so a replayed call finds the version it already wrote instead of writing another.
6
6
  */
7
+ import { createHash } from "node:crypto";
7
8
  import { constants } from "node:fs";
8
9
  import { open } from "node:fs/promises";
9
10
  import { extname, resolve } from "node:path";
@@ -15,16 +16,22 @@ import {
15
16
  type ToolRegistration,
16
17
  } from "@earendil-works/pi-durable";
17
18
  import {
19
+ ArtifactAssetDoc,
18
20
  ArtifactBodyDoc,
21
+ type ArtifactAsset,
19
22
  type ArtifactMeta,
20
23
  ArtifactsDoc,
21
24
  type ArtifactType,
22
25
  type ArtifactVersion,
23
26
  } from "../docs.ts";
24
27
  import type { PocketHost } from "../host.ts";
28
+ import { assetName, assetType } from "../http/artifact-assets.ts";
25
29
  import { expandHome } from "../paths.ts";
26
30
 
27
- const MAX_BYTES = 2_000_000;
31
+ export const MAX_BYTES = 2_000_000;
32
+ export const MAX_ASSET_BYTES = 5_000_000;
33
+ export const MAX_ASSETS_BYTES = 20_000_000;
34
+ export const MAX_ASSETS = 200;
28
35
 
29
36
  export function slugify(value: string): string {
30
37
  return value
@@ -36,7 +43,7 @@ export function slugify(value: string): string {
36
43
  }
37
44
 
38
45
  /** Agent-local files, not browser file access: parent links are allowed, the final file must not be a link. */
39
- async function readArtifact(path: string): Promise<string> {
46
+ async function readFileBytes(path: string, limit: number): Promise<Buffer> {
40
47
  const handle = await open(
41
48
  path,
42
49
  constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW,
@@ -49,12 +56,12 @@ async function readArtifact(path: string): Promise<string> {
49
56
  throw new Error("Artifact paths must name a regular file.");
50
57
  }
51
58
 
52
- if (info.size > MAX_BYTES) {
53
- throw new Error(`Artifacts are limited to ${MAX_BYTES} bytes.`);
59
+ if (info.size > limit) {
60
+ throw new Error(`Files are limited to ${limit} bytes.`);
54
61
  }
55
62
 
56
63
  // Read at most one byte beyond the limit, even when the file grows after stat.
57
- const buffer = Buffer.alloc(MAX_BYTES + 1);
64
+ const buffer = Buffer.alloc(limit + 1);
58
65
  let size = 0;
59
66
 
60
67
  while (true) {
@@ -66,24 +73,29 @@ async function readArtifact(path: string): Promise<string> {
66
73
 
67
74
  size += bytesRead;
68
75
 
69
- if (size > MAX_BYTES) {
70
- throw new Error(`Artifacts are limited to ${MAX_BYTES} bytes.`);
76
+ if (size > limit) {
77
+ throw new Error(`Files are limited to ${limit} bytes.`);
71
78
  }
72
79
  }
73
80
 
74
- const bytes = buffer.subarray(0, size);
81
+ // Do not retain the full limit-sized backing allocation for each small bundle file.
82
+ return Buffer.from(buffer.subarray(0, size));
83
+ } finally {
84
+ await handle.close();
85
+ }
86
+ }
75
87
 
76
- try {
77
- if (bytes.includes(0)) {
78
- throw new Error("Binary data");
79
- }
88
+ async function readArtifact(path: string): Promise<string> {
89
+ const bytes = await readFileBytes(path, MAX_BYTES);
80
90
 
81
- return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
82
- } catch {
83
- throw new Error("Artifact paths must contain UTF-8 text, not binary data.");
91
+ try {
92
+ if (bytes.includes(0)) {
93
+ throw new Error("Binary data");
84
94
  }
85
- } finally {
86
- await handle.close();
95
+
96
+ return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
97
+ } catch {
98
+ throw new Error("Artifact paths must contain UTF-8 text, not binary data.");
87
99
  }
88
100
  }
89
101
 
@@ -144,6 +156,7 @@ const guide = (
144
156
  - {type:"pocket-follow-up", text, selection}: puts a message in the person's message box, for them to read and send; it is never sent by itself, and the viewer closes so the box shows. Send it from a button's click or tap: the app takes it only right after the person taps or presses a key on the page (focus alone does not count; a tap serves one follow-up), and once every 2 seconds. text is up to 2,000 characters; selection, optional, is JSON up to 2,000. The app answers {type:"pocket-follow-up", ok, error}. Use it for "Ask Pi about this" buttons.
145
157
  - {type:"pocket-state-get", requestId, schema} and {type:"pocket-state-set", requestId, state, schema}: load and save up to 16 KB of JSON for the person using the artifact, so its controls survive a reload and follow them to other devices. requestId is 1 to 64 letters, digits, and _ . : - (others get no answer). The app answers {type:"pocket-state", requestId, ok, state, at, error}; state is null when nothing is saved. A set with state null clears it. schema, optional, is a string such as "v1" (up to 64 letters, digits, and . _ : -; a number is refused): change it when the state's shape changes, and older state then reads as null. Save after changes settle (at most 20 saves in 10 seconds).
146
158
  - Only HTML artifacts have this (not Markdown or SVG). Neither works in a published link or a tab of its own: the page must still work when no answer comes.
159
+ - Add images, fonts, data, stylesheets, scripts, and other HTML pages with assets: up to 200 entries of {name, path} (local file, binary allowed) or {name, content} (UTF-8 text). Names are relative paths made of letters, digits, dots, underscores, and hyphens, with no . or .. segment. One asset is at most 5 MB; one version keeps at most 20 MB. Relative URLs resolve inside the bundle. A new version keeps previous assets; replace them by name, or drop them with removeAssets. Use group (a lowercase kebab-case slug) for variations, and kind: "page" or "deck" for the design type.
147
160
  - Reuse the id to publish a new version. For small fixes, send edits against the latest version instead of the whole content.
148
161
  ${inline ? INLINE_GUIDE : ""}- To publish an existing local HTML, Markdown, or SVG file without repeating its contents, give path instead of content or edits. This copies a UTF-8 snapshot (up to 2,000,000 bytes), not a live link or its neighboring assets. Everyone who can see the conversation can open the snapshot.`;
149
162
 
@@ -156,6 +169,10 @@ type PublishArgs = {
156
169
  content?: string;
157
170
  path?: string;
158
171
  edits?: { oldText: string; newText: string }[];
172
+ assets?: { name: string; path?: string; content?: string }[];
173
+ removeAssets?: string[];
174
+ group?: string;
175
+ kind?: "page" | "deck";
159
176
  };
160
177
 
161
178
  /**
@@ -254,6 +271,78 @@ async function publish(
254
271
  throw new Error(`Artifacts are limited to ${MAX_BYTES} bytes.`);
255
272
  }
256
273
 
274
+ if (args.group !== undefined && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(args.group)) {
275
+ throw new Error("The group must be a lowercase kebab-case slug.");
276
+ }
277
+
278
+ if (args.group !== undefined && args.group.length > 64) {
279
+ throw new Error("The group is limited to 64 characters.");
280
+ }
281
+
282
+ if (
283
+ (args.assets?.length ?? 0) > MAX_ASSETS ||
284
+ (args.removeAssets?.length ?? 0) > MAX_ASSETS
285
+ ) {
286
+ throw new Error(`Give at most ${MAX_ASSETS} assets or removals.`);
287
+ }
288
+
289
+ for (const name of args.removeAssets ?? []) {
290
+ if (!assetName(name)) {
291
+ throw new Error(`Invalid asset name: ${name}`);
292
+ }
293
+ }
294
+
295
+ const prepared = new Map<string, { asset: ArtifactAsset; bytes: Buffer }>();
296
+ let preparedSize = 0;
297
+
298
+ for (const entry of args.assets ?? []) {
299
+ if (!assetName(entry.name) || prepared.has(entry.name)) {
300
+ throw new Error(`Invalid or repeated asset name: ${entry.name}`);
301
+ }
302
+
303
+ if ((entry.path === undefined) === (entry.content === undefined)) {
304
+ throw new Error(`Asset ${entry.name}: give exactly one of path or content.`);
305
+ }
306
+
307
+ let bytes: Buffer;
308
+
309
+ if (entry.path !== undefined) {
310
+ if (entry.path.trim() === "") {
311
+ throw new Error("Give a local file path.");
312
+ }
313
+
314
+ const agent = await api.agent(context);
315
+ const path = resolve(agent.cwd ?? process.cwd(), expandHome(entry.path));
316
+
317
+ bytes = await readFileBytes(path, MAX_ASSET_BYTES);
318
+ } else {
319
+ if (Buffer.byteLength(entry.content!, "utf8") > MAX_ASSET_BYTES) {
320
+ throw new Error(`Assets are limited to ${MAX_ASSET_BYTES} bytes each.`);
321
+ }
322
+
323
+ bytes = Buffer.from(entry.content!, "utf8");
324
+ }
325
+
326
+ if (bytes.length > MAX_ASSET_BYTES) {
327
+ throw new Error(`Assets are limited to ${MAX_ASSET_BYTES} bytes each.`);
328
+ }
329
+
330
+ preparedSize += bytes.length;
331
+
332
+ if (preparedSize > MAX_ASSETS_BYTES) {
333
+ throw new Error(`Bundle assets are limited to ${MAX_ASSETS_BYTES} bytes.`);
334
+ }
335
+
336
+ prepared.set(entry.name, {
337
+ asset: {
338
+ hash: createHash("sha256").update(bytes).digest("hex"),
339
+ size: bytes.length,
340
+ type: assetType(entry.name),
341
+ },
342
+ bytes,
343
+ });
344
+ }
345
+
257
346
  version = await api.commit(async (tx) => {
258
347
  const doc = await tx.doc(ArtifactsDoc, api.conversationId);
259
348
  const current = Object.hasOwn(doc.items, id) ? doc.items[id] : undefined;
@@ -286,6 +375,38 @@ async function publish(
286
375
  );
287
376
  }
288
377
 
378
+ const assets: Record<string, ArtifactAsset> = Object.fromEntries(
379
+ Object.entries(current?.versions.at(-1)?.assets ?? {}),
380
+ );
381
+
382
+ for (const name of args.removeAssets ?? []) {
383
+ delete assets[name];
384
+ }
385
+
386
+ for (const [name, value] of prepared) {
387
+ Object.defineProperty(assets, name, {
388
+ value: value.asset,
389
+ enumerable: true,
390
+ writable: true,
391
+ configurable: true,
392
+ });
393
+ }
394
+
395
+ if (Object.keys(assets).length > MAX_ASSETS) {
396
+ throw new Error(`One version keeps at most ${MAX_ASSETS} assets.`);
397
+ }
398
+
399
+ if (
400
+ Object.values(assets).reduce((total, asset) => total + asset.size, 0) >
401
+ MAX_ASSETS_BYTES
402
+ ) {
403
+ throw new Error(`Bundle assets are limited to ${MAX_ASSETS_BYTES} bytes.`);
404
+ }
405
+
406
+ for (const { asset, bytes } of prepared.values()) {
407
+ await tx.doc(ArtifactAssetDoc, asset.hash, { base64: bytes.toString("base64") });
408
+ }
409
+
289
410
  const next = (current?.versions.at(-1)?.version ?? 0) + 1;
290
411
  const record: ArtifactVersion = {
291
412
  version: next,
@@ -294,6 +415,7 @@ async function publish(
294
415
  size: Buffer.byteLength(content),
295
416
  createdAt: Date.now(),
296
417
  ...(inline ? { inline: true as const } : {}),
418
+ ...(Object.keys(assets).length > 0 ? { assets } : {}),
297
419
  };
298
420
 
299
421
  if (current === undefined) {
@@ -304,6 +426,16 @@ async function publish(
304
426
  current.versions.push(record);
305
427
  }
306
428
 
429
+ const meta = doc.items[id]!;
430
+
431
+ if (args.group !== undefined) {
432
+ meta.group = args.group;
433
+ }
434
+
435
+ if (args.kind !== undefined) {
436
+ meta.kind = args.kind;
437
+ }
438
+
307
439
  const body = await tx.doc(ArtifactBodyDoc, api.conversationId, `${id}@${next}`, {
308
440
  content,
309
441
  });
@@ -336,6 +468,47 @@ async function publish(
336
468
  };
337
469
  }
338
470
 
471
+ const bundleParameters = {
472
+ assets: Type.Optional(
473
+ Type.Array(
474
+ Type.Object({
475
+ name: Type.String({
476
+ description:
477
+ "Relative bundle path, up to 200 characters. No dot or parent segments.",
478
+ }),
479
+ path: Type.Optional(
480
+ Type.String({
481
+ description: "Local regular file to copy, binary allowed, up to 5 MB.",
482
+ }),
483
+ ),
484
+ content: Type.Optional(
485
+ Type.String({
486
+ description: "UTF-8 text. Give exactly one of path or content.",
487
+ }),
488
+ ),
489
+ }),
490
+ {
491
+ maxItems: MAX_ASSETS,
492
+ description: "Add or replace assets. Earlier assets stay. Up to 20 MB per version.",
493
+ },
494
+ ),
495
+ ),
496
+ removeAssets: Type.Optional(
497
+ Type.Array(Type.String(), {
498
+ maxItems: MAX_ASSETS,
499
+ description: "Bundle paths to drop from this version.",
500
+ }),
501
+ ),
502
+ group: Type.Optional(
503
+ Type.String({
504
+ maxLength: 64,
505
+ pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$",
506
+ description: "Group variations under one lowercase kebab-case slug.",
507
+ }),
508
+ ),
509
+ kind: Type.Optional(Type.Union([Type.Literal("page"), Type.Literal("deck")])),
510
+ };
511
+
339
512
  export default function createArtifacts(_host: PocketHost) {
340
513
  const artifact = defineTool({
341
514
  name: "artifact",
@@ -343,6 +516,7 @@ export default function createArtifacts(_host: PocketHost) {
343
516
  "Publish a viewable artifact (self-contained HTML page, Markdown document, or SVG image) that the user opens in the app's artifact viewer. " +
344
517
  "Calling again with the same id publishes a new version. Give exactly one of content, nonempty edits, or a local UTF-8 file path (up to 2,000,000 bytes).",
345
518
  parameters: Type.Object({
519
+ ...bundleParameters,
346
520
  id: Type.String({
347
521
  description:
348
522
  "Stable kebab-case id, for example solar-system. Reuse it for new versions.",
@@ -381,6 +555,7 @@ export default function createArtifacts(_host: PocketHost) {
381
555
  "Show an HTML page as a card in your reply, where the person uses it without leaving the conversation (Preview/Code, Run/Stop, and a button for the artifact viewer). " +
382
556
  "The same store as artifact: the same id adds a version, and each card keeps the version its call made. Give exactly one of content or nonempty edits.",
383
557
  parameters: Type.Object({
558
+ ...bundleParameters,
384
559
  id: Type.String({
385
560
  description:
386
561
  "Stable kebab-case id, for example loan-calculator. Reuse it for new versions.",
@@ -400,7 +575,16 @@ export default function createArtifacts(_host: PocketHost) {
400
575
  // Only its own fields: the model may send others, and a path or a type is the artifact tool's.
401
576
  execute: (args, api, context) =>
402
577
  publish(
403
- { id: args.id, title: args.title, content: args.content, edits: args.edits },
578
+ {
579
+ id: args.id,
580
+ title: args.title,
581
+ content: args.content,
582
+ edits: args.edits,
583
+ assets: args.assets,
584
+ removeAssets: args.removeAssets,
585
+ group: args.group,
586
+ kind: args.kind,
587
+ },
404
588
  api,
405
589
  context,
406
590
  true,