Struct TurnContext 

pub struct TurnContext {
    pub id: TurnId,
    pub cancel_token: CancellationToken,
    pub timeouts: TimeoutConfig,
    pub tool_allowlist: Option<Vec<String>>,
    pub current_goal_entity_id: Option<i64>,
}

Per-turn execution context shared across phases (loop, compose, persist).

TurnContext is Send + 'static and cheaply cloneable so it can be passed by value into subsystems that may outlive a &mut Turn borrow (background tasks, sub-services extracted to other crates in Phase 2 of the agent decomposition).

It carries only data that is (a) immutable for the duration of the turn or (b) intrinsically Send + Clone (the cancellation token).

Examples

use zeph_context::turn_context::{TurnContext, TurnId};
use zeph_config::security::TimeoutConfig;
use tokio_util::sync::CancellationToken;

let ctx = TurnContext::new(TurnId(0), CancellationToken::new(), TimeoutConfig::default());
assert_eq!(ctx.id, TurnId(0));

Fields

id: TurnId

Monotonically increasing identifier for this turn within the conversation.

cancel_token: CancellationToken

Per-turn cancellation token. A fresh token is created in Agent::begin_turn. Cancelled when the user aborts the turn or the agent shuts down.

timeouts: TimeoutConfig

Effective timeout configuration snapshotted at the start of the turn.

Snapshotting (rather than reading from a shared config) ensures the turn’s timeout policy is stable even if the live config is reloaded mid-turn.

tool_allowlist: Option<Vec<String>>

Optional channel-scoped tool allowlist for this turn.

None means no channel-level restriction applies (other layers may still gate tool access). When Some, only tools whose names appear in the list may be dispatched; any call to a tool not in the list is rejected before execution.

Populated from the active channel’s allowed_tools config by the agent runtime at turn start via TurnContext::with_tool_allowlist.

current_goal_entity_id: Option<i64>

Current goal entity id in the MAGMA graph, used by five-signal causal distance (issue #4374).

Initially always None; populated by the orchestration layer when a goal node can be resolved from the active task description. When None, the causal distance signal contributes zero regardless of w_causal weight (FR-006).

Implementations

impl TurnContext

pub fn new( id: TurnId, cancel_token: CancellationToken, timeouts: TimeoutConfig, ) -> TurnContext

Create a new TurnContext with no channel-level tool restriction.

Use with_tool_allowlist to set a channel-scoped allowlist.

Examples

use zeph_context::turn_context::{TurnContext, TurnId};
use zeph_config::security::TimeoutConfig;
use tokio_util::sync::CancellationToken;

let ctx = TurnContext::new(TurnId(1), CancellationToken::new(), TimeoutConfig::default());
assert_eq!(ctx.id, TurnId(1));
assert!(ctx.tool_allowlist.is_none());

pub fn with_tool_allowlist(self, allowlist: Option<Vec<String>>) -> TurnContext

Set the channel-scoped tool allowlist for this turn.

None clears any existing restriction. Some(vec![]) denies all tools.

Examples

use zeph_context::turn_context::{TurnContext, TurnId};
use zeph_config::security::TimeoutConfig;
use tokio_util::sync::CancellationToken;

let ctx = TurnContext::new(TurnId(0), CancellationToken::new(), TimeoutConfig::default())
    .with_tool_allowlist(Some(vec!["shell".to_owned(), "grep".to_owned()]));
assert!(ctx.is_tool_allowed("shell"));
assert!(!ctx.is_tool_allowed("web_scrape"));

pub fn is_tool_allowed(&self, tool_name: &str) -> bool

Returns true if tool_name is permitted by the channel-level allowlist.

When no allowlist is set (None), all tools are permitted. When the allowlist is Some, only tools explicitly listed are permitted.

Comparison is case-sensitive: "Shell" and "shell" are treated as different names. Callers must normalize tool names to lowercase before populating the allowlist if case-insensitive matching is required.

Examples

use zeph_context::turn_context::{TurnContext, TurnId};
use zeph_config::security::TimeoutConfig;
use tokio_util::sync::CancellationToken;

let unrestricted = TurnContext::new(TurnId(0), CancellationToken::new(), TimeoutConfig::default());
assert!(unrestricted.is_tool_allowed("anything"));

let restricted = unrestricted.with_tool_allowlist(Some(vec!["shell".to_owned()]));
assert!(restricted.is_tool_allowed("shell"));
assert!(!restricted.is_tool_allowed("web_scrape"));

Trait Implementations

impl Clone for TurnContext

fn clone(&self) -> TurnContext

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TurnContext

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

Formats the value using the given formatter.