@nocobase/app-plugin-agents 1.0.0-beta.20 → 1.0.0-beta.22

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

@@ -1,6 +1,6 @@
 ---
 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, 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.
+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, business tools and native web search, 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
 ---
@@ -13,10 +13,16 @@ The package README is the full reference: read it at `node_modules/@nocobase/app
 
 ## Key rules
 
-- Runner tool selection is server-owned and explicit. New registrations default to Codex and Claude Code; additional catalog tools must be selected. Native adapters take precedence over ACP. Owners manage personal tools, and runner managers may also manage team tools. Unknown tools and custom launch commands are not supported. See the README’s “Selecting runner tools and ACP agents” for protocol upgrades, detection triggers and default-model behavior.
+- Runner tool selection is server-owned and explicit. New registrations default to Codex and Claude Code; additional catalog tools must be selected. Native adapters take precedence over ACP. Owners manage personal tools, and runner managers may also manage shared tools. Unknown tools and custom launch commands are not supported. See the README’s “Selecting runner tools and ACP agents” for protocol upgrades, detection triggers and default-model behavior.
 
 - 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`.
+- Native files follow legacy Provider defaults: OpenAI/Anthropic/Google/OpenAI-compatible forward PDFs and images, Alibaba forwards images and extracts document text locally, and Moonshot forwards images and uploads supported documents to its selected Kimi Files service automatically. Ollama images remain native; PDF and other supported documents use local text extraction by default, not failure-triggered fallback. DeepSeek/Cohere retain local document extraction and do not forward undeclared images; existing exact profiles still override defaults. Read the package README's **Native document inputs** before configuring exact service/model/Provider/protocol/base URL overrides. Never promote extracted content above the user role, or silently change routes after failure.
+- Unsupported user attachments must not terminate the conversation: replace only the model replay file part with an untrusted filename/MIME/controlled-limitation description, explicitly stating that the contents were not parsed. Apply the same policy to historical follow-up and explicit extractor `unsupported` results; never forward unsupported bytes, guess contents, persist the description as an original message or cache it as extracted text. Keep authorization, inline validation, format-mismatch, budget, cancellation and actual parsing/Provider failures unchanged.
+- Local DOCX text extraction omits embedded binary images before budgeting; it does not perform OCR. Image-only documents fail as unreadable. Do not raise text limits to accommodate base64 image data or change Knowledge's default image representation.
+- File preparation failures expose only controlled reason codes in execution-status notice params, with fixed fallback titles and viewer-localized wording. Keep parser/Provider errors and credentials private; never infer a historical failure reason from current model configuration or turn Stop into a failure.
+- Local document cache hits still reauthorize and read current bytes; cache keys isolate users, sources and extractor instances. Historical/native/reference inputs count toward execution budgets; declare a verified lower native count through profile `maxNativeFiles` when the Provider requires it. Model changes and approvals rebuild replay copies from originals. Stop waits for file-stream cancellation and Worker termination; retryFinalization does not repeat extraction or tools.
+- Kimi Files extraction is automatic for Moonshot; OpenAI-compatible services require an exact remote profile. An exact local profile opts out for a Moonshot model. Use the selected service's saved API key and bound endpoint, never a model-name heuristic, environment-key fallback or second service. Native support skips upload; remote results are execution-only. Upload/content have one five-minute deadline, while DELETE has an independent five-second cleanup window awaited by Stop/shutdown. Lost upload IDs and failed DELETE can leave remote objects; log only sanitized diagnostics. Read the README's **Kimi extraction and exact overrides** section.
 - Native Skills and bash are opt-in server scope capabilities, not a Runner or default global tool set. Read [Native Skills and application CLI](../../docs/native-sandbox.md) before enabling them. Use `context.execution` only inside the current tool invocation, forward `context.signal`, and never retry unknown writes or restore approval-time `/tmp`.
 - 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`.
@@ -32,6 +38,7 @@ The package README is the full reference: read it at `node_modules/@nocobase/app
 | 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)                                                                 |
+| Enable native web search, verify platform admission, isolation, budgets and Registry upgrades                         | `node_modules/@nocobase/app-plugin-agents/docs/native-web-search.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)                                                                                                   |

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

@@ -29,7 +29,7 @@ Rules that are easy to miss:
 - `context.assemble`, brief sections and mounts run inside the claim's transaction and read the database through the claim's connection only (on SQLite it is the only connection). Read anything else in the provider's optional `prepare(run)`, which runs before the transaction. A throw leaves the run queued; three failures fail it `setupFailed`.
 - `runs.enqueue` takes an optional outer transaction; inside another plugin's transaction, publish the collected events after it commits.
 - When someone answers for the subject, pass `responsibleUserId` and the source (`requestedByUserId`, or `causedByRunId` for what a run did). Work another person causes then answers `outcome: 'pending'`: a run request only the responsible confirms (`runs.requests`, `/api/agents/runRequests`), unless `execution: 'mine'` runs it as the asker, which is refused with `NO_RUNNER_AVAILABLE` when no online runner would take the asker's work (`eligibility.canClaim` with the agent's variables). Both people must have agent access; identical pending snapshots are reused without renewing expiry. For mutable responsibility, bind `subjects.register({ …, responsibleUserId: (conn, subjectId) => … })` to read the current responsible using the supplied transaction connection, so old owners cannot confirm or reject before reassignment. Call `runs.requests.reassign` with each responsibility change; without a resolver this is the only protection against stale confirmation. If there is no usable new responsible, reassignment expires and notifies instead of dropping the work, preserving `runAsMe`. Forward `runRequest.*` events and `run_request_expired` notices to the App's inbox, and handle `outcome` before using a possibly null `runId`.
-- To tell a person before queuing whether a runner would take their work, call `eligibility.canClaim` (online now) or `mayQueue` (some registered runner could) with the subject's variable scopes; a variable marked `teamRunnersOnly` needs a team runner. Enqueue itself does not refuse work run as the responsible or as whoever woke the agent: such work waits with `secretsNotAllowed`.
+- To tell a person before queuing whether a runner would take their work, call `eligibility.canClaim` (online now) or `mayQueue` (some registered runner could) with the subject's variable scopes; a variable marked `teamRunnersOnly` needs a shared runner. Enqueue itself does not refuse work run as the responsible or as whoever woke the agent: such work waits with `secretsNotAllowed`.
 - Forward `notice` / `notice.cleared` using the exported `AgentsNotice` interface. Dispatch by its `type`: runner notices go to the runner's owner, `run_secrets_not_allowed` to the run's actor and owner, and `run_request_expired` to the requester. Subjects are of kind `runner`, `run` or `runRequest`. A secrets notice names the run, the agent and the team-only variables in its parameters. Deduplicate by the notice key. Existing copied queue components must merge the `secretsNotAllowed` type and label from the Registry.
 - A repository provider minting credentials in `prepare` implements idempotent `discard(run, prepared)` to revoke undelivered credentials. The plugin calls it outside the transaction on a skipped or rolled-back claim; the App implements the code host revocation API.
 - Name commands in a brief with `commandRef(cli, id, flag?)` rather than spelling them.

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

@@ -8,7 +8,7 @@ Use `OnlineAgentService` for SDK conversations that call application services an
 
 Import the original `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` and resolve `agentsToken.onlineAgent` in an application provider after the plugin has registered. Do not construct a second service for an HTTP entry or user: the application instance coordinates busy, stop and finalization across all facades. `OnlineAgentService` and `OnlineAgentConfigurator` are exported from `@nocobase/app-plugin-agents/server` and `@nocobase/app-plugin-agents/server/online-agent`; the latter also exports the prefixed configuration, tool and stream contracts.
 
-Application dependencies and function parameters use the complete `OnlineAgentService` type. Resolve the shared instance through `agentsToken`; do not introduce another service interface or a method-only type projection. `OnlineAgent` is the common public session interface, with `history(): Promise<AppUIMessage[]>`, session identity, status, cancellation and finalization. `RealtimeOnlineAgent extends OnlineAgent` adds `send`, `receive`, `backend`, required `approve` and `messages`; `BackgroundOnlineAgent extends OnlineAgent` adds `run`, `get` and `try`, without `send` or browser `receive`. The service's `realtime()` and `background()` factories return the corresponding interfaces, implemented by the actual session classes rather than inline facade objects.
+Application dependencies and function parameters use the complete `OnlineAgentService` type. Resolve the shared instance through `agentsToken`; do not introduce another service interface or a method-only type projection. `OnlineAgent` is the common public session interface, with `history(): Promise<AppUIMessage[]>`, session identity, status, cancellation and finalization. `RealtimeOnlineAgent extends OnlineAgent` adds `send`, `receive`, `backend`, required `approve`, `resend` and `messages`; `BackgroundOnlineAgent extends OnlineAgent` adds `run`, `get` and `try`, without `send` or browser `receive`. The service's `realtime()` and `background()` factories return the corresponding interfaces, implemented by the actual session classes rather than inline facade objects.
 
 `onlineAgent.configurator` is the `OnlineAgentConfigurator` (the configuration component). Register global layers, named business scopes and versioned tools once at application boot. It resolves prompts, variables, model lists and tool sets; a Scope selects ordinary configuration and grants no business permission.
 
@@ -62,6 +62,13 @@ Replace `billing-models/chat` with an enabled chat model in the application's ex
 
 Layers resolve in order: global registrations, selected named scopes, then explicit options. Providers run sequentially; omitted fields keep their preceding value and arrays replace it, including empty arrays. Prompt functions can compose `context.systemPrompt` and validate variables. The resolved serializable snapshot is saved. Loading an existing session restores it without reevaluating Providers. Idle explicit overrides reevaluate only the named sources requested; running configuration is frozen. `selectedModel` explicitly selects the existing model columns, while a model-list replacement selects its first entry. A prompt-only override retains the selected model.
 
+## Native web search
+
+`webSearch` is an opt-in ordinary native tool selected through the existing configuration layers, effective-tool snapshot and idle configuration update. The server derives model capabilities, freezes the same main model for isolated retrieval, and rejects unsupported explicit enabling. Do not register a business tool with that reserved name or replace main conversation tools with provider-hosted search tools. Read `node_modules/@nocobase/app-plugin-agents/docs/native-web-search.md` for the provider-level admission and model compatibility, reasoning-off settings, cancellation and execution budgets, safe sources, Registry release gate and offline-versus-live verification boundary. Compatible/custom endpoints and providers without a search adapter remain unsupported; do not improvise a fallback.
+
+The four provider adapters share a retrieval-only prompt: return concise facts and specific gaps for the main model, not a final answer or generic website recommendations. The main tool description batches non-overlapping queries and discourages similar repeats. Source records remain provider-evidence-derived, never reconstructed from prose; reference dates and locations are not automatically injected into the child.
+Alibaba is admitted by platform through its existing Chat Completions SDK and an instance-scoped fetch that sets enable_search=true and search_options.forced_search=true only for the isolated search child. Unlike the other three adapters, it may return source-free text as status=unverified with an empty sources list. Disclose that search execution and freshness cannot be verified; never fabricate citations, classify it as verified success, or silently fall back to another model/protocol. Empty answers and provider errors still fail. The shared model/public projection and installed card preserve this distinction.
+
 ## Use a realtime session or a background result
 
 Construct `OnlineAgentContext` from the authenticated user and full trusted entry identity, never from browser JSON. The authorization principal must match `user.id`. Business references are untrusted input and still require authorization in tools.
@@ -121,6 +128,7 @@ 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.
 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.

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

@@ -12,7 +12,7 @@ A runner (shown as a runtime) is `nocobase-runner` from `@nocobase/agent-runner`
 
 A runner registers once per App with a one-time registration token (10 minutes):
 
-- On the web: Runtimes page, "Add runtime". It asks who the runner works for (personal, or team for who manages `agents.runners`), which coding tools it may run and its maximum concurrent runs, then shows the one-line install and the register command with a fresh token, and waits for the runner to connect.
+- On the web: Runtimes page, "Add runtime". It asks the usage scope (personal, or shared for someone who manages `agents.runners`), which coding tools it may run and its maximum concurrent runs, then offers Prompt and Manual installation for macOS, Linux and Windows (WSL Ubuntu), with a fresh one-time registration token, and waits for the runner to connect.
 - Through the API: `POST /api/agents/runners/registrationTokens` (CLI: `runtime token create`).
 - From the App's checkout or deployment: `pnpm nocobase agents runner-token --trust team` or `--trust ownerOnly --owner <user id>`, optionally `--tools claude,codex`. It prints the token (`--json` for the envelope).
 
@@ -24,7 +24,11 @@ Registering again with the same owner, name and hostname revokes previous regist
 
 The install script requires an explicit `--server <App URL>` with `--runner` and rejects a missing or empty value before downloading or installing anything. CLI-only installation still defaults to the application that served the script.
 
-A runner authenticates afterwards with its own key. Personal runners (`ownerOnly`) run only work their owner started, and receive its variables like any runner, except those marked "Team runtimes only" (`teamRunnersOnly`): a run that gets one goes to a team runner. Their owner may share them with the team. `nocobase-runner unregister --server <url>` or "Revoke" on the Runtimes page ends a registration.
+A runner authenticates afterwards with its own key. Personal runners (`ownerOnly`) run only work their owner started, and receive its variables like any runner, except those marked "Shared runtimes only" (`teamRunnersOnly`): a run that gets one goes to a shared runner. Their owner may share them with all users. `nocobase-runner unregister --server <url>` or "Revoke" on the Runtimes page ends a registration.
+
+The Prompt option asks the host’s agent to check Node.js 24 and signed-in coding tools, use the one-time command to register and install the background service, resolve service PATH, proxy and npm global-permission issues without snap packages, and confirm the connection with `nocobase-runner status`. The Windows prompt first asks the agent to check that it is inside WSL Ubuntu. Otherwise it must stop and tell the user to run `wsl --install` in PowerShell, restart Windows, reopen the agent inside WSL Ubuntu and run the prompt again; only inside WSL may it continue. Install Node.js and the coding tools there too, and enable mirrored networking if WSL cannot reach the internet. Manual installation shows one command on macOS/Linux, or the PowerShell step followed by that same Linux command in Ubuntu on Windows.
+
+Personal (`ownerOnly`) and shared (`team`) both need a VM or isolated environment: agents have full access and the runner is not a sandbox. If no coding tools are found, run `nocobase-runner service install` again from a terminal where `which codex` / `which claude` works, then restart the service (or rerun `nocobase-runner start`) to capture PATH.
 
 ## How work reaches a runner
 
@@ -59,4 +63,4 @@ For application-owned system agents, `useAgentOption(id)` in the client kit read
 
 ## Online capacity
 
-Each application's heartbeat supplies complete total and tool slots; updated runners count only that application's tasks and build jobs. Change capacity on the Runtimes page or the application's online CLI, never with local register/start flags. New registrations default to four slots. Old servers without this heartbeat field use legacy local values temporarily; status labels that source. No local values are uploaded. A configuration change wakes waiting claims and adds one confirmation heartbeat; shrinking never kills existing leases. Custom application projections and installed page copies must forward reportedSlots, capacitySource, capacityReportedAt and toolLoad, and show pending sync or last-report time. See the package README's effective runner slots section.
+Each application's heartbeat supplies complete total and tool slots; updated runners count only that application's tasks and build jobs. Change capacity on the Runtimes page or the application's online CLI, never with local register/start flags. New registrations default to three slots. Old servers without this heartbeat field use legacy local values temporarily; status labels that source. No local values are uploaded. A configuration change wakes waiting claims and adds one confirmation heartbeat; shrinking never kills existing leases. Custom application projections and installed page copies must forward reportedSlots, capacitySource, capacityReportedAt and toolLoad, and show pending sync or last-report time. See the package README's effective runner slots section.