@nocobase/app-plugin-agents 0.1.0-beta.9 → 1.0.0-beta.16

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

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

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

@@ -2,24 +2,25 @@
 
 Everything the App contributes goes through `agentsToken` (`@nocobase/app-plugin-agents/server/tokens`), resolved in one of the App's service providers when it boots. Text people read is an `I18nText` (`{ key, ns }`) in the App's own namespace. The README's "Extension points" section describes each field; this is the map. Where the two disagree, the types exported from `server/tokens` (the `Agents` interface) are authoritative.
 
-| Extension point                                                                                                                                                | Contributes                                                                                                                                                          | Typical use                                                                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subjects.register(binding)`                                                                                                                                   | A kind of subject runs work on: `kind`, `title`, `triggers`, `preview`, `context.assemble`, `sink.onRunFinished`, `queuedExpiryMs`, `reports.describe`, `agentTypes` | An issue, a ticket, a document an agent works on                                                                                                        |
-| `runs.enqueue(...)`, `runs.withdrawQueued(...)`, `runs.workload(...)`                                                                                          | Wake an agent on a subject, withdraw queued work, read the board of open runs                                                                                        | Assigning work to an agent from a business action                                                                                                       |
-| `scopes.register(kind)`                                                                                                                                        | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`); `agent` is reserved, `workdir` is registered by the App          | Per-project or per-team variables                                                                                                                       |
-| `actions.provide(source)`                                                                                                                                      | The business actions an agent may be given (`key`, `group`, `title`, `description`, `defaultOn`), and those never granted (`grantable: false` with a `reason`)       | What the agent editor's Capabilities tab offers                                                                                                         |
-| `presets.register(preset)`                                                                                                                                     | A role a new agent starts from (`name`, `description`, `instructions`, `actions`)                                                                                    | "Reviewer", "Support assistant"                                                                                                                         |
-| `gate.set(gate)` (`ActionGate`: `allowed(identity)`, optional `consultable(action)`)                                                                           | Which business actions a caller holds now: a person their own (narrowed by an API key's scope), a run those its agent is configured with within the waking person's  | Bounding the command manifest and every request a run makes; without a gate a caller holds only `agents.agents/view` (and `agents.runs/self` for a run) |
-| `conversations.sources.register`, `conversations.contextKinds.register`, `conversations.rules.provide`, `conversations.deliver`, `consultations.rules.provide` | Where conversations start from, what a page context may reference, extra system rules, news delivered into a conversation                                            | "Ask agent" buttons on business pages                                                                                                                   |
-| `people.provide(source)`                                                                                                                                       | The App's directory: names, whom to pick, who can no longer act (`inactive`)                                                                                         | Disabling a person stops their runners                                                                                                                  |
-| `events.on('agent.removed' \| 'notice', listener)`                                                                                                             | An agent archived or deleted; people to be told, such as `runner_upgrade_required`                                                                                   | Releasing work given to an agent; forwarding notices to the App's inbox                                                                                 |
-| `jobs.register(kind, registration)`                                                                                                                            | A build job kind, only for an off-by-default runner build method                                                                                                     | Builds on runners                                                                                                                                       |
-| `reporting.usage`, `reporting.runFigures`, `reporting.range`, `reporting.modelUsage`                                                                           | What runs used and cost, grouped as the App needs                                                                                                                    | The App's report pages                                                                                                                                  |
-| `briefs.sections.register(provider)`                                                                                                                           | Sections added to every brief's context layer                                                                                                                        | Project conventions every run should read                                                                                                               |
-| `mounts.register(provider)`                                                                                                                                    | Directories of files placed beside the agent                                                                                                                         | Reference material for a run                                                                                                                            |
-| `repoAccess.register(provider)`                                                                                                                                | Commit identity and short-lived push credentials per run, at the claim or, with `issue`, whenever the runner's git needs one (`gitCredentials` runners)              | Git hosting integration                                                                                                                                 |
-| `online.skills`, `online.gateway`                                                                                                                              | Skills every online run gets; the model gateway for the App's own model calls                                                                                        | See [Online agents](online-agents.md)                                                                                                                   |
-| `vectors.collection(spec)`, `vectors.stores.register`                                                                                                          | Vector collections searched by meaning; another vector store type                                                                                                    | Semantic search for a knowledge base                                                                                                                    |
+| Extension point                                                                                                                                                | Contributes                                                                                                                                                                              | Typical use                                                                                                                                             |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subjects.register(binding)`                                                                                                                                   | A kind of subject runs work on: `kind`, `title`, `triggers`, `preview`, `context.assemble`, `sink.onRunFinished`, `queuedExpiryMs`, `reports.describe`                                   | An issue, a ticket, a document an agent works on                                                                                                        |
+| `runs.enqueue(...)`, `runs.withdrawQueued(...)`, `runs.workload(...)`                                                                                          | Wake an agent on a subject, withdraw queued work, read the board of open runs                                                                                                            | Assigning work to an agent from a business action                                                                                                       |
+| `scopes.register(kind)`                                                                                                                                        | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`); `agent` and the skill-only `global` are reserved, `workdir` is registered by the App | Per-project or per-team variables                                                                                                                       |
+| `actions.provide(source)`                                                                                                                                      | The business actions an agent may be given (`key`, `group`, `title`, `description`, `defaultOn`), and those never granted (`grantable: false` with a `reason`)                           | What the agent editor's Capabilities tab offers                                                                                                         |
+| `agents.setDefaults(provider)`, `agents.applyDefaults()`                                                                                                       | The instructions and business actions every agent discovered from runners gets; `applyDefaults` writes them to the agents that differ                                                    |
+| `agents.ensureSystem(input)`                                                                                                                                   | An agent of the App's own (fixed id, name, description, instructions, actions, tools and models), kept as given and enabled                                                              |
+| `gate.set(gate)` (`ActionGate`: `allowed(identity)`, optional `consultable(action)`)                                                                           | Which business actions a caller holds now: a person their own (narrowed by an API key's scope), a run those its agent is configured with within the waking person's                      | Bounding the command manifest and every request a run makes; without a gate a caller holds only `agents.agents/view` (and `agents.runs/self` for a run) |
+| `conversations.sources.register`, `conversations.contextKinds.register`, `conversations.rules.provide`, `conversations.deliver`, `consultations.rules.provide` | Where conversations start from, what a page context may reference, extra system rules, news delivered into a conversation                                                                | "Ask agent" buttons on business pages                                                                                                                   |
+| `people.provide(source)`                                                                                                                                       | The App's directory: names, whom to pick, who can no longer act (`inactive`)                                                                                                             | Disabling a person stops their runners                                                                                                                  |
+| `events.on('agent.removed' \| 'notice', listener)`                                                                                                             | An agent disabled; people to be told, such as `runner_upgrade_required`                                                                                                                  | Releasing work given to an agent; forwarding notices to the App's inbox                                                                                 |
+| `jobs.register(kind, registration)`                                                                                                                            | A build job kind, only for an off-by-default runner build method                                                                                                                         | Builds on runners                                                                                                                                       |
+| `reporting.usage`, `reporting.runFigures`, `reporting.range`, `reporting.modelUsage`                                                                           | What runs used and cost, grouped as the App needs                                                                                                                                        | The App's report pages                                                                                                                                  |
+| `briefs.sections.register(provider)`                                                                                                                           | Sections added to every brief's context layer                                                                                                                                            | Project conventions every run should read                                                                                                               |
+| `mounts.register(provider)`                                                                                                                                    | Directories of files placed beside the agent                                                                                                                                             | Reference material for a run                                                                                                                            |
+| `repoAccess.register(provider)`                                                                                                                                | Commit identity and short-lived push credentials per run, at the claim or, with `issue`, whenever the runner's git needs one (`gitCredentials` runners)                                  | Git hosting integration                                                                                                                                 |
+| `models.gateway`                                                                                                                                               | The model gateway for the App's own model calls                                                                                                                                          | See [Online agents](online-agents.md)                                                                                                                   |
+| `vectors.collection(spec)`, `vectors.stores.register`                                                                                                          | Vector collections searched by meaning; another vector store type                                                                                                                        | Semantic search for a knowledge base                                                                                                                    |
 
 Rules that are easy to miss:
 
@@ -29,14 +30,13 @@ Rules that are easy to miss:
 - To tell a person before queuing whether a runner would take their work, call `eligibility.canClaim` (online now) or `mayQueue` (some registered runner could) with the subject's variable scopes; a variable marked `teamRunnersOnly` needs a team runner. Enqueue itself does not refuse work run as the responsible or as whoever woke the agent: such work waits with `secretsNotAllowed`.
 - Forward `notice` / `notice.cleared` using the exported `AgentsNotice` interface. Dispatch by its `type`: runner notices go to the runner's owner, `run_secrets_not_allowed` to the run's actor and owner, and `run_request_expired` to the requester. Subjects are of kind `runner`, `run` or `runRequest`. A secrets notice names the run, the agent and the team-only variables in its parameters. Deduplicate by the notice key. Existing copied queue components must merge the `secretsNotAllowed` type and label from the Registry.
 - A repository provider minting credentials in `prepare` implements idempotent `discard(run, prepared)` to revoke undelivered credentials. The plugin calls it outside the transaction on a skipped or rolled-back claim; the App implements the code host revocation API.
-- A subject kind takes runner agents only unless its binding lists `online` in `agentTypes`; a run of another type is refused with `AGENT_TYPE_NOT_ALLOWED`.
-- Name commands in a brief with `commandRef(dialect, cli, id, flag?)` rather than spelling them, so online and runner agents both get the right form.
+- Name commands in a brief with `commandRef(cli, id, flag?)` rather than spelling them.
 - The App's CLI commands are its API routes: a route declares `...cliRoute({ command, action, ... })` in `describeRoute()`, and lists `runToken` in its `security` when a run may call it. The command manifest (`GET /api/cli/manifest`) offers each caller only the commands whose `action` the gate allows. There is no separate command registry.
 - `GET /api/agents/vocabulary` hands the browser the subjects, sources and scopes the App contributed; the browser never imports server code for them.
 
 The README's example under "Extension points" shows a subject registered and work enqueued and withdrawn.
 
-A subject assembly may return `inputs` containing only the effective inputs for its current task. Render the task and turn from that same selection. Runner and online claims use it for delivery, brief sections and mounts; omitted inputs are resolved in the claim transaction and retained in the audit history, so polling and completion do not replay obsolete work. Omit the field to deliver all queued inputs.
+A subject assembly may return `inputs` containing only the effective inputs for its current task. Render the task and turn from that same selection. Claims use it for delivery, brief sections and mounts; omitted inputs are resolved in the claim transaction and retained in the audit history, so polling and completion do not replay obsolete work. Omit the field to deliver all queued inputs.
 
 A working run is held to the same policy: before input joins a dispatched or running run, and before pending input is delivered to one, the plugin asks `admit` and then `selectInputs` with that input. New input either hook keeps from the working run waits in a queued run for the claim to admit or cancel; pending input rejected or left out by `selectInputs` is marked handled instead of being delivered. Implement `selectInputs` with the same selection the assembly returns as `inputs`.
 

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

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

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

@@ -0,0 +1,216 @@
+# OnlineAgent chats and business tools
+
+The shared OnlineAgent entry exports the SDK UI message contract; see `docs/ui-messages.md` in the installed `@nocobase/app-plugin-agents` package for types, validation, dependency versions and conversion boundaries. Realtime routes, Registry and Examples consume that contract through the SDK.
+
+Use `OnlineAgentService` for SDK conversations that call application services and continue answering with their results, or for lightweight background generation with a JSON Schema-constrained result. Native model execution runs inside the application process. Realtime sessions can also select a callable Runner agent through the same service; Runner output arrives as completed text blocks. The plugin owns persistence, model selection, execution control and public chat transport; the application owns its business tools, permissions and page composition.
+
+## Obtain and configure the shared service
+
+Import the original `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` and resolve `agentsToken.onlineAgent` in an application provider after the plugin has registered. Do not construct a second service for an HTTP entry or user: the application instance coordinates busy, stop and finalization across all facades. `OnlineAgentService` and `OnlineAgentConfigurator` are exported from `@nocobase/app-plugin-agents/server` and `@nocobase/app-plugin-agents/server/online-agent`; the latter also exports the prefixed configuration, tool and stream contracts.
+
+Application dependencies and function parameters use the complete `OnlineAgentService` type. Resolve the shared instance through `agentsToken`; do not introduce another service interface or a method-only type projection. `OnlineAgent` is the common public session interface, with `history(): Promise<AppUIMessage[]>`, session identity, status, cancellation and finalization. `RealtimeOnlineAgent extends OnlineAgent` adds `send`, `receive`, `backend`, required `approve` and `messages`; `BackgroundOnlineAgent extends OnlineAgent` adds `run`, `get` and `try`, without `send` or browser `receive`. The service's `realtime()` and `background()` factories return the corresponding interfaces, implemented by the actual session classes rather than inline facade objects.
+
+`onlineAgent.configurator` is the `OnlineAgentConfigurator` (the configuration component). Register global layers, named business scopes and versioned tools once at application boot. It resolves prompts, variables, model lists and tool sets; a Scope selects ordinary configuration and grants no business permission.
+
+```ts
+import { agentsToken } from '@nocobase/app-plugin-agents/server/tokens';
+import type {
+  OnlineAgentService,
+  OnlineAgentToolContext,
+} from '@nocobase/app-plugin-agents/server/online-agent';
+import type { ServiceResolver, ServiceToken } from '@nocobase/service-provider';
+import { z } from 'zod';
+
+type InvoiceService = {
+  read(
+    id: string,
+    actor: OnlineAgentToolContext,
+  ): Promise<{ id: string; total: number }>;
+};
+
+// Call once from the application's provider, with its existing business service token.
+export function configureInvoices(
+  resolver: ServiceResolver,
+  invoiceToken: ServiceToken<InvoiceService>,
+): OnlineAgentService {
+  const online = resolver.resolve(agentsToken).onlineAgent;
+  online.configurator.registerTool('read_invoice', {
+    version: '1',
+    definition: (services) => ({
+      inputSchema: z.object({ id: z.string() }),
+      execute: ({ id }, { context }) =>
+        services.resolve(invoiceToken).read(id, context),
+    }),
+  });
+  online.configurator.registerOnlineAgentGlobalScope({
+    model: ['billing-models/chat'],
+    systemPromptTemplate: 'Answer using the authorized business tools.',
+  });
+  online.configurator.registerOnlineAgentScope('invoices', {
+    tool: ['read_invoice'],
+    systemPromptTemplate: {
+      variableSchema: z.object({ invoiceId: z.string() }),
+      template: (context) =>
+        `${context.systemPrompt}\nInvoice reference: ${JSON.stringify(context.variable)}`,
+    },
+  });
+  return online;
+}
+```
+
+Replace `billing-models/chat` with an enabled chat model in the application's existing model services. Model credentials remain in that service. Factories resolve application dependencies once and must not capture a current user. Each tool invocation receives fresh `OnlineAgentToolContext`: user, current authorization, complete entry credentials, business data, signal and the authoritative runtime `sessionId`. Forward it to the original business service; retain its object, row and field checks. Never use model-provided user/session IDs as authority. Keep secrets out of tool output, prompts, variables and saved configuration. Every tool result and async yield must already be lossless JSON: convert Date to an ISO string and other business objects to intentional JSON values inside `execute`. Non-JSON returns are rejected, not implicitly serialized or retried. The SDK's `toModelOutput` derives model input from that raw JSON without replacing the saved result.
+
+Layers resolve in order: global registrations, selected named scopes, then explicit options. Providers run sequentially; omitted fields keep their preceding value and arrays replace it, including empty arrays. Prompt functions can compose `context.systemPrompt` and validate variables. The resolved serializable snapshot is saved. Loading an existing session restores it without reevaluating Providers. Idle explicit overrides reevaluate only the named sources requested; running configuration is frozen. `selectedModel` explicitly selects the existing model columns, while a model-list replacement selects its first entry. A prompt-only override retains the selected model.
+
+## Use a realtime session or a background result
+
+Construct `OnlineAgentContext` from the authenticated user and full trusted entry identity, never from browser JSON. The authorization principal must match `user.id`. Business references are untrusted input and still require authorization in tools.
+
+```ts
+import type {
+  OnlineAgentContext,
+  OnlineAgentService,
+} from '@nocobase/app-plugin-agents/server/online-agent';
+
+export async function askInvoice(
+  online: OnlineAgentService,
+  actor: OnlineAgentContext,
+  invoiceId: string,
+) {
+  const chat = await online.realtime(actor, {
+    scope: ['invoices'],
+    context: { variable: { invoiceId } },
+    source: 'chat',
+  });
+  await chat.send([{ role: 'user', content: 'What is the invoice total?' }]);
+  const events = await chat.receive();
+  // Consume the standard SDK stream when present; always reconcile saved history and execution state.
+  return {
+    sessionId: chat.sessionId,
+    events,
+    history: await chat.history(),
+  };
+}
+
+export async function classify(
+  online: OnlineAgentService,
+  actor: OnlineAgentContext,
+) {
+  const job = await online.background(actor);
+  await job.run(
+    [{ role: 'user', content: 'Return JSON with category: invoice.' }],
+    {
+      type: 'object',
+      properties: { category: { type: 'string' } },
+      required: ['category'],
+      additionalProperties: false,
+    },
+  );
+  // run acknowledges admission; get waits for validation, persistence and release.
+  return await job.get();
+}
+```
+
+Pass `{ sessionId }` to `realtime`/`background` to load without starting execution. Realtime `send` accepts input for the bound executor; native background `run` saves its input and starts the SDK. `status` includes pending finalization. `get` waits for the execution already admitted at invocation and returns only its successfully persisted and finalized result validated against the submitted JSON Schema. `try({ wait })` observes the same execution with a finite non-negative budget (default 0), returning pending, success, failed or cancelled without stopping work on timeout; admission, authorization and persistence errors still throw. `get` throws OnlineAgentResultError for safe failed/cancelled outcomes. Every session's `history()` returns public `AppUIMessage[]` with ordered SDK parts and stable identities, including background sessions. It never returns privileged model history or raw tool/provider evidence. Background structured results remain separate from message history: `get`/`try` observe the validated result and execution outcome, while status, cancellation and finalization retain their own execution state. Only successful JSON-safe background results persist.
+
+`run(messages, schema)` requires a plain Draft-07 JSON Schema, not Zod. Browser callers submit the same JSON through an authenticated application-owned API; the server supplies the trusted actor, scopes and tools. The schema is snapshotted and compiled before input admission, passed to the AI SDK through `Output.object({ schema: jsonSchema(...) })`, and used for final server-side validation without coercion, default insertion or property removal. Invalid schemas are rejected before model execution. Only local references are supported; schemas are limited to 64 KiB, 32 nesting levels and 4096 JSON nodes. Patterns use a linear-time RE2 engine; unsupported syntax such as lookaround and backreferences is rejected before admission. Use explicit null types instead of OpenAPI `nullable`. Provider warnings that JSON response formatting is unsupported fail the execution rather than falling back to text.
+
+Use `abort()` for explicit Stop. Native execution waits for terminal persistence; Runner acknowledges its existing cancellation request and remains busy until its normal terminal confirmation. Read saved execution state before permitting another turn. A save or seal failure keeps the session busy; `retryFinalization()` retries only that closing work and never reruns the model or tools. Application shutdown drains active executions and warns if finalization fails, allowing the application to close. Cancelled tool exchanges retain paired actual results or an explicit unknown result in private model context; advisory risk feedback never permanently blocks a finished conversation.
+
+## Browser integration and limits
+
+Native `POST /api/agents/conversations/:id/messages` accepts only the current SDK user message (`id`, `role: "user"`, text `parts`) plus authorized attachment IDs, page context and optional selected model. It returns a standard SDK UI message stream. Use a `DefaultChatTransport.prepareSendMessagesRequest` mapper; do not submit browser history or trusted metadata. Tool input/output, assistant/system messages and configuration cannot be supplied as history. Creation starts no model. Detail, list, history, config, attachment and Stop retain ownership checks.
+
+In both native realtime and background modes, `content.original` is the only complete internal UIMessage, with the same ID as its record and raw JSON tool inputs/results, reasoning and provider/approval evidence. Both modes share the same original-message storage and raw tool JSON, not a separate background ModelMessage codec. Public tools require explicit `public.input`/`public.output` projections. All public history reads, including background `history()`, and realtime streams use current projections; current `toModelOutput` rules separately derive internal model input from the original when it is read. Both conversions use detached copies and never execute tools. Missing or failed projections never expose the raw original. No duplicate full message, migration, compatibility fallback or format version is used. SDK `needsApproval` tools require these projections. The approval endpoint accepts only `{ messageId, executionId, approval: { id, approved, reason? } }` and resumes from trusted persisted history. Waiting approvals, denials and outcomes update the same message with increasing metadata revision; use message revision notifications and `GET messages?ids=...` to reread changes. Approval retains its owner/execution/message binding and does not bypass active execution occupancy. Background structured execution stays separate.
+
+Native and Runner realtime receive use the standard SDK stream with optional shared Redis recovery. Background sessions have no browser receive transport and do not require Redis. Browser disconnect never cancels generation. Finish ends the HTTP response, possibly while waiting for approval; execution detail and saved history determine business state. Failed persistence keeps occupancy and supports explicit finalization without reexecution. Missing streams require history/status reconciliation, never automatic resend. A lost producer remains interrupted and is not automatically restarted. The public ChatProvider and installed Registry/Examples consumers use SDK Chat ownership and GET recovery. See [UI messages](../../../docs/ui-messages.md) and [client coordination](../../../docs/ui-message-clients.md) for configuration, costs and limits.
+
+Permission-restricted configuration, custom permission/approval protocols and nonempty Skills execution remain unsupported. SDK approval is native-only; Runner remote tool approval is refused. Verify with isolated model fixtures and authorized application services, never real business writes.
+
+## Open UI context, custom tool cards and local form drafts
+
+Use the public `@nocobase/app-plugin-agents/client/chat` exports for these capabilities; the full contracts and integrated application wiring are in [UI context, tool cards and AI form adapters](../../../docs/ai-forms.md). The plugin supplies infrastructure only. Applications own tool names/schemas, fields, permissions, proposal cards and browser adapters. The Examples application's `examples_form_proposal`, `examples-form-fill` scope and `/ai-form-fill` page are application demonstrations, not plugin defaults or APIs to import into another application.
+
+`PageContext.ui = { version: 1, items: [...] }` is open JSON data: every `PageUIItem` has required `kind`/`id` and arbitrary accepted `AppUIJson` fields, including unknown kinds and nested values. This is separate from server-resolved/authorized `context.items`. UI items grant no server record access or tool permission and enter Native/Runner model context as explicitly untrusted data, never instructions. Accepted fields survive public user metadata, saved history and recovery. Budgets in `PAGE_UI_CONTEXT_LIMITS` reject non-JSON, dangerous keys, duplicate identities and oversized snapshots without truncation; applications must minimize data and exclude secrets.
+
+Register availability with `useChatUIContextSource({ kind, id, label, getSnapshot })`. Registration does not select, read or upload values. An explicit user action calls `useChatSources().selectUI({ kind, id }, true)`; selection state uses `selectedUIKeys` and `uiItemKey`. The installed composer awaits `snapshotUI()` immediately before Send and gives its detached envelope to `buildPageContext`. Custom composers must await this too: `buildPageContext` is synchronous and `uiSources` alone adds chips, not data. Async read failures or selection/source/lifetime changes must block sending with visible feedback. Do not register a resolver for UI data or automatically include every mounted form. Include a fresh snapshot explicitly for each turn that needs it.
+
+`AIToolRendererProvider` takes an `AIToolRendererMap` keyed by exact SDK tool name, with components accepting `AIToolRendererProps`. Registry chat dispatches static `tool-*` and `dynamic-tool` parts using the SDK name helpers; unregistered tools keep their fallback. Nested renderer providers inherit other keys and override matching keys. Renderers receive the public SDK `part`, owning `message`, and `context` with read-only/streaming gates, source message/context and the bound SDK `approval.respond(approved, reason?)` control. A registered renderer owns presentation in every streaming, input, approval, success, error and denial state; only complete schema-valid `output-available` proposals may enable local Apply. Preserve genuine approval controls for approval tools. Keep existing data/message extensions and the one Chat owner; never start effects from rendering, mount, history replay or reconnect.
+
+A card's source comes only from server-owned assistant `metadata.sourceUserMessageId`. Native execution sets it to the admitted user-message id and retains it through approval revisions/public projection. `getAIToolSourceMessage` requires an assistant conversation id and exactly one loaded user message matching that id and conversation; the Registry passes that message and its saved `metadata.context`. Missing source history, legacy messages or a backend without this linkage must disable local application, not fall back to adjacency, the latest user message, current composer selection or model-supplied allowed ids. Native-only Examples tools must not be advertised as Runner browser callbacks.
+
+`AIFormRegistryProvider`, `useAIFormRegistry`, `AIFormRegistry` and `useAIForm` provide generic draft registration, `locate`/`list` descriptors, async `snapshot(id)` and controlled `apply({ source, operationId, values, signal? })`. `useAIForm` returns a **ref callback**, not `{ ref, context }`; attach it to the form and register/select its UI source separately. A registration declares stable id, user/record identity, safe fields, synchronous `getRevision`, current `getValues`/`setValues` callbacks and optional validation. Instances rotate on reattachment or identity change, including A→B→A; duplicate live ids throw. Flat declared fields only: undeclared, read-only, dangerous paths, invalid types/enums and changed revisions are rejected before writing.
+
+Mount form/renderer providers inside the existing keyed authenticated lifetime and around both page and panel, never as a module-global registry or second `ChatProvider`. Nested form registries are isolated, not merged. A card passes the selected snapshot from its exact source message, its final user-edited patch and a stable conversation/message/tool operation key to `apply`. Same-key identical requests deduplicate; changed content under the same key is rejected. The registry checks live identity/instance/revision/capabilities, validates, awaits the setter and reports real applied/partial/failed/rejected/cancelled outcomes. A setter attempt invalidates that snapshot even on failure; do not auto-retry an uncertain or partial write.
+
+Adapters must exclude sensitive fields, advance a monotonic revision synchronously on every draft edit and remain side-effect free while reading. Async preparation must honor `signal` and check `context.isCurrent()` immediately before a synchronous draft commit, without an intervening await. The registry cannot make an arbitrary third-party setter transactional or stop one that ignores cancellation; adapters own atomicity/rollback and truthful partial/failure reporting. A successful local Apply is browser draft state only: no form submission, business save request, fabricated message/tool output, `addToolOutput`, HITL/resume or SDK continuation. The proposal tool already completed on the server. Keep explicit `public.input`/`public.output` safety projections; SDK-standard `toModelOutput` is a separate private model-conversion boundary.
+
+## Select a Runner executor
+
+Applications depend directly on the shared `OnlineAgentService`. Native and Runner realtime execution share `RealtimeOnlineAgent`, and the Runner adapter implements `OnlineAgentBackend`. Both executors return `AppUIMessage[]` history and standard SDK streams. Runner blocks retain source IDs, sequences, creation times and stable part identities in message metadata; render source segments around independent notifications while retaining one logical message. Use the SDK to parse, assemble and resume the stream. Native background sessions implement `BackgroundOnlineAgent`: public UI history is shared with realtime sessions, model conversion remains internal, and the structured `run(messages, schema)` / `get()` / `try()` result and execution state remain separate from UI history. They have neither `send()` nor a browser `receive()` method, and acquire no Redis dependency. The retired custom stream contracts and memory replay manager are no longer exported. EOF or cancelling a subscriber means neither saved completion nor business Stop.
+
+`OnlineAgentBackend` defines required realtime/background creation and restoration, configuration read/write and shutdown. Shared persistence recovery and output transport are not execution-backend capabilities. Runner implements realtime and rejects unsupported background execution, approval and Native-only configuration before persistence or dispatch. A rejected capability uses `INVALID_REQUEST` with `details.reason = 'UNSUPPORTED_CAPABILITY'`, `backend` and `capability` (HTTP exposes details as `metadata`). Applications continue to use the complete `OnlineAgentService` and its canonical `.configurator`; custom injected backends implement this execution contract rather than the removed `OnlineAgentRunnerBackend`. Session `approve` is required, with Runner explicitly rejecting the operation. There is no public Service `isActive()` or `notify()` API.
+
+Creation resolves defaults and configuration Providers once before choosing the backend. On restoration, the session manager first verifies ownership and identifies Native realtime/background or Runner realtime from persisted `mode` and versioned binding metadata, without probing configuration or running Providers. Missing, malformed, conflicting or mode-mismatched bindings and unavailable backends are explicitly rejected, never defaulted to Native. Pending overrides are resolved on send against the latest saved configuration, under the original trusted/HTTP boundary, and cannot change the Agent. Only successful acceptance consumes pending options and pins a new response. Failed or concurrent rejected sends leave the prior accepted response intact. A pinned stream cannot follow a later round; use an unpinned recovery entry to discover the current execution. Startup correction is a session-manager operation invoked directly by the service; shared producer availability is composed once from Native local occupancy and UIStreams. Shutdown drains Runner admissions before detaching projection transport and never cancels or redispatches an already accepted remote Run. Shared transport closes only after both backends have settled.
+
+```ts
+online.configurator.registerOnlineAgentScope('coding', {
+  agentId: 'runner-agent-id',
+});
+const chat = await online.realtime(actor, { scope: ['coding'] });
+// Or pass { agentId: 'runner-agent-id' } explicitly.
+await chat.send([{ role: 'user', content: 'Review the selected code.' }]);
+const events = await chat.receive();
+```
+
+`agentId` follows global → ordered scopes → explicit options. Omission or `online` selects native execution. Selection happens before native model lookup. Existing sessions restore their saved executor and configuration without evaluating providers; a different executor requires a new conversation. New creation and each admission check the actual caller, Agent and execution eligibility. Scope never grants authority. `GET /api/agents/chatAgents` reads the conversation directory directly, independently of OnlineAgent execution, and retains offline reasons; an offline Agent may be displayed but cannot accept new input until executable.
+
+Runner sessions accept one user message per round. Send authorized files by `attachmentIds`, with text parts only; native execution resolves authorized stored files into transient model data URLs. Prompts, configuration variables, resolved page context and business data are assembled on the server. Native model references, thinking settings, local tools, structured background execution and restricted credentials cannot be mapped to Runner execution and are explicitly refused. Keep native business tools in an explicit `agentId: 'online'` business scope selected by the application's native chat, Ask agent and Organize entries; do not put them in a global layer shared with Runner scopes or silently remove them in an adapter.
+
+Request-level business context is assembled directly into the existing Runner input as untrusted data. It is not stored again in message metadata or content, and public messages exclude that internal payload; public page context retains its existing authorized projection.
+
+Runner admission, files and enqueue share the existing conversation transaction. Queued, dispatched, running, cancelling and terminal-history closing all remain busy. Existing Runner synchronization is the only assistant-history writer; persisted event identity and real conversation message positions handle retransmission, blank events and notices. Notifications trigger coalesced persisted catch-up; only active executions have a one-second read fallback. No-change catch-up takes no write lock. Stop requests reuse Runner cancellation and keep the gate until terminal confirmation; retries remain the same active execution. Closing a browser only unsubscribes. Browser recovery reconnects only the standard output stream and never repeats input; Runner claim, lease, retry, spool and adapter protocols are unchanged.
+
+### History confirmation and identity lifetime
+
+Message insertion notifications advance the committed watermark; same-ID revision notifications trigger exact ID rereads. The shared coordinator drains every bounded `nextAfter` page before advancing its forward cursor and preserves older pages and active SDK output. Canonical history merges by ID and revision; browser input with an unknown outcome is reconciled without resending. SDK actions and retained Undo notifications are guarded by the Provider lifetime; removing an archived row does not invalidate its legitimate Undo. Consumers must not write stale detail snapshots into the shared cache from submission callbacks; the controller orders trusted details before notifying consumers.
+
+Use one `ChatProvider` for the authenticated identity and remount it on every identity lifetime change, including logout followed by login to the same user. The SDK orders detail refreshes and commands together, preserves fresh refreshes queued behind older pages, and replaces temporary output only when its canonical message has actually loaded. Submission reconciliation merges confirmed messages without sending again or reopening events. SDK actions and retained Undo notifications are guarded by the Provider lifetime; removing an archived row does not invalidate its legitimate Undo. Consumers must not write stale detail snapshots back into the shared cache from submission callbacks; the controller already commits those details before notifying consumers.
+
+## Chat feedback, defaults and read state
+
+`chatFeedback`, `chatIsRunning` and `useChatScroll` from the public client/chat entry provide presentation shared by the Registry block and its application copies. Local submissions show sending immediately; occupied OnlineAgent execution shows thinking until the first visible reply, even before the subscription attaches or emits text. The busy indicator belongs immediately after the latest message in the scrolling log, not in the composer footer, and is not provider reasoning output; legacy Run-only state may still show waiting. A successful Stop request remains stopping until the execution actually becomes idle. EOF or an interrupted subscription reports an unconfirmed result, never success or an automatic resend. Outcomes use localized safe keys; internal provider errors are not displayed. Legacy effect-review hints are advisory and never disable sending after execution has actually ended. Check possibly completed actions before repeating them. Layout growth follows only while the reader remains near the bottom; loading older messages preserves their position.
+
+The built-in `online` choice is part of the service directory and may be saved as a personal or team default even before a model is configured; its availability still reports `noModel`. UI selection remains picked agent, personal default, then team default and passes that choice explicitly. Service calls that omit `agentId` retain Native compatibility, regardless of a Runner preference. Explicit scope/options precedence and existing session binding are unchanged; invalid or unavailable choices never silently select another backend.
+
+Accepted user input marks the conversation read in its existing transaction. Only newly persisted visible assistant output marks it unread; empty cancellation/failure, tool-only records and duplicate finalization do not. Stop/abort resolves after the cancellation request has been processed; consumers must use execution status, saved history and terminal stream confirmation rather than the request Promise to decide whether another turn is safe. Follow-up context is limited to reauthorized references from the latest earlier page-bearing user message, with current page references taking priority. Full historical page context, including old selections, filters, routes and credentials, is not replayed.
+
+The historical `runCancelled` notice means that cancellation was requested, not that execution has ended. It is rendered as “Cancellation requested.” even when older stored text says otherwise; terminal feedback still waits for the existing execution and saved-history confirmation.
+
+## Historical page references
+
+On a follow-up, OnlineAgent may supplement the current user input with authorized references from only the latest earlier page-bearing user message. Current page references (including a selection source) take priority, duplicates are removed, and historical additions use only the remaining slots of a ten-reference budget after counting current references; existing current-context limits stay unchanged. An empty, deleted, unknown or inaccessible latest page never falls back to an older one.
+
+References are re-resolved through the existing page-kind resolver for the current user, once per kind. Only kind, identifier and the current title (at most 2,000 characters) enter the supplementary untrusted user data. Stored titles, URLs, keys, routes, filters, selections and entry credentials are not replayed. The supplement is not written back to conversation history or promoted to a system instruction. A Native entry with a restricted credential scope receives no inferred historical references because the existing resolver accepts user identity only; ordinary current context and tool authorization stay unchanged.
+
+Resolvers remain responsible for business authorization and their own database reads. One batched resolver invocation does not imply one SQL query: Studio currently resolves each issue through its authorized detail service. Native UI history validation and attachment reauthorization add reads; admission, approval and finalization reuse the existing conversation lock with no new tables or per-token writes. There is no automatic resend. Optional `agents.uiRecovery` uses the plugin-owned shared Redis stream component; SDK consumers use the authorized events endpoint for full replay and later chunks. Runner protocol and lifecycle remain unchanged; existing Runner session memory and previously generated answers are not erased by this policy.
+
+## Shared UI transport and independent notifications
+
+Native and Runner realtime history is `AppUIMessage[]`, and HTTP input for both is the current `{ message: { id, role: "user", parts }, attachmentIds?, context?, selectedModel? }`. Responses use the SDK UI message stream, not the old block events. Runner assistant ID is `runner:<runId>`; `metadata.sourceRecords` retains real saved record IDs, source sequences and stable part IDs/indices. Display segments must interleave independent notifications by source sequence without duplicating the logical assistant message. Registry and application consumers use `chatMessageSegments` to retain that source ordering. Forward history readers must drain `meta.nextAfter` before advancing to the conversation watermark.
+
+For multiple instances configure `agents.uiRecovery: { namespace, redis: { host, port, ... } }` with an application-specific namespace and a shared Redis deployment. The plugin owns the connections. `DefaultChatTransport.prepareReconnectToStreamRequest` points to `/api/agents/conversations/:id/events`. Without configuration there is one live response and history only, reported as `x-online-agent-recovery: live`; configured failures never fall back. Replay requires the live producer: process death does not restart inference, tools or Runner work. Stop remains a separate authenticated action and can signal a live native producer on another instance; read execution and saved history until termination is confirmed. Approval waiting and a missing stream are not business success. See [UI messages and recovery](../../../docs/ui-messages.md) for identity, lifecycle, limits, costs and validation boundaries.
+
+Existing system notices are delivered through `ConversationService.deliver()` in the caller's business transaction. OnlineAgent bindings persist them without starting another execution, and rollback removes them with the business changes. Native notices use standard public data parts and remain readable after a response closes. Independent application timeline content should use the authorized business subscription and rendering extensions; OnlineAgent has no separate notification-injection API.
+
+## Public UI messages
+
+Browser consumers use the SDK-owned `AppUIMessage` and `ChatProvider` from `client/chat`. Render ordered parts and use `chatMessageSegments` to preserve Runner source ordering around independent notifications. The public extension hooks receive the complete SDK message, and approval uses only a bound server-validated control. Follow [the client contract](../../../docs/ui-message-clients.md) for identity lifetimes, unknown admission, revision rereads, durable notification polling and independent Stop. A standard response finish or a missing recovery stream never implies saved business completion.
+
+## Single-instance startup and visibility
+
+Deploy one execution process per logical application/database, fully stopping the old process before starting its replacement. A real serving host repairs pre-process native occupancy at startup: complete saved results are finalized; missing terminal snapshots become failed UI messages on their stable IDs. Current-process rows, valid approval waits and Runner bindings are preserved. Command hosts do not perform crash recovery. Repeated reads and initialization do not rerun models or tools. Shared stream markers express transport reachability, never execution-process death; overlapping deployment and execution takeover are outside this contract.
+
+Normal native and Runner creation accepts showInChatList (default true); background creation always hides the record. List filtering happens in the database before pagination. A known hidden ID retains its ownership checks and remains readable. Notifications delivered through conversations.deliver join the caller's transaction, do not wake new native/Runner execution, and roll back with business changes; native realtime notices are saved as standard data parts.
+
+HTTP creation/configuration cannot override tool lists, model lists or system prompts. Business variables must be declared and validated by selected scopes; selectedModel still selects an authorized catalog entry. Trusted server SDK configuration retains its policy capability. Legacy unbound conversations are read-only but their owner can still Stop their existing Run without a current model or online Agent.

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

@@ -18,6 +18,12 @@ A runner registers once per App with a one-time registration token (10 minutes):
 
 Then on the runner's machine: `nocobase-runner register --server <App URL> --token <token>`, and `nocobase-runner start` or `nocobase-runner service install` (launchd on macOS, a systemd user unit on Linux). The install script does all of this in one line; see [Distribution](distribution.md).
 
+Registering again with the same owner, name and hostname revokes previous registrations and their keys atomically. Old runtimes take no more work, and the sweeper requeues what they held; historical records retain their ids. Hostnames are self-reported, so another owner's matching runtime is preserved. Agent configurations limited to a previous runtime id need to select the new runtime.
+
+`runtime token list` (`GET /api/agents/runners/registrationTokens`, paged with `page` and `pageSize`) lists unused, unexpired token metadata. Signed-in callers see their own tokens; managers of runners see all. Tokens and hashes are never returned: create a fresh token if the original secret is lost. To delete a runtime, run `runtime revoke <runtime>` and then `runtime delete <runtime>`; deleting a live runtime returns `RUNNER_NOT_REVOKED` with those steps.
+
+The install script requires an explicit `--server <App URL>` with `--runner` and rejects a missing or empty value before downloading or installing anything. CLI-only installation still defaults to the application that served the script.
+
 A runner authenticates afterwards with its own key. Personal runners (`ownerOnly`) run only work their owner started, and receive its variables like any runner, except those marked "Team runtimes only" (`teamRunnersOnly`): a run that gets one goes to a team runner. Their owner may share them with the team. `nocobase-runner unregister --server <url>` or "Revoke" on the Runtimes page ends a registration.
 
 ## How work reaches a runner
@@ -44,3 +50,9 @@ Run lists and details expose `executions`, one claim snapshot per attempt, with
 `effort` is requested; `actualEffort` is only a tool report, with `actualEffortSource`, `actualEffortAt` and per-attempt `effortReports`. Show unreported actual values explicitly, never infer from requests or token counts. Import `runForViewer`/`executionForViewer` from `@nocobase/app-plugin-agents/server/tokens` and apply them to custom user-facing run/workload/CLI outputs, using the runner machine rights; `machineHidden` means a generic runtime label, not a fallback to the hostname/id. A projects viewer may provide `seesExecutionMachine` from those same rights. See `docs/execution-history.md` for the report and projection contracts.
 
 The runner finds each coding tool on its PATH and reports whether it is signed in. A tool not found, or not signed in, is offered no runs: sign in on the runner's machine as the runner's user (for example `claude` and its login), then wait for the next heartbeat. Which tools a runner is offered work for is chosen on the Runtimes page (`enabledTools`). A model the tool's account cannot use fails the run `modelUnavailable`.
+
+## Quota recovery
+
+Quota exhaustion is scoped to the runtime and a tool, provider prefix or model. Known resets restore claim eligibility automatically; unknown resets require the runtime owner or an administrator to clear the selected mark after restoring quota. This never restarts failed, withdrawn or expired work. Runtime Overview, Workspaces and Runs load separately; the list contains summaries. Use runtime workspaces for directories and runtime quota clear with structured tool/scope/target/window fields for unknown-reset marks (no client revision); known resets clear automatically. Upgrade runners for usage/reset reporting; old runners only report the failure. See the package README for fields, endpoint contracts and read/write costs.
+
+For application-owned system agents, `useAgentOption(id)` in the client kit reads the same viewer-scoped agent detail endpoint and includes quota; `useAgentOptions()` lists discovered runner agents only. A final failure reuses accepted event metadata for quota deduplication, while new event sequences remain new observations. The failure snapshot is retained even when its windows were already applied.

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

@@ -37,10 +37,6 @@ agents:
     versions: { acme: 0.1.0 } # pin a product instead of the channel's highest
     npm: # a product with no tarball in dir, named on npm instead (exact versions)
       nocobase-runner: { package: '@nocobase/agent-runner', version: 1.0.0 }
-  server: # online agents, run by every instance
-    enabled: true
-    maxSteps: 16
-    consult: { timeoutMs: 120000, tokenBudget: 200000 }
   vectors:
     store: sqlite-vec # the default; pgvector (own PostgreSQL), or false
     path: storage/vectors.sqlite
@@ -49,14 +45,17 @@ agents:
 ```
 
 - `agents.cli.name` defaults to `agents.app.id`; set it to the App's `nocobase.cli.bin` so runs install and call the same CLI the App serves.
-- `agents.server.enabled: false` leaves online runs to the other instances.
 - `sqlite-vec` is local to an instance and has no build for Alpine (musl), where it reports `SQLITE_VEC_UNSUPPORTED`; an App running several instances, or on Alpine, uses `pgvector`, which takes its own PostgreSQL connection and never the App's.
 - Moving `agents.skills.disk` does not copy what is stored: copy `skills/blobs/` across first.
-- Model services are not configured here; they are added on the Models page or through the API.
+- Model services, for the App's own model calls, are not configured here; they are added on the Models page or through the API.
 - `secrets.keys` (the App's secrets service) must be set before variables or model service keys can be stored. `pnpm nocobase secrets rotate` reseals both stores.
 
 ## Pages and chat
 
-The plugin has no routes of its own. The App routes what `@nocobase/app-plugin-agents/client/routes` exports (`agentsRoute`, `runtimesRoute`, `skillsRoute`, `usageRoute`, `modelsRoute`), each behind a page grant named like its route (`PAGES` in `shared/access`); `modelsRoute` stands behind `agents.services` read. `client/kit` has the pieces for the App's own settings pages (`VariablesSection`, `DefaultSkillsSection`, `useRunnerOptions`, `useAgentOptions`), `client/runs` the headless parts of a subject's runs, `client/profile` the person's default chat agent, and `client/config` the business-action catalog context.
+The plugin has no routes of its own. The App routes what `@nocobase/app-plugin-agents/client/routes` exports (`agentsRoute`, `runtimesRoute`, `skillsRoute`, `usageRoute`, `modelsRoute`), each behind a page grant named like its route (`PAGES` in `shared/access`); `modelsRoute` stands behind `agents.services` read. `client/kit` has the pieces for the App's own pages (`RunnerAgentsSection`, the Agent page's list for an App that shows its own agents beside it, `VariablesSection`, `DefaultSkillsSection`, `useRunnerOptions`, `useAgentOptions`), `client/runs` the headless parts of a subject's runs, `client/profile` the person's default chat agent, and `client/config` the business-action catalog context.
 
 The chat is headless in `client/chat`: wrap the App's routes in `ChatProvider` and install the UI Library's `agent-chat` block (`yes n | pnpm exec shadcn add @nocobase/agent-chat`) for its UI. The README's "Web UI" section describes every export.
+
+## OnlineAgent chat
+
+Mount `ChatProvider` from the plugin client chat entry and key it by the authenticated user identity. It owns the shared submission, canonical-history and initial-stream controller for every chat view. New chats use create then messages; legacy start/fallback/restore endpoints are removed. Network uncertainty requires explicit saved-history inspection, never hidden resend or stream reconnect. Existing Runner conversations remain read-only in the switched UI. Ordinary configuration snapshots and custom server tools use `agentsToken.onlineAgent`; see [OnlineAgent chats and business tools](online-agent.md) for configuration, server examples and browser integration.

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

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