Struct AgentContext 

pub struct AgentContext<D = ()> { /* private fields */ }

Per-run carrier of infra context + typed operator-side dependencies. D defaults to () so deps-less agents pay no type-system tax.

AgentContext<D> flows into the Tool and validator surfaces. Layers consume ExecutionContext only, reached via Self::core; this keeps the layer ecosystem (tower::Service spine) D-free and avoids generic explosion.

Cloning a context with D: Clone is shallow: the inner ExecutionContext clones cheaply (Arc refcounts on tenant id, extensions, audit sink) and D clones with whatever semantics the operator gave it. Cloning is the canonical path for sub-agent dispatch — children share the parent’s deps and inherit a child cancellation token via Self::child.

Implementations

impl<D> AgentContext<D>

pub const fn new(core: ExecutionContext, deps: D) -> Self

Construct from an explicit ExecutionContext and D.

pub const fn core(&self) -> &ExecutionContext

Borrow the wrapped ExecutionContext. Layers and the tower service spine (ModelInvocation / ToolInvocation) consume the core directly so they stay D-free.

pub const fn core_mut(&mut self) -> &mut ExecutionContext

Mutable handle to the wrapped ExecutionContext. The retry middleware reaches for this to stamp an idempotency key on first entry of a retry loop; outside that path, prefer the with_* builder methods.

pub const fn deps(&self) -> &D

Borrow the typed operator-side deps. Tools consume this directly; the type system enforces that the deps shape matches the agent’s D parameter.

pub const fn deps_mut(&mut self) -> &mut D

Mutable handle to the typed deps. Operators threading per-run mutable state (counters, accumulators) reach for this; most deps are Arc<...> and immutable, so the shared-borrow Self::deps suffices.

pub fn into_parts(self) -> (ExecutionContext, D)

Decompose into (core, deps). Useful when bridging to APIs that consume each half independently.

pub fn map_deps<E, F>(self, f: F) -> AgentContext<E>

where F: FnOnce(D) -> E,

Transform D into E while preserving the infra core. Sub-agents that need a narrower deps shape than the parent project the parent’s deps through this combinator at dispatch time.

pub const fn cancellation(&self) -> &CancellationToken

Borrow the cancellation token (forwarded from ExecutionContext::cancellation).

pub const fn deadline(&self) -> Option<Instant>

Returns the deadline if one was attached.

pub fn thread_id(&self) -> Option<&str>

Borrow the thread identifier if one was attached.

pub const fn tenant_id(&self) -> &TenantId

Borrow the tenant identifier (invariant 11). Always present — defaults to the process-shared TenantId::default when not explicitly set.

pub fn run_id(&self) -> Option<&str>

Borrow the per-execute correlation id, if one has been stamped.

pub fn idempotency_key(&self) -> Option<&str>

Borrow the idempotency key for the current logical call, if one has been stamped (by RetryService on first entry of a retry loop, or pre-allocated by the caller).

pub fn is_cancelled(&self) -> bool

Convenience: did the cancellation token fire?

pub const fn extensions(&self) -> &Extensions

Borrow the typed cross-cutting carrier.

pub fn extension<T>(&self) -> Option<Arc<T>>

where T: Send + Sync + 'static,

Look up the extension entry registered for T. See ExecutionContext::extension.

pub fn run_budget(&self) -> Option<Arc<RunBudget>>

Borrow the RunBudget attached to the run, if any.

pub fn audit_sink(&self) -> Option<Arc<AuditSinkHandle>>

Borrow the AuditSinkHandle attached to the run, if any.

pub fn tool_progress_sink(&self) -> Option<Arc<ToolProgressSinkHandle>>

Borrow the ToolProgressSinkHandle attached to the run, if any.

pub async fn record_phase( &self, phase: impl Into<String> + Send, status: ToolProgressStatus, )

where D: Sync,

Emit a tool-phase transition with no metadata. Silent no-op when no sink is attached or the call is outside a tool dispatch. Fire-and-forget — sink failures stay inside the sink. Forwards to ExecutionContext::record_phase.

pub async fn record_phase_with( &self, phase: impl Into<String> + Send, status: ToolProgressStatus, metadata: Value, )

where D: Sync,

Emit a tool-phase transition with structured metadata. Forwards to ExecutionContext::record_phase_with.

pub fn with_deadline(self, deadline: Instant) -> Self

Attach a deadline. Returns self for builder-style chaining.

pub fn with_thread_id(self, thread_id: impl Into<String>) -> Self

Attach a thread_id.

pub fn with_tenant_id(self, tenant_id: TenantId) -> Self

Override the tenant scope.

pub fn with_run_id(self, run_id: impl Into<String>) -> Self

Attach a run_id.

pub fn with_idempotency_key(self, key: impl Into<String>) -> Self

Attach an idempotency key.

pub fn with_run_budget(self, budget: RunBudget) -> Self

Attach a RunBudget.

pub fn with_audit_sink(self, handle: AuditSinkHandle) -> Self

Attach an AuditSinkHandle.

pub fn with_tool_progress_sink(self, handle: ToolProgressSinkHandle) -> Self

Attach a ToolProgressSinkHandle.

pub fn add_extension<T>(self, value: T) -> Self

where T: Send + Sync + 'static,

Attach a typed cross-cutting value to the Extensions slot. See ExecutionContext::add_extension for the invariant 10 boundary.

impl<D: Clone> AgentContext<D>

pub fn child(&self) -> Self

Derive a scoped child. The child inherits deadline, thread_id, tenant_id, run_id, idempotency_key, and extensions, but holds a child cancellation token and a clone of deps. Cancelling the parent cascades; cancelling the child does not.

Use for scope-bounded fan-out (sub-agent dispatch, scatter branches) where a fail-fast leaf should signal still-running siblings to abort cooperatively without tearing the whole request down.

Trait Implementations

impl<D: Clone> Clone for AgentContext<D>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D: Debug> Debug for AgentContext<D>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentContext<()>

fn default() -> Self

Returns the “default value” for a type.

impl From<ExecutionContext> for AgentContext<()>

fn from(core: ExecutionContext) -> Self

Converts to this type from the input type.