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:
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 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.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.
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:
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.