@nocobase/app-plugin-agents 0.0.0-stage → 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# @nocobase/app-plugin-agents
+
+## 0.1.0-beta.1
+
+### Minor Changes
+
+- 476f988: A call to an OpenCode base URL (Zen or Go) carries `x-opencode-session` automatically, as OpenCode Go requires: the same session id for every model call of a conversation and a new one for each call outside any, so no service setting is needed. Every request to a provider names the plugin first in its user agent (`nocobase-agents/<version>`). The service form says which provider type serves which of OpenCode's model families.
+- b8df35c: Limit a runner's concurrent runs per coding tool, beside its total slots, so a machine with Claude Code and Codex can run, say, at most two Claude runs and one Codex run at once.
+
+  - `@nocobase/agent-protocol`: optional `toolSlots` on registration, `load.tools` on the heartbeat and `tools` on the claim (`ToolSlots`, `ToolLoad`). They are additions within protocol 7: a side that does not know them ignores them.
+  - `@nocobase/agent-runner`: `register --slots` and `start --slots` take a total, limits per tool, or both (`3,claude=2,codex=1`). The limits hold across every application the machine serves; each claim says how many runs of each limited tool the runner can still take, and the heartbeat reports them.
+  - `@nocobase/app-plugin-agents`: runners and registration tokens keep `toolSlots`, set on registration or on the runtime's settings and in the "Add runtime" dialog. A claim takes a run only when both the runner's total and the run's tool have room, using the agent's next tool while its first is full and passing over a run none of whose tools has room. A queued run waiting on a full tool reads `toolSlotsFull` rather than `runnersBusy`, and the runtimes page shows the runs by tool against each limit. The migration `202610080001_ag_add_runner_tool_slots` adds the columns. A runtime's settings list its coding tools in one table (on or off, sign-in, limit, runs now), and a tool's switch is now saved with "Save" together with the rest of the form instead of at once. The "Add runtime" dialog keeps the limits per tool under "Advanced" for the checked tools, and its button reads "Generate install command". A limit above the max concurrent runs is pointed out, since the total bounds it.
+  - `@nocobase/app-plugin-projects`: words the `toolSlotsFull` wait reason.
+
+  Every field this adds to the shared types is optional, so code that builds these objects itself needs no change: `Runner.toolSlots` and `Runner.toolLoad`, `RunnerSummary.activeByTool`, `RegistrationToken.toolSlots`, and `HeldItems.byTool` of `Slots`. The server always fills them in. A missing field reads as no limit per tool and nothing known about its use, and the runtimes page then shows no use per tool. `RUN_WAIT_REASONS` gains `toolSlotsFull`, so a `Record` keyed by every `RunWaitReason` needs an entry for it.
+
+  Applications using a copied UI Library `agent-queue` block must merge the `toolSlotsFull` reason and wording changes from `ui-library/registry/agents/agent-queue` into their copy. This PR updates the registry source, including an optional label with an English fallback, but a plugin upgrade does not update installed source. Add `queue.reasons.toolSlotsFull` to the application's translations to show the new reason in its locale.
+
+### Patch Changes
+
+- 220700e: Size the Y axis of the usage page's daily trend chart to its tick labels, so cost amounts with a currency prefix are no longer clipped at the left edge.
+- Updated dependencies [bb8484b]
+- Updated dependencies [dc91aab]
+- Updated dependencies [b8df35c]
+  - @nocobase/app-client@2.0.0-beta.2
+  - @nocobase/app-plugin-authentication@2.0.0-beta.2
+  - @nocobase/app-plugin-file@1.0.0-beta.20
+  - @nocobase/agent-protocol@0.1.0-beta.1
+  - @nocobase/app-cli@1.0.0-beta.14
+  - @nocobase/app-server@2.0.0-beta.1
+  - @nocobase/authorization@1.0.0-beta.12
+  - @nocobase/db@1.0.0-beta.18
+  - @nocobase/i18n@1.0.0-beta.5
+  - @nocobase/markdown-mermaid@0.1.0-beta.0
+  - @nocobase/service-provider@0.0.2-beta.1
+  - @nocobase/app-plugin-authorization@1.0.0-beta.25
+
+## 0.1.0-beta.0
+
+### Minor Changes
+
+- 68d4feb: Add `@nocobase/app-plugin-agents`: agents for NocoBase applications. Work agents drive a coding tool (Claude Code, Codex, OpenCode or Pi) on the runners people connect, which the plugin registers, hands runs to through a long-poll claim with slots, leases and a sweeper, and serves the runner and the application's CLI to as tarballs with a one-line install script. Online agents call a model of the model services the plugin keeps (OpenAI, Anthropic, Google, DeepSeek and other providers through the AI SDK) and run on the server with a sandboxed shell, their skills and the application's CLI. Both share runs, people's conversations with agents (with attachments and page context), transcripts, skills and variables, business-action permissions bounded by the person who woke the agent, consultations between online agents, usage and cost reports, and an embedding, rerank and text gateway for the application's own model calls. The application assembles it through extension points (subjects, scopes, business actions, presets, the action gate, conversation sources) and its CLI commands come from its own routes through `cliRoute()`. The package ships the `nocobase-app-plugin-agents` Skill.
+
+### Patch Changes
+
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [be0fbbd]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [3883eec]
+- Updated dependencies [6993158]
+- Updated dependencies [a6796d9]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [3f1b78f]
+- Updated dependencies [8885ce4]
+- Updated dependencies [0151805]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [e538d12]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [37c8d20]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [37c8d20]
+- Updated dependencies [37c8d20]
+- Updated dependencies [bc1e83f]
+- Updated dependencies [6162033]
+- Updated dependencies [37c8d20]
+  - @nocobase/agent-protocol@0.1.0-beta.0
+  - @nocobase/app-cli-client@0.1.0-beta.0
+  - @nocobase/markdown-mermaid@0.1.0-beta.0
+  - @nocobase/app-cli@1.0.0-beta.14
+  - @nocobase/app-client@2.0.0-beta.1
+  - @nocobase/app-server@2.0.0-beta.1
+  - @nocobase/app-plugin-authentication@2.0.0-beta.1
+  - @nocobase/authorization@1.0.0-beta.12
+  - @nocobase/app-plugin-authorization@1.0.0-beta.25
+  - @nocobase/db@1.0.0-beta.18
+  - @nocobase/app-plugin-file@1.0.0-beta.19
+  - @nocobase/i18n@1.0.0-beta.5
+  - @nocobase/service-provider@0.0.2-beta.1
+
+## 0.0.1
+
+Initial version.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# @nocobase/app-plugin-agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agents for NocoBase applications: the agents people configure, their runs, and people's conversations with agents. Runner agents run on the runners people connect (each a runtime: a runner on a server, a VM or someone's own device), which this plugin registers, hands work to and serves the runner and CLI tarballs for; the wire protocol runners and the application's CLI speak is `@nocobase/agent-protocol`, and the runner is `@nocobase/agent-runner` (`nocobase-runner`).
+
+An agent is one of two types, chosen when it is created and never changed. A **work** agent drives a coding tool on a runner, in a working directory. An **online** agent talks to a model of one of the model services this plugin keeps and is run by the application itself, on the server: it needs no runner, answers in seconds, and its tools are the application's commands. Both share everything else: runs, conversations, transcripts, permissions, usage and reports.
+
+The plugin knows no domain of its own beyond conversations: what agents work on (subjects), the scopes variables are kept in, the business actions an agent may be given, the presets to start an agent from and the report pages are the application's, which contributes them through the extension points below; the CLI's business commands are the application's own routes, each described with `cliRoute()`. The assembling application does it in `server/agents` and `client/agents`. With nothing contributed, the plugin still runs agents in conversations on runners, with its own commands.
+
+## What it does
+
+- **Agents** (`agAgents`): who an agent is and how it works: its name, description and avatar, optional instructions (the last layer of its brief, preferences that never override the rules or the task), its type (`runner` or `online`, immutable: a patch naming one is refused), the business actions it may perform, who may wake it and how many attempts a run gets. Which tool or model it works with is an ordered list, `modelEntries`, whose first entry is its default, each entry with its own reasoning effort (`effort`, null for the default). A runner agent's entries pair a coding tool with a model (null for the tool's default) and an effort its tool takes (`TOOL_EFFORTS` of `@nocobase/agent-protocol`), and it has its skills, its tool policy, its own variables, optionally the runners it may run on, and how many runs it may have at once; it has at least one entry. An online agent's entries pair a model service with one of its models (an entry is checked against what the model catalog offers when it is added) and an effort among `ONLINE_EFFORTS`, and it has none of a runner's settings; an online agent with no entry is not configured yet: it is listed as needing a model and left out of `GET /api/agents/available` until it has one; it is offered no business action meant for runner agents only (`AgentActionOption.types`). Its configuration carries a `revision`, raised by every change (editing, archiving, restoring): `PATCH /api/agents/:agentId` names the revision it was made against (`expectedRevision`) and is refused with 409 `REVISION_CONFLICT` (`metadata.revision` the current one) when someone saved the agent since, and a patch that changes nothing raises nothing. Every change is kept in its history (`agAgentChanges`, `GET /api/agents/:agentId/history`, with `afterRevision` for what came after a revision): who, when, and the fields that changed with their values before and after, except its variables, which are named with whether they were added, changed or removed, never valued. Archiving an agent withdraws its queued runs at once; archiving and deleting it announce `agent.removed`.
+- **Runners** (`agRunners`), shown as runtimes: registered with a one-time token (`POST /api/agents/runners/registrationTokens`, or `pnpm nocobase agents runner-token`). Anyone may add a personal runner (`ownerOnly`: it runs only work its owner started) and later share it with the team; adding a team runner needs `agents.runners` manage. A runner reports its system, its features, its coding tools with versions and whether each is signed in, and what its owner's local policy lets it take (`policy`); it authenticates with its key (`agRunnerCredentials`), sends heartbeats and long-polls for work. Which of its coding tools it is offered work for is chosen on the web (`enabledTools`, null for every tool), carried from "Add runtime" on the registration token (`agRegistrationTokens`). A runner speaking a protocol this application does not serve is kept connected as `upgrade_required`: it gets no work, has what it holds released, and its owner is told once per protocol through the `notice` event (`runner_upgrade_required`; `notice.cleared` once it no longer holds). A runner whose owner can no longer act (`people.provide({ inactive })`) is refused with `RUNNER_OWNER_DISABLED`. A runner fits an agent's run only when its owner's local policy lets it take that agent's runs, on that subject, with those repositories; `availability` and the agents list count only such runners.
+- **The claim**: one long-poll (`POST /api/agents/runners/claim?wait=true`) answers `jobs` and `runs` together, at most `free` items, from the runner's slots, which jobs and runs share (`slots`): jobs first. A heartbeat reconciles both, releasing what the server no longer thinks the runner holds and asking it to stop what was cancelled.
+- **Jobs** (`agJobs`, `agJobEvents`): only for the off-by-default runner build method (such as an application's `acme.builds.method: runner`): a `build` (check out a commit, run an administrator's command, upload its outputs), of kinds the application registers (`jobs.register(kind, { validate, prepare, onEvent, onDone })`, then `jobs.enqueue`, `get` and `watch`). A runner takes a job only when it reports `jobs.build`, someone turned on "Takes build jobs" (`acceptJobs`), it is shared or belongs to who started the job, and its policy lets it check out the job's repository. Jobs retry `runnerOffline`, `leaseExpired`, `startTimeout`, `checkoutFailed` and `policyRefused` while attempts remain, and open the stored variables they name through this plugin's variables at claim, audited as delivered.
+- **Distribution**: the application serves two products as standalone tarballs that bundle Node, one per platform (`server/distribution`): its CLI (`agents.cli.name`, such as `acme`) and the runner, `nocobase-runner` (`RUNNER_PRODUCT`). `pnpm nocobase cli build` of `@nocobase/app-cli` packs the CLI the application's `package.json` declares under `nocobase.cli`, and `cli build --runner` the runner, each into a directory of its own, `storage/runners/dist/<channel>/<product>/`, with a `manifest.json` of every file's SHA-256 and size, so CI builds them as separate artifacts mounted into storage. The install script installs the CLI under `~/.local/share/<cli>`: by default the CLI alone, with a download token any signed-in person mints (`POST /api/agents/dist/downloadTokens`, `agDownloadTokens`: the CLI for one platform, three downloads within 30 minutes), as `curl -fsSL <server>/api/agents/dist/installScript | sh -s -- --token <token>`; "Add runtime" shows the same line with `--runner --server <server>` and a registration token, which also installs `nocobase-runner` under `~/.local/share/nocobase-runner`, runs `nocobase-runner register` and `nocobase-runner service install` (an application that serves no CLI still gets its runtime). A token of the other kind fails before anything is installed. A runner reports the product it runs as on registration and every heartbeat (`agRunners.product`), and the heartbeat answer carries an `upgrade` notice when the channel serves a newer version of that product for the runner's platform; a runner that reports none (one from before) is offered no update, and the Runtimes page says to install it again.
+
+- **Runs** (`agRuns`): one agent working on one subject, keyed by (agent, subject, thread), with the agent's type kept on the run (`agentType`). A subject kind takes the agent types its binding names (`agentTypes`, runner only by default); a run of another type is refused (`AGENT_TYPE_NOT_ALLOWED`). New work joins the run already on it while that run can still be told, else the queued one, else starts a new run. Queued runs are claimed by `priority` (lower first; 0 by default), then oldest first; a run given a `fireAt` is not claimed before that moment. Work merged into a queued run raises it to the more urgent priority and the earlier moment of the two. Runners take only runner agents' runs. A claim hands a run to a runner that fits in one transaction: one of the agent's tools enabled, installed and signed in there (the run takes the first entry of the agent's list whose tool is, recorded on the run as `tool` and `model` and passed to the tool; a model the tool's account cannot use fails the run `modelUnavailable`), the agent naming no runner or naming this one, the runner shared with the team or owned by the person who woke the agent, its features covering what the run needs (worked out from the payload: checkouts, directories, skills, secrets), and a free slot within the agent's concurrency. A working directory that is a directory on one runner pins the run to that runner, one run at a time per directory. The claim renders the brief (kept per run, `agRunBriefs`), mints a run token, and hands over the working directories, the merged variables, the skills and the CLI to install. Events, usage and branches are recorded as the runner reports them; completing requires every input to be handled.
+- **Workload** (`runs.workload({ subjectKind, limit? })`, `shared/runs.ts`): the open runs on one kind of subject for a board of work, without claiming anything. Held runs come with their runner, the newest input's trigger and their newest text, tool call, status or error (`lastActivity`); queued runs with their place in the claim order (among the runs claimable now, and among the agent's) and why they wait, by the claim's own rules in its order (`RUN_WAIT_REASONS`: the agent archived, delayed until a moment, no runner online, the agent's named runners offline, its tool not signed in anywhere, only other people's personal runners, missing features, the same work already held, the agent's concurrency full, every fitting runner busy, preparation retrying, or next). It also answers each agent's load (held, queued, its limit, whether a runner could take its work) and the runners' (online, holding work, slots and slots used). It reads a bounded number of tables, never one query per subject; the caller decides what of it a person may see.
+- **Online runs** (`server/online`): every application instance runs an executor that takes online agents' runs through the same claim transaction (`claims.claimServer`, the run held by `server:<instance>`, so two instances never take one run), with the entry of the agent's list the subject asks for (a conversation's choice, `ConversationPatch.model`, while the agent still lists it) or else its first, recorded on the run as `modelService` and `model`; a failing model fails the run, nothing falls back to another entry and reports through the same lifecycle a runner's requests reach (start, events, lease, complete, fail, cancel-ack), so conversations, transcripts, retries, failed-run handling and the sweeper are unchanged. No slots and no per-agent concurrency limit apply. A run is a loop of model calls through the plugin's model gateway (`online.gateway`, below): each streams its text, which a conversation shows as a draft message growing in place, and ends with the tool calls to make and what the call used, recorded at once as the run's usage (tool `chat`, the model the provider named). It has two tools (`online/sandbox.ts`): `bash`, a sandboxed shell (`just-bash`, in process: no real processes, no network, a 10-second deadline per command, its output cut to what the model reads; the build bundles the part of `just-bash` it uses into `dist/server/vendor/just-bash.js` with `THIRD_PARTY_LICENSES.txt` beside it, so the plugin does not depend on `just-bash`, and leaves out Python, JavaScript, SQLite, curl, html-to-markdown and xz/zstd archives, which answer that they are not available), and `skill`, which reads one of the run's skills (its SKILL.md and its file tree). The shell mounts the run's skills read-only at `/skills/<slug>/` (text only, at most 5 MB per run; binary files are listed but not readable, and scripts are never run) with `/tmp` as scratch, and carries the application's CLI (`online/cli-command.ts`): `acme`, built from the run's command manifest (the application's `GET /api/cli/manifest`, the actions of the person who woke the agent that the agent is configured with), each command one request sent through the application itself with the run's token, so the route checks the permission again; the line is read by the CLI's own parser (`@nocobase/app-cli-client/parse`), so flags, `--<flag>-file` and the body's `--file` (read from the shell's files), `--from-env` (the shell's exported variables), usage errors and exit codes are the CLI's; help and `acme docs` work from the manifest, `--json` prints the cli-envelope, and commands that send or save files are refused. Skills every online run gets besides its own (the CLI's) are registered with `online.skills`. A refused or failed call is a result the model reads. Input that arrives meanwhile is answered in the same run; a run that calls tools for more than `maxSteps` model calls fails `stepLimit`. The gateway's errors become failure reasons: `config` → `modelUnavailable`, `auth` → `toolAuth`, `quota` → `toolQuota`, `rateLimit` → `toolRateLimit` and `network` → `toolNetwork` (both retried while attempts remain), `contextOverflow` → `contextOverflow`, anything else `unknown`. A cancel request aborts the model call within a second; at shutdown an instance hands its runs back (`runnerOffline`), and one that stops renewing its leases loses them to the sweeper (`leaseExpired`). The brief of an online run has a system layer of its own (`onlineSystemLayer`): the CLI in its shell instead of a terminal, no workspace, its skills by name and description (`onlineSkillsSection`), and links to the pages of what it relied on.
+- **Redaction**: what runners report is stored redacted. The runner redacts first; the server redacts every run event (content, output, input and meta), summary and failure detail, and every job event and failure detail again before storing them, with the protocol's redactor (`createRedactor` of `@nocobase/agent-protocol`): the secrets the claim handed out (a run's variables and token, a job's opened variables, repository token and upload headers, remembered in memory for recent claims) and the common secret patterns, each replaced with `[REDACTED]` (`server/kernel/redaction.ts`). After a restart, or on another instance, the patterns and the runner's own redaction still apply.
+- **The sweep** (`server/runners/sweeper.ts`, the `RunnersSweep` schedule every 30 seconds on the application's jobs service, or an in-process timer without one) marks runners not heard from for 150 s offline, takes jobs back from silent runners and fails jobs far past their timeout, and takes runs back from runners that went away, lost their lease or never started, fails runs idle for twice their idle timeout, records unacknowledged cancellations, cancels queued runs of archived agents, and fails a queued run that waited longer than its subject allows (`queuedExpiryMs` on the subject's binding, counted from the run's last change or from its `fireAt`) as `queuedExpired`.
+- **Variables** (`agSecrets`): environment variables for the agent's process, every one a secret sealed with the application's secrets service (`secrets.keys`) and bound to its scope and name, set on an agent, a working directory (`workdir`) or a scope the application registers, merged for a run in the order the subject names its scopes < its working directories < the agent, delivered only to runners with the `secrets` feature. Values are write-only; reading them back and every delivery are audited (`agSecretAudits`).
+- **Skills** (`agSkills`, `agSkillVersions`, `agSkillAttachments`): a library of skills in the open Agent Skills format (https://agentskills.io/specification): a directory of `SKILL.md` and supporting files, conventionally under `scripts/`, `references/` and `assets/`. Only the front matter of `SKILL.md` names and describes a skill: `name` (1–64 lower-case letters, digits and single hyphens) is its slug and directory, so a save that changes it renames the skill, and `description` (1–1024 characters) is required; `license`, `compatibility` (at most 500 characters), `metadata` (string values) and `allowed-tools` are checked when present, and other keys are kept. Every create, save, restore and import is checked against these rules in the browser as it is typed and on the server (`shared/skill-markdown.ts`), which answers 400 with each problem's `field` and `reason` in `metadata.problems` (`taken` for a name another skill has; `mismatch` for an archive whose folder is named otherwise). Files under `scripts/` or marked executable are scripts (`Skill.scripts`): runners may run them, online agents only read them. Every save is a new version that runs get at once, with older versions to compare and restore. Skills are attached to agents, and as defaults to a working directory or a registered scope. A skill's revision is its current version: a save or a restore names the version it was made against (`expectedRevision`) and is refused with 409 `REVISION_CONFLICT` when another save came first. A runner fetches a run's skills from `GET /api/agents/runners/runs/:runId/skills/:slug` and places them where the run's coding tool finds them.
+- **Conversations** (`agConversations`, `agConversationMessages`): a person chatting with an agent they may wake, from the chat panel. A conversation's mode is the type of the agent it started with (`mode`), for its whole life: it only ever moves to an agent of the same type, and the fallback to the system default is offered only when that agent has its mode. Only the owner reads a conversation, administrators included; its runs are hidden from everyone they do not involve. Each message the owner sends wakes the agent on the `conversation` subject as the owner, or joins the run already working on it; every text the agent writes becomes a message. A run resumes the session its runner kept; on another runner, or after the conversation switched agents, it starts fresh with the last 20 messages and the previous run's summary. When the agent is archived, no longer allowed, has no online signed-in runner, or (an online agent) its model is no longer offered (`modelUnavailable`), messages are still saved and the conversation reports why; the owner may switch it to the system default chat agent and back when that agent is of the same type. An online conversation answers with the entry of its agent's list its owner chose in the composer (`model`, `PATCH` with `model`; null for the agent's default), from the next run on; the composer offers the agent's entries (`models`) and hides the choice when there is only one. An online agent's reply is a draft (`metadata.streaming`) rewritten in place as it streams, at the same `seq`, and made final by the run's text event; a draft whose run ended first keeps what it had written (`metadata.interrupted`). `shared/conversations` is the contract (HTTP API under `/api/agents/conversations` and `/api/agents/chat*`, page context and its limits, the per-user realtime topic `agents:conversations`); `ConversationService` is the interface other code uses, so the storage can move to a shared platform layer later.
+- **Chat defaults and presets**: the system default chat agent (`agSettings`), each person's default chat agent (`agChatPreferences`), "Copy as my agent" on an agent's page (a private copy of it), each agent's "confirm before changing data" (`confirmChanges`: `always` or only `larger` changes), and the agent presets the application registers to start a new agent from (`GET /api/agents/presets`).
+- **No setup scripts.** Preparing a working directory is the agent's job: its brief tells it to follow each directory's own instructions (AGENTS.md, CLAUDE.md, README), to install what is missing inside the directory, and to say so (the way the subject's guidance tells it) when it cannot. A working directory's optional initialization prompt reaches the agent only when the runner prepared that directory fresh. "Clean working directory" (`POST /api/agents/workspaces/:subjectKind/:subjectId/reset`) makes the next run start from a fresh checkout.
+
+## Online agents
+
+The plugin keeps the model services online agents call (`agModelServices`, `server/online/services.ts`): a provider type, a name agents and model prices store (made from the title, never changed), a title, a base URL (the provider's default when empty), an API key sealed with the secrets service as variables are, bound to the service's name, an on/off switch, and the models it offers. A provider may have any number of services. The key is write-only: the API answers `apiKeySet`, never the key. Every request to a provider names the plugin first in its user agent (`nocobase-agents/<version>`); a call to an OpenCode base URL (Zen or Go) additionally carries `x-opencode-session`, the same session id for every model call of a conversation (a hash of its subject and thread, `sessionOf` in `server/online/executor.ts`) and a new one for each call outside any, such as a connection test, an embedding or a rerank. Deleting a service deletes its model prices. A model's kind (chat, embedding or rerank) is guessed from its id only as a default and can always be changed; checking a model checks it as its kind, and when it fails that way but answers as another kind its provider serves, the check says so (`ModelCheck.looksLike`). The system default chat model (`agSettings` key `models`) is what an online agent that lists no model answers with: availability, the run (which records the model it used) and the conversation's model all fall back to it. It is set on the Models page; with none set, the first chat model an enabled service offers is used, and the first chat model turned on becomes it.
+
+The providers (`MODEL_PROVIDERS` in `shared/models.ts`, `server/online/providers.ts`) are Vercel AI SDK provider packages: `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, `@ai-sdk/deepseek`, `@ai-sdk/alibaba` (Qwen), `@ai-sdk/moonshotai` (Kimi), `@ai-sdk/cohere`, `ollama-ai-provider-v2`, and `@ai-sdk/openai-compatible` for every other endpoint that speaks OpenAI's chat completions. A provider's models are read from its own list-models endpoint (`GET /models`; Anthropic's with its version header, Google's `models` that generate content, Cohere's v1 `models`, Ollama's `/tags`); a model can also be added by id.
+
+Each model of a service is of one kind (`ModelKind`), chosen in its row of the service's dialog among the kinds its provider serves (`kinds`): `chat` (what online agents talk to; the only kind agents, their pickers and the catalog's default ever see), `embedding` (texts to vectors, with an optional vector size, `dimensions`, asked through each provider's own option) or `rerank` (documents ordered by a query). OpenAI, Google, Alibaba and Ollama serve chat and embedding models; Cohere and OpenAI-compatible endpoints serve all three, an OpenAI-compatible endpoint's reranking being `POST <base>/rerank` in the shape Cohere, Jina, vLLM and SiliconFlow share (`compatibleReranking`); Anthropic, DeepSeek and Moonshot serve chat models only. A model without a kind is a chat model. Testing a model tries it as its kind says.
+
+The model gateway (`online.gateway`, `server/online/gateway.ts`) is what the executor and the admin API call: `catalog()` (the enabled services that offer a model, names only), `check(ref)` (a short `generateText`, 20 seconds, never throws), `languageModel(ref)`, the chat model an online run's loop runs over, and `stream(request)`, one `streamText` call with tools declared without an implementation, which ends at the tool calls the model made. An online run is the SDK's `ToolLoopAgent` over that model: the run's brief is its instructions, its tools are executed by the SDK step by step (a tool answers `{ ok, output }`, and the model reads `output` through `toModelOutput`), each step's usage is recorded as it finishes, and the loop stops when the model answers without a tool call or after `agents.server.maxSteps` steps (`stepLimit`); an entry's reasoning effort is the SDK's `reasoning` option. Usage is mapped to the protocol's non-overlapping counts (input without cached reads and cache writes; output with reasoning). The SDK retries a failed request twice; a failure throws `ModelError` with a code from the provider's status and error body (`config`, `auth`, `quota`, `rateLimit`, `network`, `contextOverflow`, `filtered`, `badResponse`, `aborted`, `unknown`), which become the run's failure reasons as above. A service without a key whose provider needs one fails `auth` before any request. A run's brief, and a system message marked `cache`, carry Anthropic's `cacheControl` (`ephemeral`), so the brief is read from the cache on every model call of a run after the first; OpenAI caches a long prefix by itself.
+
+The gateway also serves the application's own model calls outside runs, each naming who asks (`source`, such as `knowledge`): `embed({ model, values, source })` (`embedMany`, two requests at a time, answering the vectors, their size and the tokens read), `rerank({ model, query, documents, topN?, source })` (the SDK's `rerank`, answering each document's index and score, best first) and `generate({ model, system?, prompt, maxOutputTokens?, source })` (one short text from a chat model, `generateText`). Each names a model of the matching kind (`catalog(kind)` lists them) and throws `ModelError` as a run's calls do. What each used is recorded at once in `agModelUsage` (purpose `embedding`, `rerank` or `text`, the source, the model, its tokens and how many texts or documents), priced like online runs' calls from the service's model prices, and reported by `reporting.modelUsage(caller, { from, to })` (`GET /api/agents/usage/models`, behind the usage page's grant, rows only for a reader of every run): the usage page shows it below the runs as "Other model use".
+
+### Consultations
+
+An online run may consult another online agent synchronously, as the AI SDK's subagent pattern does: the tool `ask_agent` (`{ agent, question, context? }`, `server/online/consult-tool.ts`) is given to a run whose system prompt lists agents it may consult (`Agents you may consult`, name and the first line of the description), and only then. Those are online agents with a model that the person the run acts for may use (their "who may use it"), not already in the run's chain. The answer comes from a run of its own (`server/core/consultations`): a child of the asking run (`parentRunId`), on the subject `{ kind: 'consultation', id: <asking run> }`, one thread per tool call, one attempt, acting for the same person with its own run token. It is never claimed from the queue: the instance holding the asking run takes it at once (`claims.claimChild`) and runs it within the tool call, aborted with the asking run, within `agents.server.consult.timeoutMs` and `tokenBudget`. It only reads: the gate keeps a consultation's run to reading actions (`…/view`, `…/read`) and those the application marks `consultable` (for example, proposing an operation plan, which reaches as far as the agent and person do and is confirmed by the person in the conversation that asked, `conversations.homeOf`). Consultations go `CONSULT_MAX_DEPTH` (2) deep and never back to an agent already asked; a runner agent is refused with "use a task to delegate to a runner agent". The tool streams preliminary results, which the asking conversation shows as a card (a `consultation` notice, rewritten in place); the asking model reads only the final answer and a note of the plans proposed (`toModelOutput`). The child's transcript and usage are its own, and `RunDetail.children` lists a run's consultations.
+
+## Vectors
+
+`server/vectors` keeps vector collections for the application: items of text it names (`id`, `text`, `metadata`), embedded with the embedding model it chooses and searched by meaning, so a feature such as a knowledge base adds semantic search without knowing where vectors live. It is generic: the plugin knows no domain of what it embeds.
+
+- **Stores.** A `VectorStore` (`createIndex` with a name, dimension, metric and the metadata keys filters use; `upsert`, `update` of metadata, `query` with `topK` and a filter applied before the limit, `delete` by ids or filter, `dropIndex`; `target`, where it points with no secret) is one type of a registry (`vectors.stores.register`), like the model providers. The store is configured in `agents.vectors`, apart from the application's database, and two are built in:
+  - `sqlite-vec`, the default: a SQLite file of its own (`path`, `storage/vectors.sqlite` by default) opened with `better-sqlite3` and the [sqlite-vec](https://github.com/asg017/sqlite-vec) extension, so vectors work with nothing to run. One table per index (`agv_<index>`: the vector as a float32 blob, `metadata` as JSON text, an index on each filterable key) searched exactly: the filter in the WHERE clause, then sqlite-vec's distance and the limit. It is local to the instance, so an application running several instances uses pgvector. The extension ships as prebuilt platform packages (`sqlite-vec-<os>-<arch>`: macOS, Linux glibc and Windows on x64, macOS and Linux on arm64); where there is none, such as Alpine (musl), the store reports `SQLITE_VEC_UNSUPPORTED`.
+  - `pgvector`: a PostgreSQL database of its own with the `vector` extension (created when missing), reached with its own connection settings (`url`, or `host`, `port`, `database`, `user`, `password`; `ssl`), never the application's database connection: one table per index (`agv_<index>`: `vector(<dimension>)`, `halfvec` from 2001 to 4000 dimensions, `metadata` jsonb), an HNSW index with the metric's operator class, a btree index per filterable key, and queries filtered in their WHERE clause with pgvector's iterative index scans on (0.8 and later), so a selective filter still returns `topK`. A large delete vacuums the table so the HNSW graph forgets the rows.
+
+  A store that cannot be used reports why as a code (`VectorUnavailableCode`: `VECTORS_OFF`, `VECTOR_STORE_UNKNOWN`, `SQLITE_VEC_UNSUPPORTED`, `SQLITE_VEC_OPEN_FAILED`, `PGVECTOR_NOT_CONFIGURED`, `PGVECTOR_CONNECTION_FAILED`, `PGVECTOR_EXTENSION_MISSING`, `VECTOR_STORE_FAILED`) with an English message for the logs; then vectors queue nothing and search answers null, and the caller keeps its keyword search. `vectors.status()` answers availability, the store's type and target, and the reason.
+
+- **Collections.** `vectors.collection(spec)` names a collection (`name`, the usage `source` of its embedding calls, `model()` answering its embedding model or null, `items()` listing every item for a rebuild, its `filterable` keys and metric, and optionally `prepare`, which rewrites the texts before they are embedded, such as with a context sentence). An index is the collection embedded with one model at one dimension in one store (`agVectorIndexes`, which records the store's type and target), the model's configured dimension or what a probe embedding answers. The index registry and the queue stay in the application's database, so they change in the same transactions as the writes they follow; only the vectors live in the store. Only the indexes of the store configured now are used: pointing the store elsewhere retires the others and builds the index again there in the background. `sync()` builds the index of the model now when it is not there, queuing every item while the ready index keeps serving; once nothing is pending it becomes ready and the older index is retired and dropped. `upsert` and `replace` (the items of a metadata scope) write to the ready index and the one being built: an item whose text hash is unchanged only has its metadata updated; `remove` takes ids or a filter. `search` embeds the query with the ready index's model and answers the closest items with a similarity score, or null when there is no store, no model or no ready index yet. `status()` answers availability, the store and the reason it is unavailable, the model, the active and building index with their progress (`indexed` of `total` items), and how many items are pending or failed.
+- **The queue.** Entries (`agVectorEntries`) keep each item's text hash and, until it is embedded, its text. Each instance's worker (`vectors.start()`, woken by writes and polling every three seconds) takes due entries with a lease, so two instances never embed the same one, at most 64 of one index per embedding call; a failure backs off from five seconds, doubling up to ten minutes, and after five attempts the entry is `failed` until the item is written again.
+
+## Layout
+
+| Folder                                                 | What is there                                                                                                                                                                                   |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server/kernel`                                        | Clock, ids, transactions, events, credentials and secret sealing, scopes, redaction, HTTP helpers                                                                                               |
+| `server/core`                                          | What both agent types share: agents, runs and the queue (claims, lifecycle, sweeper), briefs, conversations, the custom command registry, usage, prices and reports, skills, variables, presets |
+| `server/online`                                        | Online agents: the model services, the providers, the model gateway, the executor and its command tools, and the model endpoints of the admin API                                               |
+| `server/vectors`                                       | Vector collections, their embedding queue, the vector store registry, and the `sqlite-vec` and `pgvector` stores                                                                                |
+| `server/runners`, `server/jobs`, `server/distribution` | The runners (registration, keys, heartbeats, slots, the sweeper), the build jobs, and the runner and CLI tarballs                                                                               |
+| `server/routes/runners`                                | The runner protocol (with a run's `runs/:runId/*` endpoints), the tarballs, the install script and the runners' admin API                                                                       |
+| `server/routes`                                        | The admin, chat and CLI endpoints, and where every endpoint is mounted (`index.ts`)                                                                                                             |
+| `server/providers`                                     | The service providers that assemble and boot the plugin                                                                                                                                         |
+| `shared`                                               | The view models the browser and the API exchange (`models.ts` for online agents' services and catalog)                                                                                          |
+| `client`                                               | The pages and components; `client/online` the model services UI of the Models page; `client/pages/usage/prices` the prices sheet of the Usage page                                              |
+
+## HTTP API
+
+Every route lives under the plugin's namespace, `/api/agents`, and names its own authentication, because callers of different kinds share it. Every JSON answer is `{ data }` (a list `{ data, meta }`: `meta.total` for the bounded lists, `meta.nextPageToken` for runs, an agent's history, variable audits, conversations, messages and a run's events, read with `pageSize` and `pageToken`), and every failure is the standard error body with domain `agents` (`ERROR_API_STATUS` of `@nocobase/agent-protocol` gives each reason's status).
+
+| Routes                                                                                                          | Authenticates                                                     | Purpose                                                                                                                                         |
+| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/api/agents/runners/{register,heartbeat,claim}`, `/api/agents/runners/runs/*`, `/api/agents/runners/jobs/*`    | Runner key header (`register` takes a registration token)         | The runner protocol (`RUNNER_ROUTES`): register, heartbeat, claim, and a run's and a job's lease, start, events, status, ending, skills, mounts |
+| `/api/agents/runners`, `/api/agents/runners/registrationTokens`, `/api/agents/runners/:runnerId[/work,/revoke]` | Session and authorization context (no scoped keys)                | Runners and registration tokens                                                                                                                 |
+| `/api/agents/dist/*`                                                                                            | Runner key, unused registration token, download token, or session | The runner and CLI tarballs (`DIST_ROUTES`); `POST /api/agents/dist/downloadTokens` mints a download token for a person (no scoped keys)        |
+| `/api/agents/dist/installScript`                                                                                | Nothing (it carries no secret)                                    | The script behind the one-line installs of the CLI and, with `--runner`, of a runtime                                                           |
+| `/api/agents/runs/current[/context]`                                                                            | Run token header                                                  | The agent's own run and its context (`RUN_ROUTES`)                                                                                              |
+| `/api/agents/cli/*`                                                                                             | Run token header, or the application's authentication             | The CLI's custom commands (`CLI_ROUTES.command`); the manifest is the application's `GET /api/cli/manifest`                                     |
+| everything else under `/api/agents`                                                                             | Session and authorization context                                 | Agents and brief previews, variables, skills, runs, the vocabulary, usage, prices, conversations, the model services and their models           |
+
+Scoped API keys reach only the routes whose every operation is a settings check (agents, skills, model services, prices and usage); elsewhere they are refused with `SCOPED_KEY_FORBIDDEN`. The API checks four settings items, which the plugin lists under an Agent team subsection of the permission workspace: `agents.agents` (read or manage agents, their variables, skills, and every run; reading also sees every runner), `agents.runners` (read every runner; manage any runner, add team runners; anyone signed in adds personal runners and manages their own), `agents.prices` (the model prices) and `agents.services` (the model services: read lists them, manage adds, edits, tests and deletes them and sets their keys; a scoped key may only read them). It also declares one business action with three levels (`BUSINESS_ACTIONS` and `RELATIONS` in `shared/access.ts`), registered as the `agents` resource type under an Agent team subsection of business, one action per level (`edit.related`, `edit.all`), whose level the application tells it through `agentsAccessToken` (`scopeOf(identity, key)`; unbound, every level is `none`): `agents.agents/edit` changes agents (their settings, skills and variables; archiving, restoring and deleting them) and edits skills (saving, restoring a version), every one at `all` and at `related` the agents the caller owns and the skills they created. Managing agents reaches every one whatever the level; creating agents and skills and deleting skills still need it. Someone editing at a level, without managing agents, does not hand an agent to another owner and adds to it only business actions they hold themselves (the command gate's `allowed`). An agent and a skill answer `canEdit` for the caller. Anyone signed in reads which model services and models online agents may use (`GET /api/agents/models`, names only, chat models unless `?kind=embedding` or `rerank` asks for another kind; `shared/models.ts`), and anyone who reads agents may test one (`POST /api/agents/checkModel`). Anyone signed in reads the system default chat model (`GET /api/agents/defaultModels`), and who manages `agents.services` sets it (`PUT /api/agents/defaultModels/chat`). Anyone signed in sees, cancels and retries the runs they started or own, and reads the vocabulary (labels only). A working directory's or a registered scope's variables and default skills follow the scope's kind: it decides who reads and who changes them.
+
+Realtime announcements carry no content: `agents:runs:<runId>` when a run's status, transcript or input changes and `agents:runners` when a runner changes. A page that hears one fetches through the API.
+
+## Extension points
+
+Everything the application contributes goes through `agentsToken` (`server/tokens.ts`) at boot. Text people read is an `I18nText` (`{ key, ns }`, `shared/i18n`) in the contributor's own namespace.
+
+| Extension point                                                       | What the application gives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `subjects.register(binding)`                                          | A kind of subject runs work on: `kind`, `title`, `triggers` (what `input.payload.trigger` values mean, for the run panel), `preview` (a `SubjectSample`: the assembly of a made-up subject of the kind, its values marked with `sampleValue`, offered as a scenario of "Preview full prompt"), `context.assemble` (the brief's task and context, the turn, the working directories, the scopes, and `guidance`: the subject's own lines of the rules and of the environment check), `sink.onRunFinished`, `queuedExpiryMs` (how long a run may wait for a runner; forever without it), `reports.describe` (a subject's label, whether the person may see it, and its `group`), and `agentTypes` (`['runner']` by default; a kind whose runs need no working directory adds `online`). The claim tells `assemble` how the agent reaches the commands (`claim.dialect`, `cli` or `tools`): name them with `commandRef(dialect, cli, id, flag?)` (`acme issue get` in both: an online agent runs the CLI in its shell, writing files under `/tmp`). |
+| `scopes.register(kind)`                                               | A scope of variables and default skills (`key`, `title`, `description`, `access(scopeId, userId)`). `agent` is reserved; `workdir` is a core key the application registers to decide who may see and change a working directory's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `actions.provide(source)`                                             | The business actions an agent may be configured with (`key`, `group`, `title`, `groupTitle`, `description`, `defaultOn` for the new-agent dialog), and those never granted to an agent, listed only to show the boundary (`grantable: false` with a `reason`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `presets.register(preset)`                                            | A role a new agent can start from (`name`, `nameText`, `description`, `descriptionText`, `instructions`, `actions`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `gate.set(gate)`                                                      | Who holds which business actions: an `ActionGate` answering `allowed(identity)` for a person or a run, and optionally `consultable(action)` for what a consultation may keep besides reading. `gate.allowed` and `gate.reach` answer for a caller; the gate also bounds what a run may do over the API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `conversations.sources.register(source)`                              | A place conversations start from besides the panel (`POST …/chat/start` takes `source` and the first message as the agent should read it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `conversations.contextKinds.register(kind, resolver)`                 | A kind of object a page context may reference, resolved for the message's owner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `conversations.rules.provide(rules)`                                  | Rules and sections added to the system layer of conversation runs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `conversations.deliver(tx, id, news)`, `conversations.lock(conn, id)` | A `news` notice (`type`, English `title`, `params`) written to a conversation, with input that wakes its agent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `people.provide(source)`                                              | The application's directory: names, whom to pick from, and who can no longer act (`inactive`: their runners stop).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `events.on('agent.removed', listener)`                                | An agent was archived or deleted (`agentId`, `name` then, `reason`, `byUserId`), after the transaction that withdrew its queued runs commits: the application lets go of the work it gave the agent. The assembling application clears it as executor of unfinished issues (`server/agents/removal.ts`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `events.on('notice', listener)`                                       | People the plugin wants told (`RunnerNotice`: `key`, `type`, `userIds`, `subject`, English `title` and `body`, `params`): today `runner_upgrade_required`, to a runner's owner; `notice.cleared` names one that no longer holds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `jobs.register(kind, registration)`                                   | A kind of build job, for the off-by-default runner build method (see Jobs above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `reporting.usage`, `reporting.runFigures`, `reporting.range`          | What runs used and cost, grouped by agent, person, `group`, `subject`, day, model, tool or agent `type`, and how the runs of a range went with their usage by type (`usageByType`) and day by day (`daily`: runs by outcome, cost by type), for the application's report pages. The plugin serves usage over HTTP for its usage page (`GET /api/agents/usage`, behind the `usage` page grant; every run for a reader of agents, else the caller's own; `series=true` breaks each day of `daily` down by the grouping).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `briefs.sections.register(provider)`                                  | Sections added to every brief's context layer after the subject's own context (`key`, `order`, `section(conn, claim, assembly)` answering Markdown or null), in claims and in brief previews. The context layer is outside the session fingerprint, so a section that changes does not end a resumable session. Database reads only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `mounts.register(provider)`                                           | Directories of files placed beside the agent (`name`, `forRun(conn, { claim, assembly, session, sessionKey })` answering `{ hash, target, note?, resumeNote? }` or null, and `bundle(conn, { runId })`). Offered at claim only to runners announcing the `mounts` feature, never required, so an older runner runs without them; served at `GET /api/agents/runners/runs/:runId/mounts/:name` while the runner holds the run. A mount's hash stays out of the session fingerprint: a resumed run gets its `resumeNote` in the turn instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `repoAccess.register(provider)`                                       | Per run, in the claim's transaction: who the run's commits name and the short-lived credentials its checkouts push with (`forRun(conn, { claim, repos })` answering `RunGit` or null). It may read from elsewhere in an optional `prepare(run)` before the transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+`GET /api/agents/vocabulary` hands the browser what the application contributed: subjects (title, triggers, preview), conversation sources, and scopes (title, description).
+
+```ts
+const agents = container.resolve(agentsToken);
+agents.subjects.register({
+  kind: 'ticket',
+  title: { key: 'subjects.ticket', ns: '@acme/app' },
+  context: { assemble: (conn, claim) => /* task, context, working directories; database reads only */ },
+  sink: { onRunFinished: (tx, run) => /* tell people how the run ended */ },
+});
+await agents.runs.enqueue({ agentId, subject: { kind: 'ticket', id }, actorUserId, priority: -2, input });
+// Withdraws the work no runner took yet, keeping why as the run's failure detail.
+await agents.runs.withdrawQueued({ subject: { kind: 'ticket', id }, byUserId: null, detail: 'The ticket is on hold.' });
+```
+
+`assemble` runs inside the claim's transaction and must not call a network or a model (nor do brief sections and mounts, which read through the claim's connection only: on SQLite the transaction holds the one connection there is; a section or mount provider reads what it needs from elsewhere, such as a person's permissions, in its optional `prepare(run)`, which runs before the transaction and whose answer it gets back); throwing leaves the run queued, and three failures fail it `setupFailed`. `enqueue` takes an optional outer transaction; inside another plugin's transaction, publish the collected events after that transaction commits.
+
+## The CLI's commands
+
+The CLI's commands are the application's API routes: `GET /api/cli/manifest` (`@nocobase/app-server/router`) answers every command the API document describes for the caller, named and shaped by each route's `x-cli` extension, and this plugin tells it who calls (a run by its run token, a person by the application's authentication) and which business actions each holds (`gate.allowed`). A run token is also a credential of the application's authentication (`server/cli/run-credential.ts`): a request carrying it acts for the person who woke the agent, as a scoped session the routes accept only where their security lists `runToken`; the application bounds it by its scope (for example, `server/agents/run-principal.ts`). A route lists `runToken` and gives its `x-cli` an `action` for the commands a run may use.
+
+The plugin's own commands are its routes. A run uses `run self`, `run context` and `conversation title set` (`GET /api/agents/runs/current`, `/current/context`, `PATCH /current/conversation`, action `agents.runs/self`), and a run or a person `agent list` (`GET /api/agents/available`, action `agents.agents/view`: the agents the caller may give work to, with what each is good at and whether it can take work now). The rest are a person's: `agent list-all|get|create|update|archive|restore|delete|copy|history|brief`, `agent action list`, `agent preset list`, `skill …` (with `skill version …` and `skill attachment get|set`), `variable list|set|delete|reveal` and `variable audit list` (positional scope kind and scope), `runtime list|get|update|revoke|delete|work` and `runtime token create`, `model list|check|usage` and `model price get|set`, `service list|create|update|delete|discover|check`, `conversation list|get|create|update|stop|fallback|restore`, `conversation message list|send`, `conversation preferences|settings get|update`, and `run list|get|events|brief|cancel|retry|usage` and `run workspace reset`. The runner protocol, the downloads and the browser's helpers (the vocabulary, the people picker, the chat agent picker, starting a conversation from a page, marking one read) stay off the command line. The application's routes and custom commands are the rest.
+
+## Workspace
+
+A run's working directories (`SubjectDir`) are a generic capability: a git repository the runner checks out on a branch the subject's domain names (`kind: 'repo'`: `url`, `branch`, `defaultBranch`), or a directory already on one runner, used in place (`kind: 'directory'`). The runner reports what it did to each checkout (`agRunRepos`: branch, head commit, whether it pushed), and "Clean working directory" starts the next run from a fresh checkout. Nothing here knows of pull requests, merges, previews or deployments: those belong to whatever the application builds on top.
+
+## The CLI runs get
+
+The CLI a run gets is the application's `agents.cli` (`resolveAgentCli` in `server/core/runs/policy.ts`): its `name`, the application's id (`agents.app.id`) when left out, and the file the run's token goes in, `.<name>/run.json` unless `credentialFile` says otherwise; The assembling application configures `acme` (`server/config/agents.ts`). Its `cli.package` is, by default, the tarball of that name this application serves for the runner's platform (`archive`, with its version and SHA-256; `server/core/runs/cli-package.ts`), which the runner downloads with its key and unpacks once per version. A runner without the `archives` feature, or a platform with no build, gets `served`'s `fallback` instead, `preinstalled` (the CLI the install script put on its host beside the runner) unless configured. `agents.cli.package` can name an npm package, a tarball or `preinstalled` instead of `{ kind: 'served' }`. `agents.app` names the application to runners; left out, it is the CLI's name, else the application's name.
+
+## Configuration
+
+Variables and model service keys are sealed with the application's secrets service, so the application needs `secrets.keys` (and `SecretsProvider` in `server/app.ts`) before any can be stored; without it, storing or reading one answers `SECRETS_KEY_MISSING` (503). The plugin registers both tables as secrets stores, `@nocobase/app-plugin-agents/variables` and `@nocobase/app-plugin-agents/model-services`, so `pnpm nocobase secrets rotate` reseals them under a new key.
+
+```yaml
+agents:
+  cli: # the CLI runs get; named after app.id when left out
+    name: acme
+    credentialFile: .acme/run.json # .<name>/run.json by default
+    package: { kind: served } # or { kind: npm, package: '<package>', version: 0.1.0 }, or { kind: preinstalled }
+  app: { id: acme, name: Acme } # how runners name this application; the CLI's name, else the application's, by default
+  dist: # optional; the runner and CLI tarballs
+    dir: /srv/runners-dist # relative to the application root; storage/runners/dist by default
+    channel: stable
+    versions: { acme: 0.1.0 } # pin a product instead of the channel's highest
+  server: # optional; online agents' runs, which every instance runs itself
+    enabled: true # false leaves them to the other instances
+    maxSteps: 16 # model calls an online run may make
+    consult: { timeoutMs: 120000, tokenBudget: 200000 } # one agent consulting another (ask_agent)
+  vectors: # optional; vector collections, apart from the application's database
+    store: sqlite-vec # the default; pgvector, or false to turn vectors off
+    path: storage/vectors.sqlite # sqlite-vec's file, relative to the application root
+    # pgvector takes its own PostgreSQL, never the application's connection:
+    # store: pgvector
+    # url: postgres://vectors:secret@db.internal:5432/vectors # or host, port, database, user, password
+    # ssl: true
+  skills: # optional; the skill library
+    disk: s3 # the Drive disk skills' file contents go to; drive.default by default
+```
+
+Skills' file contents are stored once per content at `skills/blobs/<sha256>` on the Drive disk `agents.skills.disk` names, Drive's default disk when it names none; an application without Drive keeps them under `storage/agents`. Moving to another disk does not copy what is stored: copy `skills/blobs/` across first.
+
+Model services are not configured here: they are added on the application's page or through `POST services`.
+
+## Web UI
+
+The plugin registers no routes of its own: an application mounts its pages and joins them to the pages of the runner agents do. The assembling application puts them under "Agent team" in its sidebar.
+
+- `@nocobase/app-plugin-agents/client/routes` exports `agentsRoute` (`/agents`, with the `new` dialog and the `:agentId` page), `runtimesRoute` (`/runtimes`, with the `connect` dialog), `skillsRoute` (`/skills`, with `new` and `:skillId`) and `usageRoute` (`/usage`: what runs used and cost over a date range, filtered by group, agent and person and summed by one of the groupings (`?groupBy=`, agent by default), with a daily chart of tokens or cost above the table, stacked by the top five agents or models when grouped by those (the usage route's `series`), its group and subject named and linked by the vocabulary's `groupTitle`, `path` and `groupPath`; for who reads `agents.prices` a "Set prices" header button opens the prices sheet, `?prices=1`: online models by service and model, coding tools by the models their runs report, each tool with its subscription switch and price rules, changed by who manages it; the note on missing prices links to it). Each page renders its own heading, and stands behind a page grant of the same id as its route name (`agents`, `runtimes`, `skills`, `usage`, exported as `PAGES` from `shared/access`); a page grant only opens the page, and what it shows is decided by the admin API on the settings items. It also exports `modelsRoute` (`/models`), which stands behind `agents.services` read instead: the model services (a page header with "Add service", the system default chat model's select, then a table with one row per service: its name and host, provider type, status and a menu to edit it, turn it on or off or delete it; "Add service" and clicking a row open one dialog with a single form saved at once: provider type when adding, name, base URL, the write-only key as a `SecretInput` (`client/components/secret-input.tsx`: a password field whose empty value keeps the saved key), an OpenCode base URL's note on which provider type serves which of its model families (its session header is sent automatically), connection test, models fetched from the provider or added by id and checked, each with its kind, changeable before and after it is checked, and a Test that checks it as that kind, and an on/off switch), changeable by who manages `agents.services`.
+  - Runtimes (on `/api/agents/runners`): one overview row per runtime — its name with its system, its state with the slots in use ("Busy 1/1", "Offline · 3 hours ago"), its coding tools by sign-in, personal or team, its runner version (marked "Upgradable" when a newer version of the product it runs as is served, with `nocobase-runner update`, or `<cli> runner update` for a CLI that carries the runner; the runner also updates itself) and when it was last seen — with a "…" menu (Edit, then revoke or delete). A row opens the runtime's sheet: General (name, concurrent runs, personal or team after a warning, and "Allow build jobs" only when the application gives runners jobs, as an application's off-by-default runner build method does), Tools (a switch per reported tool with its version, sign-in and, when the API sent it, its path as small text), Local policy (read only: what its owner's policy on the machine lets it take) and Recent runs (`GET /agents/runners/:runnerId/runs`). Only its owner and the managers of runners change it; they and anyone who may use an agent get its host name and its tools' paths from the API, everyone else neither. "Add runtime" asks who it works for (team only for managers of runners), which coding tools it may run (all by default) and its max concurrent runs (1 by default, carried by the token; a runner registered with its own `--slots` keeps that), then shows the one-line install and the `nocobase-runner register` command with a one-time token (copy buttons, expiry), and waits until the runtime connects, then shows the coding tools it reported.
+  - Agents: the list (type, tools, the default model and how many more, where it runs with the runners online for it, or "on the server" and whether its model is offered, active runs, visibility; a type filter; archived ones on request) and an agent's page, whose header sums it up in one line (type, tool or model, where it runs, free or busy, owner), with four tabs kept in `?tab=`; the new-agent dialog asks for the type first, then the fields of that type (its tools and models, model services and models for an online agent from `GET /api/agents/models`; with none, the agent uses the system default chat model, which the dialog names with a link to change it, or says none is offered). General: basics, avatar and instructions with "Preview full prompt" (a scenario switch among the subject kinds that offer a sample, the application's first and a conversation, `?scenario=` on the API; it shows the system prompt in one, with the agent's own prompt marked at its end, and the first message, all rendered on a made-up subject whose values are marked `[sample]`), and who may use it. Capabilities: the tools and models, a compact ordered list (one header row, then one row per entry) whose first row is the default, with rows added, removed and moved up or down (a runner agent's rows a coding tool, a model typed freely with the tool's common models suggested, and an effort among the tool's; an online agent's rows a model service, a model and an effort, each with a Test button; the new-agent dialog uses the same list), skills, the business capabilities grouped by the application's groups with a description each, and the ones never granted to an agent greyed out with the reason (`AgentActionOption.grantable: false`), and whether it confirms before changing data. Runtime (runner agents only): where it runs (any runner, or named ones, and concurrency), the command allowlist and denied patterns, and its environment variables (write-only, revealing them is audited, saved row by row). Editable when the agent says `canEdit`; a bar appears while a tab has unsaved changes and saves them in one request against the revision the page shows, and switching tabs or following a link away asks first. When someone else saved the agent meanwhile, the page reloads and a dialog shows what they changed. History: who changed what and when, long text as a line diff, lists as what was added and removed, variables named without values.
+  - Skills: the library (each skill's name, description, compatibility and whether it holds scripts), and a skill as a directory: its files in a tree beside the selected one (`client/pages/skills/workbench/`), SKILL.md rendered, other text shown, images and PDFs previewed. Editing uses the same workbench: files and folders are created (in a folder chosen from the skill's and the conventional `scripts/`, `references/`, `assets/`), uploaded (also by dropping files onto a folder), renamed and deleted from the tree, never by typing a path; SKILL.md and other Markdown are written beside their preview (in tabs on a narrow pane), with the front matter's problems listed above the source as it is typed. A new skill (`/skills/new`, a covering page) starts from a template of front matter and suggested sections. Versions can be compared with the current one and restored, and the page shows where the skill is attached. When someone saved a version while the editor was open, the draft stays and a banner offers to load the latest version. A scope's default skills list the scripts of the chosen skills, which online agents do not run (`SkillScriptsNotice`).
+  - The new agent, new skill and variable dialogs ask "Discard unsaved changes?" before closing with input in them (NP-200), through `@nocobase/app-client`'s unsaved-changes guard.
+- `@nocobase/app-plugin-agents/client/kit` exports `VariablesSection` and `DefaultSkillsSection` for a scope's settings on the application's pages (`scope` `workdir` or a registered key, with an optional `description`), `useRunnerOptions` for picking the runner a directory is on (with how many runners are `online`), and `useAgentOptions` for picking an agent.
+- `@nocobase/app-plugin-agents/client/runs` exports the headless parts of a subject's runs, for the application to present (the assembling application uses the UI Library's `agent-run-history`): `useSubjectRuns` and `useAgentNames`, `useRunWithTranscript` (a run and its transcript, fetched after the last `seq` seen when the run's realtime topic announces events, and polled every five seconds while the run is open), `useStopRun`, `useRetryRun`, `useRunBrief` and `useWorkspaceReset`. Each reads and writes the plugin's shared query cache.
+- `@nocobase/app-plugin-agents/client/chat` is the agents' chat without its UI. The UI — the panel beside the content area, one conversation as a page, the history and the header, floating and "Ask agent" launchers — is the UI Library's `agent-chat` block (`@nocobase/agent-chat`, installed with `shadcn add @nocobase/agent-chat` into `client/extensions/nocobase-agent-chat/`; its README is `ui-library/registry/agents/agent-chat/README.md` in the NocoBase repository), which the application owns and builds on this entry. What stays here is what has to stay consistent across upgrades: `ChatProvider` around the application's routes (panel state, ⌘J / Ctrl+J, `?chat=<id|new|history>` links, page context, the one subscription to the per-user conversations topic while the chat is available, and optionally `conversationPath`, the application's full-page route of a conversation), `useChatPanel()` (`available` is false without the provider), `chatLinkRoutes(base)` (links under a path the application chooses that open the panel), `useChatContextSource` / `useChatFilterSource` for pages to say what they show, and `ChatExtensionsContext`, with which the application adds items among a conversation's messages (`useTimelineItems`), renders under a message (`renderMessageExtra`), words the news it delivers (`newsText`) and shows a news notice as a card of its own (`renderNews`).
+  - The data hooks `useChatAgents`, `useConversation`, `useConversationMessages` (the newest page first, `loadOlder`, newer messages with `messages?after=<lastSeq>` on each announcement and polled while a run is open, optimistic messages through `dispatch`), `useConversationList(query)` (an infinite query over the viewer's conversations), `useSendMessage`, `useConversationActions` and `useChatApi`, keyed by `chatKeys`; `useLiveRunEvents(runId)` (a run's transcript kept current while it runs) and `useConversationSources()` (where a conversation can start from, translated); the pure models `timelineOrder`, `newConversationAgent`, `noticeText`, `liveStepsView` and `stepLineText`, and `contextChips`, `buildPageContext`, `itemKey`, `selectionPreview`, `filterText` and `SOURCE_ATTRIBUTE` for the context chips; the panel's state helpers (`CHAT_PANEL_STORAGE_KEY`, `CHAT_PARAM`, `CHAT_DOCK_QUERY`, `CHAT_MOBILE_QUERY`, `readPanelState`, `isChatShortcut`, `modifierKeyLabel`); `ChatPanelScope`, `useChatPageTracking`, `CHAT_PANEL_ID` and `CHAT_PANEL_ATTRIBUTE` for a full-page view; and the kit's `AgentAvatar`, `useAgentText` and `useFormatters`. The data hooks read and write this plugin's cache (`agentsQueryClient()`) and word their toasts in its namespace whatever is above them, so a chat UI needs only `ChatProvider` and no `withAgents` wrapper. `client/runs` also exports `useRunEvents`, `useRealtimeTopic` and `useAgentsApi`, and `client/kit` exports `useFormatters`.
+- `@nocobase/app-plugin-agents/client/profile` exports `DefaultAgentPreference`: the person's default chat agent, for the application's preferences page. The agents page shows the system default chat agent at its top, above the list, changed there with a select by who manages `agents.agents` and shown as text to everyone else, and the new-agent dialog starts from a preset (`GET /api/agents/presets`).
+- `@nocobase/app-plugin-agents/client/config` exports `AgentActionCatalogContext`: the agent editor's business actions come from the server (`GET /api/agents/actions`: what the application offers, none without it) unless an application gives another catalog.
+
+Each exported component brings the plugin's translations and its own query cache, so it works inside another plugin's tree.

package/dist/cli/index.d.ts

@@ -0,0 +1,4 @@
+import { type AppCliPlugin } from '@nocobase/app-cli';
+declare const cliPlugin: AppCliPlugin;
+export default cliPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIvE,QAAA,MAAM,SAAS,EAAE,YAKf,CAAC;AAEH,eAAe,SAAS,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,9 @@
+import { defineCliPlugin } from '@nocobase/app-cli';
+import RunnerToken from './runner-token.js';
+const cliPlugin = defineCliPlugin({
+    packageName: '@nocobase/app-plugin-agents',
+    description: "Manage the agents and the runners that run this application's work.",
+    commands: { 'runner-token': RunnerToken },
+});
+export default cliPlugin;
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,mBAAmB,CAAC;AAEvE,OAAO,WAAW,MAAM,mBAAmB,CAAC;AAE5C,MAAM,SAAS,GAAiB,eAAe,CAAC;IAC9C,WAAW,EAAE,6BAA6B;IAC1C,WAAW,EACT,qEAAqE;IACvE,QAAQ,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE;CAC1C,CAAC,CAAC;AAEH,eAAe,SAAS,CAAC"}

package/dist/cli/runner-token.d.ts

@@ -0,0 +1,21 @@
+import { type AgentTool } from '@nocobase/agent-protocol';
+import { AppCommand } from '@nocobase/app-cli';
+import type { Interfaces } from '@oclif/core';
+/** What `agents runner-token` returns, and the `result` of its `--json` document. */
+export interface RunnerTokenResult {
+    readonly token: string;
+    readonly trust: 'team' | 'ownerOnly';
+    /** The coding tools the runner may run; null for every tool. */
+    readonly enabledTools: readonly AgentTool[] | null;
+    readonly expiresAt: string;
+}
+export default class RunnerToken extends AppCommand {
+    static summary: string;
+    static flags: {
+        trust: Interfaces.OptionFlag<string>;
+        owner: Interfaces.OptionFlag<string | undefined>;
+        tools: Interfaces.OptionFlag<string | undefined>;
+    };
+    run(): Promise<RunnerTokenResult>;
+}
+//# sourceMappingURL=runner-token.d.ts.map

package/dist/cli/runner-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-token.d.ts","sourceRoot":"","sources":["../../cli/runner-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IACrC,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,UAAU;IACjD,OAAgB,OAAO,SACqD;IAC5E,OAAgB,KAAK,EAAE;QACrB,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QACjD,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;KAClD,CAaC;IAEW,GAAG,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAoC/C"}

package/dist/cli/runner-token.js

@@ -0,0 +1,52 @@
+import { AGENT_TOOLS } from '@nocobase/agent-protocol';
+import { AppCommand } from '@nocobase/app-cli';
+import { Flags } from '@oclif/core';
+export default class RunnerToken extends AppCommand {
+    static summary = 'Create a one-time token a runner registers with (valid for 10 minutes).';
+    static flags = {
+        trust: Flags.string({
+            default: 'ownerOnly',
+            options: ['team', 'ownerOnly'],
+            description: 'team runs anyone’s work; ownerOnly runs only work the owner started.',
+        }),
+        owner: Flags.string({
+            description: 'The user id that owns the runner (required for ownerOnly).',
+        }),
+        tools: Flags.string({
+            description: `The coding tools the runner may run, comma-separated (${AGENT_TOOLS.join(', ')}); every tool when omitted. They can be changed on the Runtimes page later.`,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(RunnerToken);
+        if (flags.trust === 'ownerOnly' && !flags.owner)
+            this.error('An ownerOnly runner needs --owner <user id>.');
+        const tools = flags.tools
+            ?.split(',')
+            .map((tool) => tool.trim())
+            .filter(Boolean);
+        const unknown = tools?.filter((tool) => !AGENT_TOOLS.includes(tool));
+        if (unknown?.length)
+            this.error(`Unknown coding tool: ${unknown.join(', ')}. Choose from ${AGENT_TOOLS.join(', ')}.`);
+        if (tools && tools.length === 0)
+            this.error('--tools needs at least one coding tool.');
+        // Loaded here rather than at the top of the file: the command tree imports this module for `--help` too.
+        const { agentsToken } = await import('../server/tokens.js');
+        const created = await this.withApp(async ({ app }) => {
+            await app.registerProviders();
+            return app.container
+                .resolve(agentsToken)
+                .runners.createRegistrationToken(flags.owner ?? null, {
+                trust: flags.trust,
+                ...(tools ? { enabledTools: tools } : {}),
+            });
+        });
+        this.log(created.token);
+        return {
+            token: created.token,
+            trust: created.trust,
+            enabledTools: created.enabledTools,
+            expiresAt: created.expiresAt,
+        };
+    }
+}
+//# sourceMappingURL=runner-token.js.map

package/dist/cli/runner-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-token.js","sourceRoot":"","sources":["../../cli/runner-token.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAYpC,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,UAAU;IACjD,MAAM,CAAU,OAAO,GACrB,yEAAyE,CAAC;IAC5E,MAAM,CAAU,KAAK,GAIjB;QACF,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,OAAO,EAAE,WAAW;YACpB,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC;YAC9B,WAAW,EACT,sEAAsE;SACzE,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,WAAW,EAAE,4DAA4D;SAC1E,CAAC;QACF,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,WAAW,EAAE,yDAAyD,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,6EAA6E;SAC1K,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAChD,IAAI,KAAK,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,KAAK;YAC7C,IAAI,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK;YACvB,EAAE,KAAK,CAAC,GAAG,CAAC;aACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC1B,MAAM,CAAC,OAAO,CAAC,CAAC;QACnB,MAAM,OAAO,GAAG,KAAK,EAAE,MAAM,CAC3B,CAAC,IAAI,EAAE,EAAE,CAAC,CAAE,WAAiC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAC7D,CAAC;QACF,IAAI,OAAO,EAAE,MAAM;YACjB,IAAI,CAAC,KAAK,CACR,wBAAwB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACrF,CAAC;QACJ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACxD,yGAAyG;QACzG,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;YACnD,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;YAC9B,OAAO,GAAG,CAAC,SAAS;iBACjB,OAAO,CAAC,WAAW,CAAC;iBACpB,OAAO,CAAC,uBAAuB,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,EAAE;gBACpD,KAAK,EAAE,KAAK,CAAC,KAA6B;gBAC1C,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzD,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC;IACJ,CAAC"}