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

package/docs/ui-messages.md

@@ -0,0 +1,209 @@
+# OnlineAgent UI message contract
+
+The shared public history contract for all OnlineAgent sessions is `AppUIMessage` from `@nocobase/app-plugin-agents/shared/online-agent`. It is an alias of the installed AI SDK `UIMessage<Metadata, Data, Tools>`. The client chat entry and server OnlineAgent entry export the same type. Native and Runner HTTP responses and history use this contract, with optional shared stream recovery. The public client, Registry demo and Examples application consume the same ordered parts through one SDK Chat owner per conversation and identity.
+
+## Dependencies
+
+The catalog pins `ai` to `7.0.128` and `@ai-sdk/react` to `4.0.131`. The latter's published manifest depends on exactly `ai@7.0.128`, `@ai-sdk/provider@4.0.22` and `@ai-sdk/provider-utils@5.0.54`, matching the server SDK. The templates, UI Library demo and agent-chat installation recipe use this pair. Keep them aligned when upgrading. A matching major version alone does not establish compatibility.
+
+The plugin declares `ai` as an ordinary runtime dependency: its server executes SDK code and its public declarations reference SDK types. It declares the React SDK as a required peer for the application to resolve the client integration. Applications provide the catalog pair directly; the package does not depend on a workspace-only development import. The existing React catalog satisfies the React SDK's published peer range.
+
+## Identity and persistence
+
+Allocate the UI message ID before starting a public stream. For native execution it is also the database record ID; no draft insert is required to allocate it. Metadata carries the conversation, creation time, agent, turn and execution association. These IDs are independent of SDK tool call IDs, data-part IDs and the resumable transport's stream ID. A stream ID belongs to transport state, not to the identity of a saved message.
+
+`seq` is absent until the first save. `revision` starts at zero before saving and increases when a persisted message changes, including an approval continuation. History reconciliation must compare revisions by message ID, and cannot rely on an append-only sequence cursor. Persistence emits message revisions for by-ID refresh, and client reconciliation prevents an older history response from replacing newer SDK state. Neither message identity nor stream registration requires a draft assistant row.
+
+Runner aggregation must retain every distinct source record in `metadata.sourceRecords`, with its database ID, sequence, stable stream part ID and index in the ordered parts (SDK text parts do not retain their stream IDs after assembly). A logical assistant UI message does not make those records share a database primary key. The adapter must apply the same grouping to streaming, history and pagination. It must only project information actually retained by the existing Runner, and must not invent tool calls or approvals.
+
+## Validation and public parts
+
+`validateAppUIMessages()` first rejects values that cannot be saved as lossless JSON, then delegates message and part validation to the installed SDK with the exported metadata and data schemas. It requires metadata, nonempty and unique message IDs, and rejects provider annotations and tool metadata from public parts. Callers must project public output before validation; validation does not redact private tool output or grant access to files, references or business records. SDK objects with explicitly undefined properties must be finalized into JSON data before validation; the validator rejects rather than silently dropping values.
+
+Tools use standard SDK tool parts, including approval states and real tool call IDs. `AppUITools` constrains public input and output to JSON; each tool's business schema and authorization remain the server's responsibility. Model-only evidence remains private inside the original UIMessage; public history is a projection, not access to that original. A structurally valid approval part is never evidence that a browser is entitled to approve it.
+
+`appUIDataSchemas` defines `data-notice` (notification type, fallback title and optional translated parameters) and `data-business` (business kind, stable record ID and public JSON payload). Producers and renderers must use a stable SDK data-part ID to update the same card. Application cards, references and consultation displays may use these public extension points; their presence does not restore a removed production workflow. Independent notifications are persisted and fetched through the business subscription after a model response ends. The Registry and Examples consumers preserve custom rendering and translated fallback behavior.
+
+`appUIMessageText()` joins text parts in order for search and message extensions. It does not flatten files, tools or cards into text. Ordered parts remain authoritative. `convertToModelMessages()` ignores these data parts by default; a server that needs business data in model context must explicitly convert authorized data. See the SDK's [metadata guide](https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata) and [message persistence guide](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-message-persistence).
+
+## Open page UI snapshots
+
+`PageContext` and the public `ResolvedPageContext` optionally carry `ui: { version: 1, items: PageUIItem[] }`. A `PageUIItem` requires string `kind` and `id`; every other property is arbitrary `AppUIJson`. Unknown kinds, nested application properties, `false`, `0`, empty strings and `null` are preserved. The envelope is strict; item fields are open. This is a separate channel from `context.items`: business references still go through their existing server resolvers and authorization, whereas UI data never grants access to a record, route, tool or permission. Applications must minimize snapshots and explicitly exclude credentials, password fields and other sensitive values.
+
+`PAGE_UI_CONTEXT_LIMITS` centralizes rejection budgets: 10 items, depth 12 (root envelope at depth zero), 64 KiB of UTF-8 JSON, 4,096 JSON values, 64 characters per kind, 200 per id or property key, and 16,384 per string. Duplicate `(kind, id)` pairs are rejected rather than deduplicated. Browser snapshotting, HTTP validation and public metadata use the same validator and detached clone. It rejects cycles, sparse/extended arrays, non-finite numbers, undefined, functions, BigInt, symbols, accessors, hidden properties, non-plain objects and the property names `__proto__`, `prototype` and `constructor` at any depth. There is no silent truncation or JSON serialization coercion.
+
+Registering a source is not selecting it. `useChatUIContextSource({ kind, id, label, getSnapshot })` makes a source available under the existing authenticated `ChatProvider`; `getSnapshot` may return a value or Promise and must be side-effect free. `useChatSources().selectUI({ kind, id }, true)` is a separate explicit action. `uiSources` lists the registered descriptors and `selectedUIKeys` identifies the selected ones using `uiItemKey()`. Registration validates identity without reading form values; JSON payload validation happens at the snapshot boundary. A source unmount removes its selection, old cleanup cannot remove a replacement, and a route change clears UI selections. Source/form registration alone never uploads all forms.
+
+```tsx
+const source = {
+  kind: 'application-widget',
+  id: 'planning-draft',
+  label: 'Planning draft',
+  getSnapshot: async () => ({
+    kind: 'application-widget',
+    id: 'planning-draft',
+    capabilities: ['summarize'],
+    data: { approved: false, estimate: 0, note: '', optional: null },
+  }),
+};
+useChatUIContextSource(source);
+const sources = useChatSources();
+// Call from an explicit user action, not from source registration:
+sources.selectUI(source);
+// The existing composer's asynchronous context builder, immediately before submission:
+const ui = await sources.snapshotUI();
+const context = buildPageContext({
+  route: location.pathname + location.search,
+  pinned: panel.pinned,
+  sources: sources.items,
+  uiSources: sources.uiSources.filter((item) =>
+    sources.selectedUIKeys.has(uiItemKey(item)),
+  ),
+  ui,
+  filter: sources.filter,
+  selection: sources.selection,
+  removed: sources.removed,
+});
+```
+
+`buildPageContext` remains synchronous for legacy callers: its `ui` input is an already-read envelope and is cloned again. Its optional `uiSources` input contributes UI chips only; it does not read callbacks. Await `snapshotUI()` once at send time, not when rendering chips. Snapshot reads use current callbacks, validate returned identities, reject selection changes or source replacement/unmount while awaiting, and clone accepted data. A read error prevents submission and must be shown by the composer. This source API is independent of `useAIForm` and its registry; a form is one application convention for an open UI item, not a core schema requirement.
+
+Native model conversion places saved UI snapshots into their originating user message as explicitly untrusted data, never system instructions. Runner uses the existing user-message page-context rendering with the same warning. Admission, native originals, public metadata projection, Runner projection and saved-history recovery retain accepted custom fields. Public assistant metadata `sourceUserMessageId` identifies the exact originating user message for Native responses and survives approval revisions and restoration; a renderer must resolve that ID in trusted conversation history. It must disable local application when that source message or association is absent, rather than guessing from the nearest user message. An association is not authorization: applications still validate their allowed target, active instance, field capability and revision before applying any draft changes. History and reconnect never execute a browser setter.
+
+## Consumers and background execution
+
+The plugin client controller coordinates the SDK owner, trusted history reconciliation, submissions and public extensions. Registry agent-chat, its typed website demo, Examples component copies and the generated CLI send request mapper consume this contract. See [UI message clients](./ui-message-clients.md) for rendering, identity isolation, polling costs and application integration. Private Studio consumers require their own source merge and verification; updating a published plugin does not replace installed Registry source.
+
+The former part/delta/message/saved protocol and process-local replay manager are removed. `OnlineAgent` is the common public session interface: `history(): Promise<AppUIMessage[]>`, session identity, status, cancellation and finalization. `RealtimeOnlineAgent extends OnlineAgent` adds `send`, `receive`, `backend`, `approve` and `messages`, exposing standard SDK chunks. Approval is a required operation: Runner explicitly rejects it rather than omitting the method. `BackgroundOnlineAgent extends OnlineAgent` adds `run(messages, schema)`, `get()` and `try()`, without `send` or a browser `receive()` method. `OnlineAgentService.realtime()` and `.background()` return the corresponding interfaces implemented by actual concrete session classes; neither the service nor the Runner backend assembles inline facade objects.
+
+### Backend ownership and orchestration
+
+The internal source lives under `server/online/agent/`, alongside the online model gateway and services, and is organized by domain: `native/` contains execution and session implementations, `runner/` contains remote execution and message projection, `persistence/` owns session storage and dependency-light binding/status helpers, `messages/` owns public/model conversion and JSON/input/output validation, and `transport/` owns shared output streams. `contracts.ts` contains interfaces only; `types.ts` and domain-local `types.ts` files contain data definitions only. `configuration.ts`, `errors.ts` and `service.ts` contain their respective runtime implementations. The public package subpath `server/online-agent` maps to this directory's `index.ts`; applications must not depend on internal source paths.
+
+`OnlineAgentBackend` defines execution-specific capabilities implemented by `NativeOnlineAgentBackend` and `RunnerOnlineAgentAdapter`: `kind`, realtime/background creation and restoration, `configuration`, `configure` and `shutdown`. No capability method is optional. Sending, history, cancellation, approval, finalization retries and structured-result observation remain on the corresponding session interfaces, not duplicated as backend operations. Shared storage recovery and transport probing are not backend capabilities. The former `OnlineAgentRunnerBackend` contract and `ConfiguredRunnerOnlineAgent` wrapper are removed. Custom injected backends implement this execution contract; normal applications continue to depend directly on the complete `OnlineAgentService`.
+
+The service validates trusted entry context, owns the shared `OnlineAgentConfigurator` and UIStreams, resolves new-session defaults and initial configuration exactly once, selects the backend and delegates execution operations. For existing sessions, the session manager first checks ownership, then classifies persisted `mode` and versioned binding metadata as Native realtime/background or Runner realtime. Missing, malformed, conflicting or mode-mismatched bindings are rejected, and an unavailable required backend is an explicit error; configuration reads never probe for backend identity or fall back to Native. Native model fallback and model validation occur only after Native selection. Native owns active executions, serialization gates, admission, approvals, cancellation, result observers, outcome conversion and persistence/finalization retries. Its internal executor and concrete realtime/background sessions share that backend's state; no callbacks manipulate execution state on the service. Background selection also uses the execution contract rather than a hard-coded Native call.
+
+Runner currently implements realtime creation/restoration, configuration, safe history and paging, live/shared output, cancellation requests and saved-Run finalization. Structured background execution, SDK tool approval and native model/tool/thinking configuration are explicitly unsupported. Rejections use the existing `ProtocolError` code `INVALID_REQUEST` with `details.reason = 'UNSUPPORTED_CAPABILITY'`, `backend` and `capability`; the HTTP error has reason `INVALID_REQUEST` and carries those details in `metadata`. Unsupported execution is refused before conversation creation, input admission, attachment binding or queue writes, with no Native fallback. Restricted Runner credentials remain a permission rejection. Startup does not dispatch or cancel remote Runner work; the existing Runner lifecycle owns durable recovery, and restoration repairs projection markers only after confirmed termination.
+
+One `RunnerRealtimeOnlineAgent` contains trusted context, deferred configuration and its last successfully accepted response. Opening an existing session does not reevaluate Providers. A later send resolves pending overrides against the latest persisted configuration, keeps Agent identity fixed and submits the resolved configuration separately from the expected configuration used by the final admission transaction. The session retains its HTTP parsing boundary. Only successful durable admission consumes pending options and changes response ownership; failed and competing submissions cannot replace an earlier accepted response. The same acceptance-only response binding applies to Native realtime sessions.
+
+The internal Runner admission method `ConversationService.sendRealtime()` returns only the committed `{ seq, run }` receipt, without reading or projecting conversation detail after commit. Normal `send()` and HTTP response contracts are unchanged. A detail-projection or stream-bind failure after acceptance must never cause an automatic second business submission.
+
+Both backends use the same configurator and UIStreams instances assembled by the plugin. Backend shutdown settles or detaches only its own work; the service closes the shared transport after both backends finish. Runner tracks the whole in-flight admission, including asynchronous configuration, stream registration, database acceptance and stream binding, before shutdown detaches producers. Already accepted remote Runs are neither cancelled nor redispatched by shutdown.
+
+Startup correction belongs to the session manager and is invoked directly by the service only during serving-host startup, not through backend lifecycle wrappers. The service also combines Native local execution occupancy with one shared UIStreams producer probe for Native status projection; local background execution and failed finalization remain occupied even without a browser channel. There is no public `OnlineAgentService.isActive()` or `notify()` API and no generic cross-backend occupancy aggregation.
+
+Both native modes store a complete UIMessage in `content.original`, sharing raw JSON tool inputs/results and the same public/model conversion boundaries. Background `history()` returns the same public projection as realtime history, not privileged `ModelMessage[]` or tagged model evidence. Model messages are derived internally when read for execution. The JSON-safe structured result and its execution outcome remain separate from UI history; `get`/`try`, status, cancellation and finalization retain their existing semantics. This unification adds no background browser receive transport or Redis dependency.
+
+Background SDK callers may supply user-message file/image inputs directly. These trusted inputs are normalized to JSON-persistable SDK file parts before occupancy is reserved; URL objects, URL strings, data URLs and binary payloads preserve their input semantics. Their private file indices and message-level provider options remain inside the original, are restored for model replay, and never grant public file access. Uploaded attachment references continue to use current ownership checks. Historical tagged background ModelMessage records are not accepted by the new reader; this change adds no migration or legacy fallback.
+
+## Native persistence and transport
+
+Native realtime input is `POST /api/agents/conversations/:id/messages` with `{ message: { id, role: "user", parts: [{ type: "text", text }] }, attachmentIds?, context?, selectedModel? }`. Only the current user input is accepted. Metadata, browser history, system messages, assistant parts, tool results and configuration are rejected. Uploaded files are bound atomically using existing ownership checks; file-only input uses empty text parts and nonempty attachment IDs. The server assigns the execution ID and assistant message ID before streaming, without inserting a draft assistant record. Input admission is acknowledged by the standard AI SDK response (HTTP 200); transport failure never authorizes automatic input resubmission.
+
+`createUIMessageStreamResponse` supplies SDK headers, SSE encoding and the ending marker. `DefaultChatTransport.prepareSendMessagesRequest` must submit only the current user message, rather than the SDK default full browser history. Without shared recovery, `receive()` exposes one unclaimed live response, with bounded buffering; disconnecting or a slow reader releases only that response. With shared recovery, subsequent reads replay and subscribe through the shared component. Generation and saving continue under the producer's own AbortController. The live-only mode has no replay cache. A missing response (204) does not mean idle or success; read execution and history. An unavailable producer remains interrupted/busy; this implementation never restarts it or claims it stopped.
+
+For both native realtime and background execution, the database record ID equals `UIMessage.id`. `content.original` is the single complete internal SDK UIMessage, including raw JSON tool inputs/results, reasoning and provider/approval evidence. There is no second full message in row metadata, no separate background ModelMessage codec, and no message format version or legacy fallback. Row metadata retains only execution controls such as `nativeOutcome`; conversation metadata retains ownership, execution binding and state, with the validated background structured result stored independently of message history. Outer text/search fields and unread visibility are derived from the public projection, not private tools or reasoning.
+
+`server/online/agent/messages/projection.ts` owns both pure conversion boundaries shared by native realtime and background sessions. `NativeMessages.public()` derives every native history/page/after/by-ID/SDK response using the current display rules, including background `history()`; its realtime stream adapter shares the same public tool projection and field allowlists before chunks reach the live channel or Redis. Private tools are hidden by default, reasoning/provider annotations and approval internals remain private, and errors are sanitized. Failed or missing projections never return raw data. Changing a projection changes historical display without rewriting the stored original.
+
+The SDK already validates and transforms tool inputs before execution or approval. Projection uses that parsed input without applying its schema a second time. Rejected model inputs keep `toolMetadata.nativeInputInvalid` inside the single original SDK part, so historical reads suppress them without invoking typed formatters; tool metadata never enters public messages.
+
+For either native mode, `NativeMessages.model()` reads the original UIMessage, applies each current tool's `toModelOutput` to its raw result, or uses the SDK string/JSON default, then calls `convertToModelMessages`. It does not use public history as model input or persist a second model-message representation. Missing tools or failed converters produce an explicit safe error result rather than exposing the raw result. Before conversion the store checks current file permissions and resolves authorized attachment URLs to transient data URLs, reauthorizes page references, and removes unfinished text from failed/cancelled turns while retaining paired completed tool facts. UI-only notices and cards do not enter model context. Both conversion directions work on detached copies, never execute tools and have no business effects. The next turn is allowed after actual tool termination and finalization, with advisory risk feedback.
+
+Registered tool outputs must be lossless JSON, enforced by the `OnlineAgentToolDefinition` output type and `strictJson()` at every normal result or asynchronous yield. Convert Dates to ISO strings and binary values to an intentional JSON representation inside the tool. Date, BigInt, binary objects, cycles, non-finite numbers, undefined values and other non-JSON data are rejected without implicit serialization. A validation failure is a tool error, not permission to repeat a possibly completed action; finalization retries only save the frozen message. Model converters may derive SDK model output from the raw JSON but never replace that saved raw result.
+
+`finish` is emitted only after the native snapshot transaction commits. It ends an HTTP response, including an approval-wait response; execution detail remains authoritative. A save failure emits a standard error, retains execution occupancy and an in-process immutable finalization snapshot, and permits `POST /:id/finalize` with `{}` to retry persistence only. A commit-unknown retry verifies the same ID, revision and message before clearing occupancy. Process failure loses in-process finalization and does not imply automatic execution recovery. Stop uses `POST /:id/stop` independently of subscription cancellation and waits for accepted tool work and saving.
+
+## Native SDK approvals and revisions
+
+Register SDK `needsApproval` on a tool together with explicit `public.input` and `public.output` projections. This makes approval input display intentional; projection is never authorization. Business execution still receives the fresh actor, credentials and authoritative session ID. The single saved original retains the actual tool input and raw business result. Approval tools without public projections are refused rather than exposing internal payloads. Non-approval tools remain private by default.
+
+`appUIToolApprovalInputSchema` and `AppUIToolApprovalInput` are exported through the shared, client chat and server OnlineAgent entries. `POST /:id/approval` accepts `{ messageId, executionId, approval: { id, approved, reason? } }`, matching the SDK approval response. The server locks the conversation and matches its owner, execution, message and actual pending approval in the single trusted original message. The last required response atomically changes waiting to running and increments the same message's revision; duplicate, concurrent, mismatched and expired (24-hour deadline) responses conflict. Partial answers update the saved revision without invoking tools or the model; continuation starts once all pending approvals have answers. Execution then resumes from trusted history using the SDK. Denial never invokes the tool; completed tools are not executed again. Stop while waiting persists denial and a cancelled business state. Runner remote approval is explicitly unsupported.
+
+A first saved assistant has revision 1. Accepting an approval writes revision 2 and continuation saves revision 3 on the same record and sequence. Each committed change emits `conversation.messageUpdated` with message ID and revision through the existing business subscription. `GET /:id/messages?ids=id1,id2` (at most 100 IDs) rereads current revisions; normal newest/older/after pagination is SQL-bounded. Reconcile by stable ID and revision; an older page must not overwrite an SDK-active message. Never use `after=seq` alone to detect approval updates.
+
+## Database cost
+
+The following baseline counts cover native realtime store operations, excluding existing model catalog, authorization/business service queries and the database adapter's schema metadata probes. No work is added to Runner claims, heartbeats or sweepers. There are no per-token writes or polling locks.
+
+| Operation                                   | Reads at the store boundary                                                                                | Writes and locking                                                                                                                                                                        |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Current input and eventual snapshot         | Two trusted history loads (owner + message query each), then 1 admission row read and 2 snapshot row reads | Two transactions and two existing conversation locks; each has one lock update, one message insert/update and one conversation update. No assistant draft or separate finish transaction. |
+| Approval and eventual continuation snapshot | 2 reads under the approval lock, one trusted history load (2 reads), then 2 reads under the snapshot lock  | Two transactions and two conversation locks, each updating the lock, same message and conversation. Tool execution occurs outside locks.                                                  |
+| Stop while waiting for approval             | 2 reads under the lock                                                                                     | One transaction and lock; three updates (lock, message and conversation).                                                                                                                 |
+| Failed finalization retry                   | 2 reads under the lock                                                                                     | One transaction/lock per attempt; one message and conversation write on success. A verified commit-unknown retry only updates the lock. No model/tool invocation.                         |
+| Message page or ID reread                   | Owner + bounded message query                                                                              | No writes, transactions or locks. HTTP also performs authorized backend-binding classification and executor/ownership lookups.                                                            |
+
+Background execution uses the same admission and snapshot transactions and then retains its separate finalization transaction to release occupancy only after the validated structured result is durable. This extra finalization step has one conversation lock and metadata update, and never invokes the model or tools again.
+
+Native admission and response attachment also retain the facade's ownership reads. Existing native history is currently validated twice (pre-admission safety check, then trusted history including the committed input). Attachments add the existing batched upload lookup/binding and fresh authorized file reads; historical files are reauthorized on both history passes. Page resolvers keep their own permission checks and query costs. GET execution and stream reception add no writes or locks; absent streams cannot release occupancy. Request counts do not include token, provider or application business traffic.
+
+## Runner projection and independent notifications
+
+Native and Runner realtime sessions now return `AppUIMessage[]`, standard SDK chunks and the same POST user-message input. A Runner assistant message has ID `runner:<runId>`. Every saved assistant source block becomes one ordered text part with stable stream ID `record:<recordId>`; files retain their own stable IDs. `metadata.sourceRecords` maps each part index to its real database record ID and sequence. `metadata.clientId` on user messages correlates accepted browser input without claiming that input ID is the database primary key. The first saved assistant block starts the logical SDK message; a Run with no saved assistant output ends its response without creating a phantom assistant message. No Run, machine event, message synchronization or lifecycle implementation changes.
+
+One Run remains one logical message. A standalone notification retains its own message and source record. Consumers must derive display segments from `sourceRecords` and interleave independent messages by their source sequence: for example, assistant source 2, notification 3, assistant source 4. Do not render the aggregate as an indivisible item ahead of the notice, duplicate the logical message or synthesize another model turn. SDK state continues to own one assistant message. Registry, demo and Examples use the public segment helper to apply this ordering while keeping one SDK message.
+
+Message pages expand complete assistant groups and intervening independent notifications. The page size bounds the seed query, not the size of one logical message; an unusually large Run can therefore yield a large page. Older pages use the smallest returned message anchor as their next `before`. Forward readers drain `meta.nextAfter` before advancing to `meta.lastSeq`; expanding an assistant group may reread an existing ID at a newer revision, while independent records already consumed are excluded. By-ID rereads accept logical Runner IDs. Reconcile by stable ID and revision; never overwrite a newer SDK-active response with an older page.
+
+Independent system notifications continue through the existing `ConversationService.deliver()` business transaction. OnlineAgent bindings save the notice without waking Native or Runner execution; rollback also removes the notice. Native notices use a system UIMessage in `content.original`, while existing revision/business events and normal history rereads make them visible even after a model response has closed. Notice data stays outside model input. OnlineAgent exposes no separate API for injecting independent business notifications.
+
+## Optional shared recovery
+
+Configure the plugin once in the application's server configuration:
+
+```yaml
+agents:
+  uiRecovery:
+    namespace: acme:online-ui
+    redis:
+      host: 127.0.0.1
+      port: 6379
+```
+
+Provide a unique application namespace, identical on its instances, and normal `ioredis` connection options for the shared Redis deployment. The plugin owns its publisher and subscriber connections and closes them at shutdown. The host cache API has no public pub/sub connection contract, so this explicit plugin configuration does not inspect host-private state or discover credentials from environment variables. Supply any Redis authentication through the application's normal configuration mechanism; never copy credentials into messages.
+
+Without this configuration the application starts normally and offers one live standard response plus durable history, with `x-online-agent-recovery: live`. It does not use the old memory replay manager. With configuration, the header is `shared`; unavailable configured Redis is rejected before admission instead of falling back. The manager initializes the upstream subscription/sentinel, then saves the conversation/stream/execution association in existing conversation metadata before exposing a start chunk. ID-checked cleanup completes before a normal finish chunk. Runner binds the actual accepted Run ID before projection starts; a failure after admission interrupts transport but never redispatches the Run.
+
+`GET /api/agents/conversations/:id/events` is the authorized SDK resume endpoint. Set `DefaultChatTransport.prepareReconnectToStreamRequest` to this URL. It returns a full replay and subsequent chunks; use the transport's default replay behavior so interrupted text is rebuilt by message ID. The plugin uses SDK SSE encoding/headers/ending markers and the SDK JSON event parser, with `resumable-stream@2.2.13` managing replay and subscription. It does not implement another SSE framing or replay engine. See the [SDK resume guide](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-resume-streams) and the [upstream component](https://github.com/vercel/resumable-stream).
+
+A response channel supplied by an accepted session is pinned to that submission even after its initial stream has been claimed. Shared recovery may resume only that channel's own stream/execution association; it never silently follows a later conversation execution. Only an unpinned restoration/recovery entry discovers the conversation's current association. An unavailable pinned stream requires reconciliation, not input resubmission or occupancy release.
+
+The component retains the active replay buffer on its producer and coordinates cross-instance readers through Redis pub/sub and expiring sentinels. It therefore requires a live producer; Redis is not a durable inference checkpoint. Responses are limited to 8 MiB and 4,096 pending source chunks, with at most 1,024 local producers. The projection-only producer lease expires after 30 seconds and renews every 5 seconds. This lease never claims, renews or cancels a Run. Expired associations, missing sentinels and failed replay acknowledgments produce an explicit reconciliation error. A missing response (204), SDK ready state and SDK finish do not establish business completion; read saved history and execution, including approval waiting and interrupted occupancy.
+
+Closing a browser subscription never cancels native generation, accepted tools or Runner work. `POST /:id/stop` remains the separate business action. Native Stop on another instance publishes a signal bound to the owner-authorized conversation, actual execution and current stream; the live producer performs the existing abort/save path. The returned detail can remain running until saving completes. Lost producers refuse unconfirmed native Stop rather than clearing occupancy. Runner Stop continues to use its existing cancellation acknowledgment semantics.
+
+A Redis failure after acceptance ends or invalidates the stream while the independent producer continues saving. It never resends user input or reruns a tool. Native save failure retains the existing immutable finalization snapshot and occupancy for explicit retry on its producer instance; other instances explicitly refuse a running finalization without that snapshot. A newer trusted revision of the same native message/execution can acknowledge an earlier commit-unknown save without overwriting the continuation. Shared infrastructure loss requires state reconciliation; connections fail closed and require service restart after an unavailable connection, rather than silently rebuilding execution. Process death does not resume inference or tools. A Runner process can finish through its existing execution protocol and core synchronization; this adapter does not automatically take over another projection producer. Opening a Runner conversation with a closing marker and no local producer checks the saved Run. Only a confirmed terminal Run triggers idempotent automatic finalization; a missing stream or running Run keeps the gate. Automatic or explicit finalization first synchronizes final records and clears only the matching adapter closing/stream markers; it never redispatches work. Private Studio wiring remains outside this public repository. The SDK client and installed public consumers are described in [UI message clients](./ui-message-clients.md).
+
+## Shared recovery request cost
+
+Counts exclude existing authorization, model catalog, file/page authorization and database schema metadata probes. All new SQL association mutations use the existing conversation lock, compare stream IDs on cleanup and have no token-level writes. The disabled mode adds no SQL association writes or Redis operations. Runner claims, heartbeats, sweepers, execution protocol and machine writes are unchanged.
+
+| Request or work                                         | Added SQL at the UI boundary                                                                                                                                                                     | Shared Redis work                                                                                                                                                                                                |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Native input or approval response, through completion   | Two association transactions/locks (register and clear), each with one owned-row read, lock update and metadata update; existing native admission/snapshot transactions remain                   | Preflight ping, one NX producer registration, component subscription/sentinel setup, one lease deletion; component publication per emitted SSE chunk/subscriber and completion cleanup                           |
+| Runner input through completion                         | Three association transactions/locks (register, bind accepted Run, clear), each with the same row/lock/metadata work; existing Runner admission, synchronization and closing transactions remain | The same setup/publication/cleanup as native; no execution lease changes                                                                                                                                         |
+| Authorized cross-instance resume                        | One association owner read in addition to facade authorization, no SQL writes/locks                                                                                                              | Preflight ping, producer-key GET, component sentinel GET, subscription and replay request; component sentinel watchdog GET once per 10 seconds and application producer-key GET every 5 seconds while subscribed |
+| Producer lifetime                                       | No SQL polling writes                                                                                                                                                                            | One ID-checked lease renewal every 5 seconds; SSE publication follows actual native chunks or saved Runner blocks                                                                                                |
+| Remote native execution detail/list                     | Existing native row reads, no new SQL locks                                                                                                                                                      | A remote running native producer check adds preflight ping and producer-key GET; local and idle executions avoid these                                                                                           |
+| Remote native Stop                                      | One association owner read; no added SQL write at the requesting instance                                                                                                                        | Preflight ping, producer-key GET and a bound Stop publication; producer performs its existing cancellation/snapshot write                                                                                        |
+| Native independent notification                         | One transaction/lock, owned-row and message-ID reads, one message insert and conversation update plus lock update; an identical retry only updates the lock                                      | None                                                                                                                                                                                                             |
+| Runner history/page                                     | Owner plus bounded seed query; up to one complete-group query and one interval query, no locks/writes                                                                                            | None                                                                                                                                                                                                             |
+| Runner open with a closing marker and no local producer | One saved-Run read; only a terminal Run invokes final sync and the existing association/closing cleanup transactions. Repeated cleared opens avoid this work.                                    | ID-checked association cleanup after confirmed synchronization; never a new execution                                                                                                                            |
+| Runner changed-output poll                              | Existing synchronization and owner reads plus one assistant-source snapshot query only when lastSeq advances                                                                                     | No per-poll write; published stable part IDs suppress repeated snapshots                                                                                                                                         |
+
+The association timing hook reports `ui-stream.association`, including lock acquisition and commit. These are upper bounds from isolated tests, not production throughput measurements. Published verification records contain the actual measured samples and executed checks.
+
+### Multiple approvals in one native step
+
+Each controlled approval response advances the same saved message revision. While any tool in that step remains `approval-requested`, the response ends with the saved waiting state; neither a tool nor the model continues. The last response changes the execution to running and resumes the SDK with all trusted decisions. Concurrent responses can receive a busy conflict and must reconcile and retry the still-pending decision; accepted decisions cannot execute twice. Stop while partially answered denies every unexecuted call, including an approved call that was waiting for other decisions, and preserves already completed effects.
+
+A partial answer uses one approval transaction and conversation lock (lock, message and conversation updates), without the execution-history conversion or continuation snapshot transaction. Shared recovery still uses its existing registration and release associations. Runner automatic finalization adds one saved-Run read only when a closing marker exists without a local producer. Nonterminal checks do not synchronize, write or lock; a terminal check reuses final synchronization and the existing matching-marker cleanup transactions, once per successful closing marker. No claim, heartbeat, execution retry or scheduler path changes.
+
+## Integrated startup and background contracts
+
+The serving host performs native startup correction under the single-instance deployment assumption: the previous execution process has fully exited before its replacement starts. Current-process rows and valid approval waits remain intact. Missing native terminal snapshots become failed standard UI messages; complete saved results remain intact and finish closing. No model or tool is replayed. CLI hosts do not perform startup correction. Shared recovery transports remain optional and unchanged, and their liveness markers never prove execution death. Overlapping startup, execution takeover and new execution leases are outside scope.
+
+Background `run` returns after admission. `get` and `try` observe that already accepted execution, with observer completion after saving and releasing occupancy. `try`'s finite budget ends observation only. `history()` independently returns public `AppUIMessage[]`; neither a visible message nor successful UI conversion establishes structured-result validation or terminal execution state. Background records always have showInChatList=false; normal creation defaults true. HTTP configuration rejects policy overrides and validates declared scope variables. Transactional conversation notices join their existing business unit of work; native realtime history stores validated data parts, while background notices are excluded from model input.

package/docs/workspace-cleanup.md

@@ -0,0 +1,13 @@
+# Workspace cleanup integration
+
+Heartbeats announce `workspaces.decisions: true` alongside the report interval. New runners retain the existing `workspaces` and `remove`/`keep` exchange and additionally report `directories`, including legacy directories without a last run, with a unique `reportId`. Decisions echo the report, directory path, optional last run and last use. A mismatched or duplicate decision is not usable as cleanup authority.
+
+Register optional `SubjectWorkspaces.resolveKeys(conn, keys)` to map application directory keys to subject ids. Return an array per key so ambiguity can be represented rather than choosing an arbitrary match; an ambiguous or unknown key is left undecided. A directory whose last run the application knows is resolved by that run; one without a last run, or whose run is gone, is resolved by its key. Which runner worked on the subject is not checked: once a subject's work is over, its directories go on every runner, so legacy directories nobody recorded a run for do not pile up.
+
+Keep `settled(conn, ids)` to the subject's own status: deleted or unknown subjects must not settle. The framework additionally excludes any subject with a nonterminal run on any runner. `SubjectWorkspaces.commits` is deprecated and no longer read; decisions always carry `commits: []`, which runners released before this rule still require in the protocol and which makes them keep a directory whose pushes they cannot prove.
+
+A directory whose work is over is removed whatever it holds: commits never pushed, tracked changes, submodule commits and untracked files go with it, and the runner logs that it held unpushed work. Only three things keep it: a run holding its lock, a run that used it since it was reported (its last run or last use changed), and a second report, sent before deletion, whose decision no longer says the work is over, such as a reopened subject. A directory whose work goes on, or whose status is unknown, keeps the existing protection: its unpushed work is removed only when a person forces it.
+
+The runner reports its local cleanup result against the prior decision before attempting deletion. The server accepts it only while the prior report id, directory, run, last use and settlement still match. `allowed` means permission to attempt cleanup, never proof that a directory was removed, and `discardsUntracked` there means the directory still held work that was never pushed. A missing directory in a later report is likewise not a deletion receipt. The cleanup reasons `trackedChanges`, `unpushed`, `missingEvidence` and `gitFailed`, and the decision reason `ownershipUnknown`, stay in the protocol for runners and applications released earlier.
+
+Runtime views expose `canSeeMachine` using the existing machine-information permission. Without an explicit true value, clients hide directory diagnostics. The disk summary remains subject to the existing aggregate visibility. Display the report's `measuredAt` and interval, not heartbeat time; offline or expired readings are previous reports, and unknown disk data never implies healthy space. Low disk warnings already flow through the runner collection logger; deployments should verify those service logs are visible.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@nocobase/app-plugin-agents",
   "displayName": "Agents",
   "description": "Agents for NocoBase applications: agents, the model services online agents call, their runs and conversations, and the runners people connect to run them (registration, the long-poll claim, slots, the sweeper, build jobs, and the runner and CLI tarballs the application serves).",
-  "version": "0.1.0-beta.8",
+  "version": "1.0.0-beta.15",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -62,13 +62,17 @@
       "types": "./dist/shared/reports.d.ts",
       "import": "./dist/shared/reports.js"
     },
+    "./shared/online-agent": {
+      "types": "./dist/shared/online-agent.d.ts",
+      "import": "./dist/shared/online-agent.js"
+    },
     "./shared/conversations": {
       "types": "./dist/shared/conversations.d.ts",
       "import": "./dist/shared/conversations.js"
     },
-    "./shared/presets": {
-      "types": "./dist/shared/presets.d.ts",
-      "import": "./dist/shared/presets.js"
+    "./shared/model-catalog": {
+      "types": "./dist/shared/model-catalog.d.ts",
+      "import": "./dist/shared/model-catalog.js"
     },
     "./shared/models": {
       "types": "./dist/shared/models.d.ts",
@@ -114,12 +118,17 @@
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./server/online-agent": {
+      "types": "./dist/server/online/agent/index.d.ts",
+      "import": "./dist/server/online/agent/index.js"
+    }
   },
   "files": [
     "dist",
     "README.md",
     "CHANGELOG.md",
+    "docs",
     "skills"
   ],
   "publishConfig": {
@@ -134,20 +143,27 @@
     "@ai-sdk/moonshotai": "^3.0.62",
     "@ai-sdk/openai": "^4.0.83",
     "@ai-sdk/openai-compatible": "^3.0.62",
-    "ai": "^7.0.127",
+    "@ai-sdk/provider-utils": "5.0.54",
+    "ai": "7.0.128",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "better-sqlite3": "^13.0.3",
     "hono": "^4.13.2",
+    "ioredis": "^5.11.1",
     "knex": "^3.1.0",
     "ollama-ai-provider-v2": "^4.0.1",
     "pg": "^8.23.0",
+    "re2js": "^2.8.6",
+    "resumable-stream": "2.2.13",
     "sqlite-vec": "^0.1.9",
     "yaml": "^2.9.0",
     "zod": "^4.6.5",
-    "@nocobase/agent-protocol": "^0.1.0-beta.5",
-    "@nocobase/app-cli-client": "^0.1.0-beta.4",
-    "@nocobase/cli-envelope": "^0.1.0-beta.1"
+    "@nocobase/agent-protocol": "^0.1.0-beta.10",
+    "@nocobase/cli-envelope": "^0.1.0-beta.1",
+    "@nocobase/app-cli-client": "^0.1.0-beta.10"
   },
   "peerDependencies": {
+    "@ai-sdk/react": "4.0.131",
     "@base-ui/react": "^1.6.0",
     "@oclif/core": "^4.14.0",
     "@tanstack/react-query": "^5.81.5",
@@ -160,15 +176,15 @@
     "react-router": "^7.0.2",
     "recharts": "^3.8.0",
     "remark-gfm": "^4.0.1",
-    "@nocobase/app-cli": "^1.0.0-beta.20",
-    "@nocobase/app-client": "^3.0.0-beta.1",
-    "@nocobase/app-plugin-authentication": "^2.0.0-beta.7",
-    "@nocobase/app-plugin-authorization": "^1.0.0-beta.27",
-    "@nocobase/app-plugin-file": "^1.0.0-beta.23",
-    "@nocobase/app-server": "^2.0.0-beta.4",
-    "@nocobase/authorization": "^1.0.0-beta.13",
-    "@nocobase/db": "^1.0.0-beta.19",
-    "@nocobase/i18n": "^1.0.0-beta.7",
+    "@nocobase/app-cli": "^1.0.0-beta.25",
+    "@nocobase/app-client": "^4.0.0-beta.0",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.11",
+    "@nocobase/app-plugin-authorization": "^1.0.0-beta.29",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.25",
+    "@nocobase/app-server": "^3.0.0-beta.0",
+    "@nocobase/db": "^1.0.0-beta.21",
+    "@nocobase/authorization": "^1.0.0-beta.14",
+    "@nocobase/i18n": "^2.0.0-beta.0",
     "@nocobase/markdown-mermaid": "^0.1.0-beta.2",
     "@nocobase/service-provider": "^0.0.2-beta.2"
   },
@@ -177,22 +193,20 @@
     "@testing-library/user-event": "^14.6.3",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.0",
-    "esbuild": "^0.28.2",
     "eslint": "^10.0.0",
     "jsdom": "^30.0.1",
-    "just-bash": "^3.6.0",
     "prettier": "^3.9.6",
     "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@nocobase/app-testing": "0.1.0-beta.3",
-    "@nocobase/db-postgres": "0.1.0-beta.4",
-    "@nocobase/db-sqlite": "0.1.0-beta.5",
-    "@nocobase/dev-config": "0.1.0-beta.22",
+    "@nocobase/app-testing": "0.1.0-beta.5",
+    "@nocobase/db-postgres": "0.1.0-beta.5",
+    "@nocobase/db-sqlite": "0.1.0-beta.6",
+    "@nocobase/dev-config": "0.1.0-beta.24",
     "@nocobase/jobs": "0.1.0-beta.3"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node ./scripts/bundle-just-bash.mjs && nocobase-db-manifests",
+    "build": "tsc -p tsconfig.json && nocobase-db-manifests",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.type-tests.json --noEmit",
     "test": "vitest run --passWithNoTests",
     "lint": "eslint . --max-warnings 0",

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

@@ -1,20 +1,20 @@
 ---
 name: nocobase-app-plugin-agents
-description: Register the Agents plugin in a NocoBase App and configure it (agents.* in config.yml), contribute subjects, scopes, business actions, presets, CLI commands and reports through agentsToken, set up online agents and model services, connect runners (registration tokens, protocol, upgrade_required), build and serve the CLI and runner tarballs (pnpm nocobase cli build, --runner), or work out why a run, a runner or a model fails.
+description: Register the Agents plugin in a NocoBase App and configure it (agents.* in config.yml), contribute subjects, scopes, business actions, agent defaults, the App's own agents, CLI commands and reports through agentsToken, enable the agents discovered from runners, configure OnlineAgentService and OnlineAgentConfigurator for SDK chats and business tools, set up model services for the App's own model calls, connect runners (registration tokens, protocol, upgrade_required), build and serve the CLI and runner tarballs (pnpm nocobase cli build, --runner), or work out why a run, a runner or a model fails.
 metadata:
   short-description: Agents, runners, model services and their distribution
 ---
 
 # Agents App Plugin
 
-Use this Skill when an App gives people agents to work with: online agents that answer through a model service on the server, or work agents that drive a coding tool (Claude Code, Codex, OpenCode, Pi) on a runner someone connects. Use it as well to build the App's CLI and the runner as tarballs the App serves, and to diagnose a run, a runner or a model that does not work. Do not use it for the business data agents act on; that stays with `nocobase-app-development` and the plugins that own it.
+Use this Skill when an App gives people agents to work with: agents that drive a coding tool (Claude Code, Codex, OpenCode, Pi) on a runner someone connects, one for each tool and model the runners report. Use it as well to build the App's CLI and the runner as tarballs the App serves, and to diagnose a run, a runner or a model that does not work. Do not use it for the business data agents act on; that stays with `nocobase-app-development` and the plugins that own it.
 
 The package README is the full reference: read it at `node_modules/@nocobase/app-plugin-agents/README.md` (in this repository, `packages/plugins/app-plugin-agents/README.md`). The references below say what to do and point to its sections rather than repeating them.
 
 ## Key rules
 
-- The plugin knows no business of its own. Subjects, scopes, business actions, presets, CLI commands and report pages are the App's, contributed through `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` when the App's providers boot. With nothing contributed, agents still work in conversations.
-- An agent's type (`runner` or `online`) is chosen once and never changes. Online agents need a model service and no runner; runner agents need a runner that is online, has the agent's coding tool installed and signed in, and whose owner's local policy lets it take the work.
+- The plugin knows no business of its own. Subjects, scopes, business actions, the instructions and actions every discovered agent gets, CLI commands and report pages are the App's, contributed through `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` when the App's providers boot. With nothing contributed, agents still work in conversations.
+- Nobody creates agents: each coding tool and model a runner reports becomes one, pending until someone who manages agents writes what it is good at and enables it. Only enabled agents get work, and only on a runner that is online, has the agent's tool signed in with its model, and whose owner's local policy lets it take the work. The `agentsToken.onlineAgent` service selects native SDK execution or an explicitly chosen Runner Agent through one realtime conversation contract. Native execution runs registered business tools directly through the SDK; Runner chat uses the existing queue and canonical history. The original chat API and shared browser controller use this service, and never silently change executors. Read [OnlineAgent chats and business tools](references/online-agent.md) to configure that service and its `OnlineAgentConfigurator`.
 - Variables and model service keys are sealed with the App's secrets service: configure `secrets.keys` before storing any, or the API answers `SECRETS_KEY_MISSING` (503).
 - The plugin registers no pages. The App routes the exported pages and mounts the chat; the App also binds `agentsAccessToken`, or every business action level is `none`.
 - `subjects.register`'s `context.assemble`, brief sections and mounts run inside the claim's transaction: database reads only, never a network or a model call. Read anything else in the optional `prepare(run)`.
@@ -23,12 +23,15 @@ The package README is the full reference: read it at `node_modules/@nocobase/app
 
 ## References
 
-| Task                                                                                                                  | Read                                                                               |
-| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Register the plugin, its prerequisites and `agents.*` configuration, mount the pages and the chat                     | [Setup and configuration](references/setup-and-config.md)                          |
-| Contribute subjects, scopes, actions, presets, CLI commands, people, reports, brief sections, mounts                  | [Extension points](references/extension-points.md)                                 |
-| Online agents, model services, the model gateway, consultations, vectors                                              | [Online agents and model services](references/online-agents.md)                    |
-| Register runners, how claims and heartbeats work, local policy, protocol and `upgrade_required`                       | [Runners](references/runners.md)                                                   |
-| Build the CLI and runner tarballs, serve them, CI artifacts, install script, download tokens, updates, the npm runner | [Distribution](references/distribution.md)                                         |
-| Variables and secrets, the skill library, chat attachments, usage, prices and reports                                 | [Variables, skills, attachments and usage](references/variables-skills-usage.md)   |
-| Check that everything works, and diagnose failures                                                                    | [Verification and troubleshooting](references/verification-and-troubleshooting.md) |
+| Task                                                                                                                  | Read                                                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Register the plugin, its prerequisites and `agents.*` configuration, mount the pages and the chat                     | [Setup and configuration](references/setup-and-config.md)                                                                          |
+| Contribute subjects, scopes, actions, agent defaults, the App's own agents, CLI commands, people, reports, mounts     | [Extension points](references/extension-points.md)                                                                                 |
+| Agents discovered from runners, the model catalog, enabling agents, availability, the App's own agents                | [Agents](references/agents.md)                                                                                                     |
+| Configure OnlineAgentService/OnlineAgentConfigurator, register SDK tools, use realtime/background sessions            | [OnlineAgent chats and business tools](references/online-agent.md)                                                                 |
+| Open JSON UI context, custom SDK tool cards, generic form adapters and safe browser-draft application                 | [UI context, tool cards and local form drafts](references/online-agent.md#open-ui-context-custom-tool-cards-and-local-form-drafts) |
+| Model services, the model gateway, vectors                                                                            | [Model services](references/model-services.md)                                                                                     |
+| Register runners, how claims and heartbeats work, local policy, protocol and `upgrade_required`                       | [Runners](references/runners.md)                                                                                                   |
+| Build the CLI and runner tarballs, serve them, CI artifacts, install script, download tokens, updates, the npm runner | [Distribution](references/distribution.md)                                                                                         |
+| Variables and secrets, the skill library, chat attachments, usage, prices and reports                                 | [Variables, skills, attachments and usage](references/variables-skills-usage.md)                                                   |
+| Check that everything works, and diagnose failures                                                                    | [Verification and troubleshooting](references/verification-and-troubleshooting.md)                                                 |

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

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