@nocobase/app-plugin-agents 0.1.0-beta.4 → 0.1.0-beta.6

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/extension-points.md

@@ -17,7 +17,7 @@ Everything the App contributes goes through `agentsToken` (`@nocobase/app-plugin
 | `reporting.usage`, `reporting.runFigures`, `reporting.range`, `reporting.modelUsage`                                                                           | What runs used and cost, grouped as the App needs                                                                                                                    | The App's report pages                                                                                                                                  |
 | `briefs.sections.register(provider)`                                                                                                                           | Sections added to every brief's context layer                                                                                                                        | Project conventions every run should read                                                                                                               |
 | `mounts.register(provider)`                                                                                                                                    | Directories of files placed beside the agent                                                                                                                         | Reference material for a run                                                                                                                            |
-| `repoAccess.register(provider)`                                                                                                                                | Commit identity and short-lived push credentials per run                                                                                                             | Git hosting integration                                                                                                                                 |
+| `repoAccess.register(provider)`                                                                                                                                | Commit identity and short-lived push credentials per run, at the claim or, with `issue`, whenever the runner's git needs one (`gitCredentials` runners)              | Git hosting integration                                                                                                                                 |
 | `online.skills`, `online.gateway`                                                                                                                              | Skills every online run gets; the model gateway for the App's own model calls                                                                                        | See [Online agents](online-agents.md)                                                                                                                   |
 | `vectors.collection(spec)`, `vectors.stores.register`                                                                                                          | Vector collections searched by meaning; another vector store type                                                                                                    | Semantic search for a knowledge base                                                                                                                    |
 
@@ -35,3 +35,9 @@ Rules that are easy to miss:
 - `GET /api/agents/vocabulary` hands the browser the subjects, sources and scopes the App contributed; the browser never imports server code for them.
 
 The README's example under "Extension points" shows a subject registered and work enqueued and withdrawn.
+
+A subject assembly may return `inputs` containing only the effective inputs for its current task. Render the task and turn from that same selection. Runner and online claims use it for delivery, brief sections and mounts; omitted inputs are resolved in the claim transaction and retained in the audit history, so polling and completion do not replay obsolete work. Omit the field to deliver all queued inputs.
+
+A working run is held to the same policy: before input joins a dispatched or running run, and before pending input is delivered to one, the plugin asks `admit` and then `selectInputs` with that input. New input either hook keeps from the working run waits in a queued run for the claim to admit or cancel; pending input rejected or left out by `selectInputs` is marked handled instead of being delivered. Implement `selectInputs` with the same selection the assembly returns as `inputs`.
+
+For issue/card work indicators, use `runs.workingOn(subjectKind, subjectIds)` after filtering visible subjects. It returns unique `{ subjectId, agentId, working: true }` pairs for dispatched/running runs in that exact scope, with no run details or global board cap. Match the current executor and apply the application's pending approval rules separately; queued/terminal runs do not appear. Pass a bounded batch from a view, rather than querying each card's full history.

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

@@ -1,5 +1,11 @@
 # Runners
 
+## Ended workspace diagnostics
+
+For application-owned task cleanup, keep `SubjectWorkspaces.settled` conservative and optionally register `resolveKeys` for legacy directory keys and `commits` for trusted merged PR heads by repository URL. The plugin checks current or historical runner ownership and excludes nonterminal runs; directory keys alone never authorize lookup or cleanup. Use the head at merge time, not a squash merge commit. See `packages/plugins/app-plugin-agents/docs/workspace-cleanup.md` in the source repository for protocol and integration details.
+
+Runtime pages distinguish application settlement from the runner's local cleanup check. An allowed check is not a deletion receipt. Directory diagnostics require explicit `canSeeMachine: true`; disk warnings use the report's measurement time and show expired or offline readings as prior reports. An ended workspace still stays when tracked changes, unpushed submodule commits, missing local objects or insufficient evidence prevent verification. Upgrade and serve both plugin and runner before expecting new diagnostics.
+
 A runner (shown as a runtime) is `nocobase-runner` from `@nocobase/agent-runner`, running on a server, a VM or someone's own device. It registers with one or more Apps, long-polls them for work and drives a coding tool for runner agents' runs. The wire protocol is `@nocobase/agent-protocol`. The README's "What it does" section (Runners, The claim, Runs, The sweep) and `@nocobase/agent-runner`'s README are the reference.
 
 ## Registering a runner

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