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:
enqueue(...) when the current turn should not wait, such as memory extraction or
background indexing:
Correlation metadata
Analysis calls can carry the same SDK identity and turn objects that hooks receive: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 (notoolsAllow) execute as a single direct provider completion:
systemPromptis 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, noINPUT:scaffolding.inputis sent verbatim as the sole user message.- JSON modes are the one documented exception to the verbatim guarantee: when
responseFormatis"json"or ajson_schemaobject, core appendsReturn valid JSON only.to the system role. The user message stays verbatim. providerandmodel,maxOutputTokens, andtemperatureare applied to the wire request.authProfileIdselects the credential profile.- The call rides the provider plugin transport stack (
wrapStreamFn), exactly like agent turns. Provider plugins apply: Bifrost, for example, stampsx-bf-conversation-idderived from the caller’sagentIdand the isolated analysis session keyagent:<id>:analysis:<jobId>(never the parent session key), and sends no cache-key header. In-band gateway data (extra_fields.cost, the resolvedmodel) is surfaced on the result instead of being discarded. metadata,identity,turn, andcacheKeyare correlation-only fields. They are never forwarded to the provider on this path.
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 — runtimeidentity, 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
jobIdandelapsedMs, plus acoalescedWithfield 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 reportsusageState: "not_attempted"with nousageand 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.
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 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:
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) concurrentrun(...)slots across plugins. Setplugins.analysisConcurrency.maxParallelor a plugin manifestanalysisConcurrency.maxParallelfield. 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
maxParallelPerPluginis 1 (clamped tomaxParallel).maxSequentialPerPlugininheritsmaxSequentialwhen omitted (clamped tomaxSequential). OperatormaxParallelPerPlugin/maxSequentialPerPluginare 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. Backgroundenqueue(...)stays 4 active jobs per plugin. Saturated background work returnsaccepted: falsewithreason: "queue-full".
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.
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:
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(...)returnsstatus: "rejected"witherror: "analysis concurrency limit exceeded". Cause: no free global or per-plugin active slot, and no remaining queue capacity. Reject logs on subsystemplugins/runtime/analysisincludeadmissionBoundary:plugin-queue,global-queue,plugin-active, orglobal-active(zero overflow caps never emit the queue tokens). Fix: raise the matchingplugins.analysisConcurrencyfield, orenqueue(...)work that can wait. Restart the gateway after config changes.
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:
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).
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.
enqueue(...) returns an AnalysisJob immediately:
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.