Wake and continuation

This page defines the current contract for how Holon agents wake from sleep, receive external events, and resolve continuation decisions.

Last verified: 2026-05-23 against src/types.rs ContinuationTriggerKind, ContinuationClass, ContinuationResolution, PendingWakeHint, ExternalTriggerScope, CallbackDeliveryMode, ExternalTriggerSummary, ExternalTriggerCapability, WaitingIntentRecord, and src/runtime/waiting.rs.

Source RFCs

Trigger classification

When an agent is reactivated, the continuation is classified by trigger kind and class:

Trigger kinds (`ContinuationTriggerKind`)

Kind	Source
`OperatorInput`	Direct operator message (CLI, HTTP, TUI)
`TaskResult`	A command task or child-agent task reached a terminal state
`ExternalEvent`	An external system sent a contentful event via ingress URL
`TimerFire`	A scheduled timer elapsed
`InternalFollowup`	The agent enqueued a self-follow-up via `Enqueue`
`SystemTick`	The scheduler emitted a runtime-owned follow-up for a runnable WorkItem

SystemTick is also how Holon resumes other runnable WorkItems after a promoted CompleteWorkItem report ends the current turn.

Continuation classes (`ContinuationClass`)

Class	Meaning
`ResumeExpectedWait`	The trigger matched the prior waiting reason exactly
`ResumeOverride`	The trigger overrides the prior wait (e.g., operator interrupt)
`LocalContinuation`	The agent continued without sleeping (same-turn follow-up)
`LivenessOnly`	Wake hint — does not carry model-visible content

Wake hints vs contentful events

Wake hints are liveness signals. They tell the scheduler "something changed externally, re-evaluate whether the agent should wake". The hint payload is not delivered as a model-visible message. The agent must query the external system for details after waking.

Contentful external events carry an enqueue_message delivery mode. The event payload is delivered as a message in the agent's queue with provenance preserved.

Delivery mode	Behavior
`WakeHint`	Liveness signal; scheduler emits `EmitSystemTick`
`EnqueueMessage`	Full event payload enqueued as a message

External trigger capabilities

Holon provisions a default external ingress capability for each agent at initialization. This is a capability URL with a secret token:

The URL is exposed in the agent's context as default_external_ingress.
External systems POST to this URL to deliver wake hints or events.
The capability is agent-scoped; it can be reused across WorkItems.
Capability revocation is an administrative action, not a per-cycle model tool call.

Capability model

Field	Purpose
`external_trigger_id`	Unique trigger identifier
`trigger_url`	The ingress URL (capability secret)
`target_agent_id`	The agent this trigger wakes
`delivery_mode`	`WakeHint` or `EnqueueMessage`
`scope`	`Agent`
`status`	`Active` or `Revoked`

External triggers are provisioned at agent initialization. Agents do not create or cancel triggers at runtime.

Continuation resolution

When the agent wakes, ContinuationResolution records how the activation occurred:

Field	Meaning
`trigger_kind`	Which kind of event caused the wake
`class`	How the wake relates to the prior wait
`model_reentry`	Whether the model should be re-entered with context
`prior_closure_outcome`	What the prior turn decided
`prior_waiting_reason`	What the agent was waiting for
`matched_waiting_reason`	Whether the trigger matched the reason

Key contract:

model_reentry=true means the model receives continuation context including the prior closure and trigger evidence.
model_reentry=false means the wake is a liveness check; the scheduler re-evaluates posture but may not need to re-enter the model.
matched_waiting_reason distinguishes "expected wake" from "surprise wake". An operator message arriving while waiting for a task result does not match, and the agent may need to handle the interruption.

Known gaps

WaitingIntentRecord retains an internal scope field for scheduler accounting of agent-level versus WorkItem-bound waiting state. External trigger capabilities themselves are agent-scoped and partitioned only by delivery mode.
WakeHint idempotency is implemented via PendingWakeHint deduplication but the contract for when duplicate hints are silently dropped vs surfaced as diagnostics is not yet a stable API.
EnqueueMessage delivery for external events preserves provenance but the provenance taxonomy for external sources is not yet fully specified.