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

package/package.json

@@ -1,6 +1,203 @@
 {
   "name": "@nocobase/app-plugin-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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.10",
+  "type": "module",
+  "prettier": "@nocobase/dev-config/prettier",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./server/tokens": {
+      "types": "./dist/server/tokens.d.ts",
+      "import": "./dist/server/tokens.js"
+    },
+    "./testing": {
+      "types": "./dist/server/testing.d.ts",
+      "import": "./dist/server/testing.js"
+    },
+    "./shared/access": {
+      "types": "./dist/shared/access.d.ts",
+      "import": "./dist/shared/access.js"
+    },
+    "./shared/agents": {
+      "types": "./dist/shared/agents.d.ts",
+      "import": "./dist/shared/agents.js"
+    },
+    "./shared/runs": {
+      "types": "./dist/shared/runs.d.ts",
+      "import": "./dist/shared/runs.js"
+    },
+    "./shared/runners": {
+      "types": "./dist/shared/runners.d.ts",
+      "import": "./dist/shared/runners.js"
+    },
+    "./shared/jobs": {
+      "types": "./dist/shared/jobs.d.ts",
+      "import": "./dist/shared/jobs.js"
+    },
+    "./shared/variables": {
+      "types": "./dist/shared/variables.d.ts",
+      "import": "./dist/shared/variables.js"
+    },
+    "./shared/skills": {
+      "types": "./dist/shared/skills.d.ts",
+      "import": "./dist/shared/skills.js"
+    },
+    "./shared/briefs": {
+      "types": "./dist/shared/briefs.d.ts",
+      "import": "./dist/shared/briefs.js"
+    },
+    "./shared/realtime": {
+      "types": "./dist/shared/realtime.d.ts",
+      "import": "./dist/shared/realtime.js"
+    },
+    "./shared/reports": {
+      "types": "./dist/shared/reports.d.ts",
+      "import": "./dist/shared/reports.js"
+    },
+    "./shared/conversations": {
+      "types": "./dist/shared/conversations.d.ts",
+      "import": "./dist/shared/conversations.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",
+      "import": "./dist/shared/models.js"
+    },
+    "./shared/i18n": {
+      "types": "./dist/shared/i18n.d.ts",
+      "import": "./dist/shared/i18n.js"
+    },
+    "./shared/vocabulary": {
+      "types": "./dist/shared/vocabulary.d.ts",
+      "import": "./dist/shared/vocabulary.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./client/config": {
+      "types": "./dist/client/config.d.ts",
+      "import": "./dist/client/config.js"
+    },
+    "./client/routes": {
+      "types": "./dist/client/routes.d.ts",
+      "import": "./dist/client/routes.js"
+    },
+    "./client/runs": {
+      "types": "./dist/client/runs.d.ts",
+      "import": "./dist/client/runs.js"
+    },
+    "./client/kit": {
+      "types": "./dist/client/kit.d.ts",
+      "import": "./dist/client/kit.js"
+    },
+    "./client/chat": {
+      "types": "./dist/client/chat.d.ts",
+      "import": "./dist/client/chat.js"
+    },
+    "./client/profile": {
+      "types": "./dist/client/profile.d.ts",
+      "import": "./dist/client/profile.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-sdk/alibaba": "^2.0.60",
+    "@ai-sdk/anthropic": "^4.0.71",
+    "@ai-sdk/cohere": "^4.0.54",
+    "@ai-sdk/deepseek": "^3.0.58",
+    "@ai-sdk/google": "^4.0.87",
+    "@ai-sdk/moonshotai": "^3.0.62",
+    "@ai-sdk/openai": "^4.0.83",
+    "@ai-sdk/openai-compatible": "^3.0.62",
+    "ai": "^7.0.127",
+    "better-sqlite3": "^13.0.3",
+    "hono": "^4.13.2",
+    "knex": "^3.1.0",
+    "ollama-ai-provider-v2": "^4.0.1",
+    "pg": "^8.23.0",
+    "sqlite-vec": "^0.1.9",
+    "yaml": "^2.9.0",
+    "zod": "^4.6.5",
+    "@nocobase/app-cli-client": "^0.1.0-beta.6",
+    "@nocobase/agent-protocol": "^0.1.0-beta.7",
+    "@nocobase/cli-envelope": "^0.1.0-beta.1"
+  },
+  "peerDependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@oclif/core": "^4.14.0",
+    "@tanstack/react-query": "^5.81.5",
+    "class-variance-authority": "^0.7.1",
+    "cn": "^0.4.0",
+    "lucide-react": "^0.487.0",
+    "react": "^19.0.0",
+    "react-day-picker": "10.0.1",
+    "react-markdown": "^10.1.0",
+    "react-router": "^7.0.2",
+    "recharts": "^3.8.0",
+    "remark-gfm": "^4.0.1",
+    "@nocobase/app-cli": "^1.0.0-beta.21",
+    "@nocobase/app-client": "^3.0.0-beta.1",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.8",
+    "@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.6",
+    "@nocobase/authorization": "^1.0.0-beta.13",
+    "@nocobase/db": "^1.0.0-beta.19",
+    "@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",
+    "eslint": "^10.0.0",
+    "jsdom": "^30.0.1",
+    "prettier": "^3.9.6",
+    "react-dom": "^19.2.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@nocobase/app-testing": "0.1.0-beta.3",
+    "@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 && 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",
+    "lint:fix": "eslint . --fix --max-warnings 0",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build",
+    "fix": "pnpm lint:fix && pnpm format"
+  }
 }

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

@@ -0,0 +1,35 @@
+---
+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, 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: 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, 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`), 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
+
+| 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, 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)   |
+| Check that everything works, and diagnose failures                                                                    | [Verification and troubleshooting](references/verification-and-troubleshooting.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

@@ -0,0 +1,79 @@
+# Distribution: the CLI and runner tarballs
+
+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
+
+```bash
+pnpm nocobase cli build              # the App's CLI (needs nocobase.cli in package.json)
+pnpm nocobase cli build --runner     # nocobase-runner, from @nocobase/agent-runner
+```
+
+- `--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.
+
+Each product lands in a directory of its own, with a manifest of every file's SHA-256 and size:
+
+```
+<out>/<channel>/<product>/manifest.json
+<out>/<channel>/<product>/<version>/<product>-v<version>-<target>.tar.gz
+```
+
+## 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 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
+
+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
+
+The install script (`GET /api/agents/dist/installScript`, no credential, it carries no secret) installs the App's CLI under `~/.local/share/<cli>` and links it into `~/.local/bin`:
+
+```bash
+# The CLI alone, with a download token any signed-in person mints (one platform, three downloads within 30 minutes):
+curl -fsSL https://app.example.com/api/agents/dist/installScript | sh -s -- --token <download token>
+
+# A runtime: also installs nocobase-runner, registers it and starts it as a user service. "Add runtime" shows this line:
+curl -fsSL https://app.example.com/api/agents/dist/installScript | sh -s -- --runner --server https://app.example.com --token <registration token>
+```
+
+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 (`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
+
+`@nocobase/agent-runner` is published to npm with the `nocobase-runner` command, for a machine that already has Node.js 24 or later and prefers a package manager to the install script:
+
+```bash
+npm install -g @nocobase/agent-runner
+nocobase-runner register --server https://app.example.com --token <registration token>
+nocobase-runner service install
+```
+
+Such a runner is not in the install script's layout, so it does not update itself: upgrade it with npm to a version that speaks the App's protocol. Install the App's CLI separately (the download-token line above) unless runs get it from the served tarball.

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

@@ -0,0 +1,43 @@
+# Extension points
+
+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`              | 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.
+- 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

@@ -0,0 +1,46 @@
+# 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
+
+A runner registers once per App with a one-time registration token (10 minutes):
+
+- On the web: Runtimes page, "Add runtime". It asks who the runner works for (personal, or team for who manages `agents.runners`), which coding tools it may run and its maximum concurrent runs, then shows the one-line install and the register command with a fresh token, and waits for the runner to connect.
+- Through the API: `POST /api/agents/runners/registrationTokens` (CLI: `runtime token create`).
+- From the App's checkout or deployment: `pnpm nocobase agents runner-token --trust team` or `--trust ownerOnly --owner <user id>`, optionally `--tools claude,codex`. It prints the token (`--json` for the envelope).
+
+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, 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
+
+- **Heartbeat**: the runner reports its system, features, coding tools (version, installed, signed in), its owner's local policy and the product it runs as. It is marked offline after 150 s without one. The heartbeat answer reconciles what it holds (releasing what the server no longer thinks it holds, asking it to stop what was cancelled) and carries an `upgrade` notice when a newer `nocobase-runner` is served for its platform.
+- **Claim**: one long-poll, `POST /api/agents/runners/claim?wait=true`, answers jobs and runs together, at most the runner's free slots. A run is handed over only when one of the agent's tools is enabled, installed and signed in there, the agent names no runner or this one, the runner is shared or owned by who woke the agent, its features cover what the run needs, the agent's concurrency has room and the runner's local policy allows the agent, subject and repositories. The claim renders the brief, mints a run token and hands over working directories, variables, skills and the CLI to install.
+- **Lease and sweep**: a runner renews its lease while it works; the sweeper (every 30 s) takes back runs from runners that went away or lost their lease, and retries the retryable failures (`runnerOffline`, `policyRefused`, `leaseExpired`, `startTimeout`, `cliUnavailable`, `toolNetwork`, `toolRateLimit`) while attempts remain.
+- **Local policy**: the machine's owner decides what it takes in `~/.nocobase-runner/policy.json` (agents, subjects, repos, build, per-App overrides). An App cannot change it. Work outside it fails `policyRefused` and goes to another runner; a policy file it cannot read makes it take nothing.
+
+## Protocol versions and `upgrade_required`
+
+Every runner request carries its protocol version (`PROTOCOL_VERSION` of `@nocobase/agent-protocol`). The App serves a range (`MIN_PROTOCOL_VERSION` to `PROTOCOL_VERSION`; `RunnerSummary.requiredProtocol` on the API). A runner outside it stays connected with status `upgrade_required`: it gets no work, what it held is released, and its owner is told once per protocol through the `notice` event (`runner_upgrade_required`; `notice.cleared` once it connects with a supported protocol). Forward that event to the App's inbox or notifications so the owner hears about it.
+
+What to do: upgrade the runner to a version that speaks the App's protocol. An installed runner updates itself between runs when the App serves a newer `nocobase-runner`, or now with `nocobase-runner update`; that only helps once the App serves a runner built from the matching `@nocobase/agent-runner`, so rebuild and remount the runner tarballs whenever the App's agents plugin is upgraded (see [Distribution](distribution.md)). A runner that reports no product (installed before products existed) is offered no update: install it again with the one-line install.
+
+## 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

@@ -0,0 +1,57 @@
+# Setup and configuration
+
+## Register the plugin
+
+The plugin has three entries, each listed in the App's matching composition root:
+
+| Root                | Import                                                    | Entry                                               |
+| ------------------- | --------------------------------------------------------- | --------------------------------------------------- |
+| `server/plugins.ts` | `import agents from '@nocobase/app-plugin-agents/server'` | `agents`                                            |
+| `client/plugins.ts` | `import agents from '@nocobase/app-plugin-agents/client'` | `agents()`                                          |
+| `cli/plugins.ts`    | `import agents from '@nocobase/app-plugin-agents/cli'`    | `agents` (adds `pnpm nocobase agents runner-token`) |
+
+Register `@nocobase/app-plugin-authentication`, `@nocobase/app-plugin-authorization` and `@nocobase/app-plugin-file` before it; they are its peers, and chat attachments and the skill library store files through the file plugin and Drive. Run `pnpm nocobase db apply` after adding it: the plugin brings its own migrations. Run `pnpm nocobase skills sync` so this Skill reaches the App's `.agents/skills/`.
+
+The App binds `agentsAccessToken` (`AgentsAccess.scopeOf(identity, key)`) from one of its own providers to say how far each caller's business actions reach (`BUSINESS_ACTIONS` in `@nocobase/app-plugin-agents/shared/access`). Unbound, every level is `none`, and only who manages agents (the `agents.agents` settings item) changes agents and skills. The README's "HTTP API" section lists the four settings items (`agents.agents`, `agents.runners`, `agents.prices`, `agents.services`) and what each allows.
+
+Contributions (subjects, scopes, actions and the rest) go in a provider of the App that resolves `agentsToken` at boot; see [Extension points](extension-points.md). Keep them together, for example in `server/agents/`, and the browser's side in `client/agents/`.
+
+## The App's own CLI
+
+Agents call the App through the App's CLI. An App that wants one declares it under `nocobase.cli` in its `package.json` (`bin`, `displayName`, `envPrefix`, `auth.clientId`, `skills`, …) and adds `@nocobase/app-cli-client` to its `devDependencies`, plus `@nocobase/agent-runner` to pack the runner. `@nocobase/app-cli`'s README, section "The application's own CLI: `cli build` and `cli link`", lists every field. `pnpm nocobase cli link` makes `pnpm exec acme` run it during development. Its commands are the App's API routes that declare `x-cli` (`cliRoute()` in `describeRoute()`), served by `GET /api/cli/manifest`; a route a run may call lists `runToken` in its `security` and gives its `x-cli` an `action`. The README's "The CLI's commands" section has the details.
+
+## Configuration
+
+Everything is optional. Read the README's "Configuration" section for the annotated block; in short:
+
+```yaml
+agents:
+  cli: # the CLI runs get
+    name: acme
+    credentialFile: .acme/run.json # .<name>/run.json by default
+    package: { kind: served } # or { kind: npm, package, version }, or { kind: preinstalled }
+  app: { id: acme, name: Acme } # how runners name this App
+  dist: # the runner and CLI tarballs
+    dir: storage/runners/dist # the default; relative to the App root
+    channel: stable
+    versions: { acme: 0.1.0 } # pin a product instead of the channel's highest
+    npm: # a product with no tarball in dir, named on npm instead (exact versions)
+      nocobase-runner: { package: '@nocobase/agent-runner', version: 1.0.0 }
+  vectors:
+    store: sqlite-vec # the default; pgvector (own PostgreSQL), or false
+    path: storage/vectors.sqlite
+  skills:
+    disk: s3 # Drive disk for skill files; drive.default by default
+```
+
+- `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.
+- `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, 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 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

@@ -0,0 +1,21 @@
+# Variables, skills, attachments and usage
+
+## Variables and secrets
+
+Variables (`agSecrets`) are environment variables for a runner agent's process. Every one is a secret sealed with the App's secrets service, so `secrets.keys` must be configured first (otherwise `SECRETS_KEY_MISSING`, 503). They are set on an agent, on a working directory (`workdir`) or on a scope the App registers (`scopes.register`), and merged for a run in the order the subject names its scopes, then its working directories, then the agent. They reach only runners with the `secrets` feature. Values are write-only; revealing one and every delivery are audited (`agSecretAudits`, `variable audit list`). The redactor replaces delivered values with `[REDACTED]` in everything a runner reports.
+
+On the App's own pages, `VariablesSection` from `client/kit` edits a scope's variables. On the CLI: `variable list|set|delete|reveal <scope kind> <scope>`. `pnpm nocobase secrets rotate` reseals them under a new key.
+
+## 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`). 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 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. 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 `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.