Agent Signals
Agent Signals are WednesdayAI’s lean Plugin SDK surface for non-user stimuli. They let a plugin publish structured meta-input without pretending that input came from a human conversation. Use signals for small pieces of intent such as watcher output, commitment reminders, inbox summaries, context hints, or background service findings. Keep domain behavior in your plugin. Core only owns flow control, dedupe, admission, and heartbeat dispatch.Modes
The current implementation supports four modes:context: stores the signal for plugin subscribers and future context collection. It does not wake a model turn.heartbeat: stores the signal, queues a session-scoped system event summary, and requests a targeted heartbeat wake.notify: delivers the signalsummaryto the user as an outbound message with no model turn. Anotifysignal requires a non-emptysummaryand a target. The target is resolved fromsessionKey(last channel/sender for that session) or from an explicitdeliveryTarget({ channel, to, accountId?, threadId? }, which overrides the session). Delivery reuses the existing operator gates:showAlerts(permanent suppression), active-hours, and channel readiness. SetrecordAwareness: trueto also enqueue a neutral runtime note —Notification delivered (<source>/<type>) via <channel>., never the summary body — that the next turn can see (requires asessionKey; it is a no-op for adeliveryTarget-only notify). Transient gate failures (active-hours, channel-not-ready, delivery-failed) leave the signal retryable viarequestWake.background: runs an isolated model turn off to the side that does not touch the live conversation. Results go to memory/log; the turn can hand off to the user only via an explicitnotifysignal published through the restrictedsignalstool. See Background mode below.
unsupported-mode:
steer
Runtime API
Plugins access the API throughapi.runtime.signals.
publish() is synchronous and never calls the model directly.
Nudge
api.runtime.signals.nudge(input) is async and grant-gated. It goes through the authorized
coordination seam (requestAuthorizedNudge) and, when allowed, enqueues one durable agent.turn
with kind=nudge on the target agent’s main session. Use it when your plugin has done a cheap
check and found something worth the persona’s attention. Do not hand-build a heartbeat-mode
publish() call for this. See Agent coordination for the model,
grants, and dedupe semantics.
PluginNudgeInput:
sessionKey: plugins always target the target agent’s main session. The call
resolves agentId to the main session and renders text plus any data into the turn message
under an untrusted-author header — Untrusted nudge from plugin "<id>" (not gateway-generated):
followed by the body with every continuation line indented. The target turn receives it in its
untrusted context block, never in the trusted runtime-events block. The call resolves to an
AuthorizedNudgeResult:
ok: true means the agent.turn row is
persisted (status reports queued when the claim chain starts immediately, delayed when the
nudge waits behind an in-flight main turn), not that the turn has run. workId is the
agent-turn:nudge:plugin:<pluginId>:<runId> idempotency key — requester-scoped, so one plugin
can never suppress another’s nudge. The persona stays silent-unless-it-decides.
Grant required. Nudging is denied unless the operator granted your plugin the agents it may
wake:
AuthorizationError — a denial is a thrown error carrying a
grant hint (Grant it with plugins.entries.<id>.grants.agentTurn.agents.), not an
{ ok: false } result, and nothing is enqueued. The same denial emits the
backbone.authz.rejected diagnostic event.
Manifest-declared defaults (bundled plugins only). A bundled plugin may ship a default
grant in its wednesdayai.plugin.json (or legacy openclaw.plugin.json):
plugins.entries.<id>.grants.agentTurn.agents is unset — the
operator key always wins, and an explicit empty list revokes the default. Third-party
(non-bundled) plugins cannot self-grant: a manifest grants field on a non-bundled origin is
ignored.
The CLI (wednesdayai agent nudge) goes through the same authorized seam with
the operator principal. Cron and the heartbeat wake-gate are different: they are trusted internal
producers on the legacy requestNudge path, so they need no grant, are fire-and-forget, and do
not report the refusal reasons above — see
Heartbeat. The equivalent agent-side tool is
agents_nudge (gated by tools.agentToAgent plus the cross-agent
tools.sessions.visibility="all" bar, with the default sandbox clamp).
When the nudge crosses the Gateway protocol boundary (agent.nudge), input is schema-validated:
text is required, data must be an object, and unknown fields are rejected. reason, source,
ttlMs, priority, and requiresIdle are still accepted for compatibility and ignored: a nudge is
an agent.turn with the delay busy policy — it is accepted only after it is persisted in
bus_work_items, then delivers once the lane goes idle (parked delayed turns are capped at 32
per session — a nudge that would be the 33rd is rejected). publish() stays ephemeral and is not queued
across a restart. Only nudge() creates durable agent.turn work: on Gateway
restart, recovery re-arms producer-accepted pending nudge rows; it does not
execute at boot and it does not recover publish() signals. Keep payloads small and prefer
event-derived dedupeKey values when a watcher may report the same finding repeatedly: dedupe is
scoped to (requester, target session, key) and holds for the life of the durable row, not a time
window.
Heartbeat Dispatch
Heartbeat-mode signals bridge into the existing heartbeat system:- The signal is accepted into a bounded in-memory store.
- Core enqueues a system event on the target
sessionKey. - Core requests
requestHeartbeatNow({ reason: "signal:<type>", sessionKey }). - The existing heartbeat runner decides whether to run, skip, or retry based on active hours, heartbeat configuration, main lane activity, cron lane activity, target session activity, and nested lane activity.
- When the heartbeat runs, the signal summary is framed as signal-event context so isolated heartbeat sessions still see the base-session signal content.
skipWhenBusy.
Prompt Visibility
Signals are meta-input, not user messages. Core only exposes the signal summary to the prompt-visible system-event queue:Availability
UsegetAvailability() when your plugin wants to decide whether to publish now, defer, or drop:
requiresIdle: true, core refuses immediate dispatch while availability reports busy and leaves the signal stored for a later requestWake(). The first slice does not run a separate idle watcher; plugins that need guaranteed idle delivery should keep durable state and retry requestWake() or republish a concise signal.
Dedupe And Bounds
The in-memory store applies conservative limits:- 100 signals globally
- 20 signals per target session, agent, or source
- duplicate suppression by
dedupeKey, scoped to the target session, agent, or source — the samededupeKeypublished against two different targets will not collide - duplicate suppression by
source:type:agentId:sessionKeywhendedupeKeyis omitted - lowest-priority oldest-signal eviction when a bounded target or global store is full; the incoming signal is rejected with
queue-fullif every eviction candidate is of strictly higher priority
Background mode
background runs an isolated model turn in a dedicated :background sibling session using the Analysis lane — separate from the main conversation, heartbeat, cron, and subagent lanes.
The turn’s transcript never enters the main conversation. Results go to memory (via allowlisted tools) or to the user only through an explicit notify hand-off.
Signal shape
Isolation and delivery suppression
- Runs in
<sessionKey>:background— a new session created fresh (forceNew) with cleared delivery context. The isolated turn has no implicit route back to any user channel. disableMessageTool: trueandrequireExplicitMessageTarget: trueare always set. The turn cannot message the user directly.disablePluginHooks: trueprevents recursive background/analysis spawning through prompt hooks. It also skips prompt-slot claims and turn-lane resolution, so no plugin-authored text reaches the isolated turn’s prompt.
Tool allowlist
The per-signaltoolsAllow decides the turn’s capabilities. When absent, a conservative default (BACKGROUND_DEFAULT_TOOLS_ALLOW) is applied: read-file, list-files, memory, sessions-history. The message tool is never available regardless.
Notify hand-off
The only user-facing reach from a background turn is publishing anotify signal through the restricted signals tool (only available when the caller includes it in toolsAllow):
Deferral and requiresIdle
notBeforeMs: an in-process timer fires dispatch at the specified time. Pending timers are lost on process restart.requiresIdle: true: dispatch is held until the main, session, cron, subagent, and nested lanes are all idle, checked on a bounded backoff (up to 30 attempts × 1 s).
Awareness record
WhenrecordAwareness: true and the run succeeds, a neutral metadata note is enqueued into the main session:
contextKey: background:<dedupeKey>. Only this fixed string — not the turn output or summary body — is recorded.
Lifecycle events
accepted: signal stored.dispatched: isolated turn completed (ran: true).dropped: reasons:no-handler,not-idle,no-session,run-failed. Transient drops are retryable viarequestWake({ signalId }).
Recommended Pattern
Use Agent Signals as plumbing, not product policy:- Put domain logic in the plugin.
- Publish concise summaries.
- Use
contextmode for passive context. - Use
heartbeatmode when the agent should consider acting soon. - Use
backgroundmode when the agent should think about something without interrupting the current conversation — idle review, dreaming passes, batch analysis, context pre-compute. - Add
dedupeKeyfor recurring or retried stimuli. - Add
ttlMsfor stale alerts. - Avoid including secrets or large payloads.