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

package/skills/nocobase-app-plugin-agents/references/verification-and-troubleshooting.md

@@ -0,0 +1,47 @@
+# Verification and troubleshooting
+
+## What to test
+
+Test what the App builds on the plugin, not the plugin itself. `@nocobase/app-plugin-agents/testing` assembles the services against a test database (`createAgents`, `AGENTS_MIGRATIONS`), and mounts the run and runner routes on a test server; use it with `createAppTest()` from `@nocobase/app-testing/server`.
+
+- Each subject kind: `assemble` returns the task, context and working directories for a sample subject, reads only the database, and `sink.onRunFinished` does what the App expects for completed and failed runs.
+- The gate: a person holds exactly their actions; a run holds only the waking person's actions its agent is configured with; an API key's scope narrows a person.
+- Routes a run may call: `findUndeclaredApiRoutes(app)` lists none, each route lists `runToken` in its `security`, and the command manifest for a run shows the command only when the gate allows its `action`.
+- Contributed actions and scopes appear in `GET /api/agents/actions` and `GET /api/agents/vocabulary`, and the App's own agents (`ensureSystem`) in `GET /api/agents`.
+
+## Health checks on a running App
+
+| Check                     | How                                                                                                                                                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runners                   | `GET /api/agents/runners` (`runtime list`): `status` (`online`, `offline`, `revoked`, `upgrade_required`), `lastSeenAt`, `tools` (installed, version, signed in), `policy`, `updateVersion`, `requiredProtocol`     |
+| Agents that can take work | `GET /api/agents` (`agent list-all`): every agent, its state and why it cannot take the caller's work (`unusable`); `GET /api/agents/available` (`agent list`): the enabled ones and whether each can take work now |
+| Why a run waits           | The run's detail and `runs.workload()`: `RUN_WAIT_REASONS` (`noRunnerOnline`, `toolUnavailable`, `noSharedRunner`, `missingFeatures`, `secretsNotAllowed`, `concurrencyFull`, `runnersBusy`, …)                     |
+| A run's history           | `GET /api/agents/runs/:runId` and its events (`run get`, `run events`); `failureReason` and `failureDetail`                                                                                                         |
+| Model services            | `GET /api/agents/models` (what the App's own model calls may use), `POST /api/agents/checkModel` (`model check`)                                                                                                    |
+| Tarballs served           | `GET /api/agents/dist/manifest` signed in; `GET /api/agents/dist/products/<product>/targets/linux-x64?format=env`                                                                                                   |
+| Vectors                   | `vectors.status()` on `agentsToken`: availability, store and the `VectorUnavailableCode`                                                                                                                            |
+| The runner itself         | `nocobase-runner status`, `nocobase-runner logs -f [--run <id>]`, `~/.nocobase-runner/policy.json`                                                                                                                  |
+
+## Filtering a run transcript
+
+`GET /api/agents/runs/:runId/events` accepts repeated `type` query parameters (for example, `?type=text&type=input`). The generated `run events` command exposes repeatable `--type` flags. Values are raw protocol event types, not UI groups: `text`, `thinking`, `toolUse`, `toolResult`, `permission`, `input`, `checkout`, `status`, `error`, `usage`. Omitting the filter returns every type. The service equivalent is `agents.runs.events(runId, afterSeq, limit, types?)`. Filtering happens before pagination; retain the same types with `pageToken` or the returned `lastSeq`. These API/CLI filters are exact and do not automatically include errors. A UI that summarizes hidden events must load the complete history and filter locally.
+
+## Troubleshooting
+
+| Symptom                                                                 | Cause and fix                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Runner shows offline                                                    | No heartbeat for 150 s. Check `nocobase-runner status` and `logs`, that its service is installed (`nocobase-runner service install`) and that it reaches the App's URL. `RUNNER_KEY_INVALID` or `RUNNER_REVOKED`: register it again with a new token. `RUNNER_OWNER_DISABLED`: its owner can no longer act (`people.provide` `inactive`). |
+| Runner shows `upgrade_required`                                         | It speaks a protocol outside the App's range. Rebuild and remount the runner tarball from the App's `@nocobase/agent-runner`, then `nocobase-runner update` (an npm-installed runner: `npm install -g @nocobase/agent-runner@<version>`); one that reports no product: reinstall with the one-line install. See [Runners](runners.md).    |
+| Runs queue with `toolUnavailable` or fail `toolAuth`                    | The agent's coding tool is not installed, not enabled for that runner, or not signed in. Sign in on the runner's machine as the runner's user and check the Runtimes page's Tools tab.                                                                                                                                                    |
+| Runs queue with `noRunnerOnline`, `noSharedRunner` or `missingFeatures` | No online runner fits: only other people's personal runners have the agent, or the runner is too old for what the run needs (skills, secrets, mounts). Add or share a runner, or update it.                                                                                                                                               |
+| Run fails `policyRefused`                                               | The runner owner's `policy.json` excludes the agent, subject or repository. Retried on another runner; change the policy on the machine if this one should take it.                                                                                                                                                                       |
+| Run fails `modelUnavailable`                                            | The tool's account on that runner cannot use the model. The runner is marked so and offered none of that model's runs until it reports the tool's models differently; sign in with an account that has the model, or use another agent.                                                                                                   |
+| Run fails `cliUnavailable`                                              | The run's CLI could not be installed: no served tarball for the runner's platform (`PLATFORM_UNSUPPORTED`), or `agents.cli.name` differs from the App's `nocobase.cli.bin`. Build and mount the CLI tarballs.                                                                                                                             |
+| Run fails `setupFailed`                                                 | `assemble`, a brief section or a mount threw three times; read the server log for the throw.                                                                                                                                                                                                                                              |
+| Run fails `queuedExpired`                                               | Waited longer than the subject's `queuedExpiryMs`; see why it waited.                                                                                                                                                                                                                                                                     |
+| `SECRETS_KEY_MISSING` (503)                                             | `secrets.keys` is not configured; set it before storing variables or model service keys.                                                                                                                                                                                                                                                  |
+| `SCOPED_KEY_FORBIDDEN`                                                  | A scoped API key called a route outside the settings-only ones; use a session or an unscoped key.                                                                                                                                                                                                                                         |
+| `PLATFORM_UNSUPPORTED` / `PRODUCT_NOT_FOUND` from the install script    | The product or the platform is not in `agents.dist.dir/<channel>/`; check the mount and the `--targets` the build used.                                                                                                                                                                                                                   |
+| `REGISTRATION_TOKEN_INVALID` / `DOWNLOAD_TOKEN_INVALID`                 | The token expired (10 minutes for registration, 30 for downloads), was used up, or is of the other kind; mint a new one.                                                                                                                                                                                                                  |
+| `VARIABLES_MISSING`                                                     | Not this plugin: a deployment refused because a required deployment variable is unset. Set it where the deploying plugin keeps variables; agent variables never cause it.                                                                                                                                                                 |
+| `SQLITE_VEC_UNSUPPORTED`                                                | No sqlite-vec build for the platform (Alpine/musl); configure `agents.vectors.store: pgvector`.                                                                                                                                                                                                                                           |