copilotz 1.0.0-rc.55 → 1.0.0-rc.56

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 CHANGED
@@ -4,7 +4,7 @@ A guide for coding agents (Claude Code, Codex, Cursor, Gemini) building an app w
4
4
  it whole before you write code. The last section is for work on Copilotz itself.
5
5
 
6
6
  It ships in the package (`node_modules/copilotz/AGENTS.md`, and `@copilotz/copilotz` on JSR) and
7
- goes with `copilotz@1.0.0-rc.55`. Every docs page is Markdown at
7
+ goes with `copilotz@1.0.0-rc.56`. Every docs page is Markdown at
8
8
  `https://copilotz.com/docs/<slug>.md`, and https://copilotz.com/llms.txt lists them all. When you're
9
9
  unsure of a name, fetch its page or read the package's types (`node_modules/copilotz/**/*.d.ts`).
10
10
  Don't guess.
@@ -64,12 +64,12 @@ There's no project generator. Set a project up as the docs' courses do, on Node
64
64
  ```sh
65
65
  mkdir my-app && cd my-app
66
66
  npm init -y && npm pkg set type=module
67
- npm install copilotz@1.0.0-rc.55 react@19 react-dom@19
67
+ npm install copilotz@1.0.0-rc.56 react@19 react-dom@19
68
68
  npm install -D typescript @types/node @types/react @types/react-dom esbuild
69
69
  ```
70
70
 
71
71
  Pin the version: npm's `latest` tag still points at an early release candidate. On Deno, run
72
- `deno add jsr:@copilotz/copilotz` and map `"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.55"` in
72
+ `deno add jsr:@copilotz/copilotz` and map `"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.56"` in
73
73
  `deno.json`, so imports read the same.
74
74
 
75
75
  Node runs `.ts` files as they are, so there's no build step. It doesn't run `.tsx`: tests that load
@@ -110,7 +110,7 @@ line `@AGENTS.md` (Claude Code reads `CLAUDE.md`, and follows the import). Keep
110
110
  ```markdown
111
111
  # AGENTS.md
112
112
 
113
- This app runs on Copilotz (copilotz@1.0.0-rc.55). Read node_modules/copilotz/AGENTS.md first;
113
+ This app runs on Copilotz (copilotz@1.0.0-rc.56). Read node_modules/copilotz/AGENTS.md first;
114
114
  https://copilotz.com/llms.txt lists the docs, as Markdown.
115
115
 
116
116
  - `npm test` runs every test offline, with a scripted model: run it after each change.
@@ -329,6 +329,61 @@ Test what callers may not do as well: call as someone else, and `assert.rejects`
329
329
  - **Online:** `devSignIn` is for this machine only; Copilotz won't start it with a public origin.
330
330
  Keep the `links` secret (32 bytes or more) across restarts, or MCP conversations start over.
331
331
 
332
+ ## The record and bytes
333
+
334
+ **The record lasts as the store does.** Each commit appends its events to the `events` table, and
335
+ the runtime never changes or deletes one. An event is `{ seq, id, type, data, cause, actor, at }`:
336
+ `cause` is the event behind it, `actor` the whole actor (`for`, `in`, `via`), `at` its commit's
337
+ time. `action.started` holds `{ action, input, inputHash, startedAt, attempt }`, `action.completed`
338
+ the `result`, a collection's event `{ _id, doc }`. Read it with `store.events(afterSeq, limit)` in a
339
+ test or script, `runtime.subscribe` live, or SQL (`sqlite3`, `psql`,
340
+ [maintenance](https://copilotz.com/docs/operations/maintenance.md)). Plugin code reads no log.
341
+
342
+ **Kept out:** a collection's `private` fields (keys, tokens), an Action's `private` fields, an
343
+ unrecorded Action's call (`record: false`; not its writes), and collections with `events: false` or
344
+ `durable: false`. All else an Action is given stays for good.
345
+
346
+ **Large values.** A string over 16 KiB is a blob, stored once by its hash: documents and events keep
347
+ a reference, and reads load it whole unless a `projection` leaves the field out. Blobs live in the
348
+ store, or in files or a bucket (`createRuntime({ blobs })`), chosen before it fills. A file is a
349
+ string (a `data:` address, base64). Nothing deletes a blob: a value deleted or replaced stays on the
350
+ record. [Stores](https://copilotz.com/docs/operations/stores.md) and
351
+ [BC 36](https://copilotz.com/docs/build-compass/part-12-shipping/36-postgresql-and-blobs.md) have
352
+ the rest.
353
+
354
+ **A list reads names, not pictures:** its query leaves them out (`projection: { picture: 0 }`), and
355
+ each row shows `/pictures/<id>`, a route that checks who asks before it reads. With `{ actor }`,
356
+ `runtime.bytes` reads only where a rule speaks for the collection (else it's refused); `service` has
357
+ none, so it's read as the system:
358
+
359
+ ```ts
360
+ import { definePlugin, people } from "copilotz";
361
+
362
+ const PICTURE = /^data:(image\/(?:png|jpeg|gif|webp));base64,(.+)$/;
363
+
364
+ export const pictures = definePlugin({
365
+ name: "pictures",
366
+ routes: {
367
+ "/pictures/:id": async (_request, { runtime, actor, params }) => {
368
+ const none = new Response("Not found", { status: 404 });
369
+ if (!people(actor)) return none;
370
+ const kept = await runtime.bytes("service", { _id: params.id }, "picture");
371
+ if (!kept) return none;
372
+ const text = new TextDecoder().decode(await kept.read(0, kept.size));
373
+ const [, type, base64] = PICTURE.exec(text) ?? [];
374
+ if (!base64) return none;
375
+ const body = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
376
+ return new Response(body, {
377
+ headers: { "content-type": type, "x-content-type-options": "nosniff" },
378
+ });
379
+ },
380
+ },
381
+ });
382
+ ```
383
+
384
+ **Common mistakes:** a list reading pictures whole; a key in an Action's input or in a field that
385
+ isn't `private`; a route reading before it checks who asks; counting on a delete to erase a file.
386
+
332
387
  ## A business app's web front end
333
388
 
334
389
  Screens for people at work: lists, forms in dialogs, dates, a home, printed documents.
@@ -455,8 +510,8 @@ The pieces, by job:
455
510
  - **File and image inputs:** `FileInput` (`accept`; `chooseLabel`, `changeLabel`, `removeLabel`;
456
511
  `current` and `onRemove` for a stored file). A picture chosen shows in an `Avatar`
457
512
  (`picture={URL.createObjectURL(file)}`, `initial={false}`). The form sends it to an Action as a
458
- `data:` address, the Action `private: ["picture"]` so its record doesn't keep it twice; big files
459
- are served by a route with `runtime.bytes`.
513
+ `data:` address; `private: ["picture"]` keeps it out of the call's record, and a list shows it
514
+ from a route (The record and bytes).
460
515
 
461
516
  **Common mistakes:**
462
517
 
package/CHANGELOG.md CHANGED
@@ -1,3 +1,29 @@
1
+ ## 1.0.0-rc.56 — 2026-11-18
2
+
3
+ A security fix: `runtime.bytes` no longer serves an outside actor what no rule speaks for. And the
4
+ docs of the record and bytes.
5
+
6
+ **Security:**
7
+
8
+ - **`runtime.bytes` reads for an actor only where a rule speaks for them.** With `{ actor }`, it
9
+ read under the rules, but a collection no rule speaks for has nothing to narrow, so it answered
10
+ any actor, the anonymous one too: a route of the app's that didn't check who asked served such a
11
+ collection's files to anyone. Now an actor (anyone but the system) reads only a collection a rule
12
+ speaks for, and their scope (a key's) lists, as their own reads from outside do; elsewhere, and in
13
+ `sys.*`, it's refused (`forbidden`). Without an actor, or as a grant, it reads as the system, as
14
+ before. Chat's `/files/<id>` is unchanged for people and contacts; a key now needs
15
+ `read: ["file"]` in its scope to fetch a file there. **Upgrading:** a route that passes
16
+ `{ actor }` for a collection with no rule (`shared` or a `guard`) is now refused: check who asks
17
+ in the route, then read as the system.
18
+
19
+ **Docs:**
20
+
21
+ - **Docs: the record and bytes.** AGENTS.md says what the record keeps and how to read it back, what
22
+ stays out of it (`private`, `record: false`, keys), where large values go (blobs, kept once by
23
+ hash, never deleted) and how a route serves one with `runtime.bytes`, once it has checked who
24
+ asks. Stores, the business app's guide (pictures in a list), Build Compass chapter 36 and Events
25
+ say the rest.
26
+
1
27
  ## 1.0.0-rc.55 — 2026-11-18
2
28
 
3
29
  What an app's first minutes ask of Copilotz: a welcome, a team people can shape, models chosen by
package/README.md CHANGED
@@ -152,7 +152,7 @@ ana sees: Tue 10:00, Wed 15:00
152
152
  ```sh
153
153
  npm install copilotz@next # Node 24+ (npm, pnpm, yarn)
154
154
  bun add copilotz@next # Bun
155
- deno add jsr:@copilotz/copilotz@^1.0.0-rc.55 # Deno 2.9+ (or `deno add npm:copilotz@next`)
155
+ deno add jsr:@copilotz/copilotz@^1.0.0-rc.56 # Deno 2.9+ (or `deno add npm:copilotz@next`)
156
156
  ```
157
157
 
158
158
  Until 1.0, the release candidates are on npm's `next` tag, and a plain `npm install copilotz` or
@@ -166,7 +166,7 @@ OPENAI_API_KEY=sk-… node salon.ts # or bun salon.ts, or deno run -A salon.t
166
166
  ```
167
167
 
168
168
  On Deno, map the name `copilotz` in `deno.json`
169
- (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.55"`) so the imports read the same everywhere.
169
+ (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.56"`) so the imports read the same everywhere.
170
170
  Copilotz runs on Node 24+, Deno 2.9+ and Bun, and it's built on web standards for Cloudflare Workers
171
171
  and the browser.
172
172
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "copilotz",
3
- "version": "1.0.0-rc.55",
3
+ "version": "1.0.0-rc.56",
4
4
  "description": "The open-source runtime that makes your app usable by people, your own agents and their assistants.",
5
5
  "keywords": [
6
6
  "agents",
@@ -1,2 +1,2 @@
1
1
  /** The computer program's version, as `computer.info` and `--version` say it, and its builds are named. */
2
- export declare const VERSION = "1.0.0-rc.55";
2
+ export declare const VERSION = "1.0.0-rc.56";
@@ -1,2 +1,2 @@
1
1
  /** The computer program's version, as `computer.info` and `--version` say it, and its builds are named. */
2
- export const VERSION = "1.0.0-rc.55";
2
+ export const VERSION = "1.0.0-rc.56";
@@ -10,7 +10,7 @@ export type BrowserSearch = (input: SearchInput & {
10
10
  blocked: boolean;
11
11
  }>;
12
12
  /** Who the fetch says it is: itself, not a browser it isn't. */
13
- export declare const AGENT = "copilotz-computer/1.0.0-rc.55";
13
+ export declare const AGENT = "copilotz-computer/1.0.0-rc.56";
14
14
  /** The results in a DuckDuckGo HTML page, in order. */
15
15
  export declare function parseResults(html: string, base?: string): SearchResult[];
16
16
  /** Whether a page is DuckDuckGo turning a robot away. */
@@ -14,7 +14,7 @@
14
14
  *
15
15
  * ```ts
16
16
  * plugins: [...plugins, await computerDownloads()]
17
- * plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.55" })]
17
+ * plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.56" })]
18
18
  * plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })]
19
19
  * ```
20
20
  */
@@ -73,6 +73,12 @@ export type Owner = {
73
73
  * as the system without one. Null when none is in reach, or its field
74
74
  * isn't a string.
75
75
  *
76
+ * An actor (anyone but the system) reads it only as they read the
77
+ * collection directly from outside: where a rule speaks for its reads by
78
+ * them, and their scope (a key's) lists it. Elsewhere it's refused
79
+ * (`forbidden`): a collection no rule speaks for is plugin code's alone,
80
+ * and the runtime's own (`sys.*`) nobody's outside.
81
+ *
76
82
  * The owner reads it itself, so it crosses no wire: a query's answer comes
77
83
  * whole from an executor over Oxian, no way to move megabytes. Nor does the
78
84
  * blob's reference leave the owner: the caller gets bytes, never a
package/runtime/owner.js CHANGED
@@ -615,15 +615,17 @@ export async function createOwner(options) {
615
615
  * Whether any rule speaks for a collection's reads (or writes) by this
616
616
  * actor: from outside, an actor reads (or writes) nothing else directly.
617
617
  * Asked as its own read (`direct`), with its filter: a rule may refuse one
618
- * it won't watch (thrown), as is one its scope doesn't list.
618
+ * it won't watch (thrown), as is one its scope doesn't list. Not `direct`
619
+ * for a read trusted host code makes for them once (`bytes`), which no rule
620
+ * watches.
619
621
  */
620
- const ruled = async (actor, collection, filter, access = "read") => {
622
+ const ruled = async (actor, collection, filter, access = "read", direct = true) => {
621
623
  if (!inScope(actor, access, collection)) {
622
624
  throw forbidden(`${actor.kind} ${actor.id} may not ${access} "${collection}": not in its scope.`);
623
625
  }
624
626
  let found = false;
625
627
  for (const guard of registry.guards) {
626
- const said = await guard(actor, { collection, access, ...(filter ? { filter } : {}), direct: true }, ruleReads);
628
+ const said = await guard(actor, { collection, access, ...(filter ? { filter } : {}), ...(direct ? { direct: true } : {}) }, ruleReads);
627
629
  if (said !== undefined)
628
630
  found = true;
629
631
  }
@@ -1828,6 +1830,16 @@ export async function createOwner(options) {
1828
1830
  };
1829
1831
  known(op);
1830
1832
  const { actor } = options;
1833
+ // For someone, only what they'd read from outside: a collection a rule speaks for, in their
1834
+ // scope. Without one, the rules have nothing to narrow, and the read would be everyone's.
1835
+ if (actor && actor.kind !== "system") {
1836
+ if (collection.startsWith(SYSTEM)) {
1837
+ throw forbidden(`"${collection}" is the runtime's own: nobody outside reads it.`);
1838
+ }
1839
+ if (!await ruled(actor, collection, filter, "read", false)) {
1840
+ throw forbidden(`No rule lets ${actor.kind} ${actor.id} read "${collection}".`);
1841
+ }
1842
+ }
1831
1843
  const [read] = (await guard([op], actor)).ops;
1832
1844
  const doc = await stored(store, read);
1833
1845
  const value = get(actor ? hidden(read, doc) : doc, field);