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

package/package.json

@@ -1,6 +1,205 @@
 {
   "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.1",
+  "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/presets": {
+      "types": "./dist/shared/presets.d.ts",
+      "import": "./dist/shared/presets.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/agent-protocol": "^0.1.0-beta.1",
+    "@nocobase/app-cli-client": "^0.1.0-beta.0",
+    "@nocobase/cli-envelope": "^0.1.0-beta.0"
+  },
+  "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.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"
+  },
+  "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"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ./scripts/bundle-just-bash.mjs && 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,34 @@
+---
+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.
+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.
+
+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.
+- 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.
+- 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, 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)                    |
+| 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/distribution.md

@@ -0,0 +1,62 @@
+# 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.
+
+## 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.
+- 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 tarball itself, and `POST /api/agents/dist/downloadTokens`.
+
+## 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.
+
+## 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.
+
+## 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 App's CLI, installed by the script, has `<cli> update`, and says on stderr when a newer version is served.
+- 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,33 @@
+# 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`, `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                                                                                                                    |
+
+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.
+- 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.

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

@@ -0,0 +1,31 @@
+# Online agents and model services
+
+An online agent talks to a model of a model service and is run by the App itself, on every instance (`agents.server.enabled`), through the same claim as runner runs: it needs no runner and answers in seconds. Its tools are a sandboxed in-process shell (`bash`, no real processes or network) carrying the App's CLI, and `skill`, which reads one of the run's skills. The README's "What it does" (Online runs) and "Online agents" 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, one session id per conversation. Each model has a kind: `chat` (what agents talk to), `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`.
+- The system default chat model (Models page, `PUT /api/agents/defaultModels/chat`) is what an online agent that lists no model answers with. With none set, the first chat model an enabled service offers is used.
+- An online agent lists ordered entries (service, model, effort); its first is the default. A conversation may pick another of the agent's entries. A failing model fails the run; nothing falls back to another entry.
+- `GET /api/agents/models` (anyone signed in) lists what agents may use; `POST /api/agents/checkModel` (who reads agents) tests one with a short call and never throws.
+
+## The model gateway
+
+`online.gateway` on `agentsToken` serves the App's own model calls outside runs: `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 like runs, 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.
+
+`online.skills.register(skill)` adds a skill every online run gets besides its own, typically the App's CLI skill.
+
+## Commands in an online run
+
+The run's shell carries the App's CLI, built from the command manifest for the run (the actions of the waking person that the agent is configured with). Each command is one request through the App with the run's token, so the route checks the permission again. Commands that send or save files are refused. A route therefore needs `runToken` in its `security` and an `x-cli` `action` the gate allows before an online agent can call it.
+
+Run limits: `agents.server.maxSteps` model calls (then `stepLimit`); a cancel aborts within a second; at shutdown an instance hands its runs back (`runnerOffline`).
+
+## Consultations
+
+An online run may ask another online agent a question (`ask_agent`), synchronously, in a read-only child run (`parentRunId`) bounded by `agents.server.consult.timeoutMs` and `tokenBudget`, at most `CONSULT_MAX_DEPTH` deep. The gate keeps a consultation to reading actions plus those `ActionGate.consultable` allows. See the README's "Consultations" section.
+
+## 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,32 @@
+# Runners
+
+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; 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
+
+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,60 @@
+# 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
+  server: # online agents, run by every instance
+    enabled: true
+    maxSteps: 16
+    consult: { timeoutMs: 120000, tokenBudget: 200000 }
+  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.
+- `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.
+- `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 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`). 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 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.
+
+## 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.
+
+## 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.

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

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