agently-stage

Agently Stage

Agently 4.1.4.7+ requires agently-stage>=0.3.8,<0.4.0. Use Stage for process-local lifetime, call-shape bridging, replay channels, and local listener dispatch. These APIs are independently useful, while Agently also uses Stage as a private runtime mechanism.

Read by Need

• Stage scopes/backend selection, StageHandle, settlement, cancellation, caller-loop task ownership, pressure, idle timeout, and snapshots: task-lifecycle.md.
• Stage.as_sync/as_async, StageCallBridge, StageStream, Tunnel, EventEmitter, and compatibility names: bridges-streams-events.md.
• TriggerFlow state/signals, workflow close, recovery, or application orchestration: use agently-triggerflow.
• Actions, ExecutionResources, TaskWorkspace, RecordStore, services, or DevTools: use agently-runtime.

Boundary

Choose the smallest surface that matches the caller:

• Direct call/await when caller and work already have the same shape.
• async with Stage() for explicit async lifetime; with Stage() for a deliberate blocking boundary.
• Stage.as_sync/as_async for one scalar adapter.
• Stage.go(...) plus StageHandle for a submitted result that must be read across loops or threads.
• Stage.create_task(...) for caller-loop work Stage creates; adopt(...) only for a task that already exists.
• StageCallBridge for injected lifetime, managed blocking cancellation, or iterator conversion; StageStream for generator replay.
• Tunnel for an independently writable process-local replay channel and EventEmitter for process-local listeners.

A synchronous facade blocks its calling thread. Do not bridge a call that already has the correct native shape.

Invariants

• Body completion and settlement are different facts. Read the body with get()/async_get() and wait for retained descendants/finalizers with wait_settled()/async_wait_settled() when their completion matters.
• Never block the caller-owned loop needed by the work. Use the matching async barrier when Stage reports a lifecycle conflict.
• After cancellation, wait for settlement before claiming no later Stage-owned work can occur. Stage cannot preempt a non-cooperative blocking function or undo an external side effect.
• Put concurrency, pending, worker, and idle limits at their actual pressure boundaries. Carrier-loop count is not application admission control.
• Automatic Stage scopes remain independent even when they safely reuse a carrier.

Stage does not own workflow progression, business retry, persistence, authorization, provider cancellation acknowledgement, or external side effects. TriggerFlowExecution remains Agently's public workflow lifecycle owner; Stage objects and carrier state must not enter execution snapshots.

LocalTaskScope and the historical Stage dispatch/function type names are 0.3 compatibility surfaces. Do not teach them as new owner layers.