@nocobase/app-plugin-agents 2.0.0-beta.10 → 2.0.0-beta.12

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

@@ -130,18 +130,18 @@ Use `abort()` for explicit Stop. Native execution waits for terminal persistence
 
 Native `POST /api/agents/conversations/:id/messages` accepts only the current SDK user message (`id`, `role: "user"`, text `parts`) plus authorized attachment IDs, page context and optional selected model. It returns a standard SDK UI message stream. Use a `DefaultChatTransport.prepareSendMessagesRequest` mapper; do not submit browser history or trusted metadata. Tool input/output, assistant/system messages and configuration cannot be supplied as history. Creation starts no model. Detail, list, history, config, attachment and Stop retain ownership checks.
 
-Native realtime sessions can resend or text-edit an existing user message with `chat.resend({ messageId, input: { text } })`; omitted options select the latest saved user. Admission updates that message, permanently deletes its suffix and preserves original files/context. Completed business effects are not undone. Runner refuses this capability and Background does not expose it. Browser UI uses `useResendMessage` and the official SDK regenerate/edit flow, never an automatic retry of unknown admission. See [resend and edit](../../../docs/message-resend.md) for transaction, stream, authorization and recovery contracts.
+Native realtime sessions can resend or text-edit an existing user message with `chat.resend({ messageId, input: { text } })`; omitted options select the latest saved user. Admission updates that message, permanently deletes its suffix and preserves original files/context. Completed business effects are not undone. Runner refuses this capability and Background does not expose it. Browser UI uses `useResendMessage` and the official SDK regenerate/edit flow, never an automatic retry of unknown admission. See resend and edit (`docs/message-resend.md` in the `@nocobase/app-plugin-agents` package) for transaction, stream, authorization and recovery contracts.
 In both native realtime and background modes, `content.original` is the only complete internal UIMessage, with the same ID as its record and raw JSON tool inputs/results, reasoning and provider/approval evidence. Both modes share the same original-message storage and raw tool JSON, not a separate background ModelMessage codec. Public tools require explicit `public.input`/`public.output` projections. All public history reads, including background `history()`, and realtime streams use current projections; current `toModelOutput` rules separately derive internal model input from the original when it is read. Both conversions use detached copies and never execute tools. Missing or failed projections never expose the raw original. No duplicate full message, migration, compatibility fallback or format version is used. SDK `needsApproval` tools require these projections. The approval endpoint accepts only `{ messageId, executionId, approval: { id, approved, reason? } }` and resumes from trusted persisted history. Waiting approvals, denials and outcomes update the same message with increasing metadata revision; use message revision notifications and `GET messages?ids=...` to reread changes. Approval retains its owner/execution/message binding and does not bypass active execution occupancy. Background structured execution stays separate.
 
 Native public history and realtime streams include actual model-provided SDK reasoning, including previously saved parts. Expose only `type`/`text`/optional `state` in history and the SDK routing fields (`type`, `id`, and `delta` for reasoning deltas) in the stream; never expose provider metadata or signatures. Installed Registry/Examples render nonempty parts in order with sanitized Markdown, automatically open only the active streaming part and otherwise collapse by default. A user's manual choice wins for that mounted message/part across incremental updates, part end and history revisions. Reasoning counts as visible output, but does not become answer text, a search/copy value or an execution outcome. Models and Runner responses without genuine reasoning remain ordinary text-only chat.
 
-Native and Runner realtime receive use the standard SDK stream with optional shared Redis recovery. Background sessions have no browser receive transport and do not require Redis. Browser disconnect never cancels generation. Finish ends the HTTP response, possibly while waiting for approval; execution detail and saved history determine business state. Failed persistence keeps occupancy and supports explicit finalization without reexecution. Missing streams require history/status reconciliation, never automatic resend. A lost producer remains interrupted and is not automatically restarted. The public ChatProvider and installed Registry/Examples consumers use SDK Chat ownership and GET recovery. See [UI messages](../../../docs/ui-messages.md) and [client coordination](../../../docs/ui-message-clients.md) for configuration, costs and limits.
+Native and Runner realtime receive use the standard SDK stream with optional shared Redis recovery. Background sessions have no browser receive transport and do not require Redis. Browser disconnect never cancels generation. Finish ends the HTTP response, possibly while waiting for approval; execution detail and saved history determine business state. Failed persistence keeps occupancy and supports explicit finalization without reexecution. Missing streams require history/status reconciliation, never automatic resend. A lost producer remains interrupted and is not automatically restarted. The public ChatProvider and installed Registry/Examples consumers use SDK Chat ownership and GET recovery. See UI messages (`docs/ui-messages.md` in the `@nocobase/app-plugin-agents` package) and client coordination (`docs/ui-message-clients.md` in the `@nocobase/app-plugin-agents` package) for configuration, costs and limits.
 
-Permission-restricted configuration and custom permission/approval protocols remain unsupported. New native sessions enable bash and skill by default; scopes may select Skills or explicitly replace the tool list; follow [Native Skills and application CLI](../../../docs/native-sandbox.md) for current support trees, VFS-only inputs, lazy `context.execution`, existing business authorization and approval/new-environment boundaries. SDK approval is native-only; Runner remote tool approval is refused. Verify with isolated model fixtures and authorized application services, never real business writes.
+Permission-restricted configuration and custom permission/approval protocols remain unsupported. New native sessions enable bash and skill by default; scopes may select Skills or explicitly replace the tool list; follow Native Skills and application CLI (`docs/native-sandbox.md` in the `@nocobase/app-plugin-agents` package) for current support trees, VFS-only inputs, lazy `context.execution`, existing business authorization and approval/new-environment boundaries. SDK approval is native-only; Runner remote tool approval is refused. Verify with isolated model fixtures and authorized application services, never real business writes.
 
 ## Open UI context, custom tool cards and local form drafts
 
-Use the public `@nocobase/app-plugin-agents/client/chat` exports for these capabilities; the full contracts and integrated application wiring are in [UI context, tool cards and AI form adapters](../../../docs/ai-forms.md). The plugin supplies infrastructure only. Applications own tool names/schemas, fields, permissions, proposal cards and browser adapters. The Examples application's `examples_form_proposal`, `examples-form-fill` scope and `/ai-form-fill` page are application demonstrations, not plugin defaults or APIs to import into another application.
+Use the public `@nocobase/app-plugin-agents/client/chat` exports for these capabilities; the full contracts and integrated application wiring are in UI context, tool cards and AI form adapters (`docs/ai-forms.md` in the `@nocobase/app-plugin-agents` package). The plugin supplies infrastructure only. Applications own tool names/schemas, fields, permissions, proposal cards and browser adapters. The Examples application's `examples_form_proposal`, `examples-form-fill` scope and `/ai-form-fill` page are application demonstrations, not plugin defaults or APIs to import into another application.
 
 `PageContext.ui = { version: 1, items: [...] }` is open JSON data: every `PageUIItem` has required `kind`/`id` and arbitrary accepted `AppUIJson` fields, including unknown kinds and nested values. This is separate from server-resolved/authorized `context.items`. UI items grant no server record access or tool permission and enter Native/Runner model context as explicitly untrusted data, never instructions. Accepted fields survive public user metadata, saved history and recovery. Budgets in `PAGE_UI_CONTEXT_LIMITS` reject non-JSON, dangerous keys, duplicate identities and oversized snapshots without truncation; applications must minimize data and exclude secrets.
 
@@ -211,13 +211,13 @@ Resolvers remain responsible for business authorization and their own database r
 
 Native and Runner realtime history is `AppUIMessage[]`, and HTTP input for both is the current `{ message: { id, role: "user", parts }, attachmentIds?, context?, selectedModel? }`. Responses use the SDK UI message stream, not the old block events. Runner assistant ID is `runner:<runId>`; `metadata.sourceRecords` retains real saved record IDs, source sequences and stable part IDs/indices. Display segments must interleave independent notifications by source sequence without duplicating the logical assistant message. Registry and application consumers use `chatMessageSegments` to retain that source ordering. Forward history readers must drain `meta.nextAfter` before advancing to the conversation watermark.
 
-For multiple instances configure `agents.uiRecovery: { namespace, redis: { host, port, ... } }` with an application-specific namespace and a shared Redis deployment. The plugin owns the connections. `DefaultChatTransport.prepareReconnectToStreamRequest` points to `/api/agents/conversations/:id/events`. Without configuration there is one live response and history only, reported as `x-online-agent-recovery: live`; configured failures never fall back. Replay requires the live producer: process death does not restart inference, tools or Runner work. Stop remains a separate authenticated action and can signal a live native producer on another instance; read execution and saved history until termination is confirmed. Approval waiting and a missing stream are not business success. See [UI messages and recovery](../../../docs/ui-messages.md) for identity, lifecycle, limits, costs and validation boundaries.
+For multiple instances configure `agents.uiRecovery: { namespace, redis: { host, port, ... } }` with an application-specific namespace and a shared Redis deployment. The plugin owns the connections. `DefaultChatTransport.prepareReconnectToStreamRequest` points to `/api/agents/conversations/:id/events`. Without configuration there is one live response and history only, reported as `x-online-agent-recovery: live`; configured failures never fall back. Replay requires the live producer: process death does not restart inference, tools or Runner work. Stop remains a separate authenticated action and can signal a live native producer on another instance; read execution and saved history until termination is confirmed. Approval waiting and a missing stream are not business success. See UI messages and recovery (`docs/ui-messages.md` in the `@nocobase/app-plugin-agents` package) for identity, lifecycle, limits, costs and validation boundaries.
 
 Existing system notices are delivered through `ConversationService.deliver()` in the caller's business transaction. OnlineAgent bindings persist them without starting another execution, unless a Runner binding's news passes `wake: true`, and rollback removes them with the business changes. Native notices use standard public data parts and remain readable after a response closes. Independent application timeline content should use the authorized business subscription and rendering extensions; OnlineAgent has no separate notification-injection API.
 
 ## Public UI messages
 
-Browser consumers use the SDK-owned `AppUIMessage` and `ChatProvider` from `client/chat`. Render ordered parts and use `chatMessageSegments` to preserve Runner source ordering around independent notifications. The public extension hooks receive the complete SDK message, and approval uses only a bound server-validated control. Follow [the client contract](../../../docs/ui-message-clients.md) for identity lifetimes, unknown admission, revision rereads, durable notification polling and independent Stop. A standard response finish or a missing recovery stream never implies saved business completion.
+Browser consumers use the SDK-owned `AppUIMessage` and `ChatProvider` from `client/chat`. Render ordered parts and use `chatMessageSegments` to preserve Runner source ordering around independent notifications. The public extension hooks receive the complete SDK message, and approval uses only a bound server-validated control. Follow the client contract (`docs/ui-message-clients.md` in the `@nocobase/app-plugin-agents` package) for identity lifetimes, unknown admission, revision rereads, durable notification polling and independent Stop. A standard response finish or a missing recovery stream never implies saved business completion.
 
 ## Single-instance startup and visibility