@mainsoft/agent-cms 0.7.0 → 0.10.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 (111) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +291 -32
  3. package/TODO.md +72 -26
  4. package/UPGRADE-0.10.md +36 -0
  5. package/UPGRADE-0.8.md +117 -0
  6. package/dist/agent.cjs +39 -17
  7. package/dist/agent.d.cts +2 -2
  8. package/dist/agent.d.ts +2 -2
  9. package/dist/agent.js +9 -7
  10. package/dist/bin.js +4528 -355
  11. package/dist/{chunk-OQ55GEF3.js → chunk-3OPKTBEI.js} +1 -1
  12. package/dist/chunk-6PB4ZCHH.js +328 -0
  13. package/dist/chunk-7SCYDG2G.js +2943 -0
  14. package/dist/chunk-7WJIIJCI.js +544 -0
  15. package/dist/chunk-7Y6TU2UA.js +150 -0
  16. package/dist/{chunk-EXV6JNLY.js → chunk-AKCXMT3X.js} +15 -22
  17. package/dist/{chunk-QC2M4NZY.js → chunk-BFVBHIHV.js} +72 -1
  18. package/dist/chunk-DSJETZT4.js +493 -0
  19. package/dist/{chunk-IW3D4I7Q.js → chunk-IU2SMWAM.js} +246 -4
  20. package/dist/{chunk-VICZ76TR.js → chunk-KAO3Z3CF.js} +43 -2
  21. package/dist/{chunk-CRDW6Q72.js → chunk-MA6VKJ3F.js} +87 -25
  22. package/dist/{chunk-6K5ZTGHQ.js → chunk-PEQY4N73.js} +16 -0
  23. package/dist/{chunk-DOADAH4L.js → chunk-PGV2QPIL.js} +40 -0
  24. package/dist/{chunk-Y63XQS2J.js → chunk-TOZQYJFG.js} +1 -1
  25. package/dist/cli.cjs +4528 -355
  26. package/dist/cli.d.cts +19 -3
  27. package/dist/cli.d.ts +19 -3
  28. package/dist/cli.js +206 -16
  29. package/dist/client.cjs +72 -1
  30. package/dist/client.d.cts +308 -6
  31. package/dist/client.d.ts +308 -6
  32. package/dist/client.js +1 -1
  33. package/dist/cms-C_vkAxYV.d.cts +1537 -0
  34. package/dist/cms-pqJyowu1.d.ts +1537 -0
  35. package/dist/config.d.cts +7 -1
  36. package/dist/config.d.ts +7 -1
  37. package/dist/drizzle-repo-CviH3EX7.d.cts +146 -0
  38. package/dist/drizzle-repo-DWLD0rWe.d.ts +146 -0
  39. package/dist/errors.cjs +82 -1
  40. package/dist/errors.d.cts +43 -3
  41. package/dist/errors.d.ts +43 -3
  42. package/dist/errors.js +2 -2
  43. package/dist/frontmatter.d.cts +5 -4
  44. package/dist/frontmatter.d.ts +5 -4
  45. package/dist/http.cjs +640 -94
  46. package/dist/http.d.cts +51 -2
  47. package/dist/http.d.ts +51 -2
  48. package/dist/http.js +203 -13
  49. package/dist/index.cjs +3759 -575
  50. package/dist/index.d.cts +8 -8
  51. package/dist/index.d.ts +8 -8
  52. package/dist/index.js +226 -30
  53. package/dist/markdown.cjs +89 -25
  54. package/dist/markdown.d.cts +57 -3
  55. package/dist/markdown.d.ts +57 -3
  56. package/dist/markdown.js +5 -1
  57. package/dist/mcp.cjs +314 -37
  58. package/dist/mcp.d.cts +3 -2
  59. package/dist/mcp.d.ts +3 -2
  60. package/dist/mcp.js +12 -9
  61. package/dist/messages/en.cjs +40 -0
  62. package/dist/messages/en.js +1 -1
  63. package/dist/messages/ko.cjs +40 -0
  64. package/dist/messages/ko.js +40 -0
  65. package/dist/registry/cms-audit.json +1 -1
  66. package/dist/registry/cms-doc-editor.json +15 -4
  67. package/dist/registry/cms-doc-list.json +2 -1
  68. package/dist/registry/cms-files.json +29 -0
  69. package/dist/registry/cms-lib.json +3 -3
  70. package/dist/registry/cms-media-picker.json +29 -0
  71. package/dist/registry/cms-media.json +28 -0
  72. package/dist/registry/cms-preview-comments.json +24 -0
  73. package/dist/registry/cms-releases.json +28 -0
  74. package/dist/registry/cms-shell.json +2 -2
  75. package/dist/registry/cms-trash.json +24 -0
  76. package/dist/registry/cms-versions.json +2 -1
  77. package/dist/registry/registry.json +163 -3
  78. package/dist/storage-s3.cjs +168 -0
  79. package/dist/storage-s3.d.cts +53 -0
  80. package/dist/storage-s3.d.ts +53 -0
  81. package/dist/storage-s3.js +143 -0
  82. package/dist/storage.cjs +373 -0
  83. package/dist/storage.d.cts +183 -0
  84. package/dist/storage.d.ts +183 -0
  85. package/dist/storage.js +49 -0
  86. package/dist/tables.cjs +251 -3
  87. package/dist/tables.d.cts +4965 -681
  88. package/dist/tables.d.ts +4965 -681
  89. package/dist/tables.js +14 -2
  90. package/dist/tools.cjs +331 -20
  91. package/dist/tools.d.cts +54 -7
  92. package/dist/tools.d.ts +54 -7
  93. package/dist/tools.js +16 -7
  94. package/dist/types.cjs +99 -1
  95. package/dist/types.d.cts +205 -5
  96. package/dist/types.d.ts +205 -5
  97. package/dist/types.js +5 -3
  98. package/package.json +32 -22
  99. package/dist/ai.cjs +0 -555
  100. package/dist/ai.d.cts +0 -48
  101. package/dist/ai.d.ts +0 -48
  102. package/dist/ai.js +0 -73
  103. package/dist/chunk-52NUUZC7.js +0 -1446
  104. package/dist/chunk-IGL2V6US.js +0 -324
  105. package/dist/chunk-QQV6VLYJ.js +0 -204
  106. package/dist/cms-BPp01z-8.d.ts +0 -411
  107. package/dist/cms-D6D89-qZ.d.cts +0 -411
  108. package/dist/drizzle-repo-B1rt7r4j.d.ts +0 -90
  109. package/dist/drizzle-repo-Cn-kL2FK.d.cts +0 -90
  110. package/dist/repo-BWI2Pkrv.d.ts +0 -162
  111. package/dist/repo-CeDxUxO6.d.cts +0 -162
package/CHANGELOG.md CHANGED
@@ -1,5 +1,65 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.10.0
4
+
5
+ The first npm release since 0.7.0. It contains 0.8.0 and 0.9.0 below, which were not published on their own: coming from 0.7.0, read [UPGRADE-0.8.md](./UPGRADE-0.8.md) first, then [UPGRADE-0.10.md](./UPGRADE-0.10.md).
6
+
7
+ The editing and publishing flow: its rules, REST routes, admin client, agent tools and screens. Read [UPGRADE-0.10.md](./UPGRADE-0.10.md): deletes now go to a trash, and the schema is version 4.
8
+
9
+ - **Scheduled publishing:** `cms.schedule(actor, col, slug, { publishAt, unpublishAt })`. What goes public is the version that was current when it was scheduled, not what the draft holds later. `cms.runScheduled()` does what is due; the `/_cron` route calls it and has its own secret (`createCms({ cronSecret })`, `Authorization: Bearer`). A version that no longer passes its checks is not published and the failure is in the audit log.
10
+ - **Trash:** a deleted document or file goes to the trash for 30 days (`createCms({ trash: { days } })`, `0` deletes at once). It is gone for readers, search and agents, keeps its address, and comes back as it was. `cms.trash.list / restore / purge`; purging is for admins; `runScheduled` empties what is older.
11
+ - **Review:** `defineCollection({ review: { agents: "required" } })` stops API keys and agents acting for a person from publishing a version nobody approved (`review_required`); `everyone: "required"` also stops people from approving their own request. `requestReview`, `approveReview` (publishes exactly the requested version), `rejectReview` (with a note), `reviewRequests`.
12
+ - **Comments:** threads on a section and a quoted piece of text, answers one level deep, resolve and reopen. Each thread says whether its text is still there. A preview link made with `comments: true` lets its holder read and write them without an account.
13
+ - **Releases:** documents that go out together, each pinned at a version. `cms.releases.publish` is one transaction: any blocked document stops all of it and the error lists what blocked. A release can be scheduled.
14
+ - **Versions:** a name and a pin (`labelVersion`); pinned versions are never pruned.
15
+ - **Saved filters**, **presence** (who has a document open, also agents while they save) and **`cms.preview`** (blocks with source lines, table of contents, problems and diff of unsaved text; `parseMarkdown(src, { lines: true })`).
16
+ - List states `scheduled` and `review`; `counts` has both.
17
+ - Agent tools (16 → 31, plus the file tools): `schedule_document`, `unschedule_document`, `request_review`, `list_review_requests`, `list_comments`, `add_comment`, `resolve_comment`, `list_trash`, `restore_from_trash`, `list_releases`, `create_release`, `add_to_release`, `publish_release`, `label_version`, `preview_document`. Approving a review is a person's job and has no tool.
18
+ - Schema version 4 (run `npx agent-cms migrate apply`).
19
+
20
+ Screens (`npx agent-cms add --update`, then `add cms-trash cms-releases`):
21
+
22
+ - **`cms-doc-editor`:** the publish button has a schedule panel (times on the clock of `createCms({ timeZone })`, which `GET /_me` now returns); strips under the header show a schedule, a review request ("Send back", "Approve and publish") and the release the document is in; a comments panel (a tab on phones) with marks on the commented text; who else has the document open, their cursors, and their saves merged into unsaved edits that do not overlap (`presenceMs`); "Add to a release"; "Allow comments" on preview links. The item has a second file, `cms-flow.tsx`.
23
+ - **`cms-doc-list`:** "Scheduled" and "In review" tabs and badges, who has a document open, saved filters. It needs the shadcn `label` part now.
24
+ - **`cms-trash`** (new) and **`cms-releases`** (new: `<CmsReleases>` and `<CmsRelease id>`); `cms-shell` links to both for people who can edit (`CmsShellTarget` has `releases` and `trash`).
25
+ - **`cms-versions`:** name a version, pin it, see who approved it. It needs the shadcn `dialog` and `input` parts now.
26
+ - Fix: on a phone the state tabs of `cms-doc-list` pushed the page sideways once there were seven of them. They now scroll inside their own row, and a tab you press comes fully into view.
27
+ - Korean copy picks the particle that fits a name ("김지수가", "docs-bot이"): `format()` reads `{who|이|가}`.
28
+ - **Paste clean-up** in the body: HTML from a web page, Google Docs or Word becomes markdown (headings, lists, bold, italic, links, tables, code, quotes, https images); zero-width characters, non-breaking spaces and curly quotes are tidied; a paste from a code editor stays plain text. No new dependency. Third file of the item: `cms-paste.ts`.
29
+ - **`cms-preview-comments`** (new): the comment box for guests on your public preview page.
30
+ - Not in this release: a CodeMirror editor (the body stays a text box, with a layer behind it for marks and cursors), section reordering, preview scroll sync, and a click in the preview that finds the line in the body.
31
+
32
+ ## 0.9.0 (released as part of 0.10.0)
33
+
34
+ - **File manager:** `cms-files` shows a storage bucket as it is, folder by folder, also files nobody uploaded through the CMS. Move, download, share links and delete for several files and whole folders at once; opening a file shows the media library's panel. `cms-shell` shows "Files" to whoever may look around a store (`access.browse`, default: whoever may read it).
35
+ - A file the CMS did not know gets a row when it is opened, shared or registered (`cms.assets.register`), and then works in documents. `agent-cms storage sync` registers a whole bucket and lists rows whose file is gone.
36
+ - Share links: `cms.assets.share(actor, id, { ttl: "1h" | "24h" | "7d" })`. A private file's link is a signed address that cannot be taken back; a public file gives its public address. Needs the permission to delete in the store; audited as `asset.share`.
37
+ - REST: `GET /stores/:store/files`, `…/_open`, `POST …/_register`, `…/_move`, `…/_delete` (`check: true` only counts), `POST /assets/:id/share`. Agent tools (22 → 25 with a media library): `list_store_files`, `register_asset`, `create_share_link`.
38
+ - **Media library:** "Import from URL" in the header fetches a public https address into the open folder (the same guarded path as `import_asset`), and a file can be renamed in its panel (the extension is kept; documents keep working).
39
+ - `media.scan`: the app's own check of every file that arrives (a virus scanner, a content policy). A refused file is deleted and the caller gets `asset_rejected`; a check that throws refuses too.
40
+ - Fix: `cms-media` no longer uses `asChild` on a button, which exists only in the Radix flavour of shadcn/ui. Apps on the Base UI flavour failed to typecheck after `add cms-media`. Found by moving this project's own docs site to 0.8.
41
+ - The docs site (`apps/docs`) runs on this version: its copied screens are updated, it documents the media library, the file manager and the tools without `./ai`, and its gallery has a read-only media demo.
42
+ - No schema change.
43
+
44
+ ## 0.8.0 (released as part of 0.10.0)
45
+
46
+ Read [UPGRADE-0.8.md](./UPGRADE-0.8.md). What comes next is in [docs/roadmap](./docs/roadmap/README.md).
47
+
48
+ - **Breaking: the `./ai` entry and the optional `ai` peer dependency are removed.** This package hands agents tools and never calls a model, and it no longer depends on a library that does. MCP, REST, the CLI and `./tools` are unchanged. A test keeps model libraries out of the sources and the dependencies.
49
+ - **`callTool`, `runTool`, `toolErrorResult`** in `./tools`: run a tool by name as an actor, with CMS errors returned as results. Together with `toolsFor` this is the way to give the tools to an agent in your app, whatever framework runs it. MCP runs tools through the same path.
50
+ - **An agent acting for a person:** `{ kind: "user", …, agent: { label } }`. Same permissions as the person; versions, the document and the audit log record the agent's name, and its edits are listed under "Agent changes". Requests cannot set it. The admin shows such authors as "agent, person".
51
+ - **Schema version 3** (`agent-cms migrate apply`): three nullable columns for the above, and the tables `cms_assets` and `cms_asset_refs` for the media library, with the matching `CmsRepo` methods.
52
+ - **Media library screens:** `cms-media` (stores and folders, grid and list, search, type tabs, a panel with a file's alt text, tags and the documents that use it, delete with a look at its uses, a phone layout) and `cms-media-picker` (the "choose media" dialog). The editor gets "Insert media", image and file fields, and media in the preview. `cms-shell` shows "Media" when the app has a library. Uploads go from the browser straight to the storage with progress, parts for large files, automatic retry of a failed part and "Try again" for what is missing; the browser makes the thumbnail.
53
+ - `<CmsProvider slots={{ assetAlt }}>`: a place for an extension package next to a file's alt text.
54
+ - The example app has a media library when it is given a storage (`npm run s3:dev`), and its public page renders media blocks.
55
+ - **Media library (server side):** `createCms({ media: { stores } })` with `s3Storage` from `./storage-s3` (AWS S3, Cloudflare R2, MinIO; signed with `aws4fetch`, no AWS SDK). Files go from the browser straight to the storage with signed addresses; files over 16MB go up in parts and a broken upload resumes with the missing parts. Public and private stores; private files open through `GET /files/:id/:name` after a permission check, with a link that works for 5 minutes.
56
+ - **What may be uploaded is the developer's choice** at three levels (`media.accept`, `stores.<name>.accept`, `admin.fields.<field>.accept`; the same for `maxFileSize`, default 5GB). The default list has no web pages or programs. The server checks the first bytes of what arrived and deletes a file that is not what its name says.
57
+ - **Files in documents:** `![alt](asset:ID/name "caption")`, `[label](asset:ID/name)` and `![alt](https://…)` in markdown (`media` blocks, `image` and `file` inlines in `parseMarkdown`); field widgets `image` and `file` with `assetId()`; `cms.assetsFor(doc)` and `cms.imageUrl(asset, { width })` for rendering. Saving checks the files a document names (`asset_missing`, `asset_wrong_kind`, `asset_alt_missing`, `asset_private_in_public`), and the CMS records which documents use which file, so deleting a file in use asks first (`asset_in_use`).
58
+ - **REST:** `/assets` (list, folders, uploads, import, edit, move, delete) and `/files`; `_me.media`; `createRestClient` methods. **Agent tools (16 → 22):** `list_assets`, `get_asset`, `import_asset` (https only; addresses inside the network are refused, also after redirects), `update_asset`, `move_asset`, `delete_asset`. **CLI:** `agent-cms upload`, `agent-cms storage check | cleanup`; `doctor` reports unfinished uploads.
59
+ - New entries `./storage` (`StorageAdapter`, `MemoryStorage`, `DEFAULT_ACCEPT`) and `./storage-s3`. New dependency: `aws4fetch` (no dependencies of its own). `scripts/s3-dev.sh` starts a local S3-compatible server for tests and the example.
60
+ - The audit log's route label "AI SDK" is now "Agent".
61
+ - Roadmap: `docs/roadmap/` holds one document per bundle of planned work (design, defaults, done criteria) and the approved screen mockups; `TODO.md` gained items 107 to 135.
62
+
3
63
  ## 0.7.0
4
64
 
5
65
  - **Anonymous MCP read:** `createCmsHandler({ mcp: { anonymous: "read" } })` lets agents use `/mcp` without a key. They get the read tools only (`ANONYMOUS_READ_TOOLS`) and see published documents of collections anyone may read. Off by default.
package/README.md CHANGED
@@ -12,15 +12,16 @@ notes, a help center, internal docs, a notice board.
12
12
  archive, restore. Two writers never overwrite each other: a stale save is a
13
13
  conflict (409) that carries the other person's copy, and the admin screen
14
14
  merges the two line by line.
15
- - **Agents are first-class editors.** One tool list, four ways in:
16
- - **AI SDK tools** (`./ai`) for your own agent: `cmsTools(cms, actor)`
17
- in-process, or `remoteCmsTools({ url, key })` against another app. They
18
- are plain AI SDK `Tool`s, so they also work unchanged with anything built
19
- on the AI SDK, such as slash-agent-sdk.
15
+ - **Agents are first-class editors.** One tool list, three ways in:
20
16
  - **MCP** at `/api/cms/mcp` for coding agents (Claude Code, Cursor, …),
21
17
  served with the official MCP SDK.
22
18
  - **CLI** (`agent-cms put notes/launch.md --publish`) for agents with a shell.
23
19
  - **REST** for everything else.
20
+
21
+ The list itself is in `./tools` (`toolsFor`, `callTool`), so an agent
22
+ running inside your app gets the same tools whatever framework runs it.
23
+ This package never calls a model: the model, its key and the agent loop
24
+ stay with you.
24
25
  Agents change one section at a time (`patch_document`), check a draft
25
26
  before saving (`diagnose_document`), and people review what agents changed
26
27
  block by block.
@@ -40,6 +41,7 @@ notes, a help center, internal docs, a notice board.
40
41
  > Design follows [Payload](https://payloadcms.com)'s collection, version and
41
42
  > MCP shapes, written to run on Next.js 14+/React 18 and Postgres + Drizzle.
42
43
 
44
+ Used `./ai`? It is gone: read [UPGRADE-0.8.md](./UPGRADE-0.8.md).
43
45
  Upgrading from 0.5? Read [UPGRADE-0.6.md](./UPGRADE-0.6.md) first (the
44
46
  `cms_gaps` table needs moving before anything drops it). Changes are in
45
47
  [CHANGELOG.md](./CHANGELOG.md).
@@ -51,9 +53,9 @@ npm i @mainsoft/agent-cms
51
53
  npx agent-cms init
52
54
  ```
53
55
 
54
- Peer dependencies: `drizzle-orm`, `zod` (`^3.25` or `^4`), and `ai` (only for
55
- `./ai`). `init` writes `agent-cms.config.ts`, `lib/cms.ts`, the API route,
56
- a schema re-export and `.env.example` lines, and never overwrites a file.
56
+ Peer dependencies: `drizzle-orm` and `zod` (`^3.25` or `^4`). `init` writes
57
+ `agent-cms.config.ts`, `lib/cms.ts`, the API route, a schema re-export and
58
+ `.env.example` lines, and never overwrites a file.
57
59
 
58
60
  ## Set up
59
61
 
@@ -61,7 +63,7 @@ a schema re-export and `.env.example` lines, and never overwrites a file.
61
63
  them, or put the SQL in a migration:
62
64
 
63
65
  ```ts
64
- export { cmsDocuments, cmsVersions, cmsApiKeys, cmsHits, cmsMeta, cmsAudit } from "@mainsoft/agent-cms/tables";
66
+ export { cmsDocuments, cmsVersions, cmsApiKeys, cmsHits, cmsMeta, cmsAudit, cmsAssets, cmsAssetRefs } from "@mainsoft/agent-cms/tables";
65
67
  ```
66
68
 
67
69
  ```
@@ -146,7 +148,7 @@ they go and how imports are written) and talk to the CMS through
146
148
 
147
149
  ```
148
150
  npx agent-cms add --list
149
- npx agent-cms add cms-shell cms-doc-list cms-doc-editor cms-versions cms-keys cms-audit cms-command
151
+ npx agent-cms add cms-shell cms-doc-list cms-doc-editor cms-versions cms-keys cms-audit cms-command cms-media cms-files cms-trash cms-releases
150
152
  npx agent-cms add --diff # what a new release would change in your copies
151
153
  npx agent-cms add --update # update files you did not edit; yours get a .new copy
152
154
  ```
@@ -176,6 +178,12 @@ npx shadcn@latest add <registry-url>/cms-doc-editor.json
176
178
  | `cms-keys` | Keys with expiry; the secret is shown once with MCP and CLI set-up |
177
179
  | `cms-audit` | Who did what, filterable |
178
180
  | `cms-command` | ⌘K to find any document, drafts included |
181
+ | `cms-media` | The media library: stores and folders, grid or list, a file's alt text, tags and the documents that use it, uploads with progress, delete with a look at where the file is used |
182
+ | `cms-media-picker` | The "choose media" dialog behind image and file fields and the editor's "Insert media" (comes with `cms-doc-editor`) |
183
+ | `cms-files` | The file manager: a bucket folder by folder, also files nobody uploaded through the CMS; move, download, share links and delete for several at once |
184
+ | `cms-trash` | Deleted documents and files: restore, or delete forever (admins) |
185
+ | `cms-releases` | Releases: documents that go out together, the version of each, what blocks them, publish now or at a set time |
186
+ | `cms-preview-comments` | For your public page: the comments on a draft opened through a preview link, and a box for a guest to add one |
179
187
  | `cms-empty` | Empty collection: new document, or how to write with an agent |
180
188
 
181
189
  UI text is English by default; a Korean catalog ships with the screens.
@@ -203,39 +211,284 @@ UI text is English by default; a Korean catalog ships with the screens.
203
211
  "unarchive" | "delete", items)` runs each document on its own and returns
204
212
  `{ slug, ok, error? }` for each.
205
213
 
206
- ## Agents
214
+ ### Scheduling, review, comments, releases, trash
215
+
216
+ The editor, the list and two more screens (`cms-trash`, `cms-releases`) cover
217
+ the publishing flow. Nothing here needs set-up except the cron call.
218
+
219
+ - **Schedule.** The arrow beside "Publish" sets a time to publish and a time
220
+ to unpublish, entered on the clock of `createCms({ timeZone })`. What goes
221
+ out is the version that was current when it was scheduled; an edit after
222
+ that shows a warning with "Schedule the latest version". Schedules run when
223
+ something calls the cron route, so their precision is your cron's interval:
224
+
225
+ ```ts
226
+ createCms({ cronSecret: process.env.CMS_CRON_SECRET /* ... */ });
227
+ // every minute or so: POST /api/cms/_cron Authorization: Bearer <secret>
228
+ ```
207
229
 
208
- ### Your own agent (AI SDK, slash-agent-sdk)
230
+ The same call publishes scheduled releases and empties the trash of what is
231
+ older than `trash.days`.
232
+ - **Review.** `defineCollection({ review: { agents: "required" } })` keeps what
233
+ an API key or an agent wrote from going public until a person approves it;
234
+ `everyone: "required"` asks the same of people, and the one who asked cannot
235
+ approve. The editor shows the request with "Send back" and "Approve and
236
+ publish"; the list has an "In review" tab.
237
+ - **Comments.** On a section or on selected text, with replies and resolve.
238
+ They follow the text while it is edited, and move to "Lost their place" when
239
+ the text is gone. A preview link made with "Allow comments" lets someone
240
+ without an account comment: `readPreview(token)` returns `comments: true`
241
+ for such a link, and `<CmsPreviewComments token={token} />` on your page
242
+ (`add cms-preview-comments`, no provider needed) shows the box.
243
+ - **Paste.** Text copied from a web page or a document program is pasted as
244
+ markdown (headings, lists, bold, links, tables, code); invisible characters
245
+ and curly quotes are tidied. Colours and font sizes are left out, and the
246
+ editor says so once.
247
+ - **Editing together.** Who else has the document open is shown in the editor
248
+ and in the list, with their cursors in the body. When someone else saves,
249
+ the editor takes the new version, merging it with unsaved edits when the
250
+ two do not overlap. It asks every 15 seconds (every 3 while someone else is
251
+ there); `presenceMs={0}` turns it off.
252
+ - **Releases.** Put documents in a release from the editor's menu or from the
253
+ release screen; publishing is all or nothing and lists what blocked it.
254
+ - **Trash.** Deleted documents and files stay for 30 days
255
+ (`createCms({ trash: { days } })`, `0` deletes at once). A restored document
256
+ that was published is public again.
257
+ - **Versions** take a name and a pin (pinned versions are never cleaned up).
258
+ **Saved filters** keep a tab, a search, a category and an author under a
259
+ name, for yourself or (admins) for everyone.
260
+
261
+ ## Media library
262
+
263
+ Documents can hold images, video and files. The files live in your own
264
+ storage bucket; the CMS keeps a row per file and hands the browser a signed
265
+ address, so uploads go straight to the storage and never through your app
266
+ server (which is why a 5GB video works on a serverless host). Without `media`
267
+ the feature is off and nothing changes.
209
268
 
210
269
  ```ts
211
- import { streamText } from "ai";
212
- import { cmsTools } from "@mainsoft/agent-cms/ai";
213
-
214
- const result = streamText({
215
- model,
216
- tools: {
217
- ...myTools,
218
- // Every tool this actor may use; `only` and `prefix` narrow and rename.
219
- ...cmsTools(cms, { kind: "system", label: "assistant" }, { prefix: "cms_" }),
270
+ import { s3Storage } from "@mainsoft/agent-cms/storage-s3";
271
+
272
+ const s3 = (bucket: string, publicUrl?: string) =>
273
+ s3Storage({ bucket, region: "auto", endpoint: process.env.S3_ENDPOINT, accessKeyId: process.env.S3_KEY!, secretAccessKey: process.env.S3_SECRET!, publicUrl });
274
+
275
+ export const cms = createCms({
276
+ // …
277
+ media: {
278
+ stores: {
279
+ // The first store is the default. `public`: anyone with the address can read.
280
+ public: { label: "Public", visibility: "public", adapter: s3("site-media", "https://media.example.com") },
281
+ // `private`: opened through the CMS after a permission check, with a link that works for 5 minutes.
282
+ private: { label: "Private", visibility: "private", adapter: s3("site-private"), accept: ["application/pdf"], maxFileSize: 100 * 1024 ** 2 },
283
+ },
284
+ // accept: ["image/*", "video/*", ".pdf"], // what every store takes; default below
285
+ // maxFileSize: 5 * 1024 ** 3, // default 5GB
286
+ imageUrl: ({ url, width }) => `/_next/image?url=${encodeURIComponent(url)}&w=${width}&q=75`,
220
287
  },
221
- messages,
222
288
  });
223
289
  ```
224
290
 
225
- From another process (a script, a scheduled job, another service), use a key:
291
+ `s3Storage` works with AWS S3 (leave `endpoint` out, set `region`),
292
+ Cloudflare R2 (`region: "auto"`, the account's S3 endpoint) and MinIO or any
293
+ other S3-compatible server. It signs requests itself (`aws4fetch`), so there
294
+ is no AWS SDK to install. Another kind of storage is a `StorageAdapter`
295
+ (`./storage`).
296
+
297
+ **The bucket needs a CORS rule** that lets your site `PUT` to it. Add `media`
298
+ (the same object) to `agent-cms.config.ts` and run:
299
+
300
+ ```
301
+ npx agent-cms storage check --origin https://your-site.example
302
+ ```
303
+
304
+ It uploads, reads, moves and deletes a test file in every store for real
305
+ (also in parts, also with a browser-style signed address), tests the CORS
306
+ rule, prints the rule to paste into the bucket, and lists what each store
307
+ accepts. `npx agent-cms storage cleanup` removes uploads that were started
308
+ and never finished (`doctor` tells you when there are any).
309
+
310
+ **What may be uploaded** is yours to decide, at three levels: `media.accept`
311
+ for the app, `stores.<name>.accept` for one store (replaces the app-wide
312
+ list), and `admin.fields.<field>.accept` for one field (narrows its store's
313
+ list). Entries are MIME types (`image/png`), groups (`image/*`) or
314
+ extensions (`.pdf`); `["*/*"]` takes anything. Unset, the default
315
+ (`DEFAULT_ACCEPT`) takes images, video, sound, PDF, office documents, plain
316
+ text and ZIP; web pages and programs only when you list them. `maxFileSize`
317
+ has the same three levels. The server checks the name and declared type when
318
+ an upload starts, and the first bytes of what actually arrived when it ends:
319
+ a web page named `photo.png` is deleted again (`asset_type_mismatch`).
320
+
321
+ **Your own check.** `media.scan` is called once for every file that arrives:
322
+ when a browser upload completes, when a file is imported or stored by the
323
+ server, and when a file that was already in the bucket gets registered. It
324
+ is where a virus scanner or a content policy goes:
325
+
326
+ ```ts
327
+ media: {
328
+ stores: { /* … */ },
329
+ scan: async ({ url, bytes, name, mime, size }) => {
330
+ // `url`: a signed address that works for 10 minutes. `bytes` instead when the CMS holds the file in memory.
331
+ const verdict = await myScanner.check(url ?? bytes);
332
+ return verdict.clean ? true : { ok: false, reason: verdict.name };
333
+ },
334
+ },
335
+ ```
336
+
337
+ A refused file is deleted from the storage and never becomes usable (a
338
+ registered one is left where it was); the caller gets `asset_rejected` and
339
+ the audit log has the reason. A check that throws refuses the file too.
340
+
341
+ **In a document** a file is named by its id, so moving or renaming it never
342
+ breaks a page:
343
+
344
+ ```md
345
+ ![The new dashboard](asset:8k2m4x9pq1zt/dashboard.png "Caption under the picture")
346
+
347
+ Read [the full report](asset:r7w2k9m4x1pa/report-2026.pdf).
348
+ ```
349
+
350
+ An image line of its own is a media block (a picture, a video player or a
351
+ download card, by the file's type). `![alt](https://…)` shows an image from
352
+ elsewhere. For a field, use the `image` or `file` widget; the value is the
353
+ file's id:
226
354
 
227
355
  ```ts
228
- import { remoteCmsTools } from "@mainsoft/agent-cms/ai";
356
+ import { assetId } from "@mainsoft/agent-cms";
229
357
 
230
- const tools = remoteCmsTools(
231
- { url: "https://app.example.com/api/cms", key: process.env.AGENT_CMS_KEY! },
232
- { only: ["search_documents", "get_document", "patch_document"] }
233
- );
358
+ fields: z.object({ cover: assetId().optional(), brochure: assetId().optional() }),
359
+ admin: { fields: { cover: { widget: "image" }, brochure: { widget: "file", accept: [".pdf"], maxFileSize: 20 * 1024 ** 2 } } },
360
+ media: { requireAlt: true }, // an image without alt text stops a save (default: a warning)
234
361
  ```
235
362
 
236
- `await remoteCmsToolsFor(client, opts)` does the same but first asks the
237
- server which tools the key may use (`tools/list`), so a read-only key is
238
- offered read tools only.
363
+ Saving checks the files a document names: one that does not exist or is the
364
+ wrong kind for its field is an error; a missing alt text or a private file
365
+ in a public document is a warning.
366
+
367
+ **On your page**, ask for the files a document uses and render the block
368
+ tree as before:
369
+
370
+ ```ts
371
+ const doc = await cms.get(anon, "posts", slug);
372
+ const files = await cms.assetsFor(doc); // { [id]: { url, width, height, alt, kind, mime, … } }
373
+ const cover = files[doc.fields.cover];
374
+ <img src={cms.imageUrl(cover, { width: 1200 })} width={cover.width} height={cover.height} alt={cover.alt} />
375
+ ```
376
+
377
+ `parseMarkdown` gives `{ t: "media", asset, alt, caption }` blocks; look the
378
+ `asset` up in `files`. The CMS stores originals only. Resizing is your
379
+ framework's or CDN's job, through `media.imageUrl`.
380
+
381
+ **Who may do what.** Listing files and opening private ones: signed-in
382
+ people and keys. Uploading, importing, alt text, tags, new folders: admins
383
+ and keys with `write`. Moving, renaming and deleting: admins and keys with
384
+ `publish`. A store's `access: { read, write, delete }` replaces any of the
385
+ three. Deleting a file that documents use fails with `asset_in_use` and the
386
+ list of documents until the caller confirms. Uploads, moves and deletes are
387
+ in the audit log.
388
+
389
+ The file route is `GET /api/cms/files/<id>/<name>`: it checks permission and
390
+ redirects to the public address or to a short-lived signed one
391
+ (`media.linkTtlSeconds`, default 300). Set `media.filesUrl` when your handler
392
+ is not mounted at `/api/cms`.
393
+
394
+ **In the admin**, add the screen (`npx agent-cms add cms-media`) and a page
395
+ for it; the sidebar shows "Media" by itself when the app has a library:
396
+
397
+ ```tsx
398
+ // app/admin/media/page.tsx
399
+ "use client";
400
+ import { CmsMedia } from "@/components/cms/cms-media";
401
+ export default function MediaPage() {
402
+ return <CmsMedia />;
403
+ }
404
+ ```
405
+
406
+ The browser sends files straight to the storage, four parts at a time for
407
+ large ones, tries a failed part again three times, and "Try again" sends only
408
+ what is still missing. It also makes a small picture of each image and video
409
+ (480px, WebP) for the library, and reads width, height and length.
410
+ "Import from URL" fetches a public https address into the open folder
411
+ (addresses inside your network are refused, as for agents), and the pencil
412
+ in a file's panel renames it; the extension stays, so the type cannot change.
413
+ `<CmsProvider slots={{ assetAlt }}>` lets an extension package put its own
414
+ control next to a file's alt text field.
415
+
416
+ Agents get six more tools when the app has a media library: `list_assets`,
417
+ `get_asset` (read), `import_asset` (fetch an https address into the library;
418
+ addresses inside your network are refused), `update_asset` (write),
419
+ `move_asset` and `delete_asset` (publish). From a terminal:
420
+
421
+ ```
422
+ npx agent-cms upload ./hero.png ./talk.mp4 --folder launch --alt "The launch screen" --tag launch
423
+ ```
424
+
425
+ ### File manager
426
+
427
+ The media library shows the files the CMS knows. The file manager
428
+ (`npx agent-cms add cms-files`, a page with `<CmsFiles />`) shows a bucket as
429
+ it is, folder by folder: files another program put there appear too. The
430
+ sidebar shows "Files" to whoever may look around a store (by default whoever
431
+ may read it; a store's `access.browse` narrows that).
432
+
433
+ - A file the CMS did not know gets a row when someone opens it, tags it,
434
+ shares it or an agent registers it. From then on it works in documents like
435
+ any other file. `npx agent-cms storage sync [--store name] [--folder path]`
436
+ registers everything at once and lists files the CMS knows that are gone
437
+ from the bucket (it deletes nothing).
438
+ - Several files and whole folders can be moved or deleted at once (up to
439
+ 1000 objects per request). A move copies and deletes, one file after the
440
+ other: files that fail are reported, and moving again takes the rest. A name
441
+ that is taken at the destination gets a number; nothing is overwritten.
442
+ Deleting shows the documents that use any of the files first.
443
+ - "Make a link" gives an address for someone outside. For a private store it
444
+ works for 1 hour, 24 hours or 7 days and **cannot be taken back** (it is a
445
+ signed address); for a public store it is the file's public address. Making
446
+ one needs the permission to delete in that store, and is in the audit log.
447
+ - The CMS's own folder (`_cms/`, thumbnails) is hidden and cannot be touched.
448
+
449
+ Agents get three more tools: `list_store_files` (read), `register_asset`
450
+ (write) and `create_share_link` (publish).
451
+
452
+ ## Agents
453
+
454
+ This package never calls a model. It has no model or key settings. It hands
455
+ your agent a list of tools; the model and the loop that drives it are yours.
456
+
457
+ ### Your own agent
458
+
459
+ `toolsFor(cms, actor)` lists the tools this actor may use (name, description,
460
+ a zod schema for the input). `callTool` runs one. Wrap them in whatever your
461
+ agent framework calls a tool:
462
+
463
+ ```ts
464
+ import { toolsFor, callTool } from "@mainsoft/agent-cms/tools";
465
+
466
+ const actor = { kind: "system", label: "assistant" } as const;
467
+
468
+ const tools = toolsFor(cms, actor).map((t) => ({
469
+ name: t.name,
470
+ description: t.description,
471
+ input: t.input, // a zod object; toJsonSchema(t.input) from ./mcp gives JSON Schema
472
+ run: (args: unknown) => callTool(cms, actor, t.name, args),
473
+ }));
474
+ ```
475
+
476
+ `callTool(cms, actor, name, args, { only })` checks the input, runs the tool
477
+ with the actor's permissions, and records the call as made by an agent.
478
+ `toolsFor(cms, actor, only)` and the `only` option narrow the list.
479
+
480
+ From another process (a script, a scheduled job, another service), use a key:
481
+
482
+ ```ts
483
+ import { createCmsClient } from "@mainsoft/agent-cms/client";
484
+ import { toolErrorResult } from "@mainsoft/agent-cms/tools";
485
+
486
+ const api = createCmsClient({ url: "https://app.example.com/api/cms", key: process.env.AGENT_CMS_KEY! });
487
+
488
+ const tools = await api.listTools(); // only what this key may use: { name, description, inputSchema }
489
+ const run = (name: string, args: Record<string, unknown>) =>
490
+ api.call(name, args).catch((e) => toolErrorResult(e) ?? Promise.reject(e));
491
+ ```
239
492
 
240
493
  Tool errors come back as results, not throws, so the model can re-read and
241
494
  retry: `{ error: "conflict_version", kind: "conflict", message, params: {
@@ -246,6 +499,12 @@ expected, current } }`. Every code is in `./errors` (`ERROR_CODES`).
246
499
  | `list_collections`, `search_documents`, `read_for_answer`, `list_documents`, `get_document` | read |
247
500
  | `create_document`, `update_document`, `patch_document`, `diagnose_document`, `list_versions`, `restore_version` | write |
248
501
  | `publish_document`, `unpublish_document`, `archive_document`, `delete_document`, `bulk_documents` | publish |
502
+ | `list_assets`, `get_asset` (with a media library) | read |
503
+ | `import_asset`, `update_asset` | write |
504
+ | `move_asset`, `delete_asset` | publish |
505
+ | `list_store_files` (the bucket as it is) | read |
506
+ | `register_asset` | write |
507
+ | `create_share_link` | publish |
249
508
 
250
509
  `lookupForAgent(cms, actor, collections, question, { budget, countTokens })`
251
510
  (`./agent`) is the answer-a-user helper behind `read_for_answer`: matching
@@ -328,7 +587,7 @@ Body in **markdown**.
328
587
 
329
588
  `@mainsoft/agent-cms/markdown` is browser-safe: `parseMarkdown` gives a
330
589
  small block tree (headings with stable anchors, lists, callouts `> [!tip]`,
331
- code, link rows) and `extractToc` a table of contents. Render it with your
590
+ code, link rows, media) and `extractToc` a table of contents. Render it with your
332
591
  own components.
333
592
 
334
593
  ## Develop