> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Analysis Runtime Operations

# Plugin analysis runtime operations

Plugins can run focused LLM analysis (`api.runtime.analysis`) alongside normal agent turns.
This page covers what operators need: which model and credentials those runs use, the resource
limits that bound them, and how to observe them.

## Model and credential selection

* An analysis run uses the caller-supplied `provider` + `model` pair when the plugin sets one;
  otherwise it falls back to the agent's configured default model (`agents.defaults.model.primary`
  or the per-agent override). A provider without a model is rejected outright.
* Credentials resolve through the same auth-profile plumbing as agent turns. Plugins may pin a
  profile with `authProfileId`; otherwise the default profile order applies. `aws-sdk` auth
  (Amazon Bedrock) and GitHub Copilot token exchange are both supported.
* Tool-less runs (the common case) execute as a single direct provider completion carrying only
  the plugin's prompt and input — they do not load the agent system prompt, so their token cost
  is bounded by what the plugin sends.

## Resource limits

| Limit | Default | Behavior when hit |
| - | - | - |
| Global parallel `run(...)` | 2 | Extra awaited runs queue (`maxSequential`) or reject |
| Global sequential overflow | 0 | With default 0, extra awaited runs reject immediately |
| Per-plugin active `run(...)` | 1 (clamped to `maxParallel`) | Extra same-plugin awaited runs queue (`maxSequentialPerPlugin`) or reject |
| Per-plugin queue | inherits `maxSequential` (clamped) | Extra same-plugin overflow rejects when that plugin's queue is full |
| Background jobs per plugin | 4 active | `enqueue(...)` returns `accepted: false`, `reason: "queue-full"` |
| Timeout default | 15 s awaited, 30 s background | Run returns `status: "timeout"` |
| Timeout clamp | 250 ms through 120 s | Caller-supplied `timeoutMs` clamped into range |

Tune the global analysis budget in `openclaw.json`:

```json5 theme={"dark"}
{
  plugins: {
    analysisConcurrency: {
      maxParallel: 2,
      maxSequential: 0,
      maxParallelPerPlugin: 1,
      // omit maxSequentialPerPlugin to inherit maxSequential
    },
  },
}
```

Operator `plugins.analysisConcurrency` global fields win when set. Otherwise WednesdayAI takes the most
permissive `maxParallel` / `maxSequential` among winning enabled plugin manifests. Inner
`maxParallelPerPlugin` / `maxSequentialPerPlugin` attach to that plugin id. Operator per-plugin fields
are a uniform ceiling when set. Omitting `maxSequentialPerPlugin` inherits `maxSequential`. Config is
snapshotted when plugins load. Restart the gateway after changing it
(Linux: `systemctl --user restart openclaw-gateway`; macOS: `wednesdayai gateway restart --deep`).

The timeout bounds the whole run: model resolution, credential resolution (including OAuth
refresh and Copilot token exchange), and the provider call. Analysis runs execute in the shared
analysis command lane, so they do not compete with the active user turn.

## Plugin hook timeouts

Every plugin hook defaults to 30 seconds. A hung handler is killed and logged instead of
blocking the gateway. Override per hook name (or set `default`) with:

```json5 theme={"dark"}
{
  plugins: {
    hookTimeouts: {
      default: 30000,
      "context.collect": 60000,
    },
    // Deprecated fallback for context.collect / context.project / context.prune only.
    // Used when hookTimeouts does not cover that hook.
    // contextHookTimeoutMs: 30000,
  },
}
```

Cascade: `api.on(..., { timeoutMs })` then `plugins.hookTimeouts` then plugin manifest
`hookTimeouts` then 30 s. Restart required. See [Configuration reference](https://docs.wednesdayai.dev/gateway/configuration-reference.md#plugins).

## Observability

* Every analysis run emits `run.started` and `run.completed` diagnostic events. Direct-path runs
  carry `metadata.analysisTransport: "direct"` so dashboards can split them from embedded agent
  runs. `run.completed` reports `durationMs` and `exitStatus` (`ok` | `error`).
* Logs use the `plugins/runtime/analysis` subsystem. Successful and empty runs log at `info`;
  failures and timeouts log at `warn` with the error text, provider, model, purpose, and plugin id.
  Concurrency rejects log `analysis run rejected` at `info` with
  `error: "analysis concurrency limit exceeded"` and `admissionBoundary`
  (`plugin-queue` | `global-queue` | `plugin-active` | `global-active`).
  Zero overflow caps never emit the queue tokens.
* Results report token usage (`input`, `output`, `cacheRead`, `cacheWrite`, `total`) when the
  provider returns it, so per-plugin analysis cost is attributable from diagnostics consumers
  (e.g. the OTel exporter).

## Failure modes

* `rejected` — invalid request (empty purpose/input, provider without model, disallowed tool) or
  the hierarchical budget is full. Invalid requests reject before any credential or provider work.
  Budget rejects use `error: "analysis concurrency limit exceeded"` and the `admissionBoundary`
  log field above.
* `timeout` — the run exceeded its clamped `timeoutMs`; the provider call is aborted, not
  abandoned.
* `error` — credential resolution failed, the provider returned an error, or JSON output failed
  to parse (model text is preserved in the result for the parse case).

Analysis transcripts are transient: they are not synced to session storage, and analysis runs
skip sandbox startup, workspace cwd changes, and global hook dispatch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.