salvor_tools/
context.rs

1//! [`ToolCtx`]: the per-attempt context a tool's
2//! [`call`](crate::ToolHandler::call) receives.
3
4/// What the runtime hands a tool for one execution attempt.
5///
6/// This type is kept deliberately small. The only thing a handler clearly
7/// needs is the idempotency key for the current
8/// attempt: an [`Idempotent`](salvor_core::Effect::Idempotent) tool uses it so
9/// that a retried attempt reuses the same key and the provider collapses the
10/// duplicate into one effect. Everything else a tool might want (recorded
11/// clock, randomness, model calls) belongs to `RunCtx` in the orchestration
12/// layer, not to a single tool call, so it stays out of here.
13///
14/// The type is designed for additive growth. Fields are private and reached
15/// through accessors, so run identity, the current sequence number, or a
16/// tracing span can be added later without breaking a tool's `call` signature.
17///
18/// It is constructed by the runtime, not by tools. The runtime builds
19/// one `ToolCtx` per dispatch from the idempotency key the replay cursor
20/// carries for that tool call; tests construct it directly.
21#[derive(Clone, Debug, Default, PartialEq, Eq)]
22pub struct ToolCtx {
23    idempotency_key: Option<String>,
24}
25
26impl ToolCtx {
27    /// Builds a context carrying the idempotency key for this attempt.
28    ///
29    /// Pass `None` for a tool call that has no key (a [`Read`], or a call the
30    /// runtime chose not to key); pass `Some(key)` for the keyed retry of an
31    /// [`Idempotent`](salvor_core::Effect::Idempotent) tool.
32    ///
33    /// [`Read`]: salvor_core::Effect::Read
34    pub fn new(idempotency_key: Option<String>) -> Self {
35        Self { idempotency_key }
36    }
37
38    /// The idempotency key for the current attempt, if the runtime set one.
39    ///
40    /// An idempotent tool that talks to a provider passes this through as the
41    /// provider's idempotency key so that a retry reuses it and does not create
42    /// a second effect.
43    pub fn idempotency_key(&self) -> Option<&str> {
44        self.idempotency_key.as_deref()
45    }
46}
salvor_tools/context.rs

salvor_tools/
context.rs
