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

package/package.json

@@ -2,7 +2,7 @@
   "name": "@nocobase/app-plugin-agents",
   "displayName": "Agents",
   "description": "Agents for NocoBase applications: agents, the model services online agents call, their runs and conversations, and the runners people connect to run them (registration, the long-poll claim, slots, the sweeper, build jobs, and the runner and CLI tarballs the application serves).",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.11",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -66,9 +66,9 @@
       "types": "./dist/shared/conversations.d.ts",
       "import": "./dist/shared/conversations.js"
     },
-    "./shared/presets": {
-      "types": "./dist/shared/presets.d.ts",
-      "import": "./dist/shared/presets.js"
+    "./shared/model-catalog": {
+      "types": "./dist/shared/model-catalog.d.ts",
+      "import": "./dist/shared/model-catalog.js"
     },
     "./shared/models": {
       "types": "./dist/shared/models.d.ts",
@@ -143,9 +143,9 @@
     "sqlite-vec": "^0.1.9",
     "yaml": "^2.9.0",
     "zod": "^4.6.5",
-    "@nocobase/agent-protocol": "^0.1.0-beta.1",
-    "@nocobase/app-cli-client": "^0.1.0-beta.0",
-    "@nocobase/cli-envelope": "^0.1.0-beta.0"
+    "@nocobase/agent-protocol": "^0.1.0-beta.8",
+    "@nocobase/app-cli-client": "^0.1.0-beta.7",
+    "@nocobase/cli-envelope": "^0.1.0-beta.1"
   },
   "peerDependencies": {
     "@base-ui/react": "^1.6.0",
@@ -160,39 +160,37 @@
     "react-router": "^7.0.2",
     "recharts": "^3.8.0",
     "remark-gfm": "^4.0.1",
-    "@nocobase/app-cli": "^1.0.0-beta.14",
-    "@nocobase/app-client": "^2.0.0-beta.2",
-    "@nocobase/app-plugin-authentication": "^2.0.0-beta.2",
-    "@nocobase/app-plugin-authorization": "^1.0.0-beta.25",
-    "@nocobase/app-plugin-file": "^1.0.0-beta.20",
-    "@nocobase/app-server": "^2.0.0-beta.1",
-    "@nocobase/authorization": "^1.0.0-beta.12",
-    "@nocobase/db": "^1.0.0-beta.18",
-    "@nocobase/i18n": "^1.0.0-beta.5",
-    "@nocobase/markdown-mermaid": "^0.1.0-beta.0",
-    "@nocobase/service-provider": "^0.0.2-beta.1"
+    "@nocobase/app-cli": "^1.0.0-beta.22",
+    "@nocobase/app-client": "^3.0.0-beta.1",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.9",
+    "@nocobase/app-plugin-authorization": "^1.0.0-beta.27",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.23",
+    "@nocobase/app-server": "^2.0.0-beta.7",
+    "@nocobase/authorization": "^1.0.0-beta.13",
+    "@nocobase/db": "^1.0.0-beta.20",
+    "@nocobase/i18n": "^1.0.0-beta.7",
+    "@nocobase/markdown-mermaid": "^0.1.0-beta.2",
+    "@nocobase/service-provider": "^0.0.2-beta.2"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.3",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.0",
-    "esbuild": "^0.28.2",
     "eslint": "^10.0.0",
     "jsdom": "^30.0.1",
-    "just-bash": "^3.6.0",
     "prettier": "^3.9.6",
     "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@nocobase/app-testing": "0.1.0-beta.1",
-    "@nocobase/db-postgres": "0.1.0-beta.3",
-    "@nocobase/db-sqlite": "0.1.0-beta.4",
-    "@nocobase/dev-config": "0.1.0-beta.19",
-    "@nocobase/jobs": "0.1.0-beta.2"
+    "@nocobase/app-testing": "0.1.0-beta.4",
+    "@nocobase/db-postgres": "0.1.0-beta.4",
+    "@nocobase/db-sqlite": "0.1.0-beta.5",
+    "@nocobase/dev-config": "0.1.0-beta.22",
+    "@nocobase/jobs": "0.1.0-beta.3"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node ./scripts/bundle-just-bash.mjs && nocobase-db-manifests",
+    "build": "tsc -p tsconfig.json && nocobase-db-manifests",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.type-tests.json --noEmit",
     "test": "vitest run --passWithNoTests",
     "lint": "eslint . --max-warnings 0",

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

@@ -1,24 +1,24 @@
 ---
 name: nocobase-app-plugin-agents
-description: Register the Agents plugin in a NocoBase App and configure it (agents.* in config.yml), contribute subjects, scopes, business actions, presets, CLI commands and reports through agentsToken, set up online agents and model services, connect runners (registration tokens, protocol, upgrade_required), build and serve the CLI and runner tarballs (pnpm nocobase cli build, --runner), or work out why a run, a runner or a model fails.
+description: Register the Agents plugin in a NocoBase App and configure it (agents.* in config.yml), contribute subjects, scopes, business actions, agent defaults, the App's own agents, CLI commands and reports through agentsToken, enable the agents discovered from runners, set up model services for the App's own model calls, connect runners (registration tokens, protocol, upgrade_required), build and serve the CLI and runner tarballs (pnpm nocobase cli build, --runner), or work out why a run, a runner or a model fails.
 metadata:
   short-description: Agents, runners, model services and their distribution
 ---
 
 # Agents App Plugin
 
-Use this Skill when an App gives people agents to work with: online agents that answer through a model service on the server, or work agents that drive a coding tool (Claude Code, Codex, OpenCode, Pi) on a runner someone connects. Use it as well to build the App's CLI and the runner as tarballs the App serves, and to diagnose a run, a runner or a model that does not work. Do not use it for the business data agents act on; that stays with `nocobase-app-development` and the plugins that own it.
+Use this Skill when an App gives people agents to work with: agents that drive a coding tool (Claude Code, Codex, OpenCode, Pi) on a runner someone connects, one for each tool and model the runners report. Use it as well to build the App's CLI and the runner as tarballs the App serves, and to diagnose a run, a runner or a model that does not work. Do not use it for the business data agents act on; that stays with `nocobase-app-development` and the plugins that own it.
 
 The package README is the full reference: read it at `node_modules/@nocobase/app-plugin-agents/README.md` (in this repository, `packages/plugins/app-plugin-agents/README.md`). The references below say what to do and point to its sections rather than repeating them.
 
 ## Key rules
 
-- The plugin knows no business of its own. Subjects, scopes, business actions, presets, CLI commands and report pages are the App's, contributed through `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` when the App's providers boot. With nothing contributed, agents still work in conversations.
-- An agent's type (`runner` or `online`) is chosen once and never changes. Online agents need a model service and no runner; runner agents need a runner that is online, has the agent's coding tool installed and signed in, and whose owner's local policy lets it take the work.
+- The plugin knows no business of its own. Subjects, scopes, business actions, the instructions and actions every discovered agent gets, CLI commands and report pages are the App's, contributed through `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` when the App's providers boot. With nothing contributed, agents still work in conversations.
+- Nobody creates agents: each coding tool and model a runner reports becomes one, pending until someone who manages agents writes what it is good at and enables it. Only enabled agents get work, and only on a runner that is online, has the agent's tool signed in with its model, and whose owner's local policy lets it take the work. There are no online agents; model services serve the App's own model calls.
 - Variables and model service keys are sealed with the App's secrets service: configure `secrets.keys` before storing any, or the API answers `SECRETS_KEY_MISSING` (503).
 - The plugin registers no pages. The App routes the exported pages and mounts the chat; the App also binds `agentsAccessToken`, or every business action level is `none`.
 - `subjects.register`'s `context.assemble`, brief sections and mounts run inside the claim's transaction: database reads only, never a network or a model call. Read anything else in the optional `prepare(run)`.
-- Tarballs are built by `pnpm nocobase cli build` (the App's CLI) and `cli build --runner` (`nocobase-runner`) as separate CI artifacts and mounted into `storage/runners/dist` (or `agents.dist.dir`). Never bake them into the App's image or commit them.
+- Tarballs are built by `pnpm nocobase cli build` (the App's CLI) and `cli build --runner` (`nocobase-runner`), either as separate CI artifacts mounted into `storage/runners/dist` (or `agents.dist.dir`), or by the App's own `pnpm build` into its build output (universal packages, at the versions it was built with) and served from there. Never commit them.
 - In examples, name the App's CLI after the App (`acme`), never `nocobase` or `nocobase-runner`.
 
 ## References
@@ -26,8 +26,9 @@ The package README is the full reference: read it at `node_modules/@nocobase/app
 | Task                                                                                                                  | Read                                                                               |
 | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | Register the plugin, its prerequisites and `agents.*` configuration, mount the pages and the chat                     | [Setup and configuration](references/setup-and-config.md)                          |
-| Contribute subjects, scopes, actions, presets, CLI commands, people, reports, brief sections, mounts                  | [Extension points](references/extension-points.md)                                 |
-| Online agents, model services, the model gateway, consultations, vectors                                              | [Online agents and model services](references/online-agents.md)                    |
+| Contribute subjects, scopes, actions, agent defaults, the App's own agents, CLI commands, people, reports, mounts     | [Extension points](references/extension-points.md)                                 |
+| Agents discovered from runners, the model catalog, enabling agents, availability, the App's own agents                | [Agents](references/agents.md)                                                     |
+| Model services, the model gateway, vectors                                                                            | [Model services](references/model-services.md)                                     |
 | Register runners, how claims and heartbeats work, local policy, protocol and `upgrade_required`                       | [Runners](references/runners.md)                                                   |
 | Build the CLI and runner tarballs, serve them, CI artifacts, install script, download tokens, updates, the npm runner | [Distribution](references/distribution.md)                                         |
 | Variables and secrets, the skill library, chat attachments, usage, prices and reports                                 | [Variables, skills, attachments and usage](references/variables-skills-usage.md)   |

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

@@ -0,0 +1,30 @@
+# Agents
+
+Nobody creates an agent. Each coding tool and model a runner reports signed in becomes one agent, named from the model catalog that ships with the plugin (such as "Claude · Opus 5.5"), and starts pending. `docs/runner-agents.md` in the package and the README's "What it does" (Agents) are the reference.
+
+## Enabling agents
+
+- A pending agent gets no work. Someone who manages agents (`agents.agents` manage) enables it on the Agent page ("Fill in and enable") or with `PATCH /api/agents/:agentId` (`agent update`), writing what it is good at — the project manager hands it work by this — and optionally its default reasoning effort. The page starts the description from the catalog's suggestion.
+- Every change names the agent's revision (`expectedRevision`); `REVISION_CONFLICT` means someone changed it since, so read it again. `GOOD_AT_REQUIRED`: enabling needs a description. `EFFORT_UNSUPPORTED`: the tool does not take that effort. `AGENT_MANAGED`: an App's own agent is changed through the App.
+- Disabling an agent withdraws its queued runs and announces `agent.removed` (`reason` `disabled`); the App lets go of the work it gave the agent. Work for an agent that is not enabled is refused with `AGENT_NOT_ENABLED`.
+- Anyone signed in reads the agents (`GET /api/agents`, `agent list-all`); `GET /api/agents/agentNames` names every agent there has been, for runs that name a removed one.
+
+## Discovery management
+
+The page defaults to enabled agents. New discoveries are collapsed, grouped by tool and known catalog model, and searchable by model or provider; unknown provider-qualified models are kept separate. The enable dialog chooses an original provider candidate without changing its ID or execution model. Opening an enabled group exposes the other provider candidates, and disabled agents remain accessible.
+
+Administrators ignore pending groups individually or in an atomic batch through `PUT /api/agents/discoveryPreferences` (`agent discovery set --input <file>`). Read `discoveryKey`, `discoveryRevision` and `ignored` from `GET /api/agents`, then send unique groups with their expected revision and `ignored: true` or `false`. Preferences survive reports and restarts, including new providers in the same group. Restoring returns pending discoveries without enabling them. Enabled groups cannot be ignored; stale revisions conflict with concurrent enabling. See `docs/runner-agents.md` for the body and migration.
+
+## Where an agent can run
+
+`GET /api/agents` answers, per caller, how many team and personal runners online have the agent's tool signed in with its model, whether only personal runners have it (`personalOnly`: they take their owners' work only), and `unusable`, why the caller's work cannot start now: `pending`, `disabled`, `unreported` (no runner reported it for 14 days), `notConfigured`, `noRunner` or `othersPersonal`. The roster (`GET /api/agents/available`, `agent list`, `Agents.roster`) lists the enabled agents reported recently with whether each would take the caller's work now. A run that fails `modelUnavailable` marks that tool and model unavailable on its runner until the runner reports the tool's models differently.
+
+## The App's own agents and defaults
+
+- `agents.ensureSystem(input)` keeps an agent of the App's own, such as a project manager: fixed id, name, description, instructions, business actions and the tools and models it runs with. Call it at boot; it creates the agent the first time and writes changes after.
+- `agents.setDefaults(provider)` gives every discovered agent the App's instructions and business actions; call `agents.applyDefaults()` after the provider changes so agents discovered earlier get them too. Without a provider, business actions marked `defaultOn` apply.
+- The system default chat agent is the App's to set (`PATCH /api/agents/chatSettings`); upgrading clears it along with every agent an earlier version kept.
+
+## Upgrading from configured agents
+
+The `202610240020_ag_runner_agents` migration removes every agent an earlier version kept, online agents included: their rows stay disabled with `deletedAt` so history still names them, their queued runs are cancelled, their pending run requests withdrawn, and default chat agents cleared. After upgrading, wait for runners to report (or restart them), enable the agents that appear, and set the system default chat agent again.

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` and the skill-only `global` are 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,16 @@ 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 the fixed `global/default` target, a registered application scope, or a working directory (`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.
+Every run merges global → application scopes → workdir; later targets override the same slug. `skill attachment get/set global default` requires `agents.agents` read/manage for reading and manage for writing. An empty `skillIds` array clears the target. Agent skill attachments are refused and legacy rows are ignored; agent variables remain supported. `global` is reserved and cannot be registered as an application scope or used for variables. Global changes affect subsequent claims and their existing skill fingerprint; no runner protocol change is needed.
+
+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.