@nocobase/app-plugin-agents 0.1.0-beta.8 → 1.0.0-beta.15

package/README.md

@@ -1,54 +1,59 @@
 # @nocobase/app-plugin-agents
 
-Agents for NocoBase applications: the agents people configure, their runs, and people's conversations with agents. Runner agents run on the runners people connect (each a runtime: a runner on a server, a VM or someone's own device), which this plugin registers, hands work to and serves the runner and CLI tarballs for; the wire protocol runners and the application's CLI speak is `@nocobase/agent-protocol`, and the runner is `@nocobase/agent-runner` (`nocobase-runner`).
+Applications may restrict personal runner use for comment-origin work by supplying `EnqueueRequest.comment` only at their authenticated comment entry point and binding `SubjectBinding.commentOwnerKey` and `responsibleUserId`. Runs share their first comment run as `commentRootRunId`; independent events carry no comment fields. Unconfirmed external comment work remains queued for team runners. When no compatible team runner exists, a `personalRunner` run request releases the existing chain on confirmation instead of creating another run. The original requester can use the existing `runAsMe` endpoint from a pending or rejected personal runner request; rejection remains recorded. Claims, decisions and input merging enforce this boundary on the server without changing the runner protocol.
+
+Agents for NocoBase applications: the agents discovered from the runners people connect, their runs, and people's conversations with agents. Agents run on runners (each a runtime: a runner on a server, a VM or someone's own device), which this plugin registers, hands work to and serves the runner and CLI tarballs for; the wire protocol runners and the application's CLI speak is `@nocobase/agent-protocol`, and the runner is `@nocobase/agent-runner` (`nocobase-runner`).
 
 Workspace cleanup supports optional application bindings for legacy subject keys (`SubjectWorkspaces.resolveKeys`) and trusted merged PR head evidence by repository (`SubjectWorkspaces.commits`). Ownership must be confirmed from saved runs; settlement never bypasses local tracked-change, commit or submodule checks. Runtime diagnostics require the existing machine-information permission and distinguish ended work, allowed cleanup and retained work, with the workspace report's timestamp. See [workspace cleanup integration](https://github.com/nocobase/nocobase/blob/v3-develop/packages/plugins/app-plugin-agents/docs/workspace-cleanup.md) for the protocol, binding rules and compatibility behavior.
 
-An agent is one of two types, chosen when it is created and never changed. A **work** agent drives a coding tool on a runner, in a working directory. An **online** agent talks to a model of one of the model services this plugin keeps and is run by the application itself, on the server: it needs no runner, answers in seconds, and its tools are the application's commands. Both share everything else: runs, conversations, transcripts, permissions, usage and reports.
+`GET /api/agents/runners` and `runtime list` return workspace totals only: disk capacity, directory count, unpushed count, collection time, disk measurement time and report interval. They omit `workspaceUsage.workspaces`. Open a runtime's details, call `GET /api/agents/runners/:runnerId`, or use `runtime get` to load directory diagnostics. Directory paths and cleanup evidence retain the existing machine-information permission checks; callers without that permission receive an empty directory array in the detail response. The list uses stored totals without normalizing directory entries (older reports without totals still derive them); database reads and permissions are unchanged.
+
+Nobody creates an agent. Each coding tool and model a runner reports signed in becomes one agent (`AgentService.syncRunner`, in the transaction of the runner's report), named from the model catalog that ships with the plugin (`shared/model-catalog.ts`: `normalizeModel` makes one model reported under two spellings one agent, and `agentNameOf` names it, such as "Claude · Opus 5.5" for Claude Code's `claude-opus-5-5`; a model the catalog does not know is named after its id), and starts **pending**. Someone who manages agents writes what it is good at, starting from the catalog's suggestion, picks its default reasoning effort and enables it; only **enabled** agents are offered work, and an agent may be disabled again. An application may also keep agents of its own (`ensureSystem`, `source` `system`), such as a project manager, whose name, instructions, business actions and models it writes itself. Runner agents remain separate from server-side OnlineAgent chats. `agentsToken.onlineAgent` runs the AI SDK with registered business tools over the existing conversations and messages, and powers the original chat HTTP API and shared browser client. For configuration and integration, read the [OnlineAgent Skill reference](skills/nocobase-app-plugin-agents/references/online-agent.md).
 
-The plugin knows no domain of its own beyond conversations: what agents work on (subjects), the scopes variables are kept in, the business actions an agent may be given, the presets to start an agent from and the report pages are the application's, which contributes them through the extension points below; the CLI's business commands are the application's own routes, each described with `cliRoute()`. The assembling application does it in `server/agents` and `client/agents`. With nothing contributed, the plugin still runs agents in conversations on runners, with its own commands.
+The plugin knows no domain of its own beyond conversations: what agents work on (subjects), the scopes variables are kept in, the business actions an agent may be given and those every discovered agent gets, and the report pages are the application's, which contributes them through the extension points below; the CLI's business commands are the application's own routes, each described with `cliRoute()`. The assembling application does it in `server/agents` and `client/agents`. With nothing contributed, the plugin still runs agents in conversations on runners, with its own commands.
 
 ## What it does
 
+Registering the same runner name and hostname again revokes every active prior registration and its keys for the token's owner, leaving other owners' runners untouched. Registration uses the existing transaction without a dedicated lock or additional table. Simultaneous registrations may leave multiple active records until the next registration cleans them up. Existing tasks continue through the usual sweep and retry rules.
+
 Applications forward the `notice` event of type `run_secrets_not_allowed` to the run's actor and owner: a personal runner left the run because some of its variables are for team runners only. Its subject is the run, its parameters are `runId`, `agentId` and `variables` (in words), and its key is stable per run. `notice.cleared` settles it once a runner takes the run.
 
 Repository access providers that mint credentials in `prepare` implement the idempotent `discard(run, prepared)` hook to revoke them when the claim is skipped or rolled back. It runs outside the transaction and receives the same prepared value as `forRun`. The application owns code host credentials and their revocation API; providers without this hook cannot revoke externally issued credentials.
 
-- **Agents** (`agAgents`): who an agent is and how it works: its name, description and avatar, optional instructions (the last layer of its brief, preferences that never override the rules or the task), its type (`runner` or `online`, immutable: a patch naming one is refused), the business actions it may perform, who may wake it and how many attempts a run gets. Which tool or model it works with is an ordered list, `modelEntries`, whose first entry is its default, each entry with its own reasoning effort (`effort`, null for the default). A runner agent's entries pair a coding tool with a model (null for the tool's default) and an effort its tool takes (`TOOL_EFFORTS` of `@nocobase/agent-protocol`), and it has its skills, its tool policy (of which runners use only the idle timeout and the turn limit: they run agents with full access, see the agent-runner README), its own variables, optionally the runners it may run on, and how many runs it may have at once; it has at least one entry. An online agent's entries pair a model service with one of its models (an entry is checked against what the model catalog offers when it is added) and an effort among `ONLINE_EFFORTS`, and it has none of a runner's settings; an online agent with no entry is not configured yet: it is listed as needing a model and left out of `GET /api/agents/available` until it has one; it is offered no business action meant for runner agents only (`AgentActionOption.types`). Its configuration carries a `revision`, raised by every change (editing, archiving, restoring): `PATCH /api/agents/:agentId` names the revision it was made against (`expectedRevision`) and is refused with 409 `REVISION_CONFLICT` (`metadata.revision` the current one) when someone saved the agent since, and a patch that changes nothing raises nothing. Every change is kept in its history (`agAgentChanges`, `GET /api/agents/:agentId/history`, with `afterRevision` for what came after a revision): who, when, and the fields that changed with their values before and after, except its variables, which are named with whether they were added, changed or removed, never valued. Archiving an agent withdraws its queued runs at once; archiving and deleting it announce `agent.removed`.
+- **Agents** (`agAgents`): one for each coding tool and model the runners report (`source` `runner`, its id `runnerAgentId(tool, model)`), and the application's own (`source` `system`). An agent has a name (the catalog's, or the model's id), what it is good at (`description`: the project manager hands it work by this; required to enable it), its `status` (`pending` until someone enables it, `enabled` or `disabled`), its tool and normalized model, one model entry (`modelEntries`: the tool, the model and the default reasoning effort, `medium` when the tool takes it), and when a runner last reported it (`lastReportedAt`, refreshed at most every ten minutes). Its instructions and business actions are the application's, the same for every discovered agent (`agents.setDefaults(provider)`, written to each that differs by `applyDefaults()`; actions marked `defaultOn` otherwise), and it keeps its skills, its variables and its tool policy (of which runners use only the idle timeout and the turn limit: they run agents with full access, see the agent-runner README); it may have as many runs at once as runners' slots allow. An agent no runner reported for 14 days (`AGENT_UNREPORTED_AFTER_MS`) is listed as unreported and left out of the roster until a runner reports it again. Changing an agent (`PATCH /api/agents/:agentId`, `agents.agents` manage) writes only what it is good at, its effort (one its tool takes, else 400 `EFFORT_UNSUPPORTED`) and whether it is enabled (400 `GOOD_AT_REQUIRED` without a description); an application's own agent is changed through the application (400 `AGENT_MANAGED`). Every change raises its `revision`: a patch names the revision it was made against (`expectedRevision`) and is refused with 409 `REVISION_CONFLICT` (`metadata.revision` the current one) when someone changed the agent since, and a patch that changes nothing raises nothing. Every change is kept in its history (`agAgentChanges`, `GET /api/agents/:agentId/history`, with `afterRevision` for what came after a revision): who, when, and the fields that changed with their values before and after, except its variables, which are named with whether they were added, changed or removed, never valued. Disabling an agent withdraws its queued runs at once and announces `agent.removed` (`reason` `disabled`); work for an agent that is not enabled is refused (`AGENT_NOT_ENABLED`). Nobody deletes an agent: the agents an earlier version kept were removed by the `202610240020_ag_runner_agents` migration, their rows kept with `deletedAt` for the names their runs, comments and conversations show (`GET /api/agents/agentNames` answers every agent's name, those included), their queued runs cancelled and their pending run requests withdrawn.
 - **Runners** (`agRunners`), shown as runtimes: registered with a one-time token (`POST /api/agents/runners/registrationTokens`, or `pnpm nocobase agents runner-token`). Anyone may add a personal runner (`ownerOnly`: it runs only work its owner started) and later share it with the team; adding a team runner needs `agents.runners` manage. A runner reports its system, its features, its coding tools with versions and whether each is signed in, and what its owner's local policy lets it take (`policy`); it authenticates with its key (`agRunnerCredentials`), sends heartbeats and long-polls for work. Which of its coding tools it is offered work for is chosen on the web (`enabledTools`, null for every tool), carried from "Add runtime" on the registration token (`agRegistrationTokens`). A runner speaking a protocol this application does not serve is kept connected as `upgrade_required`: it gets no work, has what it holds released, and its owner is told once per protocol through the `notice` event (`runner_upgrade_required`; `notice.cleared` once it no longer holds). Only its owner changes a runner (its name, slots, coding tools and trust), because it is their machine with their tools' sign-ins and credentials; a manager of runners changes only a runner whose owner can no longer act (none recorded, or disabled or deleted in the application's directory, `people.provide({ inactive })`). A manager of runners may still revoke anyone's runner in an emergency, and delete it once revoked: its owner is told (`runner_revoked`) and the application's `security` log records who did it. A runner whose owner can no longer act (`people.provide({ inactive })`) is refused with `RUNNER_OWNER_DISABLED`. A runner fits an agent's run only when its owner's local policy lets it take that agent's runs, on that subject, with those repositories; `availability` and the agents list count only such runners. Every heartbeat answer announces workspace reports (`workspaces`): a runner reports the working directories it keeps for this application (`POST /api/agents/runners/workspaces`, each with the last run that worked there and whether it holds unpushed work, with the free space on the disk holding them) and is told which of those runs belong to subjects whose work is over (`remove`) or goes on (`keep`), as each subject kind's `workspaces.settled` says; a kind without it never counts as over, and only the runner's own runs are answered for. The last report is kept on the runner (`agRunners.workspaceUsage`, `Runner.workspaceUsage`) with each directory's subject and what was decided, for the Runtimes page.
 - **The claim**: one long-poll (`POST /api/agents/runners/claim?wait=true`) answers `jobs` and `runs` together, at most `free` items, from the runner's slots, which jobs and runs share (`slots`): jobs first. A heartbeat reconciles both, releasing what the server no longer thinks the runner holds and asking it to stop what was cancelled.
 - **Jobs** (`agJobs`, `agJobEvents`): only for the off-by-default runner build method (such as an application's `acme.builds.method: runner`): a `build` (check out a commit, run an administrator's command, upload its outputs), of kinds the application registers (`jobs.register(kind, { validate, prepare, onEvent, onDone })`, then `jobs.enqueue`, `get` and `watch`). A runner takes a job only when it reports `jobs.build`, someone turned on "Takes build jobs" (`acceptJobs`), it is shared or belongs to who started the job, and its policy lets it check out the job's repository. Jobs retry `runnerOffline`, `leaseExpired`, `startTimeout`, `checkoutFailed` and `policyRefused` while attempts remain, and open the stored variables they name through this plugin's variables at claim, audited as delivered.
 - **Distribution**: the application serves two products as standalone tarballs that bundle Node, one per platform, or as one universal tarball (`cli build --universal`) that runs on the machine's Node.js 24 or newer and is served to every platform without one of its own, answered with `universal: true` (`server/distribution`): its CLI (`agents.cli.name`, such as `acme`) and the runner, `nocobase-runner` (`RUNNER_PRODUCT`). `pnpm nocobase cli build` of `@nocobase/app-cli` packs the CLI the application's `package.json` declares under `nocobase.cli`, and `cli build --runner` the runner, each into a directory of its own, `storage/runners/dist/<channel>/<product>/`, with a `manifest.json` of every file's SHA-256 and size, so CI builds them as separate artifacts mounted into storage, or an application builds them into its own build output and points `agents.dist.dir` there, as NocoBase Studio does. The install script installs the CLI under `~/.local/share/<cli>`: by default the CLI alone, with a download token any signed-in person mints (`POST /api/agents/dist/downloadTokens`, `agDownloadTokens`: the CLI for one platform, three downloads within 30 minutes), as `curl -fsSL <server>/api/agents/dist/installScript | sh -s -- --token <token>`; "Add runtime" shows the same line with `--runner --server <server>` and a registration token, which also installs `nocobase-runner` under `~/.local/share/nocobase-runner`, runs `nocobase-runner register` and `nocobase-runner service install` (an application that serves no CLI still gets its runtime). A token of the other kind fails before anything is installed. A runner reports the product it runs as on registration and every heartbeat (`agRunners.product`), and the heartbeat answer carries an `upgrade` notice when the channel serves a newer version of that product for the runner's platform; a runner that reports none (one from before) is offered no update, and the Runtimes page says to install it again. A product the directory has no current version of may be named on npm instead (`agents.dist.npm`: its package and exact version, which a machine installs with the Node.js 24 or later it already has): the resolve route answers `{ kind: 'npm', product, version, package, channel }` to a caller that sends `accept=npm`, and a heartbeat answer carries `npmUpgrade` to a runner with the `npm` feature when it runs an older version. Everyone else is answered as before (404, no update), and a product the directory has is always served from it. The install script, `<cli> update` and the runner's self-update all ask with `accept=npm` (the runner declares `npm`) and install an npm answer with the machine's npm into the same layout as a tarball: `npm install --prefix <prefix>/versions/<version> --no-save --no-audit --no-fund --omit=optional <package>@<version>`, then a launcher at `versions/<version>/bin/<command>` that starts `node_modules/.bin/<command>` on `<prefix>/node` (`npmLauncherScript` of `@nocobase/app-cli-client/install`).
 
-- **Runs** (`agRuns`): one agent working on one subject, keyed by (agent, subject, thread), with the agent's type kept on the run (`agentType`). A subject kind takes the agent types its binding names (`agentTypes`, runner only by default); a run of another type is refused (`AGENT_TYPE_NOT_ALLOWED`). New work joins the run already on it as the same person (`actorUserId`) while that run can still be told, else that person's queued one, else starts a new run: work woken by different people never shares a run, so it neither borrows another's identity nor waits for a runner that will not take it. Runs of one key are still claimed one at a time, whoever they work as. Queued runs are claimed by `priority` (lower first; 0 by default), then oldest first; a run given a `fireAt` is not claimed before that moment. Work merged into a queued run raises it to the more urgent priority and the earlier moment of the two. Runners take only runner agents' runs. A claim hands a run to a runner that fits in one transaction: one of the agent's tools enabled, installed and signed in there (the run takes the first entry of the agent's list whose tool is, recorded on the run as `tool` and `model` and passed to the tool; a model the tool's account cannot use fails the run `modelUnavailable`), the agent naming no runner or naming this one, the runner shared with the team or owned by the person who woke the agent, its features covering what the run needs (worked out from the payload: checkouts, directories, skills, secrets), a team runner when one of the variables the run gets is for team runners only (`teamRunnersOnly`), and a free slot within the agent's concurrency. The variables are checked and opened in the claim's transaction, so the runner receives what was checked; a personal runner left out for them notes on the run which variables asked for a team runner (`teamOnlyVariables`, cleared when the run is taken, requeued or given new input), and its wait is `secretsNotAllowed` with those variables. Before a run exists, `eligibility` (`runnersFor`, `canClaim`, `mayQueue`, `teamOnly`) answers by the same rules whether a runner would take an agent's work done as a person, with the scopes and features the caller names; `availability` and `GET /api/agents/available` use it for the caller. A working directory that is a directory on one runner pins the run to that runner, one run at a time per directory. The claim renders the brief (kept per run, `agRunBriefs`), mints a run token, and hands over the working directories, the merged variables, the skills and the CLI to install. Events, usage and branches are recorded as the runner reports them; completing requires every input to be handled. A runner that finds the subject's working directory held by another live run reports `workspaceBusy`: the run goes back to the queue, freeing its slot, and is tried again after 30 seconds, doubling up to two minutes; these waits do not count against the agent's attempts, and the run fails `workspaceBusy` only once it has waited six hours (`WORKSPACE_WAIT_LIMIT_MS`).
+- **Runs** (`agRuns`): one agent working on one subject, keyed by (agent, subject, thread) (`agentType` is `runner`; `online` only on runs earlier versions kept). New work joins the run already on it as the same person (`actorUserId`) while that run can still be told, else that person's queued one, else starts a new run: work woken by different people never shares a run, so it neither borrows another's identity nor waits for a runner that will not take it. Runs of one key are still claimed one at a time, whoever they work as. Queued runs are claimed by `priority` (lower first; 0 by default), then oldest first; a run given a `fireAt` is not claimed before that moment. Work merged into a queued run raises it to the more urgent priority and the earlier moment of the two. A claim hands a run to a runner that fits in one transaction: the agent's tool enabled, installed and signed in there with its model among those the runner reports for the tool and not marked unavailable there (`runsEntry` in `shared/runners.ts`; recorded on the run as `tool` and `model` and passed to the tool; a model the tool's account cannot use fails the run `modelUnavailable` and marks that tool and model unavailable on the runner, `Runner.unavailableModels`, until it reports the tool's models differently), the runner shared with the team or owned by the person who woke the agent, its features covering what the run needs (worked out from the payload: checkouts, directories, skills, secrets), a team runner when one of the variables the run gets is for team runners only (`teamRunnersOnly`), and a free slot within the agent's concurrency. The variables are checked and opened in the claim's transaction, so the runner receives what was checked; a personal runner left out for them notes on the run which variables asked for a team runner (`teamOnlyVariables`, cleared when the run is taken, requeued or given new input), and its wait is `secretsNotAllowed` with those variables. Before a run exists, `eligibility` (`runnersFor`, `canClaim`, `mayQueue`, `teamOnly`) answers by the same rules whether a runner would take an agent's work done as a person, with the scopes and features the caller names; `availability` and `GET /api/agents/available` use it for the caller. A working directory that is a directory on one runner pins the run to that runner, one run at a time per directory. The claim renders the brief (kept per run, `agRunBriefs`), mints a run token, and hands over the working directories, the merged variables, the skills and the CLI to install. Events, usage and branches are recorded as the runner reports them; completing requires every input to be handled. A failed attempt is tried again after 30 seconds (`agents.runs.retryBaseDelayMs`), doubling up to ten minutes, except when the runner went away or lost its lease, which retries at once. A runner that finds the subject's working directory held by another live run reports `workspaceBusy`: the run goes back to the queue, freeing its slot, and is tried again after 30 seconds, doubling up to two minutes; these waits do not count against the agent's attempts, and the run fails `workspaceBusy` only once it has waited six hours (`WORKSPACE_WAIT_LIMIT_MS`).
 - **Run requests** (`agRunRequests`): work someone asked of an agent on a subject another person answers for, waiting for that person to confirm it (see "Work someone else causes" below).
-- **Workload** (`runs.workload({ subjectKind, limit? })`, `shared/runs.ts`): the open runs on one kind of subject for a board of work, without claiming anything. Held runs come with their runner, the newest input's trigger and their newest text, tool call, status or error (`lastActivity`); queued runs with their place in the claim order (among the runs claimable now, and among the agent's) and why they wait, by the claim's own rules in its order (`RUN_WAIT_REASONS`: the agent archived, delayed until a moment, no runner online, the agent's named runners offline, its tool not signed in anywhere, only other people's personal runners, missing features, only personal runners whose owner may not receive the run's variables, the same work already held, the agent's concurrency full, every fitting runner busy, preparation retrying, or next). A wait is a code and the values its words need (`params`), never text: the client words it with `formatRunWait(t, wait)` from `client/runs.ts`, in this plugin's namespace (`runWait.reasons.<reason>`), which an application may override in its locale file or replace with its own formatter. It also answers each agent's load (held, queued, its limit, whether a runner could take its work) and the runners' (online, holding work, slots and slots used). It reads a bounded number of tables, never one query per subject; the caller decides what of it a person may see.
-- **Online runs** (`server/online`): every application instance runs an executor that takes online agents' runs through the same claim transaction (`claims.claimServer`, the run held by `server:<instance>`, so two instances never take one run), with the entry of the agent's list the subject asks for (a conversation's choice, `ConversationPatch.model`, while the agent still lists it) or else its first, recorded on the run as `modelService` and `model`; a failing model fails the run, nothing falls back to another entry and reports through the same lifecycle a runner's requests reach (start, events, lease, complete, fail, cancel-ack), so conversations, transcripts, retries, failed-run handling and the sweeper are unchanged. No slots and no per-agent concurrency limit apply. A run is a loop of model calls through the plugin's model gateway (`online.gateway`, below): each streams its text, which a conversation shows as a draft message growing in place, and ends with the tool calls to make and what the call used, recorded at once as the run's usage (tool `chat`, the model the provider named). It has two tools (`online/sandbox.ts`): `bash`, a sandboxed shell (`just-bash`, in process: no real processes, no network, a 10-second deadline per command, its output cut to what the model reads; the build bundles the part of `just-bash` it uses into `dist/server/vendor/just-bash.js` with `THIRD_PARTY_LICENSES.txt` beside it, so the plugin does not depend on `just-bash`, and leaves out Python, JavaScript, SQLite, curl, html-to-markdown and xz/zstd archives, which answer that they are not available), and `skill`, which reads one of the run's skills (its SKILL.md and its file tree). The shell mounts the run's skills read-only at `/skills/<slug>/` (text only, at most 5 MB per run; binary files are listed but not readable, and scripts are never run) with `/tmp` as scratch, and carries the application's CLI (`online/cli-command.ts`): `acme`, built from the run's command manifest (the application's `GET /api/cli/manifest`, the actions of the person who woke the agent that the agent is configured with), each command one request sent through the application itself with the run's token, so the route checks the permission again; the line is read by the CLI's own parser (`@nocobase/app-cli-client/parse`), so flags, `--<flag>-file` and the body's `--file` (read from the shell's files), `--from-env` (the shell's exported variables), usage errors and exit codes are the CLI's; help and `acme docs` work from the manifest, `--json` prints the cli-envelope, and commands that send or save files are refused. Skills every online run gets besides its own (the CLI's) are registered with `online.skills`. A refused or failed call is a result the model reads. Input that arrives meanwhile is answered in the same run; a run that calls tools for more than `maxSteps` model calls fails `stepLimit`. The gateway's errors become failure reasons: `config` → `modelUnavailable`, `auth` → `toolAuth`, `quota` → `toolQuota`, `rateLimit` → `toolRateLimit` and `network` → `toolNetwork` (both retried while attempts remain), `contextOverflow` → `contextOverflow`, anything else `unknown`. A cancel request aborts the model call within a second; at shutdown an instance hands its runs back (`runnerOffline`), and one that stops renewing its leases loses them to the sweeper (`leaseExpired`). The brief of an online run has a system layer of its own (`onlineSystemLayer`): the CLI in its shell instead of a terminal, no workspace, its skills by name and description (`onlineSkillsSection`), and links to the pages of what it relied on.
+- **Workload** (`runs.workload({ subjectKind, limit? })`, `shared/runs.ts`): the open runs on one kind of subject for a board of work, without claiming anything. Held runs come with their runner, the newest input's trigger and their newest text, tool call, status or error (`lastActivity`); queued runs with their place in the claim order (among the runs claimable now, and among the agent's) and why they wait, by the claim's own rules in its order (`RUN_WAIT_REASONS`: the agent not enabled, `agentArchived`, delayed until a moment, no runner online, the agent's named runners offline, its tool not signed in anywhere, only other people's personal runners, missing features, only personal runners whose owner may not receive the run's variables, the same work already held, the agent's concurrency full, every fitting runner busy, preparation retrying, or next). A wait is a code and the values its words need (`params`), never text: the client words it with `formatRunWait(t, wait)` from `client/runs.ts`, in this plugin's namespace (`runWait.reasons.<reason>`), which an application may override in its locale file or replace with its own formatter. It also answers each agent's load (held, queued, its limit, whether a runner could take its work) and the runners' (online, holding work, slots and slots used). It reads a bounded number of tables, never one query per subject; the caller decides what of it a person may see.
 - **Redaction**: what runners report is stored redacted. The runner redacts first; the server redacts every run event (content, output, input and meta), summary and failure detail, and every job event and failure detail again before storing them, with the protocol's redactor (`createRedactor` of `@nocobase/agent-protocol`): the secrets the claim handed out (a run's variables and token, a job's opened variables, repository token and upload headers, remembered in memory for recent claims) and the common secret patterns, each replaced with `[REDACTED]` (`server/kernel/redaction.ts`). After a restart, or on another instance, the patterns and the runner's own redaction still apply.
-- **The sweep** (`server/runners/sweeper.ts`, the `RunnersSweep` schedule every 30 seconds on the application's jobs service, or an in-process timer without one) marks runners not heard from for 150 s offline, takes jobs back from silent runners and fails jobs far past their timeout, and takes runs back from runners that went away, lost their lease or never started, fails runs idle for twice their idle timeout, records unacknowledged cancellations, cancels queued runs of archived agents, and fails a queued run that waited longer than its subject allows (`queuedExpiryMs` on the subject's binding, counted from the run's last change or from its `fireAt`) as `queuedExpired`.
+- **The sweep** (`server/runners/sweeper.ts`, the `RunnersSweep` schedule every 30 seconds, or `agents.runners.sweepIntervalMs`, on the application's jobs service, or an in-process timer without one) marks runners not heard from for 150 s offline, takes jobs back from silent runners and fails jobs far past their timeout, and takes runs back from runners that went away, lost their lease or never started, fails runs idle for twice their idle timeout, records unacknowledged cancellations, cancels queued runs of archived agents, and fails a queued run that waited longer than its subject allows (`queuedExpiryMs` on the subject's binding, counted from the run's last change or from its `fireAt`) as `queuedExpired`.
 - **Variables** (`agSecrets`): environment variables for the agent's process, every one a secret sealed with the application's secrets service (`secrets.keys`) and bound to its scope and name, set on an agent, a working directory (`workdir`) or a scope the application registers, merged for a run in the order the subject names its scopes < its working directories < the agent, delivered only to runners with the `secrets` feature: to whichever runner takes the run, a personal runner of anyone who may use the agent included, since sharing an agent shares the tokens it works with. A variable marked `teamRunnersOnly` (off by default; `PUT /api/agents/variables/...` with `teamRunnersOnly`, and without `value` to change only that) keeps runs and jobs that get it on team runners. Jobs check the exact variables referenced by their prepared spec, including repository credentials, before opening any value in the claim transaction; a personal runner skips such a job without counting a preparation failure, leaving it queued for a team runner and continuing to other jobs. Values are write-only; reading them back and every delivery are audited (`agSecretAudits`).
-- **Skills** (`agSkills`, `agSkillVersions`, `agSkillAttachments`): a library of skills in the open Agent Skills format (https://agentskills.io/specification): a directory of `SKILL.md` and supporting files, conventionally under `scripts/`, `references/` and `assets/`. Only the front matter of `SKILL.md` names and describes a skill: `name` (1–64 lower-case letters, digits and single hyphens) is its slug and directory, so a save that changes it renames the skill, and `description` (1–1024 characters) is required; `license`, `compatibility` (at most 500 characters), `metadata` (string values) and `allowed-tools` are checked when present, and other keys are kept. Every create, save, restore and import is checked against these rules in the browser as it is typed and on the server (`shared/skill-markdown.ts`), which answers 400 with each problem's `field` and `reason` in `metadata.problems` (`taken` for a name another skill has; `mismatch` for an archive whose folder is named otherwise). Files under `scripts/` or marked executable are scripts (`Skill.scripts`): runners may run them, online agents only read them. Every save is a new version that runs get at once, with older versions to compare and restore. Skills are attached to agents, and as defaults to a working directory or a registered scope. A skill's revision is its current version: a save or a restore names the version it was made against (`expectedRevision`) and is refused with 409 `REVISION_CONFLICT` when another save came first. A runner fetches a run's skills from `GET /api/agents/runners/runs/:runId/skills/:slug` and places them where the run's coding tool finds them.
-- **Conversations** (`agConversations`, `agConversationMessages`): a person chatting with an agent they may wake, from the chat panel. A conversation's mode is the type of the agent it answers with (`mode`): it moves to an agent of the same type, except that a runner conversation may move to the online fallback agent and back. Only the owner reads a conversation, administrators included; its runs are hidden from everyone they do not involve. Each message the owner sends wakes the agent on the `conversation` subject as the owner, or joins the run already working on it; every text the agent writes becomes a message. A run resumes the session its runner kept; on another runner, or after the conversation switched agents, it starts fresh with the last 20 messages and the previous run's summary. When the agent is archived, no longer allowed, has no online signed-in runner, or (an online agent) its model is no longer offered (`modelUnavailable`), messages are still saved and the conversation reports why; the owner may switch it to the system default chat agent and back when that agent is of the same type, or else a runner conversation to the online fallback agent (`ChatSettings.onlineFallbackAgentId`). A conversation started with a runner agent that no runner may run for its owner now, such as one whose only online runner is someone else's personal one, starts on the online fallback agent when one is set, as if switched (`fallbackFrom` names the runner agent, notice `switchedToOnline`), and the owner may switch it back once the original agent can answer again; `chatAgents` says so per agent (`fallbackAgentId`). Runner availability uses claim eligibility, including required features and variables restricted to team runners. Existing runner conversations check again on the next message; if no eligible runner remains, they switch to the usable online fallback and transfer unanswered queued messages. Manual fallback skips an unavailable system default. If the configured online fallback has no offered answering model, the conversation stays on the runner and records an `onlineFallbackUnavailable` notice explaining why. The owner answers for their own conversation, so none of this asks anyone to confirm. Without an online fallback agent set, runner conversations do not switch automatically. An online conversation answers with the entry of its agent's list its owner chose in the composer (`model`, `PATCH` with `model`; null for the agent's default), from the next run on; the composer offers the agent's entries (`models`) and hides the choice when there is only one. An online agent's reply is a draft (`metadata.streaming`) rewritten in place as it streams, at the same `seq`, and made final by the run's text event; a draft whose run ended first keeps what it had written (`metadata.interrupted`). `shared/conversations` is the contract (HTTP API under `/api/agents/conversations` and `/api/agents/chat*`, page context and its limits, the per-user realtime topic `agents:conversations`); `ConversationService` is the interface other code uses, so the storage can move to a shared platform layer later.
-- **Chat defaults and presets**: the system default chat agent and the online fallback agent (`agSettings`), each person's default chat agent (`agChatPreferences`), "Copy as my agent" on an agent's page (a private copy of it), each agent's "confirm before changing data" (`confirmChanges`: `always` or only `larger` changes), and the agent presets the application registers to start a new agent from (`GET /api/agents/presets`).
+- **Skills** (`agSkills`, `agSkillVersions`, `agSkillAttachments`): a library of skills in the open Agent Skills format (https://agentskills.io/specification): a directory of `SKILL.md` and supporting files, conventionally under `scripts/`, `references/` and `assets/`. Only the front matter of `SKILL.md` names and describes a skill: `name` (1–64 lower-case letters, digits and single hyphens) is its slug and directory, so a save that changes it renames the skill, and `description` (1–1024 characters) is required; `license`, `compatibility` (at most 500 characters), `metadata` (string values) and `allowed-tools` are checked when present, and other keys are kept. Every create, save, restore and import is checked against these rules in the browser as it is typed and on the server (`shared/skill-markdown.ts`), which answers 400 with each problem's `field` and `reason` in `metadata.problems` (`taken` for a name another skill has; `mismatch` for an archive whose folder is named otherwise). Files under `scripts/` or marked executable are scripts (`Skill.scripts`): runners may run them. Every save is a new version that runs get at once, with older versions to compare and restore. Skills are attached globally, or as defaults to a working directory or a registered scope. A skill's revision is its current version: a save or a restore names the version it was made against (`expectedRevision`) and is refused with 409 `REVISION_CONFLICT` when another save came first. A runner fetches a run's skills from `GET /api/agents/runners/runs/:runId/skills/:slug` and places them where the run's coding tool finds them.
+- **Conversations** (`agConversations`, `agConversationMessages`): owner-only chats through the OnlineAgent service, with native model execution or a callable Runner binding. Existing bindings are immutable. Historical unbound conversations retain readable history and owner-authorized Stop for unfinished runs, but cannot continue chatting through HTTP. Ordinary conversations default to visible; new background sessions are hidden from lists before pagination. The [OnlineAgent reference](skills/nocobase-app-plugin-agents/references/online-agent.md) documents execution, result observation, browser configuration, notification transactions and migration from removed start/fallback/restore endpoints and CLI commands.
+- **Chat defaults**: the system default chat agent (`agSettings`, `PATCH /api/agents/chatSettings` by who manages `agents.agents`, or the application), each person's default chat agent (`agChatPreferences`), and each agent's "confirm before changing data" (`confirmChanges`: `always` or only `larger` changes).
 - **No setup scripts.** Preparing a working directory is the agent's job: its brief tells it to follow each directory's own instructions (AGENTS.md, CLAUDE.md, README), to install what is missing inside the directory, and to say so (the way the subject's guidance tells it) when it cannot. A working directory's optional initialization prompt reaches the agent only when the runner prepared that directory fresh. "Clean working directory" (`POST /api/agents/workspaces/:subjectKind/:subjectId/reset`) makes the next run start from a fresh checkout.
 
-The configured online fallback must have an available default answering model, either its own first model entry or the system default when it has no entries. Disabled or removed model services and removed models make it unavailable. If automatic fallback cannot answer, the conversation retains its original runner agent and writes an `onlineFallbackUnavailable` system notice explaining the reason; its runner availability remains `noRunner`. `chatAgents` and the manual fallback action apply the same model check.
+## Chat integration documentation
 
-## Online agents
+- [OnlineAgent service and business tools](skills/nocobase-app-plugin-agents/references/online-agent.md): trusted server configuration, Native/Runner sessions, public browser transport and lifecycle boundaries.
+- [UI messages](docs/ui-messages.md) and [client coordination](docs/ui-message-clients.md): SDK message ownership, safe projections, streaming, persistence and recovery.
+- [UI context, tool cards and AI form adapters](docs/ai-forms.md): open `context.ui.items`, exact-name `AIToolRendererProvider` registration, `useAIForm` ref callbacks, explicit async context selection and guarded browser-draft application, with integrated Examples wiring. The plugin provides no built-in form-filling business tool/card and never submits or saves a form or continues a server tool when a user applies a local proposal.
 
-The plugin keeps the model services online agents call (`agModelServices`, `server/online/services.ts`): a provider type, a name agents and model prices store (made from the title, never changed), a title, a base URL (the provider's default when empty), an API key sealed with the secrets service as variables are, bound to the service's name, an on/off switch, and the models it offers. A provider may have any number of services. The key is write-only: the API answers `apiKeySet`, never the key. Every request to a provider names the plugin first in its user agent (`nocobase-agents/<version>`); a call to an OpenCode base URL (Zen or Go) additionally carries `x-opencode-session`, the same session id for every model call of a conversation (a hash of its subject and thread, `sessionOf` in `server/online/executor.ts`) and a new one for each call outside any, such as a connection test, an embedding or a rerank. Deleting a service deletes its model prices. A model's kind (chat, embedding or rerank) is guessed from its id only as a default and can always be changed; checking a model checks it as its kind, and when it fails that way but answers as another kind its provider serves, the check says so (`ModelCheck.looksLike`). The system default chat model (`agSettings` key `models`) is what an online agent that lists no model answers with: availability, the run (which records the model it used) and the conversation's model all fall back to it. It is set on the Models page; with none set, the first chat model an enabled service offers is used, and the first chat model turned on becomes it.
+## Model services
 
-The providers (`MODEL_PROVIDERS` in `shared/models.ts`, `server/online/providers.ts`) are Vercel AI SDK provider packages: `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, `@ai-sdk/deepseek`, `@ai-sdk/alibaba` (Qwen), `@ai-sdk/moonshotai` (Kimi), `@ai-sdk/cohere`, `ollama-ai-provider-v2`, and `@ai-sdk/openai-compatible` for every other endpoint that speaks OpenAI's chat completions. A provider's models are read from its own list-models endpoint (`GET /models`; Anthropic's with its version header, Google's `models` that generate content, Cohere's v1 `models`, Ollama's `/tags`); a model can also be added by id.
+The plugin keeps model services (`agModelServices`, `server/online/services.ts`) for the application's own model calls, such as a knowledge base's embeddings; agents do not use them. A service has a provider type, a name model prices store (made from the title, never changed), a title, a base URL (the provider's default when empty), an API key sealed with the secrets service as variables are, bound to the service's name, an on/off switch, and the models it offers. A provider may have any number of services. The key is write-only: the API answers `apiKeySet`, never the key. Every request to a provider names the plugin first in its user agent (`nocobase-agents/<version>`); a call to an OpenCode base URL (Zen or Go) additionally carries `x-opencode-session`, a new session id for each call. Deleting a service deletes its model prices. A model's kind (chat, embedding or rerank) is guessed from its id only as a default and can always be changed; checking a model checks it as its kind, and when it fails that way but answers as another kind its provider serves, the check says so (`ModelCheck.looksLike`).
 
-Each model of a service is of one kind (`ModelKind`), chosen in its row of the service's dialog among the kinds its provider serves (`kinds`): `chat` (what online agents talk to; the only kind agents, their pickers and the catalog's default ever see), `embedding` (texts to vectors, with an optional vector size, `dimensions`, asked through each provider's own option) or `rerank` (documents ordered by a query). OpenAI, Google, Alibaba and Ollama serve chat and embedding models; Cohere and OpenAI-compatible endpoints serve all three, an OpenAI-compatible endpoint's reranking being `POST <base>/rerank` in the shape Cohere, Jina, vLLM and SiliconFlow share (`compatibleReranking`); Anthropic, DeepSeek and Moonshot serve chat models only. A model without a kind is a chat model. Testing a model tries it as its kind says.
-
-The model gateway (`online.gateway`, `server/online/gateway.ts`) is what the executor and the admin API call: `catalog()` (the enabled services that offer a model, names only), `check(ref)` (a short `generateText`, 20 seconds, never throws), `languageModel(ref)`, the chat model an online run's loop runs over, and `stream(request)`, one `streamText` call with tools declared without an implementation, which ends at the tool calls the model made. An online run is the SDK's `ToolLoopAgent` over that model: the run's brief is its instructions, its tools are executed by the SDK step by step (a tool answers `{ ok, output }`, and the model reads `output` through `toModelOutput`), each step's usage is recorded as it finishes, and the loop stops when the model answers without a tool call or after `agents.server.maxSteps` steps (`stepLimit`); an entry's reasoning effort is the SDK's `reasoning` option. Usage is mapped to the protocol's non-overlapping counts (input without cached reads and cache writes; output with reasoning). The SDK retries a failed request twice; a failure throws `ModelError` with a code from the provider's status and error body (`config`, `auth`, `quota`, `rateLimit`, `network`, `contextOverflow`, `filtered`, `badResponse`, `aborted`, `unknown`), which become the run's failure reasons as above. A service without a key whose provider needs one fails `auth` before any request. A run's brief, and a system message marked `cache`, carry Anthropic's `cacheControl` (`ephemeral`), so the brief is read from the cache on every model call of a run after the first; OpenAI caches a long prefix by itself.
+The providers (`MODEL_PROVIDERS` in `shared/models.ts`, `server/online/providers.ts`) are Vercel AI SDK provider packages: `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, `@ai-sdk/deepseek`, `@ai-sdk/alibaba` (Qwen), `@ai-sdk/moonshotai` (Kimi), `@ai-sdk/cohere`, `ollama-ai-provider-v2`, and `@ai-sdk/openai-compatible` for every other endpoint that speaks OpenAI's chat completions. A provider's models are read from its own list-models endpoint (`GET /models`; Anthropic's with its version header, Google's `models` that generate content, Cohere's v1 `models`, Ollama's `/tags`); a model can also be added by id.
 
-The gateway also serves the application's own model calls outside runs, each naming who asks (`source`, such as `knowledge`): `embed({ model, values, source })` (`embedMany`, two requests at a time, answering the vectors, their size and the tokens read), `rerank({ model, query, documents, topN?, source })` (the SDK's `rerank`, answering each document's index and score, best first) and `generate({ model, system?, prompt, maxOutputTokens?, source })` (one short text from a chat model, `generateText`). Each names a model of the matching kind (`catalog(kind)` lists them) and throws `ModelError` as a run's calls do. What each used is recorded at once in `agModelUsage` (purpose `embedding`, `rerank` or `text`, the source, the model, its tokens and how many texts or documents), priced like online runs' calls from the service's model prices, and reported by `reporting.modelUsage(caller, { from, to })` (`GET /api/agents/usage/models`, behind the usage page's grant, rows only for a reader of every run): the usage page shows it below the runs as "Other model use".
+Each model of a service is of one kind (`ModelKind`), chosen in its row of the service's dialog among the kinds its provider serves (`kinds`): `chat` (short texts, `generate`), `embedding` (texts to vectors, with an optional vector size, `dimensions`, asked through each provider's own option) or `rerank` (documents ordered by a query). OpenAI, Google, Alibaba and Ollama serve chat and embedding models; Cohere and OpenAI-compatible endpoints serve all three, an OpenAI-compatible endpoint's reranking being `POST <base>/rerank` in the shape Cohere, Jina, vLLM and SiliconFlow share (`compatibleReranking`); Anthropic, DeepSeek and Moonshot serve chat models only. A model without a kind is a chat model. Testing a model tries it as its kind says.
 
-### Consultations
+The model gateway (`models.gateway` of `agentsToken`, `server/online/gateway.ts`) is what the application and the admin API call: `catalog(kind?)` (the enabled services that offer a model of the kind, names only), `check(ref)` (a short `generateText`, 20 seconds, never throws), and the calls below. Usage is mapped to non-overlapping counts (input without cached reads and cache writes; output with reasoning). The SDK retries a failed request twice; a failure throws `ModelError` with a code from the provider's status and error body (`config`, `auth`, `quota`, `rateLimit`, `network`, `contextOverflow`, `filtered`, `badResponse`, `aborted`, `unknown`). A service without a key whose provider needs one fails `auth` before any request.
 
-An online run may consult another online agent synchronously, as the AI SDK's subagent pattern does: the tool `ask_agent` (`{ agent, question, context? }`, `server/online/consult-tool.ts`) is given to a run whose system prompt lists agents it may consult (`Agents you may consult`, name and the first line of the description), and only then. Those are online agents with a model that the person the run acts for may use (their "who may use it"), not already in the run's chain. The answer comes from a run of its own (`server/core/consultations`): a child of the asking run (`parentRunId`), on the subject `{ kind: 'consultation', id: <asking run> }`, one thread per tool call, one attempt, acting for the same person with its own run token. It is never claimed from the queue: the instance holding the asking run takes it at once (`claims.claimChild`) and runs it within the tool call, aborted with the asking run, within `agents.server.consult.timeoutMs` and `tokenBudget`. It only reads: the gate keeps a consultation's run to reading actions (`…/view`, `…/read`) and those the application marks `consultable` (for example, proposing an operation plan, which reaches as far as the agent and person do and is confirmed by the person in the conversation that asked, `conversations.homeOf`). Consultations go `CONSULT_MAX_DEPTH` (2) deep and never back to an agent already asked; a runner agent is refused with "use a task to delegate to a runner agent". The tool streams preliminary results, which the asking conversation shows as a card (a `consultation` notice, rewritten in place); the asking model reads only the final answer and a note of the plans proposed (`toModelOutput`). The child's transcript and usage are its own, and `RunDetail.children` lists a run's consultations.
+The gateway serves the application's own model calls, each naming who asks (`source`, such as `knowledge`): `embed({ model, values, source })` (`embedMany`, two requests at a time, answering the vectors, their size and the tokens read), `rerank({ model, query, documents, topN?, source })` (the SDK's `rerank`, answering each document's index and score, best first) and `generate({ model, system?, prompt, maxOutputTokens?, source })` (one short text from a chat model, `generateText`). Each names a model of the matching kind (`catalog(kind)` lists them) and throws `ModelError` as a run's calls do. What each used is recorded at once in `agModelUsage` (purpose `embedding`, `rerank` or `text`, the source, the model, its tokens and how many texts or documents), priced from the service's model prices, and reported by `reporting.modelUsage(caller, { from, to })` (`GET /api/agents/usage/models`, behind the usage page's grant, rows only for a reader of every run): the usage page shows it below the runs as "Other model use".
 
 ## Vectors
 
@@ -65,18 +70,18 @@ An online run may consult another online agent synchronously, as the AI SDK's su
 
 ## Layout
 
-| Folder                                                 | What is there                                                                                                                                                                                   |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `server/kernel`                                        | Clock, ids, transactions, events, credentials and secret sealing, scopes, redaction, HTTP helpers                                                                                               |
-| `server/core`                                          | What both agent types share: agents, runs and the queue (claims, lifecycle, sweeper), briefs, conversations, the custom command registry, usage, prices and reports, skills, variables, presets |
-| `server/online`                                        | Online agents: the model services, the providers, the model gateway, the executor and its command tools, and the model endpoints of the admin API                                               |
-| `server/vectors`                                       | Vector collections, their embedding queue, the vector store registry, and the `sqlite-vec` and `pgvector` stores                                                                                |
-| `server/runners`, `server/jobs`, `server/distribution` | The runners (registration, keys, heartbeats, slots, the sweeper), the build jobs, and the runner and CLI tarballs                                                                               |
-| `server/routes/runners`                                | The runner protocol (with a run's `runs/:runId/*` endpoints), the tarballs, the install script and the runners' admin API                                                                       |
-| `server/routes`                                        | The admin, chat and CLI endpoints, and where every endpoint is mounted (`index.ts`)                                                                                                             |
-| `server/providers`                                     | The service providers that assemble and boot the plugin                                                                                                                                         |
-| `shared`                                               | The view models the browser and the API exchange (`models.ts` for online agents' services and catalog)                                                                                          |
-| `client`                                               | The pages and components; `client/online` the model services UI of the Models page; `client/pages/usage/prices` the prices sheet of the Usage page                                              |
+| Folder                                                 | What is there                                                                                                                                                     |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server/kernel`                                        | Clock, ids, transactions, events, credentials and secret sealing, scopes, redaction, HTTP helpers                                                                 |
+| `server/core`                                          | Agents, runs and the queue (claims, lifecycle, sweeper), briefs, conversations, the custom command registry, usage, prices and reports, skills, variables         |
+| `server/online`                                        | The model services, the providers, the model gateway, and the model endpoints of the admin API                                                                    |
+| `server/vectors`                                       | Vector collections, their embedding queue, the vector store registry, and the `sqlite-vec` and `pgvector` stores                                                  |
+| `server/runners`, `server/jobs`, `server/distribution` | The runners (registration, keys, heartbeats, slots, the sweeper), the build jobs, and the runner and CLI tarballs                                                 |
+| `server/routes/runners`                                | The runner protocol (with a run's `runs/:runId/*` endpoints), the tarballs, the install script and the runners' admin API                                         |
+| `server/routes`                                        | The admin, chat and CLI endpoints, and where every endpoint is mounted (`index.ts`)                                                                               |
+| `server/providers`                                     | The service providers that assemble and boot the plugin                                                                                                           |
+| `shared`                                               | The view models the browser and the API exchange (`models.ts` for the model services and their catalog; `model-catalog.ts` for the models agents are named after) |
+| `client`                                               | The pages and components; `client/online` the model services UI of the Models page; `client/pages/usage/prices` the prices sheet of the Usage page                |
 
 ## HTTP API
 
@@ -92,7 +97,7 @@ Every route lives under the plugin's namespace, `/api/agents`, and names its own
 | `/api/agents/cli/*`                                                                                             | Run token header, or the application's authentication             | The CLI's custom commands (`CLI_ROUTES.command`); the manifest is the application's `GET /api/cli/manifest`                                     |
 | everything else under `/api/agents`                                                                             | Session and authorization context                                 | Agents and brief previews, variables, skills, runs, the vocabulary, usage, prices, conversations, the model services and their models           |
 
-Scoped API keys reach only the routes whose every operation is a settings check (agents, skills, model services, prices and usage); elsewhere they are refused with `SCOPED_KEY_FORBIDDEN`. The API checks four settings items, which the plugin lists under an Agent team subsection of the permission workspace: `agents.agents` (read or manage agents, their variables, skills, and every run; reading also sees every runner), `agents.runners` (read every runner; manage revokes and deletes any runner, changes a runner whose owner can no longer act and adds team runners; anyone signed in adds personal runners and changes, revokes and deletes their own, and only the owner changes a runner), `agents.prices` (the model prices) and `agents.services` (the model services: read lists them, manage adds, edits, tests and deletes them and sets their keys; a scoped key may only read them). It also declares one business action with three levels (`BUSINESS_ACTIONS` and `RELATIONS` in `shared/access.ts`), registered as the `agents` resource type under an Agent team subsection of business, one action per level (`edit.related`, `edit.all`), whose level the application tells it through `agentsAccessToken` (`scopeOf(identity, key)`; unbound, every level is `none`): `agents.agents/edit` changes agents (their settings, skills and variables; archiving, restoring and deleting them) and edits skills (saving, restoring a version), every one at `all` and at `related` the agents the caller owns and the skills they created. Managing agents reaches every one whatever the level; creating agents and skills and deleting skills still need it. Someone editing at a level, without managing agents, does not hand an agent to another owner and adds to it only business actions they hold themselves (the command gate's `allowed`). An agent and a skill answer `canEdit` for the caller. Anyone signed in reads which model services and models online agents may use (`GET /api/agents/models`, names only, chat models unless `?kind=embedding` or `rerank` asks for another kind; `shared/models.ts`), and anyone who reads agents may test one (`POST /api/agents/checkModel`). Anyone signed in reads the system default chat model (`GET /api/agents/defaultModels`), and who manages `agents.services` sets it (`PUT /api/agents/defaultModels/chat`). Anyone signed in sees, cancels and retries the runs they started or own, and reads the vocabulary (labels only). A working directory's or a registered scope's variables and default skills follow the scope's kind: it decides who reads and who changes them.
+Scoped API keys reach only the routes whose every operation is a settings check (skills, model services, prices and usage); elsewhere they are refused with `SCOPED_KEY_FORBIDDEN`. The API checks four settings items, which the plugin lists under an Agent team subsection of the permission workspace: `agents.agents` (manage changes agents and their variables; read sees agents' variables, skills and every run, and every runner; anyone signed in reads the agents themselves, `GET /api/agents`, with `canEdit` for a manager), `agents.runners` (read every runner; manage revokes and deletes any runner, changes a runner whose owner can no longer act and adds team runners; anyone signed in adds personal runners and changes, revokes and deletes their own, and only the owner changes a runner), `agents.prices` (the model prices) and `agents.services` (the model services the application calls: read lists them, manage adds, edits, tests and deletes them and sets their keys; a scoped key may only read them). It also declares one business action with three levels (`BUSINESS_ACTIONS` and `RELATIONS` in `shared/access.ts`), registered as the `agents` resource type under an Agent team subsection of business, one action per level (`edit.related`, `edit.all`), whose level the application tells it through `agentsAccessToken` (`scopeOf(identity, key)`; unbound, every level is `none`): `agents.agents/edit` edits skills (saving, restoring a version), every one at `all` and at `related` the skills the caller created; agents are changed only by who manages them. Managing agents reaches every skill whatever the level; creating and deleting skills still need it. A skill answers `canEdit` for the caller. Anyone signed in reads which model services and models are offered (`GET /api/agents/models`, names only, chat models unless `?kind=embedding` or `rerank` asks for another kind; `shared/models.ts`), and anyone who reads agents may test one (`POST /api/agents/checkModel`). Anyone signed in sees, cancels and retries the runs they started or own, and reads the vocabulary (labels only). A working directory's or a registered scope's variables and default skills follow the scope's kind: it decides who reads and who changes them.
 
 Realtime announcements carry no content: `agents:runs:<runId>` when a run's status, transcript or input changes and `agents:runners` when a runner changes. A page that hears one fetches through the API.
 
@@ -102,17 +107,18 @@ Everything the application contributes goes through `agentsToken` (`server/token
 
 | Extension point                                                       | What the application gives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subjects.register(binding)`                                          | A kind of subject runs work on: `kind`, `title`, `triggers` (what `input.payload.trigger` values mean, for the run panel), `preview` (a `SubjectSample`: the assembly of a made-up subject of the kind, its values marked with `sampleValue`, offered as a scenario of "Preview full prompt"), `context.assemble` (the brief's task and context, the turn, the working directories, the scopes, and `guidance`: the subject's own lines of the rules and of the environment check), `sink.onRunFinished`, `queuedExpiryMs` (how long a run may wait for a runner; forever without it), `reports.describe` (a subject's label, whether the person may see it, and its `group`), and `agentTypes` (`['runner']` by default; a kind whose runs need no working directory adds `online`). The claim tells `assemble` how the agent reaches the commands (`claim.dialect`, `cli` or `tools`): name them with `commandRef(dialect, cli, id, flag?)` (`acme issue get` in both: an online agent runs the CLI in its shell, writing files under `/tmp`).                                                                                               |
+| `subjects.register(binding)`                                          | A kind of subject runs work on: `kind`, `title`, `triggers` (what `input.payload.trigger` values mean, for the run panel), `preview` (a `SubjectSample`: the assembly of a made-up subject of the kind, its values marked with `sampleValue`, offered as a scenario of "Preview full prompt"), `context.assemble` (the brief's task and context, the turn, the working directories, the scopes, and `guidance`: the subject's own lines of the rules and of the environment check), `sink.onRunFinished`, `queuedExpiryMs` (how long a run may wait for a runner; forever without it), `reports.describe` (a subject's label, whether the person may see it, and its `group`). Name the commands `assemble` mentions with `commandRef(cli, id, flag?)` (`acme issue get`).                                                                                                                                                                                                                                                                                                                                                                     |
 | `scopes.register(kind)`                                               | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`). `agent` is reserved; `workdir` is a core key the application registers to decide who may see and change a working directory's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `actions.provide(source)`                                             | The business actions an agent may be configured with (`key`, `group`, `title`, `groupTitle`, `description`, `defaultOn` for the new-agent dialog), and those never granted to an agent, listed only to show the boundary (`grantable: false` with a `reason`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `presets.register(preset)`                                            | A role a new agent can start from (`name`, `nameText`, `description`, `descriptionText`, `instructions`, `actions`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `actions.provide(source)`                                             | The business actions an agent may be configured with (`key`, `group`, `title`, `groupTitle`, `description`, `defaultOn` for the ones every discovered agent gets unless `agents.setDefaults` says otherwise), and those never granted to an agent, listed only to show the boundary (`grantable: false` with a `reason`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `agents.setDefaults(provider)`                                        | The instructions and business actions every agent discovered from runners gets (`AgentDefaults`), asked whenever one is written; `agents.applyDefaults()` writes them to every one that differs. Returns what removes the provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `agents.ensureSystem(input)`                                          | An agent of the application's own (`SystemAgentInput`: its fixed id, name, description, instructions, business actions and the tools and models it runs with, none until it is configured), created the first time, kept as given and enabled; people do not change it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `gate.set(gate)`                                                      | Who holds which business actions: an `ActionGate` answering `allowed(identity)` for a person or a run, and optionally `consultable(action)` for what a consultation may keep besides reading. `gate.allowed` and `gate.reach` answer for a caller; the gate also bounds what a run may do over the API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `conversations.sources.register(source)`                              | A place conversations start from besides the panel (`POST …/chat/start` takes `source` and the first message as the agent should read it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `conversations.sources.register(source)`                              | A place conversations start from besides the panel (`POST /conversations` takes `source`, then `POST /conversations/:id/messages` the first message as the agent should read it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `conversations.contextKinds.register(kind, resolver)`                 | A kind of object a page context may reference, resolved for the message's owner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `conversations.rules.provide(rules)`                                  | Rules and sections added to the system layer of conversation runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `conversations.deliver(tx, id, news)`, `conversations.lock(conn, id)` | A `news` notice (`type`, English `title`, `params`) written to a conversation, with input that wakes its agent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `conversations.deliver(tx, id, news)`, `conversations.lock(conn, id)` | A `news` notice (`type`, English `title`, `params`) saved in the caller's transaction. Native and Runner OnlineAgent bindings ignore wake-up input and return null; unbound conversations retain the existing wake-up path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `people.provide(source)`                                              | The application's directory: names, whom to pick from, and who can no longer act (`inactive`: their runners stop).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `events.on('agent.removed', listener)`                                | An agent was archived or deleted (`agentId`, `name` then, `reason`, `byUserId`), after the transaction that withdrew its queued runs commits: the application lets go of the work it gave the agent. The assembling application clears it as executor of unfinished issues (`server/agents/removal.ts`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `events.on('agent.removed', listener)`                                | An agent was disabled (`agentId`, `name` then, `reason` `disabled`, `byUserId`), after the transaction that withdrew its queued runs commits: the application lets go of the work it gave the agent. The assembling application clears it as executor of unfinished issues (`server/agents/removal.ts`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `events.on('notice', listener)`                                       | People the plugin wants told (`AgentsNotice`: `key`, `type`, `userIds`, `subject`, English `title` and `body`, `params`): runner notices to their owner, `run_secrets_not_allowed` to a run's actor and owner, and `run_request_expired` to its requester. Subjects are `runner`, `run` or `runRequest`; `notice.cleared` names one that no longer holds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `jobs.register(kind, registration)`                                   | A kind of build job, for the off-by-default runner build method (see Jobs above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `reporting.usage`, `reporting.runFigures`, `reporting.range`          | What runs used and cost, grouped by agent, person, `group`, `subject`, day, model, tool or agent `type`, and how the runs of a range went with their usage by type (`usageByType`) and day by day (`daily`: runs by outcome, cost by type), for the application's report pages. The plugin serves usage over HTTP for its usage page (`GET /api/agents/usage`, behind the `usage` page grant; every run for a reader of agents, else the caller's own; `series=true` breaks each day of `daily` down by the grouping).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -169,11 +175,17 @@ A request settles once, and keeps the work's `fireAt` and `maxAttempts` for its
 
 Creating an `auto` request requires that both the source and the responsible may invoke the agent. Repeated enqueues with identical pending work reuse its request without another creation event or a renewed expiry; comparison includes the input snapshot, execution options, subject, thread and both people. Different input or scheduling options remain separate requests.
 
+### Locking on the claim path
+
+Runners poll together, so anything a poll does per queued candidate is multiplied by the queue and the number of runners. A poll decides from reads which candidates it can take — identity, `fits()`, slots, concurrency and comment consent — and opens a transaction only for the one it is about to claim. The only row lock taken on purpose is the agent row (`lockAgentForClaim`), in that final claim transaction after `fits()` and the cheap checks; the run itself is taken with a guarded `status = 'queued'` update, and 0 rows means another claim or a decision won. PostgreSQL runs at READ COMMITTED, so every statement already reads the latest committed rows: a transaction never needs a no-op self-update to refresh its snapshot, and nothing locks a whole comment chain. Consent decisions settle the request row with a guarded update and then change the chain's runs with guarded updates on their status, so a claim that took a run first makes the decision roll back. Run as me takes the chain's agent rows, in id order, before stopping its runs, the same order claims and enqueues use. A new write or lock on the claim path, the sweeper or a run event handler needs a measured reason; `tests/claim-concurrency.test.ts` counts the writing transactions and lock waits of concurrent polls on PostgreSQL (`pnpm test:db postgres --filter @nocobase/app-plugin-agents -- tests/claim-concurrency.test.ts`).
+
 ## The CLI's commands
 
+Native agents use the application's CLI for every operation on the management instance hosting their task, identified by the server URL in the CLI's `--help`. Its commands remain bounded by the requesting person's identity and permissions; a refusal must never be bypassed through a browser, HTTP, another identity or a test environment. Within the task's authorized scope, local builds and tests are allowed, as are Playwright, browser and test HTTP requests to an explicitly authorized PR preview or independent test instance identified separately from management, even if both products share a name. Establish the target's host, port, application base path and instance ownership from the task and existing preview information; a different URL alone does not establish independence. Use only the test instance's authorized native authentication, never management run credentials or credential files, and clarify an uncertain target before accessing it outside the CLI. Workspace and tool restrictions still apply. Online agents retain their sandboxed shell and skill tools; this native-agent boundary does not add browser or real build capabilities to their sandbox.
+
 The CLI's commands are the application's API routes: `GET /api/cli/manifest` (`@nocobase/app-server/router`) answers every command the API document describes for the caller, named and shaped by each route's `x-cli` extension, and this plugin tells it who calls (a run by its run token, a person by the application's authentication) and which business actions each holds (`gate.allowed`). A run token is also a credential of the application's authentication (`server/cli/run-credential.ts`): a request carrying it acts for the person who woke the agent, as a scoped session the routes accept only where their security lists `runToken`; the application bounds it by its scope (for example, `server/agents/run-principal.ts`). A route lists `runToken` and gives its `x-cli` an `action` for the commands a run may use.
 
-The plugin's own commands are its routes. A run uses `run self`, `run context` and `conversation title set` (`GET /api/agents/runs/current`, `/current/context`, `PATCH /current/conversation`, action `agents.runs/self`), and a run or a person `agent list` (`GET /api/agents/available`, action `agents.agents/view`: the agents the caller may give work to, with what each is good at and whether it can take work now). The rest are a person's: `agent list-all|get|create|update|archive|restore|delete|copy|history|brief`, `agent action list`, `agent preset list`, `skill …` (with `skill version …` and `skill attachment get|set`), `variable list|set|delete|reveal` and `variable audit list` (positional scope kind and scope), `runtime list|get|update|revoke|delete|work` and `runtime token create`, `model list|check|usage` and `model price get|set`, `service list|create|update|delete|discover|check`, `conversation list|get|create|update|stop|fallback|restore`, `conversation message list|send`, `conversation preferences|settings get|update`, and `run list|get|events|brief|cancel|retry|usage`, `run workspace reset` and `run request list|get|confirm|reject|withdraw|run-as-me`. The runner protocol, the downloads and the browser's helpers (the vocabulary, the people picker, the chat agent picker, starting a conversation from a page, marking one read) stay off the command line. The application's routes and custom commands are the rest.
+The plugin's own commands are its routes. A run uses `run self`, `run context` and `conversation title set` (`GET /api/agents/runs/current`, `/current/context`, `PATCH /current/conversation`, action `agents.runs/self`), and a run or a person `agent list` (`GET /api/agents/available`, action `agents.agents/view`: the agents the caller may give work to, with what each is good at and whether it can take work now). The rest are a person's: `agent list-all|get|update|history|brief`, `agent action list`, `skill …` (with `skill version …` and `skill attachment get|set`), `variable list|set|delete|reveal` and `variable audit list` (positional scope kind and scope), `runtime list|get|update|revoke|delete|work` and `runtime token create`, `model list|check|usage` and `model price get|set`, `service list|create|update|delete|discover|check`, `conversation list|get|create|update|stop`, `conversation message list|send`, `conversation preferences|settings get|update`, `conversation attachment upload|download`, and `run list|get|events|brief|cancel|retry|usage`, `run workspace reset` and `run request list|get|confirm|reject|withdraw|run-as-me`. The runner protocol, the downloads and the browser's helpers (the vocabulary, the people picker, every agent's name, the chat agent picker, starting a conversation from a page, marking one read) stay off the command line. The application's routes and custom commands are the rest.
 
 ## Workspace
 
@@ -189,6 +201,10 @@ Variables and model service keys are sealed with the application's secrets servi
 
 ```yaml
 agents:
+  # Optional SDK UI replay across instances; omit for live responses and history only.
+  # uiRecovery:
+  #   namespace: acme:online-ui
+  #   redis: { host: 127.0.0.1, port: 6379 }
   cli: # the CLI runs get; named after app.id when left out
     name: acme
     credentialFile: .acme/run.json # .<name>/run.json by default
@@ -200,10 +216,7 @@ agents:
     versions: { acme: 0.1.0 } # pin a product instead of the channel's highest
     npm: # optional; a product with no tarball in dir is named on npm instead, to callers that understand it
       nocobase-runner: { package: '@nocobase/agent-runner', version: 1.0.0 } # an exact version, never a range
-  server: # optional; online agents' runs, which every instance runs itself
-    enabled: true # false leaves them to the other instances
-    maxSteps: 16 # model calls an online run may make
-    consult: { timeoutMs: 120000, tokenBudget: 200000 } # one agent consulting another (ask_agent)
+
   vectors: # optional; vector collections, apart from the application's database
     store: sqlite-vec # the default; pgvector, or false to turn vectors off
     path: storage/vectors.sqlite # sqlite-vec's file, relative to the application root
@@ -223,17 +236,17 @@ Model services are not configured here: they are added on the application's page
 
 The plugin registers no routes of its own: an application mounts its pages and joins them to the pages of the runner agents do. The assembling application puts them under "Agent team" in its sidebar.
 
-- `@nocobase/app-plugin-agents/client/routes` exports `agentsRoute` (`/agents`, with the `new` dialog and the `:agentId` page), `runtimesRoute` (`/runtimes`, with the `connect` dialog), `skillsRoute` (`/skills`, with `new` and `:skillId`) and `usageRoute` (`/usage`: what runs used and cost over a date range, filtered by group, agent and person and summed by one of the groupings (`?groupBy=`, agent by default), with a daily chart of tokens or cost above the table, stacked by the top five agents or models when grouped by those (the usage route's `series`), its group and subject named and linked by the vocabulary's `groupTitle`, `path` and `groupPath`; for who reads `agents.prices` a "Set prices" header button opens the prices sheet, `?prices=1`: online models by service and model, coding tools by the models their runs report, each tool with its subscription switch and price rules, changed by who manages it; the note on missing prices links to it). Each page renders its own heading, and stands behind a page grant of the same id as its route name (`agents`, `runtimes`, `skills`, `usage`, exported as `PAGES` from `shared/access`); a page grant only opens the page, and what it shows is decided by the admin API on the settings items. It also exports `modelsRoute` (`/models`), which stands behind `agents.services` read instead: the model services (a page header with "Add service", the system default chat model's select, then a table with one row per service: its name and host, provider type, status and a menu to edit it, turn it on or off or delete it; "Add service" and clicking a row open one dialog with a single form saved at once: provider type when adding, name, base URL, the write-only key as a `SecretInput` (`client/components/secret-input.tsx`: a password field whose empty value keeps the saved key), an OpenCode base URL's note on which provider type serves which of its model families (its session header is sent automatically), connection test, models fetched from the provider or added by id and checked, each with its kind, changeable before and after it is checked, and a Test that checks it as that kind, and an on/off switch), changeable by who manages `agents.services`.
+- `@nocobase/app-plugin-agents/client/routes` exports `agentsRoute` (`/agents`), `runtimesRoute` (`/runtimes`, with the `connect` dialog), `skillsRoute` (`/skills`, with `new` and `:skillId`) and `usageRoute` (`/usage`: what runs used and cost over a date range, filtered by group, agent and person and summed by one of the groupings (`?groupBy=`, agent by default), with a daily chart of tokens or cost above the table, stacked by the top five agents or models when grouped by those (the usage route's `series`), its group and subject named and linked by the vocabulary's `groupTitle`, `path` and `groupPath`; for who reads `agents.prices` a "Set prices" header button opens the prices sheet, `?prices=1`: models by service and model, coding tools by the models their runs report, each tool with its subscription switch and price rules, changed by who manages it; the note on missing prices links to it). Each page renders its own heading, and stands behind a page grant of the same id as its route name (`agents`, `runtimes`, `skills`, `usage`, exported as `PAGES` from `shared/access`); a page grant only opens the page, and what it shows is decided by the admin API on the settings items. It also exports `modelsRoute` (`/models`), which stands behind `agents.services` read instead: the model services (a page header with "Add service", then a table with one row per service: its name and host, provider type, status and a menu to edit it, turn it on or off or delete it; "Add service" and clicking a row open one dialog with a single form saved at once: provider type when adding, name, base URL, the write-only key as a `SecretInput` (`client/components/secret-input.tsx`: a password field whose empty value keeps the saved key), an OpenCode base URL's note on which provider type serves which of its model families (its session header is sent automatically), connection test, models fetched from the provider or added by id and checked, each with its kind, changeable before and after it is checked, and a Test that checks it as that kind, and an on/off switch), changeable by who manages `agents.services`.
   - Runtimes (on `/api/agents/runners`): one overview row per runtime — its name with its system, its state with the slots in use ("Busy 1/1", "Offline · 3 hours ago"), its coding tools by sign-in, personal or team, its runner version (marked "Upgradable" when a newer version of the product it runs as is served, with `nocobase-runner update`, or `<cli> runner update` for a CLI that carries the runner; the runner also updates itself) and when it was last seen — with a "…" menu (Edit, then revoke or delete). A row opens the runtime's sheet: General (name, concurrent runs, personal or team after a warning, and "Allow build jobs" only when the application gives runners jobs, as an application's off-by-default runner build method does), Tools (a switch per reported tool with its version, sign-in and, when the API sent it, its path as small text), Local policy (read only: what its owner's policy on the machine lets it take) and Recent runs (`GET /agents/runners/:runnerId/runs`). Only its owner changes it (the managers of runners only a runner whose owner can no longer act); a manager of runners sees someone else's read only, with revoke or delete as the only menu items. Its owner, the managers of runners and anyone who may use an agent get its host name and its tools' paths from the API, everyone else neither. "Add runtime" asks who it works for (team only for managers of runners), which coding tools it may run (all by default) and its max concurrent runs (1 by default, carried by the token; a runner registered with its own `--slots` keeps that), then shows the one-line install and the `nocobase-runner register` command with a one-time token (copy buttons, expiry), and waits until the runtime connects, then shows the coding tools it reported.
-  - Agents: the list (type, tools, the default model and how many more, where it runs with the runners online for it, or "on the server" and whether its model is offered, active runs, visibility; a type filter; archived ones on request; agents everyone can use first, the application's own in the order it added them, then the viewer's own (`AgentSummary.owned`), then the ones shared with them, each group by the name shown) and an agent's page, whose header sums it up in one line (type, tool or model, where it runs, free or busy, owner), with four tabs kept in `?tab=`; the new-agent dialog asks for the type first, then the fields of that type (its tools and models, model services and models for an online agent from `GET /api/agents/models`; with none, the agent uses the system default chat model, which the dialog names with a link to change it, or says none is offered). General: basics, avatar and instructions with "Preview full prompt" (a scenario switch among the subject kinds that offer a sample, the application's first and a conversation, `?scenario=` on the API; it shows the system prompt in one, with the agent's own prompt marked at its end, and the first message, all rendered on a made-up subject whose values are marked `[sample]`), and who may use it. Capabilities: the tools and models, a compact ordered list (one header row, then one row per entry) whose first row is the default, with rows added, removed and moved up or down (a runner agent's rows a coding tool, a model typed freely with the tool's common models suggested, and an effort among the tool's; an online agent's rows a model service, a model and an effort, each with a Test button; the new-agent dialog uses the same list), skills, the business capabilities grouped by the application's groups with a description each, and the ones never granted to an agent greyed out with the reason (`AgentActionOption.grantable: false`), and whether it confirms before changing data. Runtime (runner agents only): where it runs (any runner, or named ones, and concurrency) and its environment variables (write-only, revealing them is audited, saved row by row). Editable when the agent says `canEdit`; a bar appears while a tab has unsaved changes and saves them in one request against the revision the page shows, and switching tabs or following a link away asks first. When someone else saved the agent meanwhile, the page reloads and a dialog shows what they changed. History: who changed what and when, long text as a line diff, lists as what was added and removed, variables named without values.
+  - Agents (`client/pages/agents`, on `GET /api/agents`): one row per agent discovered from runners, filtered by All, Enabled, To enable and No runner: its name with its tool and model, what it is good at, where it can run now (the team and personal runners online with it, the caller's own counted, with a few of their names; "personal runners only", or when a runner last reported it), its default reasoning effort and its state. For who manages `agents.agents`, a pending agent offers "Fill in and enable" and the others "Edit": one dialog (`agent-dialog.tsx`) with what it is good at (started from the catalog's suggestion in the viewer's language), the effort among those its tool takes, and, when editing, whether it is enabled, saved against the revision it shows. Everyone else reads. Under the table, how to add an agent: connect a runner whose tool has the model. An application that keeps agents of its own composes `RunnerAgentsSection` (from `client/kit`) into its own page instead.
   - Skills: the library (each skill's name, description, compatibility and whether it holds scripts), and a skill as a directory: its files in a tree beside the selected one (`client/pages/skills/workbench/`), SKILL.md rendered, other text shown, images and PDFs previewed. Editing uses the same workbench: files and folders are created (in a folder chosen from the skill's and the conventional `scripts/`, `references/`, `assets/`), uploaded (also by dropping files onto a folder), renamed and deleted from the tree, never by typing a path; SKILL.md and other Markdown are written beside their preview (in tabs on a narrow pane), with the front matter's problems listed above the source as it is typed. A new skill (`/skills/new`, a covering page) starts from a template of front matter and suggested sections. Versions can be compared with the current one and restored, and the page shows where the skill is attached. When someone saved a version while the editor was open, the draft stays and a banner offers to load the latest version. A scope's default skills list the scripts of the chosen skills, which online agents do not run (`SkillScriptsNotice`).
-  - The new agent, new skill and variable dialogs ask "Discard unsaved changes?" before closing with input in them (NP-200), through `@nocobase/app-client`'s unsaved-changes guard.
-- `@nocobase/app-plugin-agents/client/kit` exports `VariablesSection` and `DefaultSkillsSection` for a scope's settings on the application's pages (`scope` `workdir` or a registered key, with an optional `description`), `useRunnerOptions` for picking the runner a directory is on (with how many runners are `online`), and `useAgentOptions` for picking an agent.
+  - The new skill and variable dialogs ask "Discard unsaved changes?" before closing with input in them (NP-200), through `@nocobase/app-client`'s unsaved-changes guard.
+- `@nocobase/app-plugin-agents/client/kit` exports `RunnerAgentsSection` (the Agent page's list, for an application's own page), `VariablesSection` and `DefaultSkillsSection` for a scope's settings on the application's pages (`scope` `workdir` or a registered key, with an optional `description`), `useRunnerOptions` for picking the runner a directory is on (with how many runners are `online`), and `useAgentOptions` for picking an agent.
 - `@nocobase/app-plugin-agents/client/runs` exports the headless parts of a subject's runs, for the application to present (the assembling application uses the UI Library's `agent-run-history`): `useSubjectRuns` and `useAgentNames`, `useRunWithTranscript` (a run and its transcript, fetched after the last `seq` seen when the run's realtime topic announces events, and polled every five seconds while the run is open), `useStopRun`, `useRetryRun`, `useRunBrief` and `useWorkspaceReset`. Each reads and writes the plugin's shared query cache.
 - `@nocobase/app-plugin-agents/client/chat` is the agents' chat without its UI. The UI — the panel beside the content area, one conversation as a page, the history and the header, floating and "Ask agent" launchers — is the UI Library's `agent-chat` block (`@nocobase/agent-chat`, installed with `shadcn add @nocobase/agent-chat` into `client/extensions/nocobase-agent-chat/`; its README is `ui-library/registry/agents/agent-chat/README.md` in the NocoBase repository), which the application owns and builds on this entry. What stays here is what has to stay consistent across upgrades: `ChatProvider` around the application's routes (panel state, ⌘J / Ctrl+J, `?chat=<id|new|history>` links, page context, the one subscription to the per-user conversations topic while the chat is available, and optionally `conversationPath`, the application's full-page route of a conversation), `useChatPanel()` (`available` is false without the provider), `chatLinkRoutes(base)` (links under a path the application chooses that open the panel), `useChatContextSource` / `useChatFilterSource` for pages to say what they show, and `ChatExtensionsContext`, with which the application adds items among a conversation's messages (`useTimelineItems`), renders under a message (`renderMessageExtra`), words the news it delivers (`newsText`) and shows a news notice as a card of its own (`renderNews`).
   - The data hooks `useChatAgents`, `useConversation`, `useConversationMessages` (the newest page first, `loadOlder`, newer messages with `messages?after=<lastSeq>` on each announcement and polled while a run is open, optimistic messages through `dispatch`), `useConversationList(query)` (an infinite query over the viewer's conversations), `useSendMessage`, `useConversationActions` and `useChatApi`, keyed by `chatKeys`; `useLiveRunEvents(runId)` (a run's transcript kept current while it runs) and `useConversationSources()` (where a conversation can start from, translated); the pure models `timelineOrder`, `newConversationAgent`, `noticeText`, `liveStepsView` and `stepLineText`, and `contextChips`, `buildPageContext`, `itemKey`, `selectionPreview`, `filterText` and `SOURCE_ATTRIBUTE` for the context chips; the panel's state helpers (`CHAT_PANEL_STORAGE_KEY`, `CHAT_PARAM`, `CHAT_DOCK_QUERY`, `CHAT_MOBILE_QUERY`, `readPanelState`, `isChatShortcut`, `modifierKeyLabel`); `ChatPanelScope`, `useChatPageTracking`, `CHAT_PANEL_ID` and `CHAT_PANEL_ATTRIBUTE` for a full-page view; and the kit's `AgentAvatar`, `useAgentText` and `useFormatters`. The data hooks read and write this plugin's cache (`agentsQueryClient()`) and word their toasts in its namespace whatever is above them, so a chat UI needs only `ChatProvider` and no `withAgents` wrapper. `client/runs` also exports `useRunEvents`, `useRealtimeTopic` and `useAgentsApi`, and `client/kit` exports `useFormatters`.
-- `@nocobase/app-plugin-agents/client/profile` exports `DefaultAgentPreference`: the person's default chat agent, for the application's preferences page. The agents page shows the system default chat agent and the online fallback agent (online agents only) at its top, above the list, changed there with a select by who manages `agents.agents` and shown as text to everyone else, and the new-agent dialog starts from a preset (`GET /api/agents/presets`).
-- `@nocobase/app-plugin-agents/client/config` exports `AgentActionCatalogContext`: the agent editor's business actions come from the server (`GET /api/agents/actions`: what the application offers, none without it) unless an application gives another catalog.
+- `@nocobase/app-plugin-agents/client/profile` exports `DefaultAgentPreference`: the person's default chat agent, for the application's preferences page. The system default chat agent is the application's to set (`PATCH /api/agents/chatSettings`).
+- `@nocobase/app-plugin-agents/client/config` exports `AgentActionCatalogContext`: the business actions an agent can be given, from the server (`GET /api/agents/actions`: what the application offers, none without it) unless an application gives another catalog. No page of the plugin edits an agent's actions any more; they are the application's defaults.
 
 Each exported component brings the plugin's translations and its own query cache, so it works inside another plugin's tree.
 
@@ -242,3 +255,33 @@ A subject assembly may return `inputs` to select the effective claim inputs. Use
 ### Scoped work summaries
 
 `agents.runs.workingOn(subjectKind, subjectIds)` returns each subject/agent pair with a `dispatched` or `running` run once, as `{ subjectId, agentId, working: true }`. Empty scopes return nothing. Reads are restricted to the supplied kind and IDs, without the workload board's global limit; queued and terminal runs are excluded. This service exposes no run details and does not enforce viewer permissions or approval rules: the consuming application must filter visible subjects first and apply its own waiting rules.
+
+## Team default skills
+
+Managers can change global attachment from the skill editor, independently of saving a content version. `SkillSettingsContext` from `client/config` accepts an optional host component with `skillId` for application-owned defaults; `SkillMountToggle` supplies the same immediate-save list membership control. Applications can provide `ScopeKind.describe(scopeIds, userId, keyScope)` to resolve visible names and internal links in a batch on skill detail responses, preserving the credential's action and object limits when a key scope is supplied. Omitted or invisible targets retain a neutral placeholder; this callback is never used when resolving run skills.
+
+Attach skills to `global default` to include them in every new run. The fixed scope ID is `default`; other IDs are refused. Global reads require `agents.agents` read or manage, and writes require manage. Use `nb-studio skill attachment get global default` and `nb-studio skill attachment set global default --skills <id>,<id>`; pass a JSON file containing `{ "skillIds": [] }` with `--file` to clear defaults. Registered application scopes and working directories retain their own access policies.
+
+Runs resolve skills in global → application scopes → workdir order, with the later target winning a shared slug. Resolution reads attachment and current-version metadata with one joined query, without reading file bodies. Missing current versions still fail. Effective skills feed the existing fingerprint and workspace preparation; clearing global attachments affects later claims. Agent skill attachments are no longer accepted, read or shown; existing rows remain stored. Agent variables and CLI-packaged skills retain their existing behavior. The global name is reserved for skills and is unavailable to variables or application scope registration.
+
+## Run process data retention
+
+Set `agents.runs.retentionDays` in the application's `config.yml` to a non-negative integer (default `14`); `0` disables cleanup. Invalid values fail configuration validation. The independent `RunDataPurge` job runs hourly and deletes only events and prompt snapshots belonging to completed, failed or cancelled runs whose `finishedAt` is strictly earlier than the fixed cutoff for that round. Run records, summaries, inputs, usage, repositories, chat messages, comments and deliveries remain available.
+
+Each batch selects up to 200 runs with events or briefs, ordered by finish time and ID, then deletes both child tables in one transaction using their existing run ID indexes. Batches pause for 100 ms; a round handles at most 2,000 runs and stops starting batches after five minutes. There are no run locks, run updates, new fields, indexes or migrations. Cleanup is idempotent. Deletion makes database space reusable; it does not immediately shrink database files.
+
+Multi-instance deployments must set `jobs.default: redis` with a shared Redis connection and namespace so the existing jobs scheduler claims each firing on one instance. Memory jobs and the in-process timer fallback when no jobs service is installed serve single-instance deployments. No additional distributed lock or exactly-once ledger is introduced.
+
+Studio publishes `agents.runs.retentionDays` through its existing public configuration. The process view displays a retention notice only for an expired terminal run with a complete empty transcript and no brief. This uses the current retention rule, rather than a historical cleanup marker; changing or disabling the policy changes the inferred notice. Run, event and brief API contracts are unchanged.
+
+## Runtime quotas and detail tabs
+
+Runtime quota marks share `unavailableModels` with model availability marks and use internal `quotaRevision` conditional writes. Known reset times restore eligibility automatically and cannot be cleared manually. Unknown limits remain until the owner or a runtime administrator clears the selected mark. Expiry and clearing never revive terminal runs or extend queue deadlines.
+
+Usage snapshots are saved when usage changes by at least five percentage points, crosses the near-limit threshold, or changes window state. Only mark changes broadcast `runner.changed`. Quota reports use the existing events/fail transaction; ordinary heartbeats and claims add no queries, writes or locks. Final failures read only accepted quota-event metadata for deduplication, retaining the complete failure snapshot. New event sequences and new runs can mark exhaustion again.
+
+The runtime list omits model catalogs, policy, variables, quota details and load; `takes` contains at most three entries with `takesCount`. Runtime get returns Overview and workspace totals without directory rows. Its recent-run count uses a bounded ten-row read. Workspace sizes and category counts reuse the directory snapshot already read. `GET /agents/runners/:runnerId/workspaces` accepts `status`, `page` and `pageSize` and returns directory rows in `data`, with totals and paging in `meta`. Recent runs load from `/runs` only when that tab opens.
+
+`POST /agents/runners/:runnerId/quota/clear` takes structured `tool`, `scope`, `target` and `window` fields, without a client revision. The server rereads state transactionally and removes only that target, idempotently. A known reset returns `409 CONFLICT`; a concurrent conditional-write race returns `409 REVISION_CONFLICT`. Only revision races are retryable. Clear checks ownership or `agents.runners/manage` independently of edit permission. Owner notices include the triggering run and issue identifiers; `notice.cleared` names the selected quota key so applications settle only that notice group.
+
+Applications can call `useAgentOption(id)` from the client kit for a system executor's viewer-scoped availability, rather than listing only discovered runner agents. The shared cache refreshes at quota reset or runtime changes.