1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
//! # ironflow-core
//!
//! Core building blocks for the **ironflow** workflow engine. This crate
//! provides composable, async operations that can be chained via plain Rust
//! variables to build headless CI/CD, DevOps, and AI-powered workflows.
//!
//! # Operations
//!
//! | Operation | Description |
//! |-----------|-------------|
//! | [`Shell`](operations::shell::Shell) | Execute a shell command with timeout, env control, and `kill_on_drop`. |
//! | [`Agent`](operations::agent::Agent) | Invoke an AI agent (Claude Code by default) with structured output support. |
//! | [`Http`](operations::http::Http) | Perform HTTP requests via [`reqwest`] with builder-pattern ergonomics. |
//!
//! # Provider trait
//!
//! The [`AgentProvider`](provider::AgentProvider) trait abstracts the AI
//! backend. The built-in [`ClaudeCodeProvider`](providers::claude::ClaudeCodeProvider)
//! shells out to the `claude` CLI; swap it for
//! [`RecordReplayProvider`](providers::record_replay::RecordReplayProvider)
//! in tests for deterministic, zero-cost replay.
//!
//! # Known limitations: Structured output
//!
//! When using [`AgentConfig::output::<T>()`](provider::AgentConfig::output) to request
//! structured (typed) output from the Claude CLI, be aware of these upstream bugs:
//!
//! | Issue | Impact |
//! |-------|--------|
//! | [claude-code#18536] | `structured_output` is always `null` when tools are used alongside `--json-schema`. ironflow prevents this at compile time via typestate (tools and schema are mutually exclusive). |
//! | [claude-code#9058] | The CLI does not validate output against the provided JSON schema -- non-conforming JSON may be returned. |
//! | [claude-agent-sdk-python#502] | Wrapper objects with a single array field may be flattened to a bare array (e.g. `[...]` instead of `{"items": [...]}`). |
//! | [claude-agent-sdk-python#374] | The wrapping behavior is non-deterministic: the same prompt can produce differently shaped output across runs. |
//!
//! **Recommended workarounds:**
//!
//! 1. **Two-step pattern**: use one agent with tools to gather data, then a second
//! agent with `.output::<T>()` (no tools) to structure the result.
//! 2. **Defensive deserialization**: when deserializing structured output, handle
//! both the expected wrapper object and a bare array/value as fallback.
//! 3. **`max_turns >= 2`**: structured output requires at least 2 turns; setting
//! `max_turns(1)` with a schema will fail with `error_max_turns`.
//!
//! [claude-code#18536]: https://github.com/anthropics/claude-code/issues/18536
//! [claude-code#9058]: https://github.com/anthropics/claude-code/issues/9058
//! [claude-agent-sdk-python#502]: https://github.com/anthropics/claude-agent-sdk-python/issues/502
//! [claude-agent-sdk-python#374]: https://github.com/anthropics/claude-agent-sdk-python/issues/374
//!
//! # Quick start
//!
//! ```no_run
//! use ironflow_core::prelude::*;
//!
//! # async fn example() -> Result<(), OperationError> {
//! let files = Shell::new("ls -la").await?;
//!
//! let provider = ClaudeCodeProvider::new();
//! let review = Agent::new()
//! .prompt(&format!("Summarise:\n{}", files.stdout()))
//! .model(Model::HAIKU)
//! .max_budget_usd(0.10)
//! .run(&provider)
//! .await?;
//!
//! println!("{}", review.text());
//! # Ok(())
//! # }
//! ```
/// Workflow operations (shell commands, agent calls, HTTP requests).
/// Re-exports of the most commonly used types.