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

package/docs/ui-message-clients.md

@@ -0,0 +1,80 @@
+# UI message clients
+
+The public client entry is `@nocobase/app-plugin-agents/client/chat`. `ChatProvider` owns one `@ai-sdk/react` Chat per conversation. Sidebar, full-page and home surfaces share that owner. The SDK owns messages, ordered parts, streaming status, response parsing, approval updates and resumption. The application coordinator owns history page metadata, unknown submissions, admission reconciliation, identity disposal and business Stop.
+
+Mount a single provider inside the application's router and key its lifetime by authenticated identity. Dispose the old identity before mounting the next, clear the unscoped panel storage and chat query cache, and discard retained application callbacks. Examples implements this in `OnlineAgentProvider`; it preserves drafts across surface changes within the same identity. A request finishing after disposal cannot publish messages, navigate an abandoned editor, update another account's cache or invoke retained Undo.
+
+## Input, admission and recovery
+
+The SDK transport uses the host's authenticated `ApiClient.stream`. A POST contains only the current `message: { id, role: "user", parts: [{ type: "text", text }] }`, authorized attachment IDs and optional page context. It never sends the SDK's complete browser history, assistant parts or tool output as input. Uploaded files remain the existing attachment service's responsibility.
+
+The response headers acknowledge admission; the coordinator then reads canonical history and conversation detail. Pending controls remain until the stable user ID, or Runner's `metadata.clientId`, is found in saved history. An unknown POST result is reconciled without automatic resend. Explicit creation recovery still warns that a conversation may already have been created.
+
+Initial recovery starts only for a known running, non-approval-waiting conversation. GET recovery uses the SDK transport's reconnect entry, including on browser online/realtime reconnection. Manual recovery never POSTs user input. The shared component replays a response's full prefix. After a network error, the coordinator retires the SDK owner that retained delta-resume state and publishes one fresh shared owner using public UIMessage state. Pending tool state is reread from trusted history before replay; a missing stream retains the interrupted display and occupancy. No SDK private fields or custom stream parser are used. A missing/expired stream or a disabled shared recovery facility leaves durable history and execution detail authoritative. An SDK `ready`, EOF, `onFinish` or standard `finish` cannot mark business execution complete. Approval waiting remains occupied.
+
+Stop uses the independent business endpoint. It remains stopping until trusted detail confirms idle. Disposing a subscriber only stops its SDK reader. A lost reader may be released after its matching saved assistant message and terminal execution have been read; that reconciliation never stops business execution or repeats input/tools. Save failure keeps occupancy and exposes explicit finalization retry with visible failure feedback.
+
+## History and source segments
+
+An aborted SDK text part can retain `state: "streaming"` in saved history. A writing cursor therefore also requires the message to own the current active SDK response. Registry and Examples pass that presentation flag only to the active response at the SDK working array's tail; saved partial replies stay still after Stop, refresh and later turns. This presentation flag does not establish business completion.
+
+History APIs return `AppUIMessage[]`. During a live response the SDK working array keeps its active assistant last so subsequent SDK chunks update it in place. Independent notices remain in that same owner; source metadata determines their displayed position. Approval and recovery select the same response target, and the scroll anchor follows the first displayed source segment. Merge by message ID and monotonic `metadata.revision`; preserve an actively streaming SDK assistant against stale history snapshots. A canonical user replaces its optimistic counterpart by ID or client ID. Drain every `nextAfter` page before advancing the forward watermark. Revision events reread exact IDs in batches of at most 100 and never advance that watermark. Failed revision reads retain the requested IDs for later durable polls or repeated announcements until the requested revision is acknowledged.
+
+`chatMessageSegments(messages)` creates rendering descriptors referencing the original SDK object. It does not create additional logical messages. Each Runner source record carries its actual sequence, creation time, source record ID and stable part ID in `metadata.sourceRecords`. Render the descriptor's part indexes at its source time; independent notifications retain their own identity between source blocks. A complete logical message remains intact in history pagination. Render `renderMessageExtra` once, on the final segment.
+
+The shared presentation omits empty text, SDK step/reasoning bookkeeping, and only the framework's `execution-status` success notice; the original SDK messages and their durable execution outcomes remain unchanged. Thinking is shown at the next response position rather than as an empty assistant bubble. Successful turns add no generic completion banner, while failure, cancellation, approval and uncertain-effect feedback remain available. An application's `renderMessageExtra` still renders once even when the message has no visible standard parts. The Registry transcript scrolls vertically; long code blocks and tables keep their bounded, local scrolling rather than widening the conversation.
+
+Native messages generally have one segment. The server places the authorized display snapshot in `metadata.context`, stripping provider-private fields. Input context remains IDs-only and is reauthorized on the server. File parts use their authorized URL and media type; the installed attachment list retains image previews without inventing a size the SDK file part does not contain.
+
+## Extensions
+
+`ChatExtensionsContext` accepts UIMessage directly. Existing application business components adapt to these public boundaries:
+
+| Extension                                    | Input and behavior                                                                                                                                                                                                                                                            |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useTimelineItems(conversationId, revision)` | Stable-key business items sorted by time among source segments; the hook may query authorized application data. Message insertions, revisions and business occupancy update its revision input. Application business subscriptions may refresh its own queries independently. |
+| `renderMessageExtra(message)`                | The complete original UIMessage once per logical message. Extract all text with `appUIMessageText`; reference discovery, code exclusion, deduplication and record permissions remain application responsibilities.                                                            |
+| `renderNews(notice, message)`                | Independent `data-notice` card. Returning null falls back to `newsText`, then the persisted title.                                                                                                                                                                            |
+| `newsText(notice, t)`                        | Localized wording, or null for the persisted title.                                                                                                                                                                                                                           |
+| `renderDataPart(part, message)`              | Ordered public `data-notice` or `data-business` display. Null retains the built-in display, including the ConsultationCard for a genuine consultation payload.                                                                                                                |
+
+Independent system notifications are persisted through the existing `ConversationService.deliver()` business transaction, then read through business announcements or durable polling. They do not write into a finished model response or wake a new OnlineAgent execution. There is no separate `OnlineAgentService.notify()` entry. These display contracts do not restore a historical Studio plan/delegation producer or the deleted ask_agent chain.
+
+`Composer` exposes `toolbar` and `notice` as child component props. The installed view uses them for application actions and notices; they are not generic top-level ChatPanel slots. Preserve application-owned headers, avatars, menus and readiness/error handling when updating installed Registry source.
+
+Tool approval buttons use genuine SDK approval parts, binding `messageId`, `executionId` and `approval.id` to the server's pending call. SDK approval updates are followed by a controlled approval POST and canonical reread. They never submit browser tool output. Runner does not gain remote tool approval support. Effect-review hints are advisory after actual tool termination and finalization; pending approvals still enforce their owner, execution, message and tool-call bindings.
+
+## Requests and cost
+
+A visible conversation has one shared durable-history poll, regardless of surfaces: every 5 seconds while running, every 30 seconds while idle, and none while the document is hidden or after the last surface unmounts. This provides independent-notification catch-up when instance-local announcements are missed. Running conversation detail retains the existing 5-second React Query polling; shared keys deduplicate in-flight reads, while staggered observers can each refetch. The SDK stream removes the old one-second text-growth polling.
+
+A forward history poll makes one GET plus each bounded `nextAfter` continuation. Recovery of an interrupted pending tool can add one ID GET before its GET stream. A revision announcement makes one batched ID GET; duplicate revision announcements from multiple surfaces are coalesced. Successful input admission adds history reconciliation and a detail GET; SDK completion/recovery adds detail, forward history and an ID reread for a revisable assistant. A stalled subscription may require a second completion reconciliation after its SDK reader stops. None of these reads creates SQL writes, locks or transactions. Source creation timestamps and public context are derived in the existing projection/snapshot write; no new storage write is introduced.
+
+Measured warm read requests, excluding the host's authentication and authorization queries, are shown below. The native fixture has one completed reply; the Runner fixture has two saved source blocks and an interleaved notification. These counts describe the extra requests a client makes, not new SQL added inside an existing endpoint. Every sample has zero writes, transactions and explicit locks.
+
+| Request                          | Native SELECTs | Runner SELECTs |
+| -------------------------------- | -------------: | -------------: |
+| Full history                     |              3 |              6 |
+| Forward poll with no new row     |              3 |              4 |
+| One logical message reread by ID |              3 |              5 |
+| Saved execution detail           |              2 |              6 |
+
+Thus an added idle forward poll costs three native or four Runner SELECTs per visible conversation every 30 seconds in these fixtures. Opening a page, reading a changed group or following pagination adds its corresponding read requests. Batched IDs and larger source groups change row counts and execution time; the table is not a production latency estimate. Existing approval, input, Stop and finalization mutations retain their server-side costs; the SDK coordinator does not add another mutation or lock around them.
+
+The server's existing native, notification and shared Redis costs remain those in [UI messages](./ui-messages.md#shared-recovery-request-cost). Runner claims, heartbeats, execution scheduling, synchronization, lifecycle and machine writes are unchanged.
+
+## CLI input
+
+The public command uses the same current-message body, without legacy `content/clientId` request mapping. Put the entire JSON body in a file:
+
+```json
+{
+  "message": {
+    "id": "new-client-uuid",
+    "role": "user",
+    "parts": [{ "type": "text", "text": "Review the checklist" }]
+  }
+}
+```
+
+Run `conversation message send <conversation> --file current-user-message.json`, optionally with repeatable `--attach`. Use a new ID for a new input. An unknown outcome requires history/state reconciliation; do not blindly repeat the command. Its response is the standard UI stream, not the former JSON send envelope. The history command's columns read SDK `metadata.seq`, `role`, `parts` and `metadata.createdAt` directly.

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.9",
+  "version": "1.0.0-beta.16",
   "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.6",
-    "@nocobase/app-cli-client": "^0.1.0-beta.5",
+    "@nocobase/agent-protocol": "^0.1.0-beta.10",
+    "@nocobase/app-cli-client": "^0.1.0-beta.11",
     "@nocobase/cli-envelope": "^0.1.0-beta.1"
   },
   "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,39 +176,37 @@
     "react-router": "^7.0.2",
     "recharts": "^3.8.0",
     "remark-gfm": "^4.0.1",
-    "@nocobase/app-cli": "^1.0.0-beta.20",
-    "@nocobase/app-plugin-authentication": "^2.0.0-beta.7",
-    "@nocobase/app-client": "^3.0.0-beta.1",
-    "@nocobase/app-plugin-authorization": "^1.0.0-beta.27",
-    "@nocobase/app-plugin-file": "^1.0.0-beta.23",
-    "@nocobase/authorization": "^1.0.0-beta.13",
-    "@nocobase/app-server": "^2.0.0-beta.4",
-    "@nocobase/db": "^1.0.0-beta.19",
-    "@nocobase/i18n": "^1.0.0-beta.7",
-    "@nocobase/service-provider": "^0.0.2-beta.2",
-    "@nocobase/markdown-mermaid": "^0.1.0-beta.2"
+    "@nocobase/app-cli": "^1.0.0-beta.25",
+    "@nocobase/app-client": "^4.0.0-beta.0",
+    "@nocobase/app-plugin-authentication": "^2.0.0-beta.12",
+    "@nocobase/app-plugin-authorization": "^1.0.0-beta.30",
+    "@nocobase/app-plugin-file": "^1.0.0-beta.26",
+    "@nocobase/app-server": "^3.0.0-beta.0",
+    "@nocobase/authorization": "^1.0.0-beta.15",
+    "@nocobase/db": "^1.0.0-beta.21",
+    "@nocobase/i18n": "^2.0.0-beta.1",
+    "@nocobase/markdown-mermaid": "^0.1.0-beta.2",
+    "@nocobase/service-provider": "^0.0.2-beta.2"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.3",
     "@types/node": "^24.0.0",
     "@types/react": "^19.2.0",
-    "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)                                                 |