Struct Trampoline 

pub struct Trampoline { /* private fields */ }

Dispatches registered local calls until execution reaches a scheduler boundary.

The trampoline is deliberately small. It knows how to call named Rust functions and how to recognize workflow steps that require an external runtime. It does not own persistence, provider credentials, or scheduling policy.

Implementations

impl Trampoline

pub fn set_observability_config(&mut self, config: ObservabilityConfig)

Set event summarization and validation configuration.

pub async fn run( &self, workflow: Workflow, ) -> Result<WorkflowOutcome, WorkflowError>

Run local workflow steps until the workflow halts or suspends.

Registered calls execute asynchronously in the current task. When a call chooses an Anthropic, human, OpenAI, or fork/join continuation, the trampoline returns the corresponding WorkflowResult instead of performing the external work itself.

Errors

Returns missing-function if a Call step names a function that has not been registered. Also returns any handled::SError produced by a registered call.

Examples

use langcontinuation::{CallFuture, Trampoline, Workflow, WorkflowResult};

#[tokio::main]
async fn main() -> Result<(), handled::SError> {
    let mut trampoline = Trampoline::default();
    trampoline.register("mark", |workflow| -> CallFuture<'_> {
        Box::pin(async move {
            workflow.into_env("done", true).unwrap();
            Ok(())
        })
    });

    let result = trampoline.run(Workflow::new("run", "mark")).await?.result;
    let WorkflowResult::Halt { workflow } = result else {
        panic!("workflow should halt");
    };
    assert_eq!(workflow.from_env::<bool>("done").unwrap(), Some(true));
    Ok(())
}

pub fn next_action(&self, workflow: &Workflow) -> WorkflowNext

Return the next sanitized action the trampoline would take.

pub async fn run_one_local_call( &self, workflow: Workflow, ) -> Result<WorkflowStepOutcome, WorkflowError>

Execute exactly one local call.

Errors

Returns WorkflowError if the workflow is not currently at a local call, if the function is not registered, or if the function itself returns an error.

pub fn resume_anthropic( &self, workflow: Workflow, output_key: impl Into<String>, message: Message, ) -> Result<Workflow, SError>

Store an Anthropic response and advance the suspended workflow.

The workflow must be paused at the Anthropic step that requested output_key. The message is serialized into the environment and the workflow advances to the continuation that was waiting behind the provider step.

Errors

Returns not-suspended-at-anthropic if the workflow is not paused at an Anthropic step, anthropic-output-key-mismatch if the supplied key does not match the suspended step, or invalid-anthropic-response if the response cannot be serialized into the environment.

pub fn resume_human<T: Serialize>( &self, workflow: Workflow, output_key: impl Into<String>, value: T, ) -> Result<Workflow, SError>

Store a human answer and advance the suspended workflow.

The workflow must be paused at the human step that requested output_key. The answer is serialized into the environment and the workflow advances to the continuation that was waiting behind the human request.

Errors

Returns not-suspended-at-human if the workflow is not paused at a human step, human-output-key-mismatch if the supplied key does not match the suspended step, or invalid-human-response if the answer cannot be serialized into the environment.

pub fn resume_tool_call( &self, workflow: Workflow, output_key: impl Into<String>, results: Vec<ToolResultBlock>, ) -> Result<Workflow, SError>

Store tool results and advance the suspended workflow.

The workflow must be paused at the tool-call step that requested output_key. The Vec<ToolResultBlock> is serialized into the environment under that key and the workflow advances to the receiver that was waiting behind the tool-call step. The crate does not thread the blocks into a conversation; the receiver owns the transcript and decides how the results become the next user message.

Errors

Returns not-suspended-at-tool-call if the workflow is not paused at a tool-call step, tool-call-output-key-mismatch if the supplied key does not match the suspended step, or invalid-tool-results if the results cannot be serialized into the environment.

pub fn resume_fork_join( &self, workflow: Workflow, lhs: Workflow, rhs: Workflow, ) -> Result<Workflow, SError>

Merge halted branch workflows and advance the parent to its join call.

Branch environments are compared to the parent environment captured at the fork. A key changed by only one branch is accepted. A key changed by both branches is accepted only when both branches wrote the same JSON value.

Errors

Returns not-suspended-at-fork-join if the parent is not paused at a fork/join step, fork-join-branch-not-halted if either branch still has work remaining, or fork-join-env-conflict if branches wrote conflicting values for the same environment key.

pub fn resume_open_ai<T: Serialize>( &self, workflow: Workflow, output_key: impl Into<String>, value: T, ) -> Result<Workflow, SError>

Store an OpenAI response value and advance the suspended workflow.

OpenAI is represented in the workflow state machine, but the bundled live executor does not yet perform OpenAI requests. Custom runtimes can use this method to resume workflows after they have obtained a response from a suitable Rust OpenAI client.

Errors

Returns not-suspended-at-openai if the workflow is not paused at an OpenAI step, or invalid-openai-response if value cannot be serialized into the environment.

pub fn register( &mut self, function: impl Into<String>, implementation: impl for<'a> Fn(&'a mut Workflow) -> CallFuture<'a> + 'static, )

Associate an exact function name with a local workflow call.

Names used by Workflow::new, Continuation::call, and ForkBranch::new must match a registration name exactly before the trampoline can execute that call. Registering the same name again replaces the previous implementation.

Examples

use langcontinuation::{CallFuture, Trampoline, Workflow, WorkflowResult};

#[tokio::main]
async fn main() -> Result<(), handled::SError> {
    let mut trampoline = Trampoline::default();
    trampoline.register("entry", |workflow| -> CallFuture<'_> {
        Box::pin(async move {
            let run_id = workflow.run_id().to_string();
            workflow.into_env("visited", run_id).unwrap();
            Ok(())
        })
    });

    let WorkflowResult::Halt { workflow } =
        trampoline.run(Workflow::new("run", "entry")).await?.result
    else {
        panic!("workflow should halt");
    };
    assert_eq!(
        workflow.from_env::<String>("visited").unwrap(),
        Some("run".to_string())
    );
    Ok(())
}

Examples found in repository

examples/durable_tool_call.rs (line 181)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut workflow = Workflow::new("durable-tool-call", "entry");
    push_env!(workflow.question: String = "What is 21 plus 21?".to_string());

    let mut trampoline = Trampoline::default();
    trampoline.register("entry", entry);
    trampoline.register("receive", receive);
    trampoline.register("after_tools", after_tools);
    trampoline.register_tool(CalculatorTool);

    let anthropic = Anthropic::new(None)?;
    let executor = Executor::new(trampoline).with_anthropic("anthropic", anthropic);
    let workflow = executor.run_workflow(workflow).await?;

    from_env!(let answer: String = workflow.lookup());
    println!("{answer}");
    Ok(())
}

examples/three_stage_support_pipeline.rs (line 36)

async fn main() -> Result<(), handled::SError> {
    async {
        let ticket = Ticket {
            id: "ticket-001".into(),
            what:
                "Customer reports that chargeback details are missing from the invoice export UI."
                    .into(),
        };
        let mut workflow = Workflow::new("ticket-001", "triage_ticket");
        push_env!(workflow.input_ticket: Ticket = ticket);

        let mut trampoline = Trampoline::default();
        trampoline.register("triage_ticket", triage_ticket);
        trampoline.register("close_ticket_with_reason", close_ticket_with_reason);

        let executor = Executor::new(trampoline);
        let workflow = executor.run_workflow(workflow).await?;
        from_env!(let reason: String = workflow.lookup());
        println!("{reason}");
        Ok(())
    }
    .await
}

examples/tool_calling_and_web_searching.rs (line 655)

fn register_workflow(config: &RunConfig) -> Trampoline {
    let mut trampoline = Trampoline::default();
    trampoline.register("entrypoint", entrypoint);
    trampoline.register("start_langchain_branch", start_langchain_branch);
    trampoline.register(
        "start_langcontinuation_branch",
        start_langcontinuation_branch,
    );
    trampoline.register("ask_langchain", ask_langchain);
    trampoline.register("ask_langcontinuation", ask_langcontinuation);
    trampoline.register("handle_langchain_response", handle_langchain_response);
    trampoline.register(
        "handle_langcontinuation_response",
        handle_langcontinuation_response,
    );
    trampoline.register("after_langchain_tools", after_langchain_tools);
    trampoline.register("after_langcontinuation_tools", after_langcontinuation_tools);
    trampoline.register("start_join", start_join);
    trampoline.register("ask_join", ask_join);
    trampoline.register("handle_join_response", handle_join_response);
    trampoline.register("after_join_tools", after_join_tools);
    // One registered tool serves every branch and the join.
    trampoline.register_tool(TextEditorTool::new(config));
    trampoline
}

pub fn register_tool(&mut self, tool: impl Tool + 'static)

Register a client-side Tool under a name.

The name should match the name field of the ToolUseBlock values the model emits. A runtime resolves a WorkflowResult::ToolCall by looking up each tool_use by name in this registry. Registering the same name again replaces the previous tool. Tools are held only by the trampoline; they are never serialized into a Workflow.

Examples

use std::pin::Pin;
use std::future::Future;
use langcontinuation::{Tool, ToolCallId, Trampoline};
use claudius::{ToolResultBlock, ToolUnionParam, ToolUseBlock};

struct Echo;
impl Tool for Echo {
    fn name(&self) -> String {
        "echo".into()
    }
    fn to_param(&self) -> ToolUnionParam {
        unimplemented!("doc test does not advertise the tool")
    }
    fn call<'a>(
        &'a self,
        _id: ToolCallId,
        tool_use: &'a ToolUseBlock,
    ) -> Pin<Box<dyn Future<Output = ToolResultBlock> + Send + 'a>> {
        let id = tool_use.id.clone();
        Box::pin(async move { ToolResultBlock::new(id).with_string_content("ok".into()) })
    }
}

let mut trampoline = Trampoline::default();
trampoline.register_tool(Echo);

Examples found in repository

examples/durable_tool_call.rs (line 184)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut workflow = Workflow::new("durable-tool-call", "entry");
    push_env!(workflow.question: String = "What is 21 plus 21?".to_string());

    let mut trampoline = Trampoline::default();
    trampoline.register("entry", entry);
    trampoline.register("receive", receive);
    trampoline.register("after_tools", after_tools);
    trampoline.register_tool(CalculatorTool);

    let anthropic = Anthropic::new(None)?;
    let executor = Executor::new(trampoline).with_anthropic("anthropic", anthropic);
    let workflow = executor.run_workflow(workflow).await?;

    from_env!(let answer: String = workflow.lookup());
    println!("{answer}");
    Ok(())
}

examples/tool_calling_and_web_searching.rs (line 675)

fn register_workflow(config: &RunConfig) -> Trampoline {
    let mut trampoline = Trampoline::default();
    trampoline.register("entrypoint", entrypoint);
    trampoline.register("start_langchain_branch", start_langchain_branch);
    trampoline.register(
        "start_langcontinuation_branch",
        start_langcontinuation_branch,
    );
    trampoline.register("ask_langchain", ask_langchain);
    trampoline.register("ask_langcontinuation", ask_langcontinuation);
    trampoline.register("handle_langchain_response", handle_langchain_response);
    trampoline.register(
        "handle_langcontinuation_response",
        handle_langcontinuation_response,
    );
    trampoline.register("after_langchain_tools", after_langchain_tools);
    trampoline.register("after_langcontinuation_tools", after_langcontinuation_tools);
    trampoline.register("start_join", start_join);
    trampoline.register("ask_join", ask_join);
    trampoline.register("handle_join_response", handle_join_response);
    trampoline.register("after_join_tools", after_join_tools);
    // One registered tool serves every branch and the join.
    trampoline.register_tool(TextEditorTool::new(config));
    trampoline
}

pub fn tool(&self, name: &str) -> Option<Arc<dyn Tool>>

Look up a registered tool by name.

Runtimes use this while performing a WorkflowResult::ToolCall. Returns None if no tool was registered under the name.

pub async fn run_tool_calls( &self, run_id: &str, tool_uses: &[ToolUseBlock], ) -> Result<Vec<ToolResultBlock>, SError>

Run every tool_use block through the registered tools.

This is the shared dispatch used by both the live and batch runtimes when they perform a WorkflowResult::ToolCall. Each tool_use is resolved by name with Self::tool, assigned a replay-deterministic ToolCallId from run_id and the tool_use id, and executed in order. The returned blocks are in the same order as tool_uses.

Errors

Returns missing-tool if any tool_use names a tool that is not registered.

Trait Implementations

impl Default for Trampoline

fn default() -> Trampoline

Returns the “default value” for a type.