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.
- package/AGENTS.md +2 -0
- package/README.md +5 -3
- package/docs/architecture.md +21 -0
- package/docs/design/design-mode.md +108 -0
- package/docs/design/notes-a.md +106 -0
- package/docs/design/notes-b.md +123 -0
- package/docs/design/notes-c.md +92 -0
- package/docs/design/notes-d.md +78 -0
- package/docs/design/release-notes-design.md +46 -0
- package/docs/extensions/browser-modules.md +2 -0
- package/docs/extensions/policies/api-stability.md +2 -0
- package/docs/extensions/reference/api-versions.md +1 -0
- package/docs/extensions/reference/host.md +1 -1
- package/docs/extensions/reference/limits.md +4 -0
- package/docs/extensions/reference/names.md +2 -2
- package/docs/extensions/reference/pocket.md +38 -0
- package/docs/features.md +19 -5
- package/docs/map.md +75 -54
- package/docs/release-notes.md +1 -1
- package/docs/self-editing.md +1 -1
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/launcher/main.ts +20 -9
- package/src/server/app.ts +113 -4
- package/src/server/background.ts +3 -3
- package/src/server/cache-keeper.ts +605 -0
- package/src/server/compaction.ts +68 -15
- package/src/server/design/bundle.ts +65 -0
- package/src/server/design/export.ts +118 -0
- package/src/server/design/files.ts +49 -0
- package/src/server/design/guide.ts +56 -0
- package/src/server/design/index.ts +232 -0
- package/src/server/design/pptx.ts +304 -0
- package/src/server/design/render.ts +593 -0
- package/src/server/design/system.ts +248 -0
- package/src/server/docs.ts +55 -0
- package/src/server/extensions/artifacts.ts +202 -18
- package/src/server/extensions/design/canvas.js +304 -0
- package/src/server/extensions/design/comments.js +15 -0
- package/src/server/extensions/design/data.js +263 -0
- package/src/server/extensions/design/devices.js +70 -0
- package/src/server/extensions/design/docks.js +647 -0
- package/src/server/extensions/design/edits.js +37 -0
- package/src/server/extensions/design/index.js +326 -0
- package/src/server/extensions/design/messages.js +92 -0
- package/src/server/extensions/design/parts.js +160 -0
- package/src/server/extensions/design/state.js +146 -0
- package/src/server/extensions/design/style.css +1332 -0
- package/src/server/extensions/design/tweaks.js +161 -0
- package/src/server/extensions/design/views.js +375 -0
- package/src/server/extensions/design/workspace.js +723 -0
- package/src/server/extensions/design.ts +620 -0
- package/src/server/extensions/plan.ts +11 -9
- package/src/server/extensions/prompt.ts +11 -3
- package/src/server/extensions/subagents.ts +7 -1
- package/src/server/extensions/updates/index.js +16 -6
- package/src/server/extensions/updates.ts +2 -2
- package/src/server/http/artifact-assets.ts +216 -0
- package/src/server/http/artifact-inspect.ts +1281 -0
- package/src/server/http/artifacts.ts +89 -14
- package/src/server/http/conversation-routes.ts +46 -1
- package/src/server/http.ts +12 -4
- package/src/server/main.ts +4 -0
- package/src/server/npm-install.ts +82 -0
- package/src/server/npm-update.ts +100 -0
- package/src/server/reload.ts +5 -0
- package/src/server/room.ts +2 -0
- package/src/server/spend.ts +73 -9
- package/src/server/update-state.ts +257 -8
- package/src/server/updates.ts +268 -33
- package/src/server/zip.ts +163 -0
- package/types/pocket.d.ts +32 -0
- package/web/activity-fold.js +28 -0
- package/web/artifact-bridge.js +506 -82
- package/web/extension-ui.js +21 -1
- package/web/pip.js +46 -9
- package/web/sessions.js +1 -1
- package/web/sheets/appearance.js +10 -0
- package/web/sheets/viewers.js +26 -1
- package/web/style.css +11 -0
- package/web/taps.js +26 -0
- package/web/theme.js +6 -0
- package/web/transcript.js +19 -10
- 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
|
+
}
|
package/src/server/docs.ts
CHANGED
|
@@ -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
|
|
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 >
|
|
53
|
-
throw new Error(`
|
|
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(
|
|
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 >
|
|
70
|
-
throw new Error(`
|
|
76
|
+
if (size > limit) {
|
|
77
|
+
throw new Error(`Files are limited to ${limit} bytes.`);
|
|
71
78
|
}
|
|
72
79
|
}
|
|
73
80
|
|
|
74
|
-
|
|
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
|
-
|
|
77
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
throw new Error("
|
|
91
|
+
try {
|
|
92
|
+
if (bytes.includes(0)) {
|
|
93
|
+
throw new Error("Binary data");
|
|
84
94
|
}
|
|
85
|
-
|
|
86
|
-
|
|
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
|
-
{
|
|
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,
|