@nocobase/app-plugin-agents 0.1.0-beta.3 → 0.1.0-beta.5

package/package.json

@@ -2,7 +2,7 @@
   "name": "@nocobase/app-plugin-agents",
   "displayName": "Agents",
   "description": "Agents for NocoBase applications: agents, the model services online agents call, their runs and conversations, and the runners people connect to run them (registration, the long-poll claim, slots, the sweeper, build jobs, and the runner and CLI tarballs the application serves).",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -143,8 +143,8 @@
     "sqlite-vec": "^0.1.9",
     "yaml": "^2.9.0",
     "zod": "^4.6.5",
-    "@nocobase/agent-protocol": "^0.1.0-beta.2",
-    "@nocobase/app-cli-client": "^0.1.0-beta.1",
+    "@nocobase/agent-protocol": "^0.1.0-beta.3",
+    "@nocobase/app-cli-client": "^0.1.0-beta.2",
     "@nocobase/cli-envelope": "^0.1.0-beta.0"
   },
   "peerDependencies": {
@@ -160,15 +160,15 @@
     "react-router": "^7.0.2",
     "recharts": "^3.8.0",
     "remark-gfm": "^4.0.1",
-    "@nocobase/app-cli": "^1.0.0-beta.16",
-    "@nocobase/app-client": "^2.0.0-beta.2",
-    "@nocobase/app-plugin-authentication": "^2.0.0-beta.2",
-    "@nocobase/app-plugin-authorization": "^1.0.0-beta.25",
-    "@nocobase/app-plugin-file": "^1.0.0-beta.21",
-    "@nocobase/app-server": "^2.0.0-beta.2",
+    "@nocobase/app-cli": "^1.0.0-beta.18",
+    "@nocobase/app-client": "^3.0.0-beta.0",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.4",
+    "@nocobase/app-plugin-authorization": "^1.0.0-beta.26",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.22",
+    "@nocobase/app-server": "^2.0.0-beta.3",
     "@nocobase/authorization": "^1.0.0-beta.12",
     "@nocobase/db": "^1.0.0-beta.18",
-    "@nocobase/i18n": "^1.0.0-beta.5",
+    "@nocobase/i18n": "^1.0.0-beta.6",
     "@nocobase/markdown-mermaid": "^0.1.0-beta.1",
     "@nocobase/service-provider": "^0.0.2-beta.1"
   },
@@ -185,10 +185,10 @@
     "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@nocobase/app-testing": "0.1.0-beta.1",
+    "@nocobase/app-testing": "0.1.0-beta.2",
     "@nocobase/db-postgres": "0.1.0-beta.3",
     "@nocobase/db-sqlite": "0.1.0-beta.4",
-    "@nocobase/dev-config": "0.1.0-beta.20",
+    "@nocobase/dev-config": "0.1.0-beta.21",
     "@nocobase/jobs": "0.1.0-beta.2"
   },
   "scripts": {

package/skills/nocobase-app-plugin-agents/SKILL.md

@@ -18,7 +18,7 @@ The package README is the full reference: read it at `node_modules/@nocobase/app
 - Variables and model service keys are sealed with the App's secrets service: configure `secrets.keys` before storing any, or the API answers `SECRETS_KEY_MISSING` (503).
 - The plugin registers no pages. The App routes the exported pages and mounts the chat; the App also binds `agentsAccessToken`, or every business action level is `none`.
 - `subjects.register`'s `context.assemble`, brief sections and mounts run inside the claim's transaction: database reads only, never a network or a model call. Read anything else in the optional `prepare(run)`.
-- Tarballs are built by `pnpm nocobase cli build` (the App's CLI) and `cli build --runner` (`nocobase-runner`) as separate CI artifacts and mounted into `storage/runners/dist` (or `agents.dist.dir`). Never bake them into the App's image or commit them.
+- Tarballs are built by `pnpm nocobase cli build` (the App's CLI) and `cli build --runner` (`nocobase-runner`), either as separate CI artifacts mounted into `storage/runners/dist` (or `agents.dist.dir`), or by the App's own `pnpm build` into its build output (universal packages, at the versions it was built with) and served from there. Never commit them.
 - In examples, name the App's CLI after the App (`acme`), never `nocobase` or `nocobase-runner`.
 
 ## References

package/skills/nocobase-app-plugin-agents/references/distribution.md

@@ -1,6 +1,6 @@
 # Distribution: the CLI and runner tarballs
 
-The App serves two products itself, as standalone tarballs that bundle Node.js, one per platform: its own CLI (the `nocobase.cli.bin` of its `package.json`, such as `acme`) and the runner, `nocobase-runner`. Nothing is published to a registry and a machine needs nothing installed beforehand. The README's "What it does" (Distribution) and "The CLI runs get" sections, and `@nocobase/app-cli`'s README section "The application's own CLI: `cli build` and `cli link`", are the reference.
+The App serves two products itself: its own CLI (the `nocobase.cli.bin` of its `package.json`, such as `acme`) and the runner, `nocobase-runner`, each as standalone tarballs that bundle Node.js, one per platform, or as one universal tarball without Node that runs on the machine's own Node.js 24 or newer on every platform. An App that serves no tarball of a product may instead name the exact npm version to install it from ("Naming a product on npm instead" below), as NocoBase Studio does. The README's "What it does" (Distribution) and "The CLI runs get" sections, and `@nocobase/app-cli`'s README section "The application's own CLI: `cli build` and `cli link`", are the reference.
 
 ## Building
 
@@ -10,6 +10,7 @@ pnpm nocobase cli build --runner     # nocobase-runner, from @nocobase/agent-run
 ```
 
 - `--targets` takes a comma-separated list; the default is `darwin-arm64,darwin-x64,linux-x64,linux-arm64`. Windows is not supported.
+- `--universal` also packs `<product>-v<version>-universal.tar.gz`, which carries no Node.js and runs on the machine's Node.js 24 or newer; without `--targets` it packs only that one (no Node download). The App serves it to every platform without a tarball of its own; one built for the platform wins.
 - Node.js for each target is downloaded from nodejs.org and checked against `SHASUMS256.txt` (cached in `node_modules/.cache/nocobase-cli/node`). `--node-version` picks the version (default: the one running the command). `--host-node` uses this machine's Node.js for its own platform instead of downloading, for a quick local build: `pnpm nocobase cli build --targets darwin-arm64 --host-node`.
 - `--out` (default `storage/runners/dist`), `--channel` (default `stable`), `--version` (default `nocobase.cli.version`, else the App's version; with `--runner`, the runner's), `--skip-build`, `--keep-staging`.
 - The App needs `@nocobase/app-cli-client` in its `devDependencies` for the CLI and `@nocobase/agent-runner` for the runner; `npm`, `pnpm` and `tar` come from the environment.
@@ -23,11 +24,22 @@ Each product lands in a directory of its own, with a manifest of every file's SH
 
 ## Serving
 
-The plugin serves `agents.dist.dir` (default `storage/runners/dist`, relative to the App root), channel `agents.dist.channel` (default `stable`). A product's current version is the highest in the channel, unless `agents.dist.versions` pins one. Only files a manifest lists are served. Routes (`DIST_ROUTES` of `@nocobase/agent-protocol`): `GET /api/agents/dist/manifest`, `GET /api/agents/dist/products/<product>/targets/<target>` (`?format=env` for a shell; 404 `PLATFORM_UNSUPPORTED` with the targets there are), the tarball itself, and `POST /api/agents/dist/downloadTokens`.
+The plugin serves `agents.dist.dir` (default `storage/runners/dist`, relative to the App root), channel `agents.dist.channel` (default `stable`). A product's current version is the highest in the channel, unless `agents.dist.versions` pins one. Only files a manifest lists are served. Routes (`DIST_ROUTES` of `@nocobase/agent-protocol`): `GET /api/agents/dist/manifest`, `GET /api/agents/dist/products/<product>/targets/<target>` (`?format=env` for a shell; 404 `PLATFORM_UNSUPPORTED` with the targets there are; the universal tarball answers with the asked target and `universal: true`, `universal=true` in env form), the tarball itself, and `POST /api/agents/dist/downloadTokens`.
+
+### Naming a product on npm instead
+
+`agents.dist.npm` names the npm package and exact version (never a range) of a product, such as `{ nocobase-runner: { package: '@nocobase/agent-runner', version: 1.0.0 } }`. It is used only when `agents.dist.dir` has no current version of that product; a product the directory has is served from it exactly as without the setting. The machine needs Node.js 24 or later already; nothing bundles it on this path.
+
+Only callers that say they understand the answer get it, so an older runner, install script or CLI never sees one:
+
+- The resolve route with `accept=npm` (a comma-separated list) answers `{ kind: 'npm', product, version, package, channel }`, or with `format=env` the lines `kind=npm`, `product=`, `version=`, `package=` and `channel=`. Without it, such a product is 404 as before.
+- A heartbeat answer carries `npmUpgrade` (`latestVersion`, `package`, `channel`, `reason`) instead of `upgrade` only to a runner that declares the `npm` feature (protocol 8) and runs an older version; any other runner is offered no update for that product. The Runtimes page marks only those runners "Upgradable".
+
+An App that builds its runner and CLI into its deployment pins them to the versions it was built with this way, so redeploying it moves every runner to that version.
 
 ## CI and deployment
 
-Build the two products as separate artifacts in CI, one job each (`pnpm nocobase cli build --out output/dist` and `pnpm nocobase cli build --runner --out output/dist`, uploading `output/dist`), and mount or copy each into the deployment's `storage/runners/dist` (or the directory `agents.dist.dir` names), keeping the `<channel>/<product>/` layout. Do not bake them into the App's image: they change on their own schedule and are large. Rebuild the runner whenever `@nocobase/agent-runner` or the agents plugin is upgraded, so runners can update to a version that speaks the App's protocol, and rebuild the CLI whenever the App's `nocobase.cli` or its CLI skills change.
+There are two ways to deliver the packages. When the runner and CLI follow the App's own releases, build them with the App: an `afterServerBuild` build hook in `cli/plugins.ts` runs `pnpm nocobase cli build --universal --skip-build --out dist/runners` (and the same with `--runner`), and `agents.dist.dir` in the App's configuration points at that directory, so every build, archive and image serves the runner and CLI it was built with; universal packages keep the build small, and `cli build` needs the npm registry for their dependencies. NocoBase Studio does this. Otherwise build the two products as separate artifacts in CI, one job each (`pnpm nocobase cli build --out output/dist` and `pnpm nocobase cli build --runner --out output/dist`, uploading `output/dist`), and mount or copy each into the deployment's `storage/runners/dist` (or the directory `agents.dist.dir` names), keeping the `<channel>/<product>/` layout. Rebuild the runner whenever `@nocobase/agent-runner` or the agents plugin is upgraded, so runners can update to a version that speaks the App's protocol, and rebuild the CLI whenever the App's `nocobase.cli` or its CLI skills change.
 
 ## Installing on a machine
 
@@ -43,10 +55,15 @@ curl -fsSL https://app.example.com/api/agents/dist/installScript | sh -s -- --ru
 
 Options: `--prefix`, `--bin-dir`, `--dry-run`; with `--runner`, `--runner-prefix`, `--name`, `--label` and `--no-service` (register only). A token of the other kind fails before anything is installed. An App that serves no CLI still installs the runtime.
 
+For a universal tarball the script checks, before downloading, that `node` on PATH is Node.js 24 or newer and stops with how to install it otherwise; it then links `<prefix>/node` to that `node`. The package's launcher tries `NOCOBASE_NODE`, `<prefix>/node`, `node` on PATH, and a Node an older standalone version in `<prefix>/versions/` still carries, so a runner's user service (launchd, systemd), whose PATH usually has no `node`, starts it. An update to a universal version leaves the Node it ran on in `<prefix>/node` before removing old versions. With `--runner`, a missing `pnpm` only prints a hint to run `corepack enable`.
+
+The script resolves with `accept=npm`. For an npm answer it checks Node.js 24 the same way and that `npm` is on PATH (or `NOCOBASE_NPM` names one), stopping with how to get it otherwise, then runs `npm install --prefix <prefix>/versions/<version>.partial --no-save --no-audit --no-fund --omit=optional <package>@<version>` with the npm configuration (registry, proxy) of the person running it, writes a launcher at `bin/<command>` beside `node_modules`, renames the directory to `<prefix>/versions/<version>` and links `<prefix>/node`. `current`, the command link and the runner's service are then exactly as for a tarball. `--omit=optional` keeps the coding tools' per-platform SDK packages, each carrying a binary the runner never starts, off the machine.
+
 ## Updates
 
-- The runner reports its product and version on every heartbeat; the answer names a newer `nocobase-runner` when the channel serves one for its platform. An installed runner started by its service updates itself between runs; `nocobase-runner update` does it now (`--check` only checks, `--auto on|off` switches automatic updates). The Runtimes page marks such a runner "Upgradable".
+- The runner reports its product and version on every heartbeat; the answer names a newer `nocobase-runner` when the channel serves one for its platform (`upgrade`), or the npm version `agents.dist.npm` pins (`npmUpgrade`, to runners with the `npm` feature). An installed runner started by its service updates itself between runs; `nocobase-runner update` does it now (`--check` only checks, `--auto on|off` switches automatic updates). The Runtimes page marks such a runner "Upgradable".
 - The App's CLI, installed by the script, has `<cli> update`, and says on stderr when a newer version is served.
+- Both ask with `accept=npm` and install an npm answer into `<prefix>/versions/<version>` the way the install script does, with the machine's npm; an installation moves between tarball and npm versions in either direction. The runner and `@nocobase/app-cli-client` depend on exactly the `@nocobase/agent-protocol` they were built with, so an exact npm version speaks one known protocol.
 - A run gets the App's CLI as `agents.cli.package` says: by default the tarball the App serves for the runner's platform (`{ kind: served }`), downloaded once per version. A runner without the `archives` feature, or a platform with no build, falls back to the CLI installed beside it (`preinstalled`). `{ kind: npm, package, version }` names an npm package instead.
 
 ## The npm package as an alternative

package/skills/nocobase-app-plugin-agents/references/setup-and-config.md

@@ -35,6 +35,8 @@ agents:
     dir: storage/runners/dist # the default; relative to the App root
     channel: stable
     versions: { acme: 0.1.0 } # pin a product instead of the channel's highest
+    npm: # a product with no tarball in dir, named on npm instead (exact versions)
+      nocobase-runner: { package: '@nocobase/agent-runner', version: 1.0.0 }
   server: # online agents, run by every instance
     enabled: true
     maxSteps: 16

package/skills/nocobase-app-plugin-agents/references/verification-and-troubleshooting.md

@@ -22,6 +22,10 @@ Test what the App builds on the plugin, not the plugin itself. `@nocobase/app-pl
 | Vectors                   | `vectors.status()` on `agentsToken`: availability, store and the `VectorUnavailableCode`                                                                                                                        |
 | The runner itself         | `nocobase-runner status`, `nocobase-runner logs -f [--run <id>]`, `~/.nocobase-runner/policy.json`                                                                                                              |
 
+## Filtering a run transcript
+
+`GET /api/agents/runs/:runId/events` accepts repeated `type` query parameters (for example, `?type=text&type=input`). The generated `run events` command exposes repeatable `--type` flags. Values are raw protocol event types, not UI groups: `text`, `thinking`, `toolUse`, `toolResult`, `permission`, `input`, `checkout`, `status`, `error`, `usage`. Omitting the filter returns every type. The service equivalent is `agents.runs.events(runId, afterSeq, limit, types?)`. Filtering happens before pagination; retain the same types with `pageToken` or the returned `lastSeq`. These API/CLI filters are exact and do not automatically include errors. A UI that summarizes hidden events must load the complete history and filter locally.
+
 ## Troubleshooting
 
 | Symptom                                                                      | Cause and fix                                                                                                                                                                                                                                                                                                                             |