> ## 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

# Plugin analysis runtime

`api.runtime.analysis` lets plugins run focused LLM analysis through the same
provider, model, auth profile, and timeout plumbing that WednesdayAI already uses for
agent turns.

Use `run(...)` when the current turn should wait for the result. The examples pass
`event.rawUserText` — the plain text the user sent — rather than
`event.cleanUserMessage.content`, which still carries the inbound framing blocks and may be
a content-block array:

```ts theme={"dark"}
const result = await api.runtime.analysis.run({
  purpose: "topic-detection",
  systemPrompt: "Return a compact JSON object with the topic and confidence.",
  input: event.rawUserText,
  responseFormat: "json",
  timeoutMs: 10_000,
});

if (result.status === "ok" && result.json) {
  return {
    contribution: {
      systemPrompt: `Detected topic: ${JSON.stringify(result.json)}`,
    },
  };
}
```

Use `enqueue(...)` when the current turn should not wait, such as memory extraction or
background indexing:

```ts theme={"dark"}
api.runtime.analysis.enqueue(
  {
    purpose: "memory-extraction",
    systemPrompt: "Extract durable user facts as JSON.",
    input: event.rawUserText,
    responseFormat: "json",
    timeoutMs: 30_000,
    identity: ctx.runtimeIdentity,
    turn: ctx.turn,
    cacheKey: ctx.runtimeIdentity?.providerConversationId,
  },
  async (result) => {
    if (result.status === "ok") {
      await saveFacts(result.json);
    }
  },
);
```

## Correlation metadata

Analysis calls can carry the same SDK identity and turn objects that hooks receive:

```ts theme={"dark"}
await api.runtime.analysis.run({
  purpose: "turn-classification",
  input: event.rawUserText,
  responseFormat: {
    type: "json_schema",
    schema: {
      type: "object",
      properties: { label: { type: "string" } },
      required: ["label"],
    },
  },
  identity: ctx.runtimeIdentity,
  turn: ctx.turn,
  cacheKey: ctx.runtimeIdentity?.providerConversationId,
  metadata: { sourceHook: "context.collect" },
});
```

These fields are additive. Existing callers that pass only `purpose`, `input`,
model options, and timeouts continue to work. `enqueue(...)` carries `identity`,
`turn`, `cacheKey`, and `responseFormat` into the queued in-process job payload
so completion handlers and telemetry can correlate background work with the
originating turn.

Use the typed `identity` and `turn` params for correlation. Do not copy raw
`identityLinks`, raw sender ids that are not already exposed by the hook context,
or provider hash preimages into `metadata`; reserved correlation keys in arbitrary
`metadata` are stripped and replaced by the typed fields.

`cacheKey` is caller-supplied correlation metadata for analysis work. It is metadata only:
WednesdayAI never derives a provider cache key or header from it, so no provider-side
response caching is opted into. It is not a request to expose or recompute raw session
identity. When available, use the opaque `ctx.runtimeIdentity.providerConversationId` or a
plugin-owned derived key.

Analysis runs do not rewrite the raw user message. If a plugin wants analysis to affect
the active turn, it should contribute context through normal hook returns, such as a
`PromptContribution` from `context.collect`.

`api.runtime.analysis` is deliberately bounded to analysis, classification,
extraction, and summarisation. It is not a general subagent runtime. For full
agent delegation, expose a tool or use the documented agent/subagent workflows
instead of trying to run a multi-turn agent through analysis.

## Prompt role mapping

Tool-less analysis runs (no `toolsAllow`) execute as a single direct provider completion:

* `systemPrompt` is sent verbatim as the wire system role for non-JSON requests. When omitted,
  core sends a minimal neutral analysis prompt instead. Nothing else is added on this path: no
  host-agent system prompt, no wrapper text, no `INPUT:` scaffolding.
* `input` is sent verbatim as the sole user message.
* JSON modes are the one documented exception to the verbatim guarantee: when `responseFormat`
  is `"json"` or a `json_schema` object, core appends `Return valid JSON only.` to the system
  role. The user message stays verbatim.
* `provider` and `model`, `maxOutputTokens`, and `temperature` are applied to the wire request.
  `authProfileId` selects the credential profile.
* The call rides the provider plugin transport stack (`wrapStreamFn`), exactly like agent turns.
  Provider plugins apply: Bifrost, for example, stamps `x-bf-conversation-id` derived from the
  caller's `agentId` and the isolated analysis session key `agent:<id>:analysis:<jobId>` (never
  the parent session key), and sends no cache-key header. In-band gateway data (`extra_fields.cost`,
  the resolved `model`) is surfaced on the result instead of being discarded.
* `metadata`, `identity`, `turn`, and `cacheKey` are correlation-only fields. They are never
  forwarded to the provider on this path.

Tool-enabled runs (`toolsAllow` set) still execute through the embedded agent runner, which
builds its own agent system prompt; on that path `systemPrompt` is folded into the user message.
This divergence is intentional. Keep tool-enabled analysis prompts self-contained and treat the
tool-less path as the one with strict payload guarantees.

## Direct-path coalescing and retry

Tool-less calls that are identical and in flight at the same time share one provider call.
"Identical" is decided by a coalescing key over who is asking — runtime `identity`, `turn`,
`sessionKey` (opaque, never parsed), `pluginId`, the resolved `agentId`, and `authProfileId` —
and over the effective request exactly as dispatched: the built system prompt, the messages,
the effective thinking level, temperature, and max output tokens after config resolution,
`responseFormat` (including a `json_schema` body), and `purpose`. The key is built from the same
dispatch plan the leader sends, so a config reload that changes the effective request stops
coalescing. Requests that differ in any of these never coalesce.

* The first caller (the leader) runs as usual and is the one billed for the shared call.
* Later identical callers (followers) do not occupy analysis-lane slots. Each receives a copy of
  the shared result with its own `jobId` and `elapsedMs`, plus a `coalescedWith` field naming the
  leader job that ran the shared call.
* Exactly one subscriber reports the shared call's spend: the leader if it is still subscribed
  when the call settles, otherwise the earliest surviving follower. That subscriber carries the
  `usage`, `usageState`, and cost of the real provider call; every other follower reports
  `usageState: "not_attempted"` with no `usage` and no cost, so the spend ledger counts the
  provider call exactly once.
* Cancellation stays per caller: one caller's abort or timeout ends only that caller's wait and
  never affects the shared run while others remain. The shared provider call is aborted only
  after every caller has left; if the last subscribed caller aborts a call that was already
  dispatched, its own result follows the normal abort contract (`status: "timeout"`,
  `usageState: "unavailable"`). The shared run's deadline is the latest deadline among live
  callers.
* Nothing is cached after the shared run settles. The next identical call starts a new run.

When the gateway replays a truncated cached stream, pi-ai fails the call with
`Stream ended without finish_reason`. The direct transport retries that call exactly once and
asks the provider plugin for a cache bypass on the retry attempt (Bifrost: a fresh
`wai-bypass-<uuid>` `x-bf-cache-key` plus `x-bf-cache-no-store: true`; see
[Providers → Bifrost](https://docs.wednesdayai.dev/next/admin/providers/bifrost.md) and ExpansionX/bifrost#401). Any other error is not
retried. A retried result carries `transportAttempts: 2`. Usage is summed across both attempts
when the first reported real usage; in-band gateway cost is summed only when both attempts
reported it — otherwise attempt 2's value stands for the known part. When the first attempt's
spend is unknown (a truncated stream sends no usage chunk, so nothing billable is evidenced
for it), the result keeps attempt 2's usable verdict and usage but flags the gap with
`unaccountedAttempts: 1`: `usage` and `costUsd` are a lower bound, not the attempt total.

By default, analysis runs are LLM-only. The v1 runtime only supports read-only memory
tools in analysis runs. If a plugin needs memory access, pass a small explicit tool
allow-list:

```ts theme={"dark"}
await api.runtime.analysis.run({
  purpose: "memory-recall",
  systemPrompt: "Find relevant durable memories. Return concise bullets.",
  input: event.rawUserText,
  sessionKey: event.sessionKey,
  toolsAllow: ["memory_search", "memory_get"],
});
```

Only `memory_search` and `memory_get` are accepted in analysis allow-lists. Analysis runs
use a dedicated command lane so awaited hook-time analysis does not queue behind the active
user turn.

Concurrency is two-tier:

* Global `maxParallel` (default 2) concurrent `run(...)` slots across plugins.
  Set `plugins.analysisConcurrency.maxParallel` or a plugin manifest
  `analysisConcurrency.maxParallel` field. Operator global values win when
  set; otherwise WednesdayAI keeps the most permissive value among winning
  enabled manifests.
* Global `maxSequential` (default 0) is the overflow queue for calls blocked by
  either the global or per-plugin active boundary. With the default of 0, extra
  awaited runs are rejected rather than queued.
* Per plugin, inner bounds attach to that plugin's winning enabled manifest.
  Default `maxParallelPerPlugin` is 1 (clamped to `maxParallel`).
  `maxSequentialPerPlugin` inherits `maxSequential` when omitted (clamped to
  `maxSequential`). Operator `maxParallelPerPlugin` / `maxSequentialPerPlugin`
  are a uniform ceiling for every plugin when set. A disabled workspace winner
  does not let a bundled same-id duplicate contribute. Overflow uses one
  eligibility-aware queue; queued awaited runs occupy ordinary global parallel
  slots when started. Background `enqueue(...)` stays 4 active jobs per plugin.
  Saturated background work returns `accepted: false` with `reason: "queue-full"`.

Awaited `run(...)` can occupy a free parallel slot even when a background job is already
running. Nested `run(...)` from inside an analysis run is rejected.

What not to do: do not assume a second same-plugin `run(...)` starts immediately,
and do not assume another plugin's larger inner budget applies to yours.
Without raising this plugin's `maxParallelPerPlugin` (and having a free global
slot), the second call is queued or rejected. Zero overflow caps never queue.

Default timeout is 15 s for `run(...)` and 30 s for background jobs. Caller-supplied
`timeoutMs` is clamped to 250 ms through 120 s. The timeout bounds the whole run,
including credential resolution, not just the provider call. Keep analysis prompts narrow,
set a timeout, and prefer `enqueue(...)` for work that can update plugin-owned state for
future turns. The completion callback runs after the analysis lane is released; keep
callback work bounded anyway, because it still runs inside the plugin host process.

If you call `run(...)` from a plugin hook (especially `context.collect`), the hook itself
also has a 30 s default timeout. Raise it with `api.on(name, handler, { timeoutMs })` or
ask the operator to set `plugins.hookTimeouts`. See [Plugins](https://docs.wednesdayai.dev/next/users/tools/plugin.md#typed-hook-registration-apion).

### Correlating by lane

`providerConversationId` is the opaque provider/cache **session** identity derived from
`agentId + (sessionKey || sessionId)`. It is NOT lane-specific: in a multi-user group agent with
workspace lanes, several lane users can share one `providerConversationId`. To partition correctly
per lane, consumers (e.g. brain/background/cache systems) should dedupe on the composite key:

```text theme={"dark"}
providerConversationId + (laneId ?? canonicalIdentity ?? hashedUserId ?? sessionKey) + turnId + (entryId ?? cursor.entryId ?? rawSha256)
```

`laneId` is the opaque `lane-<hash>` digest, present only for an allowed multi-lane turn and
`undefined` for single-user and denied resolutions. Never correlate on raw `identityLinks` or a
lane hash preimage — they are intentionally stripped from runtime metadata.

Both `run(...)` and `enqueue(...)` validate the requested params synchronously before
claiming the lane or the per-plugin background quota. Invalid requests (empty `purpose`,
empty `input`, a `provider` without a `model`, or a tool that is not in the analysis
allow-list) are rejected immediately — `run(...)` returns `status: "rejected"` with a
descriptive `error`, and `enqueue(...)` returns `accepted: false` with
`reason: "invalid"` — so a misconfigured caller cannot starve the awaited slot or
consume background-queue slots.

## Troubleshooting

* Symptom: `run(...)` returns `status: "rejected"` with
  `error: "analysis concurrency limit exceeded"`.
  Cause: no free global or per-plugin active slot, and no remaining queue
  capacity. Reject logs on subsystem `plugins/runtime/analysis` include
  `admissionBoundary`: `plugin-queue`, `global-queue`, `plugin-active`, or
  `global-active` (zero overflow caps never emit the queue tokens).
  Fix: raise the matching `plugins.analysisConcurrency` field, or `enqueue(...)`
  work that can wait. Restart the gateway after config changes.

System-level failures (timeouts, context overflow, image-size errors, auth/role-ordering
problems) populate `result.error` only and leave `result.text` undefined. The `text`
field is reserved for actual model output, including the case where the model returned
text that failed JSON parsing. Callers should branch on `result.status` first and read
`result.text` only for `"ok"` and JSON-parse `"error"` outcomes.

## Result and job fields

`run(...)` resolves to an `AnalysisResult`:

| Field | Type | Notes |
| - | - | - |
| `status` | `string` | One of: `ok`, `empty`, `timeout`, `error`, `rejected`. Branch on this before reading model output. |
| `text` | `string` | Model text output. Undefined for system-level failures. |
| `json` | `unknown` | Parsed output when `responseFormat` is `"json"` or `json_schema`. |
| `error` | `string` | Rejection, timeout, provider, parse, or runtime error detail. |
| `provider` | `string` | Provider used for the analysis run, when known. |
| `model` | `string` | Model used for the analysis run, when known. |
| `usage` | `{ input?, output?, cacheRead?, cacheWrite?, total? }` | Token/cache accounting reported by the provider path, when available. |
| `usageState` | `string` | `not_attempted` (never reached a provider), `available` (completed with usage), or `unavailable`. |
| `truncated` | `boolean` | Present when the provider signalled an output-length stop; `text` may be partial. |
| `transportAttempts` | `number` | Provider attempts behind this result; `2` after the transport's one cache-bypass retry. |
| `unaccountedAttempts` | `number` | Dispatched attempts whose spend is unknown (e.g. a truncated first attempt with no usage chunk). `usage` and `costUsd` are a lower bound. |
| `coalescedWith` | `string` | Leader `jobId` of the shared direct run this result joined. The one accountable subscriber carries `usage` and cost instead. |
| `costUsd` | `number` | Set by the Gateway only when `usageState` is `available`: the in-band gateway cost when the provider gateway reported one, otherwise the model-entry estimate. |
| `costOrigin` | `string` | Provenance of `costUsd`: `gateway` (in-band, e.g. Bifrost `extra_fields.cost`) or `estimate` (computed from `models.providers`). |
| `responseModel` | `string` | Resolved model reported by the provider response, when present (e.g. a gateway answered with `gpt-4o` while `model` names the proxy id). |
| `elapsedMs` | `number` | Wall-clock runtime for the analysis attempt. |
| `jobId` | `string` | Present for queued jobs and generated runs where correlation needs it. |

`usageState` is authored by the transport, never guessed. `unavailable` means the call was
dispatched but its usage may be missing or synthesized (an error, an abort, or a provider that
reported none); treat it as spent. Pricing has two sources. When the provider gateway reports the
cost in-band (`usage.cost.origin === "gateway"`, e.g. Bifrost's `extra_fields.cost`), that value
is the real spend and wins over any estimate — including `$0` (`costOrigin: "gateway"`); a
`gateway-unpriced` marker counts as missing cost, never `$0`. Otherwise `costUsd` is estimated by
the Gateway from the model entry under `models.providers` (`costOrigin: "estimate"`), and any
`costUsd` a transport supplies is discarded, so plugins never price calls themselves. The
embedded transport has no in-band gateway cost and is always estimated. A model declared there
without a `cost` block has no published price: it gets no `costUsd` (`costSource: "unpriced"`),
exactly like a model with no config entry. A model whose `cost` block is all zeros is priced at
`$0`. Task passes can roll results up with
`createPassUsageAccumulator()` (see [Recording pass measurement](https://docs.wednesdayai.dev/next/developers/concepts/tasks#recording-pass-measurement)).

Pass `signal` (an `AbortSignal`) to cancel a call. A job still waiting in the plugin admission
queue or the shared analysis lane is removed and resolves `rejected` with
`usageState: "not_attempted"`; an in-flight provider call is aborted and resolves with
`usageState: "unavailable"`. On the coalescing direct path, cancelling your call never affects
another caller's shared run — see [Direct-path coalescing and retry](#direct-path-coalescing-and-retry).

`enqueue(...)` returns an `AnalysisJob` immediately:

| Field | Type | Notes |
| - | - | - |
| `jobId` | `string` | Opaque id for the accepted or rejected queued analysis request. |
| `accepted` | `boolean` | `true` when the job was accepted into the in-process queue. |
| `reason` | `string` | One of: `invalid`, `rejected`, `queue-full`, `shutdown`. Present when `accepted` is `false`. |

When using memory tools, pass the originating session key so memory scope rules evaluate
against the source channel or direct chat. The analysis transcript still uses a transient
internal session key and is not synced back to session storage. Analysis is text-only in
v1: prompt text that looks like a local image path is not auto-loaded into the model.
Transient analysis runs also skip workspace cwd changes, skill environment overrides,
sandbox startup, bootstrap context loading, and global hook dispatch.

Provider overrides must include both `provider` and `model`. A provider-only override is
rejected so extensions do not accidentally pair one provider with another provider's
default model id.


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