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

package/docs/runner-agents.md

@@ -1,18 +1,18 @@
 # Agents discovered from runners
 
-Each runner reports the coding tools it has, and for each tool whether it is signed in and the models its account lists (`tools[].models`). In the transaction of that report, `AgentService.syncRunner` keeps one agent for each tool and model the runner reports for a tool it has enabled, installed and signed in (`reportedModels` in `shared/runners.ts`): a combination no agent exists for yet becomes a new agent, `pending`, and the agents the runner still reports get their `lastReportedAt` refreshed, at most every ten minutes. The agent's id is `runnerAgentId(tool, model)`, so two runners reporting the same combination keep one agent.
+Each runner reports the coding tools it has, and for each tool whether it is signed in and the models its account lists (`tools[].models`). In the transaction of that report, `AgentService.syncRunner` keeps one agent for each tool and model the runner reports for a tool it has enabled, installed and signed in (`reportedModels` in `shared/runners.ts`): a combination no agent exists for yet becomes a new agent, `pending`, and the agents the runner still reports get their `lastReportedAt` refreshed, at most every ten minutes. The agent's id is `runnerAgentId(tool, model)`, so two runners reporting the same combination keep one agent. Reports do not restore marked records or fill missing model entries. Runner agents are listed according to their status; their model entry is derived from their own tool and model when read, preserving a stored reasoning effort when present.
 
 Models are normalized before they are compared (`normalizeModel` in `shared/model-catalog.ts`): a known alias such as Claude Code's `opus` becomes the catalog's id, a release suffix (a date or `-latest`) is dropped, and OpenCode and Pi keep their `provider/` prefix with the model after it normalized the same way. The catalog names each agent (`agentNameOf`, such as "Claude · Opus 5.5") and suggests, in English and Chinese, what it is good at; a model it does not know is named after its id with nothing suggested. Keep the catalog to the models the tools offer today, checked against `TOOL_MODEL_SUGGESTIONS` in `@nocobase/agent-protocol`; removing a model from it only loses its label and suggestion, never the agent.
 
 A pending agent is offered no work. Someone who manages agents (`agents.agents` manage) enables it on the Agent page or with `PATCH /api/agents/:agentId` (`agent update` on the CLI), writing what it is good at (required: `GOOD_AT_REQUIRED` otherwise) and, optionally, its default reasoning effort among those its tool takes (`EFFORT_UNSUPPORTED` otherwise; `medium` by default when the tool takes it). Every change names the revision it was made against and is refused with `REVISION_CONFLICT` when the agent changed since. Disabling an agent withdraws its queued runs and announces `agent.removed` with `reason` `disabled`; its conversations report it as not enabled until it is enabled again.
 
-Where an agent can run is worked out per caller (`GET /api/agents`, `AgentView`): the online team runners and personal runners whose tool is enabled, installed and signed in with the agent's model, not marked unavailable there, and whose owner's policy takes the agent. `personalOnly` says only personal runners have it, which take their owners' work only. `unusable` says why the caller's work cannot start now: `pending`, `disabled`, `unreported` (no runner reported it for 14 days, `AGENT_UNREPORTED_AFTER_MS`), `notConfigured` (an application's own agent with no tool and model yet), `noRunner` or `othersPersonal` (only other people's personal runners have it). The roster a project manager picks from (`GET /api/agents/available`, `Agents.roster`) lists the enabled agents reported recently, each with whether a runner would take the caller's work now.
+Where an agent can run is worked out per caller (`GET /api/agents`, `AgentView`): the online shared runners and personal runners whose tool is enabled, installed and signed in with the agent's model, not marked unavailable there, and whose owner's policy takes the agent. `personalOnly` says only personal runners have it, which take their owners' work only. `unusable` says why the caller's work cannot start now: `pending`, `disabled`, `unreported` (no runner reported it for 14 days, `AGENT_UNREPORTED_AFTER_MS`), `notConfigured` (an application's own agent with no tool and model yet), `noRunner` or `othersPersonal` (only other people's personal runners have it). The roster a project manager picks from (`GET /api/agents/available`, `Agents.roster`) lists the enabled agents reported recently, each with whether a runner would take the caller's work now.
 
 A run fails `modelUnavailable` when the tool's account cannot use the model after all. The claim's runner then marks that tool and model unavailable (`Runner.unavailableModels`, with the models it reported at the time), and no claim offers the model there until the runner reports the tool's models differently, such as after its account changed. Other runners are unaffected.
 
 An application keeps agents of its own with `ensureSystem` (`source` `system`), such as a project manager: their name, description, instructions, business actions and tools and models are what the application writes, and people do not change them (`AGENT_MANAGED`). Every discovered agent gets the application's instructions and business actions through `setDefaults(provider)`; `applyDefaults()` writes them to every agent that differs, so a change in the application reaches agents discovered before it. An application updating only its compatibility action catalog can use `applyDefaults({ preserveInstructions: true })` to retain existing instructions.
 
-Upgrading removes every agent an earlier version kept, online agents included (`202610240020_ag_runner_agents`): their rows stay, marked `deletedAt` and disabled, so the runs, comments and conversations that name them still show their names; their queued runs are cancelled, their pending run requests withdrawn, and the default chat agents that named them cleared. Nothing replaces them until runners report again and someone enables the agents that appear. The model services stay and keep serving the application's own model calls.
+Upgrading from before runner agents were introduced removes every agent an earlier version kept, online agents included (`202610240020_ag_runner_agents`): their rows stay marked `deletedAt` and disabled, so runs, comments and conversations that name them still show their names; their queued runs are cancelled, pending run requests withdrawn, and default chat agents that named them cleared. Those legacy records remain removed. A repair migration clears stale deletion and archive markers on runner agents and fills an empty model entry from the stored tool and model, using the tool's initial reasoning effort. It keeps each agent's status unchanged, and rolling back leaves the repaired data in place. Reads already show runner agents by status and derive a missing model entry, so an enabled agent can keep taking work before the migration runs. Older hand-configured and application-owned agents keep their existing removal behavior. The model services stay and keep serving the application's own model calls.
 
 ## Discovery management
 

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": "1.0.0-beta.21",
+  "version": "1.0.0-beta.22",
   "type": "module",
   "prettier": "@nocobase/dev-config/prettier",
   "engines": {
@@ -166,6 +166,7 @@
     "sqlite-vec": "^0.1.9",
     "yaml": "^2.9.0",
     "zod": "^4.6.5",
+    "@nocobase/document-extractor": "^0.1.0-beta.0",
     "@nocobase/agent-protocol": "^0.1.0-beta.14",
     "@nocobase/app-cli-client": "^0.1.0-beta.15",
     "@nocobase/cli-envelope": "^0.1.0-beta.1",
@@ -211,7 +212,7 @@
     "react-dom": "^19.2.8",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@nocobase/agent-runner": "0.1.0-beta.17",
+    "@nocobase/agent-runner": "0.1.0-beta.18",
     "@nocobase/app-testing": "0.1.0-beta.6",
     "@nocobase/db-postgres": "0.1.0-beta.5",
     "@nocobase/db-sqlite": "0.1.0-beta.6",

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

@@ -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`.

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/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.