@nocobase/app-plugin-agents 0.1.0-beta.1 → 0.1.0-beta.10

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

@@ -2,32 +2,42 @@
 
 Everything the App contributes goes through `agentsToken` (`@nocobase/app-plugin-agents/server/tokens`), resolved in one of the App's service providers when it boots. Text people read is an `I18nText` (`{ key, ns }`) in the App's own namespace. The README's "Extension points" section describes each field; this is the map. Where the two disagree, the types exported from `server/tokens` (the `Agents` interface) are authoritative.
 
-| Extension point                                                                                                                                                | Contributes                                                                                                                                                          | Typical use                                                                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subjects.register(binding)`                                                                                                                                   | A kind of subject runs work on: `kind`, `title`, `triggers`, `preview`, `context.assemble`, `sink.onRunFinished`, `queuedExpiryMs`, `reports.describe`, `agentTypes` | An issue, a ticket, a document an agent works on                                                                                                        |
-| `runs.enqueue(...)`, `runs.withdrawQueued(...)`, `runs.workload(...)`                                                                                          | Wake an agent on a subject, withdraw queued work, read the board of open runs                                                                                        | Assigning work to an agent from a business action                                                                                                       |
-| `scopes.register(kind)`                                                                                                                                        | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`); `agent` is reserved, `workdir` is registered by the App          | Per-project or per-team variables                                                                                                                       |
-| `actions.provide(source)`                                                                                                                                      | The business actions an agent may be given (`key`, `group`, `title`, `description`, `defaultOn`), and those never granted (`grantable: false` with a `reason`)       | What the agent editor's Capabilities tab offers                                                                                                         |
-| `presets.register(preset)`                                                                                                                                     | A role a new agent starts from (`name`, `description`, `instructions`, `actions`)                                                                                    | "Reviewer", "Support assistant"                                                                                                                         |
-| `gate.set(gate)` (`ActionGate`: `allowed(identity)`, optional `consultable(action)`)                                                                           | Which business actions a caller holds now: a person their own (narrowed by an API key's scope), a run those its agent is configured with within the waking person's  | Bounding the command manifest and every request a run makes; without a gate a caller holds only `agents.agents/view` (and `agents.runs/self` for a run) |
-| `conversations.sources.register`, `conversations.contextKinds.register`, `conversations.rules.provide`, `conversations.deliver`, `consultations.rules.provide` | Where conversations start from, what a page context may reference, extra system rules, news delivered into a conversation                                            | "Ask agent" buttons on business pages                                                                                                                   |
-| `people.provide(source)`                                                                                                                                       | The App's directory: names, whom to pick, who can no longer act (`inactive`)                                                                                         | Disabling a person stops their runners                                                                                                                  |
-| `events.on('agent.removed' \| 'notice', listener)`                                                                                                             | An agent archived or deleted; people to be told, such as `runner_upgrade_required`                                                                                   | Releasing work given to an agent; forwarding notices to the App's inbox                                                                                 |
-| `jobs.register(kind, registration)`                                                                                                                            | A build job kind, only for an off-by-default runner build method                                                                                                     | Builds on runners                                                                                                                                       |
-| `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                                                                                                                                 |
-| `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                                                                                                                    |
+| Extension point                                                                                                                                                | Contributes                                                                                                                                                         | Typical use                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subjects.register(binding)`                                                                                                                                   | A kind of subject runs work on: `kind`, `title`, `triggers`, `preview`, `context.assemble`, `sink.onRunFinished`, `queuedExpiryMs`, `reports.describe`              | An issue, a ticket, a document an agent works on                                                                                                        |
+| `runs.enqueue(...)`, `runs.withdrawQueued(...)`, `runs.workload(...)`                                                                                          | Wake an agent on a subject, withdraw queued work, read the board of open runs                                                                                       | Assigning work to an agent from a business action                                                                                                       |
+| `scopes.register(kind)`                                                                                                                                        | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`); `agent` is reserved, `workdir` is registered by the App         | Per-project or per-team variables                                                                                                                       |
+| `actions.provide(source)`                                                                                                                                      | The business actions an agent may be given (`key`, `group`, `title`, `description`, `defaultOn`), and those never granted (`grantable: false` with a `reason`)      | What the agent editor's Capabilities tab offers                                                                                                         |
+| `agents.setDefaults(provider)`, `agents.applyDefaults()`                                                                                                       | The instructions and business actions every agent discovered from runners gets; `applyDefaults` writes them to the agents that differ                               |
+| `agents.ensureSystem(input)`                                                                                                                                   | An agent of the App's own (fixed id, name, description, instructions, actions, tools and models), kept as given and enabled                                         |
+| `gate.set(gate)` (`ActionGate`: `allowed(identity)`, optional `consultable(action)`)                                                                           | Which business actions a caller holds now: a person their own (narrowed by an API key's scope), a run those its agent is configured with within the waking person's | Bounding the command manifest and every request a run makes; without a gate a caller holds only `agents.agents/view` (and `agents.runs/self` for a run) |
+| `conversations.sources.register`, `conversations.contextKinds.register`, `conversations.rules.provide`, `conversations.deliver`, `consultations.rules.provide` | Where conversations start from, what a page context may reference, extra system rules, news delivered into a conversation                                           | "Ask agent" buttons on business pages                                                                                                                   |
+| `people.provide(source)`                                                                                                                                       | The App's directory: names, whom to pick, who can no longer act (`inactive`)                                                                                        | Disabling a person stops their runners                                                                                                                  |
+| `events.on('agent.removed' \| 'notice', listener)`                                                                                                             | An agent disabled; people to be told, such as `runner_upgrade_required`                                                                                             | Releasing work given to an agent; forwarding notices to the App's inbox                                                                                 |
+| `jobs.register(kind, registration)`                                                                                                                            | A build job kind, only for an off-by-default runner build method                                                                                                    | Builds on runners                                                                                                                                       |
+| `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, at the claim or, with `issue`, whenever the runner's git needs one (`gitCredentials` runners)             | Git hosting integration                                                                                                                                 |
+| `models.gateway`                                                                                                                                               | 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                                                                                                                    |
 
 Rules that are easy to miss:
 
 - `context.assemble`, brief sections and mounts run inside the claim's transaction and read the database through the claim's connection only (on SQLite it is the only connection). Read anything else in the provider's optional `prepare(run)`, which runs before the transaction. A throw leaves the run queued; three failures fail it `setupFailed`.
 - `runs.enqueue` takes an optional outer transaction; inside another plugin's transaction, publish the collected events after it commits.
-- A subject kind takes runner agents only unless its binding lists `online` in `agentTypes`; a run of another type is refused with `AGENT_TYPE_NOT_ALLOWED`.
-- Name commands in a brief with `commandRef(dialect, cli, id, flag?)` rather than spelling them, so online and runner agents both get the right form.
+- When someone answers for the subject, pass `responsibleUserId` and the source (`requestedByUserId`, or `causedByRunId` for what a run did). Work another person causes then answers `outcome: 'pending'`: a run request only the responsible confirms (`runs.requests`, `/api/agents/runRequests`), unless `execution: 'mine'` runs it as the asker, which is refused with `NO_RUNNER_AVAILABLE` when no online runner would take the asker's work (`eligibility.canClaim` with the agent's variables). Both people must have agent access; identical pending snapshots are reused without renewing expiry. For mutable responsibility, bind `subjects.register({ …, responsibleUserId: (conn, subjectId) => … })` to read the current responsible using the supplied transaction connection, so old owners cannot confirm or reject before reassignment. Call `runs.requests.reassign` with each responsibility change; without a resolver this is the only protection against stale confirmation. If there is no usable new responsible, reassignment expires and notifies instead of dropping the work, preserving `runAsMe`. Forward `runRequest.*` events and `run_request_expired` notices to the App's inbox, and handle `outcome` before using a possibly null `runId`.
+- To tell a person before queuing whether a runner would take their work, call `eligibility.canClaim` (online now) or `mayQueue` (some registered runner could) with the subject's variable scopes; a variable marked `teamRunnersOnly` needs a team runner. Enqueue itself does not refuse work run as the responsible or as whoever woke the agent: such work waits with `secretsNotAllowed`.
+- Forward `notice` / `notice.cleared` using the exported `AgentsNotice` interface. Dispatch by its `type`: runner notices go to the runner's owner, `run_secrets_not_allowed` to the run's actor and owner, and `run_request_expired` to the requester. Subjects are of kind `runner`, `run` or `runRequest`. A secrets notice names the run, the agent and the team-only variables in its parameters. Deduplicate by the notice key. Existing copied queue components must merge the `secretsNotAllowed` type and label from the Registry.
+- A repository provider minting credentials in `prepare` implements idempotent `discard(run, prepared)` to revoke undelivered credentials. The plugin calls it outside the transaction on a skipped or rolled-back claim; the App implements the code host revocation API.
+- Name commands in a brief with `commandRef(cli, id, flag?)` rather than spelling them.
 - The App's CLI commands are its API routes: a route declares `...cliRoute({ command, action, ... })` in `describeRoute()`, and lists `runToken` in its `security` when a run may call it. The command manifest (`GET /api/cli/manifest`) offers each caller only the commands whose `action` the gate allows. There is no separate command registry.
 - `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. 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/model-services.md

@@ -0,0 +1,17 @@
+# Model services
+
+Agents run on runners and do not use model services. The plugin keeps model services for the App's own model calls, such as a knowledge base's embeddings, reranking and short texts. The README's "Model services" and "Vectors" sections are the reference.
+
+## Model services
+
+- A service is a provider type (`MODEL_PROVIDERS` in `@nocobase/app-plugin-agents/shared/models`: OpenAI, Anthropic, Google, DeepSeek, Alibaba, Moonshot, Cohere, Ollama, and OpenAI-compatible endpoints), a name, a base URL, a write-only API key sealed with the secrets service, an on/off switch and the models it offers. OpenCode Zen and Go serve each model family through its own API under one base URL: DeepSeek, GLM, Kimi and MiMo through a DeepSeek or OpenAI-compatible service, Claude, MiniMax and Qwen through an Anthropic one, GPT and Grok through an OpenAI one; a call to an OpenCode base URL sends `x-opencode-session` automatically. Each model has a kind: `chat` (short texts), `embedding` or `rerank`.
+- Services are added on the Models page (`modelsRoute`, behind `agents.services`) or through the API (`service create|discover|check` on the CLI). They are never configured in `config.yml`.
+- `GET /api/agents/models` (anyone signed in) lists the models of a kind the enabled services offer; `POST /api/agents/checkModel` (who reads agents) tests one with a short call and never throws.
+
+## The model gateway
+
+`models.gateway` on `agentsToken` serves the App's own model calls: `catalog(kind)`, `check(ref)`, `embed({ model, values, source })`, `rerank({ model, query, documents, topN?, source })` and `generate({ model, system?, prompt, maxOutputTokens?, source })`. Each names who asks (`source`), is recorded in `agModelUsage` and priced from the service's model prices, and throws `ModelError` with a code (`config`, `auth`, `quota`, `rateLimit`, `network`, `contextOverflow`, `filtered`, `badResponse`, `aborted`, `unknown`). Use it rather than calling a provider SDK, so keys, usage and prices stay in one place.
+
+## Vectors
+
+`vectors.collection(spec)` gives the App semantic search over items it names, embedded with the model it chooses, in the store `agents.vectors` configures (`sqlite-vec` by default, `pgvector` for several instances or Alpine). `status()` answers availability and a `VectorUnavailableCode` when it is not available; then search answers null and the caller keeps its keyword search. See the README's "Vectors" section.

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
@@ -12,7 +18,7 @@ A runner registers once per App with a one-time registration token (10 minutes):
 
 Then on the runner's machine: `nocobase-runner register --server <App URL> --token <token>`, and `nocobase-runner start` or `nocobase-runner service install` (launchd on macOS, a systemd user unit on Linux). The install script does all of this in one line; see [Distribution](distribution.md).
 
-A runner authenticates afterwards with its own key. Personal runners (`ownerOnly`) run only work their owner started; their owner may share them with the team. `nocobase-runner unregister --server <url>` or "Revoke" on the Runtimes page ends a registration.
+A runner authenticates afterwards with its own key. Personal runners (`ownerOnly`) run only work their owner started, and receive its variables like any runner, except those marked "Team runtimes only" (`teamRunnersOnly`): a run that gets one goes to a team runner. Their owner may share them with the team. `nocobase-runner unregister --server <url>` or "Revoke" on the Runtimes page ends a registration.
 
 ## How work reaches a runner
 
@@ -29,4 +35,12 @@ What to do: upgrade the runner to a version that speaks the App's protocol. An i
 
 ## Coding tools
 
+`RunnerSummary.tools` also carries optional advisory capabilities: `models` (model `id` and optional `efforts`), `modelsDetectedAt` (the last discovery attempt), `modelsDetectionStatus` (`detected`, `unsupported`, `failed`) and a fixed brief `modelsDetectionError` on failure. Missing status means capability information is unknown; missing efforts means unknown support, while an empty model list is a successful discovery of no available models. Discovery runs in the background every five minutes, so completed results arrive on a later heartbeat. The App stores these per runner in its existing tools JSON, keeps the same runner visibility and machine-information filtering, and never writes the suggestions into Agent configuration or uses them to authorize or route work. Pi reports provider/model IDs, and its table does not enumerate per-model efforts; OpenCode variants and Codex reasoning efforts do. Claude reports unsupported. Rebuild and serve the updated runner tarballs to enable reporting; upgrading the plugin alone does not update an already installed runner.
+
+Capability reports are advisory across independently released runners and Apps: registration and heartbeats discard invalid model entries, individual invalid efforts, malformed detection timestamps and unfamiliar status or error values while still validating the tool's basic fields. A report containing only invalid models does not retain detected status; a valid empty list still means no models were found. Counts and identifier lengths remain bounded, and versioned model ids such as `claude-sonnet-4@20250514` are supported.
+
+Run lists and details expose `executions`, one claim snapshot per attempt, with the runner's name, owner and trust, the tool version, requested model, reported `actualModels` and reasoning effort. Retries retain these facts after releasing `runnerId` to null; use the latest snapshot for historical display and the current holder for authorization. Only the primary tool's usage identifies its actual model, and multiple models remain visible. Older runs have no snapshots: their known usage models can be displayed, but their historical machine names and attempt boundaries must not be invented. Applications must forward the fields through custom CLI projections and update their installed UI Library run components.
+
+`effort` is requested; `actualEffort` is only a tool report, with `actualEffortSource`, `actualEffortAt` and per-attempt `effortReports`. Show unreported actual values explicitly, never infer from requests or token counts. Import `runForViewer`/`executionForViewer` from `@nocobase/app-plugin-agents/server/tokens` and apply them to custom user-facing run/workload/CLI outputs, using the runner machine rights; `machineHidden` means a generic runtime label, not a fallback to the hostname/id. A projects viewer may provide `seesExecutionMachine` from those same rights. See `docs/execution-history.md` for the report and projection contracts.
+
 The runner finds each coding tool on its PATH and reports whether it is signed in. A tool not found, or not signed in, is offered no runs: sign in on the runner's machine as the runner's user (for example `claude` and its login), then wait for the next heartbeat. Which tools a runner is offered work for is chosen on the Runtimes page (`enabledTools`). A model the tool's account cannot use fails the run `modelUnavailable`.

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

@@ -35,10 +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
-  server: # online agents, run by every instance
-    enabled: true
-    maxSteps: 16
-    consult: { timeoutMs: 120000, tokenBudget: 200000 }
+    npm: # a product with no tarball in dir, named on npm instead (exact versions)
+      nocobase-runner: { package: '@nocobase/agent-runner', version: 1.0.0 }
   vectors:
     store: sqlite-vec # the default; pgvector (own PostgreSQL), or false
     path: storage/vectors.sqlite
@@ -47,14 +45,13 @@ agents:
 ```
 
 - `agents.cli.name` defaults to `agents.app.id`; set it to the App's `nocobase.cli.bin` so runs install and call the same CLI the App serves.
-- `agents.server.enabled: false` leaves online runs to the other instances.
 - `sqlite-vec` is local to an instance and has no build for Alpine (musl), where it reports `SQLITE_VEC_UNSUPPORTED`; an App running several instances, or on Alpine, uses `pgvector`, which takes its own PostgreSQL connection and never the App's.
 - Moving `agents.skills.disk` does not copy what is stored: copy `skills/blobs/` across first.
-- Model services are not configured here; they are added on the Models page or through the API.
+- Model services, for the App's own model calls, are not configured here; they are added on the Models page or through the API.
 - `secrets.keys` (the App's secrets service) must be set before variables or model service keys can be stored. `pnpm nocobase secrets rotate` reseals both stores.
 
 ## Pages and chat
 
-The plugin has no routes of its own. The App routes what `@nocobase/app-plugin-agents/client/routes` exports (`agentsRoute`, `runtimesRoute`, `skillsRoute`, `usageRoute`, `modelsRoute`), each behind a page grant named like its route (`PAGES` in `shared/access`); `modelsRoute` stands behind `agents.services` read. `client/kit` has the pieces for the App's own settings pages (`VariablesSection`, `DefaultSkillsSection`, `useRunnerOptions`, `useAgentOptions`), `client/runs` the headless parts of a subject's runs, `client/profile` the person's default chat agent, and `client/config` the business-action catalog context.
+The plugin has no routes of its own. The App routes what `@nocobase/app-plugin-agents/client/routes` exports (`agentsRoute`, `runtimesRoute`, `skillsRoute`, `usageRoute`, `modelsRoute`), each behind a page grant named like its route (`PAGES` in `shared/access`); `modelsRoute` stands behind `agents.services` read. `client/kit` has the pieces for the App's own pages (`RunnerAgentsSection`, the Agent page's list for an App that shows its own agents beside it, `VariablesSection`, `DefaultSkillsSection`, `useRunnerOptions`, `useAgentOptions`), `client/runs` the headless parts of a subject's runs, `client/profile` the person's default chat agent, and `client/config` the business-action catalog context.
 
 The chat is headless in `client/chat`: wrap the App's routes in `ChatProvider` and install the UI Library's `agent-chat` block (`yes n | pnpm exec shadcn add @nocobase/agent-chat`) for its UI. The README's "Web UI" section describes every export.

package/skills/nocobase-app-plugin-agents/references/variables-skills-usage.md

@@ -8,14 +8,14 @@ On the App's own pages, `VariablesSection` from `client/kit` edits a scope's var
 
 ## The skill library
 
-Skills (`agSkills`) follow the open Agent Skills format: a directory with `SKILL.md` (front matter `name` and `description` required) and supporting files under `scripts/`, `references/` and `assets/`. Every save is a version runs get at once; saves name the revision they were made against and conflict with 409 `REVISION_CONFLICT`. Skills are attached to agents, and as defaults to a working directory or a registered scope (`DefaultSkillsSection` in `client/kit`). Runner agents may run a skill's scripts; online agents only read them. File contents go to the Drive disk `agents.skills.disk` names. See the README's "What it does" (Skills) and "Configuration" sections.
+Skills (`agSkills`) follow the open Agent Skills format: a directory with `SKILL.md` (front matter `name` and `description` required) and supporting files under `scripts/`, `references/` and `assets/`. Every save is a version runs get at once; saves name the revision they were made against and conflict with 409 `REVISION_CONFLICT`. Skills are attached to agents, and as defaults to a working directory or a registered scope (`DefaultSkillsSection` in `client/kit`). Agents may run a skill's scripts. File contents go to the Drive disk `agents.skills.disk` names. See the README's "What it does" (Skills) and "Configuration" sections.
 
-Skills the App's CLI ships (`nocobase.cli.skills`) reach every runner run beside the run's own; `online.skills.register` does the same for online runs.
+Skills the App's CLI ships (`nocobase.cli.skills`) reach every run beside the run's own.
 
 ## Chat attachments
 
-A person may send files with a message: each is uploaded first (`POST /api/agents/chatAttachments`, one file, stored through the file plugin), readable only by its uploader until sent, then sent with the message (`attachmentIds`). After that only the conversation's owner and a run of its agent on that conversation read it. A runner agent downloads a file with the CLI (`conversation attachment download <file-id>`); an online agent is shown the images and only the names of the rest. Uploads never sent are purged. Size and count limits are the `CHAT_ATTACHMENT_*` constants in `@nocobase/app-plugin-agents/shared/conversations`, whose header comment is the contract.
+A person may send files with a message: each is uploaded first (`POST /api/agents/chatAttachments`, one file, stored through the file plugin), readable only by its uploader until sent, then sent with the message (`attachmentIds`). After that only the conversation's owner and a run of its agent on that conversation read it. The agent downloads a file with the CLI (`conversation attachment download <file-id>`). Uploads never sent are purged. Size and count limits are the `CHAT_ATTACHMENT_*` constants in `@nocobase/app-plugin-agents/shared/conversations`, whose header comment is the contract.
 
 ## Usage, prices and reports
 
-Every run records what it used (tokens per model and tool) as it reports. The Usage page (`usageRoute`, `GET /api/agents/usage`) groups it by agent, person, group, subject, day, model, tool or type; who reads `agents.prices` sets prices on its prices sheet, and costs are computed from them. Model calls outside runs (embeddings, reranking, short generations through `online.gateway`) appear as "Other model use" (`GET /api/agents/usage/models`). The App's own report pages read `reporting.usage`, `reporting.runFigures`, `reporting.range` and `reporting.modelUsage` from `agentsToken`, and each subject kind's `reports.describe` labels and groups its runs.
+Every run records what it used (tokens per model and tool) as it reports. The Usage page (`usageRoute`, `GET /api/agents/usage`) groups it by agent, person, group, subject, day, model, tool or type; who reads `agents.prices` sets prices on its prices sheet, and costs are computed from them. Model calls outside runs (embeddings, reranking, short generations through `models.gateway`) appear as "Other model use" (`GET /api/agents/usage/models`). The App's own report pages read `reporting.usage`, `reporting.runFigures`, `reporting.range` and `reporting.modelUsage` from `agentsToken`, and each subject kind's `reports.describe` labels and groups its runs.

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

@@ -2,45 +2,46 @@
 
 ## What to test
 
-Test what the App builds on the plugin, not the plugin itself. `@nocobase/app-plugin-agents/testing` assembles the services against a test database (`createAgents`, `AGENTS_MIGRATIONS`), mounts the run and runner routes on a test server, and runs the online executor over a scripted model gateway; use it with `createAppTest()` from `@nocobase/app-testing/server`.
+Test what the App builds on the plugin, not the plugin itself. `@nocobase/app-plugin-agents/testing` assembles the services against a test database (`createAgents`, `AGENTS_MIGRATIONS`), and mounts the run and runner routes on a test server; use it with `createAppTest()` from `@nocobase/app-testing/server`.
 
 - Each subject kind: `assemble` returns the task, context and working directories for a sample subject, reads only the database, and `sink.onRunFinished` does what the App expects for completed and failed runs.
 - The gate: a person holds exactly their actions; a run holds only the waking person's actions its agent is configured with; an API key's scope narrows a person.
 - Routes a run may call: `findUndeclaredApiRoutes(app)` lists none, each route lists `runToken` in its `security`, and the command manifest for a run shows the command only when the gate allows its `action`.
-- Contributed actions, presets and scopes appear in `GET /api/agents/actions`, `GET /api/agents/presets` and `GET /api/agents/vocabulary`.
+- Contributed actions and scopes appear in `GET /api/agents/actions` and `GET /api/agents/vocabulary`, and the App's own agents (`ensureSystem`) in `GET /api/agents`.
 
 ## Health checks on a running App
 
-| Check                     | How                                                                                                                                                                                                             |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Runners                   | `GET /api/agents/runners` (`runtime list`): `status` (`online`, `offline`, `revoked`, `upgrade_required`), `lastSeenAt`, `tools` (installed, version, signed in), `policy`, `updateVersion`, `requiredProtocol` |
-| Agents that can take work | `GET /api/agents/available` (`agent list`): each agent and whether it can take work now                                                                                                                         |
-| Why a run waits           | The run's detail and `runs.workload()`: `RUN_WAIT_REASONS` (`noRunnerOnline`, `toolUnavailable`, `noSharedRunner`, `missingFeatures`, `concurrencyFull`, `runnersBusy`, …)                                      |
-| A run's history           | `GET /api/agents/runs/:runId` and its events (`run get`, `run events`); `failureReason` and `failureDetail`                                                                                                     |
-| Models                    | `GET /api/agents/models` (what agents may use), `POST /api/agents/checkModel` (`model check`), `GET /api/agents/defaultModels`                                                                                  |
-| Tarballs served           | `GET /api/agents/dist/manifest` signed in; `GET /api/agents/dist/products/<product>/targets/linux-x64?format=env`                                                                                               |
-| 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`                                                                                                              |
+| Check                     | How                                                                                                                                                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runners                   | `GET /api/agents/runners` (`runtime list`): `status` (`online`, `offline`, `revoked`, `upgrade_required`), `lastSeenAt`, `tools` (installed, version, signed in), `policy`, `updateVersion`, `requiredProtocol`     |
+| Agents that can take work | `GET /api/agents` (`agent list-all`): every agent, its state and why it cannot take the caller's work (`unusable`); `GET /api/agents/available` (`agent list`): the enabled ones and whether each can take work now |
+| Why a run waits           | The run's detail and `runs.workload()`: `RUN_WAIT_REASONS` (`noRunnerOnline`, `toolUnavailable`, `noSharedRunner`, `missingFeatures`, `secretsNotAllowed`, `concurrencyFull`, `runnersBusy`, …)                     |
+| A run's history           | `GET /api/agents/runs/:runId` and its events (`run get`, `run events`); `failureReason` and `failureDetail`                                                                                                         |
+| Model services            | `GET /api/agents/models` (what the App's own model calls may use), `POST /api/agents/checkModel` (`model check`)                                                                                                    |
+| Tarballs served           | `GET /api/agents/dist/manifest` signed in; `GET /api/agents/dist/products/<product>/targets/linux-x64?format=env`                                                                                                   |
+| 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                                                                                                                                                                                                                                                                                                                             |
-| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Runner shows offline                                                         | No heartbeat for 150 s. Check `nocobase-runner status` and `logs`, that its service is installed (`nocobase-runner service install`) and that it reaches the App's URL. `RUNNER_KEY_INVALID` or `RUNNER_REVOKED`: register it again with a new token. `RUNNER_OWNER_DISABLED`: its owner can no longer act (`people.provide` `inactive`). |
-| Runner shows `upgrade_required`                                              | It speaks a protocol outside the App's range. Rebuild and remount the runner tarball from the App's `@nocobase/agent-runner`, then `nocobase-runner update` (an npm-installed runner: `npm install -g @nocobase/agent-runner@<version>`); one that reports no product: reinstall with the one-line install. See [Runners](runners.md).    |
-| Runs queue with `toolUnavailable` or fail `toolAuth`                         | The agent's coding tool is not installed, not enabled for that runner, or not signed in. Sign in on the runner's machine as the runner's user and check the Runtimes page's Tools tab.                                                                                                                                                    |
-| Runs queue with `noRunnerOnline`, `noSharedRunner` or `missingFeatures`      | No online runner fits: only other people's personal runners, the agent names an offline runner, or the runner is too old for what the run needs (skills, secrets, mounts). Add or share a runner, or update it.                                                                                                                           |
-| Run fails `policyRefused`                                                    | The runner owner's `policy.json` excludes the agent, subject or repository. Retried on another runner; change the policy on the machine if this one should take it.                                                                                                                                                                       |
-| Run fails `modelUnavailable`                                                 | Runner: the tool's account cannot use the model; pick another model on the agent. Online: the service or model is disabled, deleted or unknown to its provider; check the Models page and `model check`.                                                                                                                                  |
-| Online run fails `toolAuth`, `toolQuota`, `toolRateLimit`, `contextOverflow` | The model service's key, quota or rate limit, or a conversation too long for the model. Fix the service's key or plan; rate limits and network errors are retried.                                                                                                                                                                        |
-| Online run fails `stepLimit`                                                 | The model kept calling tools; raise `agents.server.maxSteps` or tighten the agent's instructions.                                                                                                                                                                                                                                         |
-| Run fails `cliUnavailable`                                                   | The run's CLI could not be installed: no served tarball for the runner's platform (`PLATFORM_UNSUPPORTED`), or `agents.cli.name` differs from the App's `nocobase.cli.bin`. Build and mount the CLI tarballs.                                                                                                                             |
-| Run fails `setupFailed`                                                      | `assemble`, a brief section or a mount threw three times; read the server log for the throw.                                                                                                                                                                                                                                              |
-| Run fails `queuedExpired`                                                    | Waited longer than the subject's `queuedExpiryMs`; see why it waited.                                                                                                                                                                                                                                                                     |
-| `SECRETS_KEY_MISSING` (503)                                                  | `secrets.keys` is not configured; set it before storing variables or model service keys.                                                                                                                                                                                                                                                  |
-| `SCOPED_KEY_FORBIDDEN`                                                       | A scoped API key called a route outside the settings-only ones; use a session or an unscoped key.                                                                                                                                                                                                                                         |
-| `AGENT_TYPE_NOT_ALLOWED`                                                     | The subject kind does not list the agent's type in `agentTypes`.                                                                                                                                                                                                                                                                          |
-| `PLATFORM_UNSUPPORTED` / `PRODUCT_NOT_FOUND` from the install script         | The product or the platform is not in `agents.dist.dir/<channel>/`; check the mount and the `--targets` the build used.                                                                                                                                                                                                                   |
-| `REGISTRATION_TOKEN_INVALID` / `DOWNLOAD_TOKEN_INVALID`                      | The token expired (10 minutes for registration, 30 for downloads), was used up, or is of the other kind; mint a new one.                                                                                                                                                                                                                  |
-| `VARIABLES_MISSING`                                                          | Not this plugin: a deployment refused because a required deployment variable is unset. Set it where the deploying plugin keeps variables; agent variables never cause it.                                                                                                                                                                 |
-| `SQLITE_VEC_UNSUPPORTED`                                                     | No sqlite-vec build for the platform (Alpine/musl); configure `agents.vectors.store: pgvector`.                                                                                                                                                                                                                                           |
+| Symptom                                                                 | Cause and fix                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runner shows offline                                                    | No heartbeat for 150 s. Check `nocobase-runner status` and `logs`, that its service is installed (`nocobase-runner service install`) and that it reaches the App's URL. `RUNNER_KEY_INVALID` or `RUNNER_REVOKED`: register it again with a new token. `RUNNER_OWNER_DISABLED`: its owner can no longer act (`people.provide` `inactive`). |
+| Runner shows `upgrade_required`                                         | It speaks a protocol outside the App's range. Rebuild and remount the runner tarball from the App's `@nocobase/agent-runner`, then `nocobase-runner update` (an npm-installed runner: `npm install -g @nocobase/agent-runner@<version>`); one that reports no product: reinstall with the one-line install. See [Runners](runners.md).    |
+| Runs queue with `toolUnavailable` or fail `toolAuth`                    | The agent's coding tool is not installed, not enabled for that runner, or not signed in. Sign in on the runner's machine as the runner's user and check the Runtimes page's Tools tab.                                                                                                                                                    |
+| Runs queue with `noRunnerOnline`, `noSharedRunner` or `missingFeatures` | No online runner fits: only other people's personal runners have the agent, or the runner is too old for what the run needs (skills, secrets, mounts). Add or share a runner, or update it.                                                                                                                                               |
+| Run fails `policyRefused`                                               | The runner owner's `policy.json` excludes the agent, subject or repository. Retried on another runner; change the policy on the machine if this one should take it.                                                                                                                                                                       |
+| Run fails `modelUnavailable`                                            | The tool's account on that runner cannot use the model. The runner is marked so and offered none of that model's runs until it reports the tool's models differently; sign in with an account that has the model, or use another agent.                                                                                                   |
+| Run fails `cliUnavailable`                                              | The run's CLI could not be installed: no served tarball for the runner's platform (`PLATFORM_UNSUPPORTED`), or `agents.cli.name` differs from the App's `nocobase.cli.bin`. Build and mount the CLI tarballs.                                                                                                                             |
+| Run fails `setupFailed`                                                 | `assemble`, a brief section or a mount threw three times; read the server log for the throw.                                                                                                                                                                                                                                              |
+| Run fails `queuedExpired`                                               | Waited longer than the subject's `queuedExpiryMs`; see why it waited.                                                                                                                                                                                                                                                                     |
+| `SECRETS_KEY_MISSING` (503)                                             | `secrets.keys` is not configured; set it before storing variables or model service keys.                                                                                                                                                                                                                                                  |
+| `SCOPED_KEY_FORBIDDEN`                                                  | A scoped API key called a route outside the settings-only ones; use a session or an unscoped key.                                                                                                                                                                                                                                         |
+| `PLATFORM_UNSUPPORTED` / `PRODUCT_NOT_FOUND` from the install script    | The product or the platform is not in `agents.dist.dir/<channel>/`; check the mount and the `--targets` the build used.                                                                                                                                                                                                                   |
+| `REGISTRATION_TOKEN_INVALID` / `DOWNLOAD_TOKEN_INVALID`                 | The token expired (10 minutes for registration, 30 for downloads), was used up, or is of the other kind; mint a new one.                                                                                                                                                                                                                  |
+| `VARIABLES_MISSING`                                                     | Not this plugin: a deployment refused because a required deployment variable is unset. Set it where the deploying plugin keeps variables; agent variables never cause it.                                                                                                                                                                 |
+| `SQLITE_VEC_UNSUPPORTED`                                                | No sqlite-vec build for the platform (Alpine/musl); configure `agents.vectors.store: pgvector`.                                                                                                                                                                                                                                           |

package/dist/client/chat/settings-section.d.ts

@@ -1,5 +0,0 @@
-import type { ReactElement } from 'react';
-export declare function ChatSettingsSection({ canManage, }: {
-    readonly canManage: boolean;
-}): ReactElement;
-//# sourceMappingURL=settings-section.d.ts.map

package/dist/client/chat/settings-section.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"settings-section.d.ts","sourceRoot":"","sources":["../../../client/chat/settings-section.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAsB1C,wBAAgB,mBAAmB,CAAC,EAClC,SAAS,GACV,EAAE;IACD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,GAAG,YAAY,CAoGf"}

package/dist/client/chat/settings-section.js

@@ -1,76 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * The system default chat agent, at the top of the agents page: new conversations go to it when a person has no
- * default of their own (and a conversation may switch to it while its agent is offline). Those who manage agents
- * change it with the agent picker as a form field (avatar with availability, the menu grouped by type, "None" first);
- * everyone else reads its name.
- */
-import { useTranslation } from '@nocobase/i18n/client';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { agentsKeys } from '../api/keys.js';
-import { AgentPicker } from '../components/agent-picker.js';
-import { Field, FieldContent, FieldDescription, FieldGroup, FieldLabel, FieldTitle, } from '../components/ui/field.js';
-import { Skeleton } from '../components/ui/skeleton.js';
-import { useAgentPickerLabels } from '../hooks/use-agent-picker-labels.js';
-import { useAgentsApi } from '../hooks/use-agents-api.js';
-import { useNotify } from '../hooks/use-notify.js';
-import { useAgentText } from '../hooks/use-vocabulary.js';
-import { pickerAgentOf } from '../lib/agents.js';
-import { chatKeys } from './keys.js';
-import { useChatApi } from './use-chat.js';
-export function ChatSettingsSection({ canManage, }) {
-    const { t } = useTranslation();
-    const text = useAgentText();
-    const chat = useChatApi();
-    const agentsApi = useAgentsApi();
-    const notify = useNotify();
-    const queryClient = useQueryClient();
-    const settings = useQuery({
-        queryKey: chatKeys.settings,
-        queryFn: () => chat.settings(),
-    });
-    const agents = useQuery({
-        queryKey: agentsKeys.agents,
-        queryFn: () => agentsApi.agents(),
-    });
-    const save = useMutation({
-        mutationFn: (defaultAgentId) => chat.updateSettings({ defaultAgentId }),
-        onSuccess: (next) => {
-            queryClient.setQueryData(chatKeys.settings, next);
-            void queryClient.invalidateQueries({ queryKey: chatKeys.agents });
-            notify.success(t('chat.settings.saved'));
-        },
-        onError: (error) => notify.error(error),
-    });
-    const id = 'ag-chat-default';
-    const current = settings.data?.defaultAgentId ?? null;
-    const labels = useAgentPickerLabels(t('chat.settings.title'));
-    // The picker's agents, as the chat lists them.
-    const options = (agents.data ?? [])
-        .filter((agent) => !agent.archivedAt)
-        .map((agent) => pickerAgentOf(agent, text.name(agent), agent.id === current));
-    const currentName = current === null
-        ? t('chat.settings.none')
-        : (options.find((option) => option.id === current)?.name ??
-            t('chat.settings.unknown'));
-    let control;
-    if (!settings.data || !agents.data)
-        control = _jsx(Skeleton, { className: 'h-8 w-full sm:w-80' });
-    else if (!canManage)
-        control = (_jsx("p", { className: 'text-sm font-medium sm:max-w-80 sm:text-right', children: currentName }));
-    else
-        control = (_jsx(AgentPicker, { id: id, agents: options, 
-            // None, or an agent the list does not hold, reads as such.
-            value: current, labels: { ...labels, unknown: t('chat.settings.unknown') }, noneOption: {
-                label: t('chat.settings.none'),
-                onSelect: () => {
-                    if (current !== null)
-                        save.mutate(null);
-                },
-            }, onSelect: (agentId) => {
-                if (agentId !== current)
-                    save.mutate(agentId);
-            }, disabled: save.isPending, align: 'end', className: 'sm:w-80', "data-testid": 'chat-default-agent' }));
-    return (_jsx("section", { className: 'rounded-lg border p-4', "aria-labelledby": `${id}-title`, "data-testid": 'chat-settings', children: _jsx(FieldGroup, { children: _jsxs(Field, { orientation: 'responsive', children: [_jsxs(FieldContent, { children: [canManage ? (_jsx(FieldLabel, { id: `${id}-title`, htmlFor: id, children: t('chat.settings.title') })) : (_jsx(FieldTitle, { id: `${id}-title`, children: t('chat.settings.title') })), _jsx(FieldDescription, { children: t('chat.settings.description') })] }), control] }) }) }));
-}
-//# sourceMappingURL=settings-section.js.map

package/dist/client/chat/settings-section.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"settings-section.js","sourceRoot":"","sources":["../../../client/chat/settings-section.tsx"],"names":[],"mappings":"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"}

package/dist/client/components/agent-fields.d.ts

@@ -1,45 +0,0 @@
-/**
- * Fields the new-agent dialog and the agent page share: the coding tool (with how many runners offer it now), an
- * entry's reasoning effort, and the business actions the application lets an agent be given.
- */
-import { type AgentTool } from '@nocobase/agent-protocol';
-import type { ReactElement } from 'react';
-import { type AgentType } from '../../shared/agents.js';
-import type { RunnerSummary } from '../../shared/runners.js';
-export declare function ToolSelect({ id, value, runners, disabled, ariaLabel, onChange, }: {
-    readonly id: string;
-    readonly value: AgentTool;
-    /** For the count of runners each tool can run on now; none while loading. */
-    readonly runners: readonly RunnerSummary[] | undefined;
-    readonly disabled?: boolean;
-    /** For a select with no visible label. */
-    readonly ariaLabel?: string;
-    readonly onChange: (tool: AgentTool) => void;
-}): ReactElement;
-/** An entry's reasoning effort, among those its tool or service takes (`effortsFor`). */
-export declare function EffortSelect({ id, efforts, value, disabled, ariaLabel, onChange, }: {
-    readonly id: string;
-    readonly efforts: readonly string[];
-    /** Empty: the tool's or provider's default. */
-    readonly value: string;
-    readonly disabled?: boolean;
-    /** For a select with no visible label. */
-    readonly ariaLabel?: string;
-    readonly onChange: (effort: string) => void;
-}): ReactElement;
-/**
- * The business actions as checkboxes, grouped as the application groups them, with its titles. Actions meant for
- * another type of agent (`AgentActionOption.types`) are left out. `detailed` (the agent page) adds each action's
- * description, and lists the actions that are never granted to an agent greyed out with the reason, so people see the
- * boundary; elsewhere those are left out.
- */
-export declare function ActionCheckboxes({ idPrefix, value, type, disabled, detailed, onChange, }: {
-    readonly idPrefix: string;
-    readonly value: readonly string[];
-    /** The agent's type; every action when absent. */
-    readonly type?: AgentType;
-    readonly disabled?: boolean;
-    readonly detailed?: boolean;
-    readonly onChange: (actions: string[]) => void;
-}): ReactElement;
-//# sourceMappingURL=agent-fields.d.ts.map

package/dist/client/components/agent-fields.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-fields.d.ts","sourceRoot":"","sources":["../../../client/components/agent-fields.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAkD7D,wBAAgB,UAAU,CAAC,EACzB,EAAE,EACF,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;CAC9C,GAAG,YAAY,CAiCf;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,EAC3B,EAAE,EACF,OAAO,EACP,KAAK,EACL,QAAQ,EACR,SAAS,EACT,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C,GAAG,YAAY,CAgCf;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAChD,GAAG,YAAY,CA2Ff"}