agentic-drive 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.9.0
+
+### Changed
+
+- **The web UI has a calm list view.** Files show in a table with sortable Name and Modified columns, a search that opens from a button, and a Share button next to the title of a folder. Select rows with the check boxes to see a bar at the bottom of the page that moves them all to the trash. A search with no match has its own empty state. The design classes in the list view are now `drive-*` classes of the app, not `agd-file-*` classes.
+
+## 0.8.0
+
+Read the breaking changes before you upgrade.
+
+### Breaking changes
+
+- **The design class prefix is now `agd-`.** The CSS classes, the custom properties, and the data attributes that used the old two-letter prefix change name. Ad blockers hide elements with the old prefix, so the prefix moved. There is no alias for the old names. Rename any class, custom property, or data attribute that you set or query so it starts with `agd-`. `agentic-design` moves from `^0.1.0` to `^0.4.0`, which uses the `agd-` prefix.
+- **The CLI uses `agentic-identity/file`.** The old `createFileStore` and `createFileBlobs` exports are gone: import them from `agentic-identity/file`. The local layout changes: the store is `store.json` in the data folder and blobs sit in `blobs/blobs/<hash>.blob`. `openLocal` now also returns `blobs`, and it throws on a folder with an old `db/store.jsonl` until `importLegacyLocal(dir, store, blobs)` (new, exported) has copied the old data. The CLI does this on its first run, once, and leaves the old files in place.
+
+### Added
+
+- Host operations: `findByRef`, `listTrashWithPaths`, and `claimRef` (put a reference and give a role, or do neither), in the SDK, the HTTP API (`GET /refs`, `POST /refs`, `GET /trash/paths`), the client, the CLI (`find-ref`, `claim-ref`, `trash --paths`), and MCP (`drive_find_ref`, `drive_claim_ref`, `drive_trash` with `paths`).
+- `ERROR_STATUS`, the map from each error code to its HTTP status, is exported from the root and `agentic-drive/worker`. `Node` and `ErrorCode` types are exported from the client and worker entries too.
+
+### Changed
+
+- **Transactions no longer nest store calls.** Access answers come from outside the transaction, so each transaction reads before it writes and runs on the file store of `agentic-identity/file`. A test runs the sharing and person suites on it.
+
 ## 0.7.0
 
 Read the breaking changes before you upgrade.

package/README.md

@@ -7,7 +7,7 @@
 
 Store, sort, and share files and folders.
 
-> Status: 0.7.0, early. The library, CLI, MCP server, and HTTP API work, with sharing in the SDK, the HTTP API, the CLI, and the MCP server.
+> Status: 0.9.0, early. The library, CLI, MCP server, and HTTP API work, with sharing in the SDK, the HTTP API, the CLI, and the MCP server.
 > A small web UI works. See [UI](#ui).
 
 ## Live demo
@@ -33,9 +33,10 @@ npm install agentic-drive
 ## Quick start
 
 ```ts
-import { createDrive, createFileStore, createFileBlobs } from "agentic-drive";
+import { createDrive } from "agentic-drive";
+import { createFileBlobs, createFileStore } from "agentic-identity/file";
 
-const drive = createDrive({ store: createFileStore("./data/db"), blobs: createFileBlobs("./data/blobs") });
+const drive = createDrive({ store: createFileStore({ path: "./data/db" }), blobs: createFileBlobs({ dir: "./data/blobs" }) });
 const me = { owner: "u1", actor: { id: "u1", kind: "human" as const } };
 
 await drive.mkdir(me, "/reports/2026", { parents: true });
@@ -91,7 +92,7 @@ curl -H "authorization: Bearer <token>" "$URL/api/v1/drive/items?path=/"
 
 Routes: `GET /items`, `GET /stat`, `POST /folders`, `PUT /files`, `GET /files`, `GET /url`,
 `POST /move`, `POST /trash`, `GET /trash`, `POST /restore`, `POST /purge`, `GET /search`,
-`GET /export`, `DELETE /account?confirm=yes`, `GET /home`, `POST /documents`, `DELETE /documents?ref=`.
+`GET /export`, `DELETE /account?confirm=yes`, `GET /home`, `POST /documents`, `DELETE /documents?ref=`, `GET /trash/paths`, `GET /refs?ref=`, `POST /refs`.
 Sign in with a bearer token from agentic-identity. The token is a credential in the `credentials` collection of
 the same D1 database, and it names a principal in `principals`. The Worker resolves the whole delegation chain on
 every request. A missing, expired, or revoked credential, or a revoked or expired principal (or one above it), gets 401.
@@ -124,7 +125,7 @@ try {
 }
 ```
 
-- One method for each bearer route and each shared route: `list`, `stat`, `mkdir`, `upload`, `download`, `url`, `move`, `trash`, `listTrash`, `restore`, `purge`, `search`, `export`, `deleteAccount`, `home`, `registerDocument`, `forgetDocument`, `shares`, `share`, `unshare`, `invite`, `acceptInvite`, `createLink`, `revokeLink`, `openShared`, `listShared`, and `readShared`.
+- One method for each bearer route and each shared route: `list`, `stat`, `mkdir`, `upload`, `download`, `url`, `move`, `trash`, `listTrash`, `restore`, `purge`, `search`, `export`, `deleteAccount`, `home`, `registerDocument`, `forgetDocument`, `findByRef`, `listTrashWithPaths`, `claimRef`, `shares`, `share`, `unshare`, `invite`, `acceptInvite`, `createLink`, `revokeLink`, `openShared`, `listShared`, and `readShared`.
 - Each method has typed input and output. The client checks the shape of every answer, and `download` checks the bytes against their hash (it needs WebCrypto). `readShared` does not: the Worker sends no hash there. An answer that fails a check throws `BAD_RESPONSE`. `url` gives a signed link that you fetch yourself. The last argument takes `{ signal }` to stop the call with an `AbortSignal`.
 - A failed call throws `DriveApiError`. It has the `code` of the API and the HTTP `status`. A call that gets no answer has the code `NETWORK_ERROR` and status 0. An abort stays the abort error of `fetch`. A code that the client does not know gives `BAD_RESPONSE`.
 - The client never sends a write again. `retries` (default 0) sends a read (GET) again after a network error or a 502, 503, or 504, with a short wait. A redirect is an error (`BAD_RESPONSE`, with the status of the redirect, or 0 in a browser): set `baseUrl` to the final URL.
@@ -146,12 +147,12 @@ The root export, `agentic-drive`, also exports these names. The package typings
   a control character (U+0000 to U+001F, or U+007F), or a name over 255 bytes in UTF-8. `parseSubject(input)` returns `{ kind, id }` for a valid subject, and throws
   `INVALID_SHARE` for any other input. `subjectKindOf(kind)` returns `human` or `agent`, and throws
   `INVALID_SHARE` for any other kind.
-- A `DriveError` has a `code` from `ErrorCode`, such as `NOT_FOUND` or `NAME_TAKEN`.
+- A `DriveError` has a `code` from `ErrorCode`, such as `NOT_FOUND` or `NAME_TAKEN`. `ERROR_STATUS` maps each code to the HTTP status that the Worker answers with (404 for `NOT_FOUND`, 409 for `NAME_TAKEN`, and so on). A host that serves the drive reuses it, and the `agentic-drive/worker` entry exports it too. The types `Node` and `ErrorCode` come from the root, `agentic-drive/client`, and `agentic-drive/worker`.
 - `readZip(bytes)` reads a zip that `writeZip` made, with stored (uncompressed) entries only. It returns a `Map`
   from each entry name to its bytes. It throws for a compressed entry. `writeZip(entries, at)` writes a zip with
   one `{ name, data }` entry for each file, and `at` sets the time in milliseconds. It throws for an unsafe
   name, such as one with `..` or a leading `/`.
-- The local drive has the functions behind the CLI. `openLocal(dir)` returns `{ drive, store }` for a folder.
+- The local drive has the functions behind the CLI. `openLocal(dir)` returns `{ drive, store, blobs }` for a folder. Call `await importLegacyLocal(dir, store, blobs)` first on a folder that an older version made. It copies the old data once, and it refuses when the new store already holds data.
   `addPrincipal(store, id, { parent?, scopes? })` makes a principal. `issueKey(store, principalId, label?)`
   returns the key. Keep it: the store keeps no plain copy. `resolveToken(store, token)` returns the caller, or throws `AuthError`
   with the code `UNAUTHENTICATED`. `revokeKey(store, token)` stops one key. `revokePrincipal(store, id)` stops a
@@ -202,7 +203,7 @@ drive.update({ baseUrl, getToken });  // use another server or callback
 drive.unmount();                      // remove the UI
 ```
 
-`getToken` returns 1 to 512 letters, digits, `-` or `_`, or `undefined` to send no `authorization` header. A bad `baseUrl` or a `getToken` that is not a function makes `mount` throw a `TypeError`. The server still checks every request against the token. The embed shows files and trash with upload, rename, move, share, and the "Created by agent" label. It has no sign-in form, because your app owns sign-in. It does not change the page address, and it has no theme switch. `agentic-design/styles.css` sets base styles for the whole page, and it follows the dark mode of the system unless your page sets `data-theme`. Add `agentic-design` to your own dependencies, because your page imports its files. The Worker sends no CORS headers, so the server must be on the origin of your page. Set `baseUrl` to the same address as `DRIVE_PUBLIC_URL`, or the UI refuses its download links. `unmount` and `update` abort the requests that run and stop an upload that has more files to send. The UI keeps the list or grid choice in `localStorage` under `agentic-drive-view`, and it has its own heading for each view. Dialogs, menus, and messages render in `document.body`, outside your element. A click with Ctrl, Cmd, Shift, or the middle button on a folder link does not open the folder. The class names start with `drive-`. `DriveBrowser` is the same UI as a React component. It closes its requests when it unmounts. Wrap it in `TooltipProvider` and `ToastProvider` from `agentic-design/react`. `react` and `react-dom` (version 19 or later) are optional peer dependencies. Install them in your project when you use `agentic-drive/ui`. The web UI that the Worker serves uses the same views.
+`getToken` returns 1 to 512 letters, digits, `-` or `_`, or `undefined` to send no `authorization` header. A bad `baseUrl` or a `getToken` that is not a function makes `mount` throw a `TypeError`. The server still checks every request against the token. The embed shows files and trash with upload, rename, move, share, and the "Created by agent" label. It has no sign-in form, because your app owns sign-in. It does not change the page address, and it has no theme switch. `agentic-design/styles.css` sets base styles for the whole page, and it follows the dark mode of the system unless your page sets `data-theme`. Add `agentic-design@^0.4.0` to your own dependencies, because your page imports its files. The Worker sends no CORS headers, so the server must be on the origin of your page. Set `baseUrl` to the same address as `DRIVE_PUBLIC_URL`, or the UI refuses its download links. `unmount` and `update` abort the requests that run and stop an upload that has more files to send. The UI keeps the list or grid choice in `localStorage` under `agentic-drive-view`, and it has its own heading for each view. Dialogs, menus, and messages render in `document.body`, outside your element. A click with Ctrl, Cmd, Shift, or the middle button on a folder link does not open the folder. The class names start with `drive-`. The design-system classes start with `agd-`. `DriveBrowser` is the same UI as a React component. It closes its requests when it unmounts. Wrap it in `TooltipProvider` and `ToastProvider` from `agentic-design/react`. `react` and `react-dom` (version 19 or later) are optional peer dependencies. Install them in your project when you use `agentic-drive/ui`. The web UI that the Worker serves uses the same views.
 
 ### Serve the UI from the package
 
@@ -278,6 +279,7 @@ export default { fetch: app.fetch };
 - `downloadUrl()` returns a signed URL. The URL signs an attachment header with the file name and the stored type. The Worker verifies it and serves the bytes with those headers, so the link holder cannot change how the bytes are served. A link lasts 15 minutes by default and 1 hour at most. Trashing a file does not revoke a link already issued.
 - `search()` finds live items by name, type, kind, size, and who made them.
 - App documents: an app calls `registerDocument({ ref: "docs:<id>", name, folder })` to put a document in the drive, and `forgetDocument(ref)` when it deletes the document. `home({ app })` lists files and every app's documents together, newest change first, with a count per app. `search({ app })` filters the same way. The CLI has `home`, `register`, and `forget`. The MCP server has `drive_home`, `drive_register_document`, and `drive_forget_document`.
+- Host operations. `findByRef(ref)` returns `{ node, path }` for each live reference to an app document in the caller's own drive that the caller can read, sorted by path (a reference that sits in a drive shared with the caller is not listed). `listTrashWithPaths()` lists what is in the trash (it reads the whole drive, so it costs more than `listTrash` on a big one), newest first, with the path each item had before. `claimRef(path, ref, { subject, role }, opts)` puts a reference and gives the subject a role on it as one step: if the grant fails (a bad subject or role, or a caller who is not an owner of the new item), the reference is removed again, the error is thrown, and the name is free. Folders that `parents` made stay. `onConflict: "replace"` acts as `fail` here, because a rollback could not bring back an item that was replaced. It needs sharing. The rollback is not a database transaction, because identity's sharing writes outside one: another caller can see the reference for a moment before it goes. The routes are `GET /refs?ref=`, `POST /refs`, and `GET /trash/paths`. The CLI has `find-ref`, `claim-ref`, and `trash --paths`. The MCP server has `drive_find_ref`, `drive_claim_ref`, and `drive_trash` with `paths`.
 - `buildExport()` writes everything one person has to a zip with a `manifest.json` (format version 2). It names the person by id and kind. It lists the person's own items (trashed ones are flagged, and a file whose bytes are gone is marked `missing`). For the person in person it also lists the ids of what they or their agents made or changed in other drives (no names, and nothing of the people who own them), the shares they hold, the invites they sent, and the audit entries of what they and their agents did. An agent gets `partial: true` and none of that. Invitee emails and link tokens are never in it. Entries are named by item id.
 - `erasePerson()` erases a person for good, and only the person in person can call it (the CLI `delete-all` and `DELETE /account` call it). It deletes their drive with all its shares, the shares they hold, and the invites they or their agents sent, on drive items only: the grants of other apps stay for those apps and for identity. What they or their agents made in other drives stays, because it belongs to those drives: the id becomes `erased`, and the kind stays, so machine-made work keeps its label. Agents are found through the `principals` collection, as identity finds them: an agent with its own identity names the person as `ownerId`, and a delegated agent names its parent. An agent with its own identity belongs to the person, and so does its drive: erase deletes it, and the export lists its items (no bytes). A person with more than 1000 agents cannot be erased here: the call fails and deletes nothing more. The audit entries of the erased items go with them, through identity `deleteResource`. The entries about what the person did in other drives stay: they hold ids and kinds only. A failed call can run again. `deleteAll()` is the drive part alone.
 - A `can()` hook decides who may read, write, or delete. Without `sharing`, the default allows the owner only.
@@ -289,9 +291,9 @@ export default { fetch: app.fetch };
 - There are no retention settings yet, and no per-workspace export. An export covers one person.
 - `registerDocument` makes one item per document in a drive. Two calls at the same moment can make two.
 
-- Drive reads the `store_docs` table in D1 and `store.jsonl` in the CLI folder. It does not read older layouts. There is no import and no claim backfill.
+- Drive reads the `store_docs` table in D1. The CLI keeps its data in the file store of `agentic-identity/file`. On first run it copies data from an old `store.jsonl` journal and hashed blob files in the same folder, once, and leaves the old files in place. Drive reads no other older layout, and there is no claim backfill.
 - Uploads buffer the stream in memory up to the cap. The default cap is 25 MiB (`DEFAULT_MAX_BYTES`).
-- Local file blobs return a `file:` URL that nothing serves or checks.
+- The CLI folder has no signing secret, so its blobs make no download URL. The Worker signs its own.
 - Drive writes each new blob only when its key is free (`ifNoneMatch`). A write that finds the key taken fails with `BLOB_EXISTS`.
 - Only `upload()` enforces the size cap. A caller of `putFile()` must check size first.
 - A claimed type that a browser would run (HTML, SVG, scripts) is stored as `application/octet-stream`.

package/dist/chunk-AB2RTTHJ.js

@@ -0,0 +1,59 @@
+// src/legacy.ts
+import { createHash } from "crypto";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+async function importLegacyLocal(dir, store, blobs) {
+  const journal = join(dir, "db", "store.jsonl");
+  if (!existsSync(journal) || await store.get("drive_meta", "legacy_import")) return;
+  const lines = readFileSync(journal, "utf8").split("\n");
+  const tail = lines.pop();
+  const docs = /* @__PURE__ */ new Map();
+  const isChange = (c) => Array.isArray(c) && c.length === 3 && typeof c[0] === "string" && typeof c[1] === "string" && (c[2] === null || typeof c[2] === "object" && !Array.isArray(c[2]));
+  const replay = (line, at) => {
+    let changes;
+    try {
+      changes = JSON.parse(line);
+    } catch {
+      throw new Error(`the journal ${journal} has a bad line ${at}`);
+    }
+    if (!Array.isArray(changes) || !changes.every(isChange)) throw new Error(`the journal ${journal} has a bad line ${at}`);
+    for (const change of changes) docs.set(`${change[0]}\0${change[1]}`, change);
+  };
+  for (const [i, line] of lines.entries()) if (line !== "") replay(line, i + 1);
+  if (tail !== "") {
+    let cut = false;
+    try {
+      JSON.parse(tail);
+    } catch {
+      cut = true;
+    }
+    if (!cut) replay(tail, "last");
+  }
+  let missing = 0;
+  const path = (key) => join(dir, "blobs", createHash("sha256").update(key).digest("hex"));
+  for (const [collection, , doc] of docs.values()) {
+    const key = collection === "drive_nodes" ? doc?.blobKey : void 0;
+    if (typeof key !== "string") continue;
+    if (!existsSync(path(key))) {
+      missing++;
+      continue;
+    }
+    const type = existsSync(`${path(key)}.type`) ? readFileSync(`${path(key)}.type`, "utf8") : void 0;
+    await blobs.put(key, new Uint8Array(readFileSync(path(key))), { ifNoneMatch: "*", ...type ? { contentType: type } : {} });
+  }
+  if (missing > 0) console.error(`import: ${missing} old blob files are missing, so those files cannot be read.`);
+  await store.transaction(async (tx) => {
+    if (await tx.get("drive_meta", "legacy_import")) return;
+    for (const collection of ["drive_nodes", "drive_names", "principals"]) {
+      if ((await tx.query(collection, { limit: 1 })).items.length > 0) {
+        throw new Error(`the folder holds old data and new data, and the old data was not imported. Move ${journal} away or import by hand.`);
+      }
+    }
+    for (const [collection, id, doc] of docs.values()) if (doc) await tx.put(collection, id, doc);
+    await tx.put("drive_meta", "legacy_import", { importedAt: Date.now() });
+  });
+}
+
+export {
+  importLegacyLocal
+};

package/dist/{chunk-EFO5PSJL.js → chunk-IMWV5QEH.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.7.0" : readPackageVersion();
+var VERSION = true ? "0.9.0" : readPackageVersion();
 
 export {
   VERSION

package/dist/{chunk-S4AGCKXW.js → chunk-LELTSSZF.js}

@@ -214,6 +214,12 @@ function createClient(options) {
     /** Erases the caller for good. The client sends `confirm=yes`. */
     deleteAccount: (o = {}) => json("DELETE", "/account?confirm=yes", o, numbers("removed", "grants", "invites", "anonymized")),
     home: (q = {}, o = {}) => json("GET", `/home${query(q)}`, o, isHome),
+    /** The live references to `ref`, with their paths. */
+    findByRef: (ref, o = {}) => json("GET", `/refs${query({ ref })}`, o, listOf(isPathItem)),
+    /** Items in the trash, newest first, each with the path it had before. */
+    listTrashWithPaths: (o = {}) => json("GET", "/trash/paths", o, listOf(isPathItem)),
+    /** Puts a reference and gives the subject a role on it, or does neither. Needs sharing. */
+    claimRef: (input, o = {}) => json("POST", "/refs", { json: { path: input.path, ref: input.ref, subjectKind: input.subject.kind, subjectId: input.subject.id, role: input.role, parents: input.parents, onConflict: input.onConflict }, ...o }, isItem),
     registerDocument: (input, o = {}) => json("POST", "/documents", { json: input, ...o }, isItem),
     forgetDocument: (ref, o = {}) => json("DELETE", `/documents${query({ ref })}`, o, numbers("trashed")),
     shares: (path, o = {}) => json("GET", `/shares${query({ path })}`, o, isShares),