@nocobase/app-plugin-agents 1.0.0-beta.26 → 1.0.0-beta.28

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

@@ -4,25 +4,25 @@ A subject's optional `sink.onCancelRequested(tx, run)` runs once in the accepted
 
 Everything the App contributes goes through `agentsToken` (`@nocobase/app-plugin-agents/server/tokens`), resolved in one of the App's service providers when it boots. Text people read is an `I18nText` (`{ key, ns }`) in the App's own namespace. The README's "Extension points" section describes each field; this is the map. Where the two disagree, the types exported from `server/tokens` (the `Agents` interface) are authoritative.
 
-| Extension point                                                                                                                                                | Contributes                                                                                                                                                                                                          | Typical use                                                                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subjects.register(binding)`                                                                                                                                   | A kind of subject runs work on: `kind`, `title`, `triggers`, `preview`, `context.assemble`, `sink.onRunFinished`, `queuedExpiryMs`, `reports.describe`                                                               | An issue, a ticket, a document an agent works on                                                                                                        |
-| `runs.enqueue(...)`, `runs.withdrawQueued(...)`, `runs.workload(...)`                                                                                          | Wake an agent on a subject, withdraw queued work, read the board of open runs                                                                                                                                        | Assigning work to an agent from a business action                                                                                                       |
-| `scopes.register(kind)`                                                                                                                                        | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`); `agent` and the skill-only `global` are reserved, `workdir` is registered by the App                             | Per-project or per-team variables                                                                                                                       |
-| `actions.provide(source)`                                                                                                                                      | The business actions an agent may be given (`key`, `group`, `title`, `description`, `defaultOn`), and those never granted (`grantable: false` with a `reason`)                                                       | What the agent editor's Capabilities tab offers                                                                                                         |
-| `agents.setDefaults(provider)`, `agents.applyDefaults()`                                                                                                       | The instructions and business actions every agent discovered from runners gets; `applyDefaults` writes them to the agents that differ                                                                                |
-| `agents.ensureSystem(input)`                                                                                                                                   | An agent of the App's own (fixed id, name, description, instructions, actions, tools and models), kept as given and enabled                                                                                          |
-| `gate.set(gate)` (`ActionGate`: `allowed(identity)`, optional `consultable(action)`)                                                                           | Which business actions a caller holds now: a person their own (narrowed by an API key's scope), a run those its agent is configured with within the waking person's                                                  | Bounding the command manifest and every request a run makes; without a gate a caller holds only `agents.agents/view` (and `agents.runs/self` for a run) |
-| `conversations.sources.register`, `conversations.contextKinds.register`, `conversations.rules.provide`, `conversations.deliver`, `consultations.rules.provide` | Where conversations start from, what a page context may reference, extra system rules, news delivered into a conversation                                                                                            | "Ask agent" buttons on business pages                                                                                                                   |
-| `people.provide(source)`                                                                                                                                       | The App's directory: names, whom to pick, who can no longer act (`inactive`)                                                                                                                                         | Disabling a person stops their runners                                                                                                                  |
-| `events.on('agent.removed' \| 'notice', listener)`                                                                                                             | An agent disabled; people to be told, such as `runner_upgrade_required`                                                                                                                                              | Releasing work given to an agent; forwarding notices to the App's inbox                                                                                 |
-| `jobs.register(kind, registration)`                                                                                                                            | A build job kind, only for an off-by-default runner build method                                                                                                                                                     | Builds on runners                                                                                                                                       |
-| `reporting.usage`, `reporting.runFigures`, `reporting.range`, `reporting.modelUsage`                                                                           | What runs used and cost, grouped as the App needs                                                                                                                                                                    | The App's report pages                                                                                                                                  |
-| `briefs.sections.register(provider)`                                                                                                                           | Sections added to every brief's context layer                                                                                                                                                                        | Project conventions every run should read                                                                                                               |
-| `mounts.register(provider)`                                                                                                                                    | Directories of files placed beside the agent                                                                                                                                                                         | Reference material for a run                                                                                                                            |
-| `repoAccess.register(provider)`                                                                                                                                | Commit identity and short-lived push credentials per run, at the claim or, with `issue`, whenever the runner's git needs one (`gitCredentials` runners); code host CLI wrappers (`RunGit.tools`, `gitTools` runners) | Git hosting integration                                                                                                                                 |
-| `models.gateway`                                                                                                                                               | The model gateway for the App's own model calls                                                                                                                                                                      | See [Online agents](online-agents.md)                                                                                                                   |
-| `vectors.collection(spec)`, `vectors.stores.register`                                                                                                          | Vector collections searched by meaning; another vector store type                                                                                                                                                    | Semantic search for a knowledge base                                                                                                                    |
+| Extension point                                                                                                                                                                       | Contributes                                                                                                                                                                                                          | Typical use                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subjects.register(binding)`                                                                                                                                                          | A kind of subject runs work on: `kind`, `title`, `triggers`, `preview`, `context.assemble`, `sink.onRunFinished`, `queuedExpiryMs`, `reports.describe`                                                               | An issue, a ticket, a document an agent works on                                                                                                        |
+| `runs.enqueue(...)`, `runs.withdrawQueued(...)`, `runs.workload(...)`                                                                                                                 | Wake an agent on a subject, withdraw queued work, read the board of open runs                                                                                                                                        | Assigning work to an agent from a business action                                                                                                       |
+| `scopes.register(kind)`                                                                                                                                                               | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`); `agent` and the skill-only `global` are reserved, `workdir` is registered by the App                             | Per-project or per-team variables                                                                                                                       |
+| `actions.provide(source)`                                                                                                                                                             | The business actions an agent may be given (`key`, `group`, `title`, `description`, `defaultOn`), and those never granted (`grantable: false` with a `reason`)                                                       | What the agent editor's Capabilities tab offers                                                                                                         |
+| `agents.setDefaults(provider)`, `agents.applyDefaults()`                                                                                                                              | The instructions and business actions every agent discovered from runners gets; `applyDefaults` writes them to the agents that differ                                                                                |
+| `agents.ensureSystem(input)`                                                                                                                                                          | An agent of the App's own (fixed id, name, description, instructions, actions, tools and models), kept as given and enabled                                                                                          |
+| `gate.set(gate)` (`ActionGate`: `allowed(identity)`, optional `consultable(action)`)                                                                                                  | Which business actions a caller holds now: a person their own (narrowed by an API key's scope), a run those its agent is configured with within the waking person's                                                  | Bounding the command manifest and every request a run makes; without a gate a caller holds only `agents.agents/view` (and `agents.runs/self` for a run) |
+| `conversations.sources.register`, `conversations.contextKinds.register`, `conversations.rules.provide`, `conversations.deliver`, `conversations.links`, `consultations.rules.provide` | Where conversations start from, what a page context may reference, extra system rules, news delivered into a conversation                                                                                            | "Ask agent" buttons on business pages                                                                                                                   |
+| `people.provide(source)`                                                                                                                                                              | The App's directory: names, whom to pick, who can no longer act (`inactive`)                                                                                                                                         | Disabling a person stops their runners                                                                                                                  |
+| `events.on('agent.removed' \| 'notice', listener)`                                                                                                                                    | An agent disabled; people to be told, such as `runner_upgrade_required`                                                                                                                                              | Releasing work given to an agent; forwarding notices to the App's inbox                                                                                 |
+| `jobs.register(kind, registration)`                                                                                                                                                   | A build job kind, only for an off-by-default runner build method                                                                                                                                                     | Builds on runners                                                                                                                                       |
+| `reporting.usage`, `reporting.runFigures`, `reporting.range`, `reporting.modelUsage`                                                                                                  | What runs used and cost, grouped as the App needs                                                                                                                                                                    | The App's report pages                                                                                                                                  |
+| `briefs.sections.register(provider)`                                                                                                                                                  | Sections added to every brief's context layer                                                                                                                                                                        | Project conventions every run should read                                                                                                               |
+| `mounts.register(provider)`                                                                                                                                                           | Directories of files placed beside the agent                                                                                                                                                                         | Reference material for a run                                                                                                                            |
+| `repoAccess.register(provider)`                                                                                                                                                       | Commit identity and short-lived push credentials per run, at the claim or, with `issue`, whenever the runner's git needs one (`gitCredentials` runners); code host CLI wrappers (`RunGit.tools`, `gitTools` runners) | Git hosting integration                                                                                                                                 |
+| `models.gateway`                                                                                                                                                                      | The model gateway for the App's own model calls                                                                                                                                                                      | See [Online agents](online-agents.md)                                                                                                                   |
+| `vectors.collection(spec)`, `vectors.stores.register`                                                                                                                                 | Vector collections searched by meaning; another vector store type                                                                                                                                                    | Semantic search for a knowledge base                                                                                                                    |
 
 Rules that are easy to miss:
 

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

@@ -213,7 +213,7 @@ Native and Runner realtime history is `AppUIMessage[]`, and HTTP input for both
 
 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.
 
-Existing system notices are delivered through `ConversationService.deliver()` in the caller's business transaction. OnlineAgent bindings persist them without starting another execution, 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.
+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
 
@@ -223,10 +223,24 @@ Browser consumers use the SDK-owned `AppUIMessage` and `ChatProvider` from `clie
 
 Deploy one execution process per logical application/database, fully stopping the old process before starting its replacement. A real serving host repairs pre-process native occupancy at startup: complete saved results are finalized; missing terminal snapshots become failed UI messages on their stable IDs. Current-process rows, valid approval waits and Runner bindings are preserved. Command hosts do not perform crash recovery. Repeated reads and initialization do not rerun models or tools. Shared stream markers express transport reachability, never execution-process death; overlapping deployment and execution takeover are outside this contract.
 
-Normal native and Runner creation accepts showInChatList (default true); background creation always hides the record. List filtering happens in the database before pagination. A known hidden ID retains its ownership checks and remains readable. Notifications delivered through conversations.deliver join the caller's transaction, do not wake new native/Runner execution, and roll back with business changes; native realtime notices are saved as standard data parts.
+Normal native and Runner creation accepts showInChatList (default true); background creation always hides the record. List filtering happens in the database before pagination. A known hidden ID retains its ownership checks and remains readable. Notifications delivered through conversations.deliver join the caller's transaction, do not wake new native/Runner execution (Runner only with `wake: true`), and roll back with business changes; native realtime notices are saved as standard data parts.
 
 HTTP creation/configuration cannot override tool lists, model lists or system prompts. Business variables must be declared and validated by selected scopes; selectedModel still selects an authorized catalog entry. Trusted server SDK configuration retains its policy capability. Legacy unbound conversations are read-only but their owner can still Stop their existing Run without a current model or online Agent.
 
+## Runner binding, links and attention
+
+A conversation is bound to the first runner that takes one of its runs, in the claim's transaction; later runs go only to that runner (`SubjectBinding.runnerPin`), so its working directory `chat-<id>.task` and the coding tool's session carry on. Task runs are unaffected. While the bound runner is offline, revoked or deleted, queued runs and new turns wait instead of failing; `ConversationSummary.runner` (`id`, `name`, `status` `online|offline|revoked|missing`) lets the client say so, and `POST /api/agents/conversations/{conversationId}/switchRunner` (owner only) unbinds it, so the next eligible runner binds it and starts a fresh session with the history and the last summary. A session whose directory a runner's workspace report no longer lists is forgotten, so a cleaned directory also starts fresh with the history.
+
+An application registers what conversations may be tied to with `conversations.links.registerKind({ key, title?, resolve? })`; `resolve(conn, userId, targetIds)` answers the views (`key`, `title`, `status`, `url`) the owner may see, reading only through `conn`. Owners tie and untie records with `GET|POST /api/agents/conversations/{conversationId}/links` and `DELETE …/links/{linkId}`; the application ties what a run created with `conversations.links.attach(conversationId, target, { origin: 'agent', outer? })`, finding the conversation with `conversations.ofRunId(runId)`. `GET /api/agents/conversations?linkKind=&linkTargetId=` lists the viewer's conversations tied to a record, and `conversations.links.linkedTo(conn, target)` every owner's, for delivering news to each. Each turn of a conversation lists its links as "Linked work" after the turn's first line; `conversations.rules.provide` may return `turn` sections as well, which never stop a session from resuming.
+
+A turn that ends completed or failed while the owner has not seen everything sets `needsYou` (`reply`, `failed`), and a run's `conversation ask-owner "<question>"` (`POST /api/agents/runs/current/conversation/askOwner`) sets `confirm`, which waits until the owner writes. Each is announced once per turn as the `conversation.attention` event (`conversationId`, `userId`, `reason`, `seq`, `title`, `text`) for reminders and push; the client moves the read position with `POST …/markSeen { seq }` (`seenSeq`), which settles a reply or failure, and reads badge counts from `GET /api/agents/conversationAttention` (`unread`, `needsYou`). `conversations.markNoticed(id, seq)` records what the application already told the owner (`noticedSeq`).
+
+## Queued messages, usage and deletion
+
+While a Runner conversation's agent works, `RealtimeOnlineAgent.queue(messages, input?)` (HTTP `POST /api/agents/conversations/{conversationId}/queue`, the same body as sending) joins one more user message to that work instead of refusing it as busy: the runner steers it into the running turn when its tool can, and takes it as the next turn otherwise. It answers the saved message, whose `metadata.queue` is `queued` until the agent takes it; one taken as the next turn gets an answer of its own, split from the run's response. `POST …/messages/{messageId}/withdraw` takes it back while no runner has it (`queue: 'withdrawn'`); once a runner has it the answer is `400 CONVERSATION_CONFLICT` with `metadata.reason` `messageTaken`. `queue` is refused (`409`) when the agent is not working: send the message instead. Native sessions do not implement it.
+
+`GET /api/agents/conversations/{conversationId}/usage` sums the tokens of the conversation's runs and returns the latest context window and the cost, each `null` where the runs' coding tools do not report it. Each ended run closes its response with a `data-turn` part (duration, tokens, outcome), and the agent's todo list shows as a `data-plan` part. `DELETE /api/agents/conversations/{conversationId}` deletes the owner's conversation for good; archived conversations are deleted after `agents.conversations.archivedRetentionDays`.
+
 ## Runner conversation previews
 
 Upgrade the server agents plugin before runners. Conversation claims automatically include `outputBlocks: true` when the runner advertises the capability; tasks never receive it, and there is no application configuration switch. All task adapters, storage, summaries and run-history components keep their previous behavior.