Struct ToolCallContext 

pub struct ToolCallContext<'a> { /* private fields */ }

Execution context for tool invocations.

Provides typed state access (read/write), run policy access, identity, message queuing, and activity tracking. Tools receive &ToolCallContext instead of &Thread.

Implementations

impl<'a> ToolCallContext<'a>

pub fn new( doc: &'a DocCell, ops: &'a Mutex<Vec<Op>>, call_id: impl Into<String>, source: impl Into<String>, run_policy: &'a RunPolicy, pending_messages: &'a Mutex<Vec<Arc<Message>>>, activity_manager: Arc<dyn ActivityManager>, ) -> Self

Create a new tool call context.

pub fn as_read_only(self) -> Self

Mark this context as read-only; state writes via apply_op are rejected.

pub fn with_cancellation_token(self, token: &'a CancellationToken) -> Self

Attach cancellation token.

pub fn with_run_identity(self, run_identity: RunIdentity) -> Self

pub fn with_caller_context(self, caller_context: CallerContext) -> Self

pub fn with_tool_call_progress_sink( self, sink: Arc<dyn ToolCallProgressSink>, ) -> Self

Override the sink used for tool-call progress payload forwarding.

This allows runtime integrations to decouple progress collection from activity transport details.

pub fn doc(&self) -> &DocCell

Borrow the underlying document cell.

pub fn call_id(&self) -> &str

Current call id (typically the tool_call_id).

pub fn idempotency_key(&self) -> &str

Stable idempotency key for the current tool invocation.

Tools should use this value when implementing idempotent side effects.

pub fn source(&self) -> &str

Source identifier used for tracked patches.

pub fn is_cancelled(&self) -> bool

Whether the run cancellation token has already been cancelled.

pub async fn cancelled(&self)

Await cancellation for this context.

If no cancellation token is available, this future never resolves.

pub fn cancellation_token(&self) -> Option<&CancellationToken>

Borrow the cancellation token when present.

pub fn run_policy(&self) -> &RunPolicy

Borrow the run policy.

pub fn run_identity(&self) -> &RunIdentity

pub fn caller_context(&self) -> &CallerContext

pub fn state<T: State>(&self, path: &str) -> T::Ref<'_>

Typed state reference at path.

pub fn state_of<T: State>(&self) -> T::Ref<'_>

Typed state reference at the type’s canonical path.

Panics if T::PATH is empty (no bound path via #[tirea(path = "...")]).

pub fn call_state<T: State>(&self) -> T::Ref<'_>

Typed state reference for current call (tool_calls.<call_id>).

pub fn tool_call_state_for( &self, call_id: &str, ) -> TireaResult<Option<ToolCallState>>

Read persisted runtime state for a specific tool call.

pub fn tool_call_state(&self) -> TireaResult<Option<ToolCallState>>

Read persisted runtime state for current call_id.

pub fn set_tool_call_state_for( &self, call_id: &str, state: ToolCallState, ) -> TireaResult<()>

Upsert persisted runtime state for a specific tool call.

pub fn set_tool_call_state(&self, state: ToolCallState) -> TireaResult<()>

Upsert persisted runtime state for current call_id.

pub fn clear_tool_call_state_for(&self, call_id: &str) -> TireaResult<()>

Remove persisted runtime state for a specific tool call.

pub fn clear_tool_call_state(&self) -> TireaResult<()>

Remove persisted runtime state for current call_id.

pub fn resume_input_for( &self, call_id: &str, ) -> TireaResult<Option<ToolCallResume>>

Read resume payload for a specific tool call.

pub fn resume_input(&self) -> TireaResult<Option<ToolCallResume>>

Read resume payload for current call_id.

pub fn add_message(&self, message: Message)

Queue a message addition in this operation.

pub fn add_messages(&self, messages: impl IntoIterator<Item = Message>)

Queue multiple messages in this operation.

pub fn activity( &self, stream_id: impl Into<String>, activity_type: impl Into<String>, ) -> ActivityContext

Create an activity context for a stream/type pair.

pub fn progress_stream_id(&self) -> String

Stable stream id used by default for this tool call’s progress activity.

pub fn report_tool_call_progress( &self, update: ToolCallProgressUpdate, ) -> TireaResult<()>

Publish a typed tool-call progress node update.

The update is written to activity(progress_stream_id(), "tool-call-progress") with payload schema tool-call-progress.v1.

pub fn snapshot(&self) -> Value

Snapshot the current document state.

Returns the current state including all write-through updates. Equivalent to Thread::rebuild_state() in transient contexts.

pub fn snapshot_of<T: State>(&self) -> TireaResult<T>

Typed snapshot at the type’s canonical path.

Reads current doc state and deserializes the value at T::PATH.

pub fn snapshot_at<T: State>(&self, path: &str) -> TireaResult<T>

Typed snapshot at an explicit path.

Reads current doc state and deserializes the value at the given path.

pub fn take_patch(&self) -> TrackedPatch

Extract accumulated patch with context source metadata.

pub fn has_changes(&self) -> bool

Whether state has pending transient changes.

pub fn ops_count(&self) -> usize

Number of queued transient operations.