Crate ironflow_core 

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	Execute a shell command with timeout, env control, and kill_on_drop.
Agent	Invoke an AI agent (Claude Code by default) with structured output support.
Http	Perform HTTP requests via reqwest with builder-pattern ergonomics.

Provider trait

The AgentProvider trait abstracts the AI backend. The built-in ClaudeCodeProvider shells out to the claude CLI; swap it for RecordReplayProvider in tests for deterministic, zero-cost replay.

Known limitations: Structured output

When using AgentConfig::output::<T>() to request structured (typed) output from the Claude CLI, be aware of these upstream bugs:

Issue	Impact
claude-code#18536	structured_output reported null when tools are used alongside --json-schema. No longer reproduced with Claude Code 2.1.296 and 2.1.304, so a step may combine tools and .output::<T>(). On an older CLI the answer is read from result, or the step fails with AgentError::SchemaValidation.
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. Defensive deserialization: when deserializing structured output, handle both the expected wrapper object and a bare array/value as fallback.
2. max_turns >= 2: structured output requires at least 2 turns; setting max_turns(1) with a schema will fail with error_max_turns. A step with tools needs one more turn per round of tool calls.

Quick start

use ironflow_core::prelude::*;

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());

Modules

account

Provider Accounts: credentials and usage limits of AI provider accounts.

account_strategy

Selection of a Provider Account for an agent step.

auth_proxy

Auth proxy: the agent pod never holds the Claude credential.

decision

DecisionProvider – typed, calibrated machine decisions.

dry_run

Global dry-run mode control.

error

Error types for ironflow operations.

metric_names

Centralised metric name constants for Prometheus instrumentation.

operation

Operation trait and OperationContext for user-defined step operations.

operations

Workflow operations (shell commands, agent calls, HTTP requests).

parallel

Parallel step execution utilities.

prelude

Re-exports of the most commonly used types.

pricing

Unified LLM cost attribution per step and workflow.

prompt

Agent prompts that mix the workflow’s own text with untrusted content.

provider

Provider trait and configuration types for agent invocations.

providers

Built-in AgentProvider implementations.

retry

Retry policy for transient failures with exponential backoff.

schema_transform

JSON Schema transformations for Claude CLI compatibility.

trace_context

W3C Trace Context propagation for workflow distributed tracing.

tracker

Workflow-level cost, token, and duration tracking.

utils

Utility functions for output handling and OOM protection.