Crate motosan_workflow_core

Expand description

§motosan-workflow-core

A general-purpose DAG-based agent workflow engine for orchestrating LLM agents.

This crate is a thin facade that re-exports from three sub-crates:

motosan_workflow_model — types, traits, graph, loader, templates
motosan_workflow_skill — skill system, ACP
motosan_workflow_runtime — execution engine

§Quick Start

use motosan_workflow_core::*;
use serde_json::json;

// Build a workflow
let workflow = Workflow::builder("research")
    .name("Research Pipeline")
    .node(
        Node::agent("researcher")
            .system_prompt("Find key facts about the topic.")
            .build(),
    )
    .node(
        Node::agent("writer")
            .system_prompt("Write a structured report.")
            .input_from("researcher")
            .build(),
    )
    .edge("researcher", "writer")
    .build()
    .unwrap();

§Node Types

Type	Description	LLM
`Node::agent`	LLM-powered agent	Yes
`Node::human`	Human-in-the-loop gate	No
`Node::transform`	Pure function transform	No
`Node::condition`	Conditional branching	No
`Node::loop_node`	Iterative loop with `_loop` context injection	Depends
`Node::sub_workflow`	Nested sub-workflow	Depends
`Node::acp_agent`	ACP coding agent (external CLI agent)	No

§Features

DAG execution: Topological sort with automatic parallelization
YAML/JSON loader: load_workflow and load_workflow_from_str
Schema validation: JSON Schema with auto self-correction
Retry policies: Exponential backoff with Skip/Abort/Fallback modes
Event streaming: WorkflowEvent via tokio mpsc channel
Cost estimation: estimate_cost with per-node token tracking
Skill system: SkillResolver with extends/compose resolution
Node $ref: Reusable node definitions via load_workflow_with_base
Loop context injection: Body nodes receive _loop with iteration, history, previous
8 built-in templates: builtin_workflows

§Feature Flags

Flag	Description
`ag-ui`	AG-UI protocol event adapter
`notify-human`	Telegram notification for human nodes

Modules§

acp
cancel
context
cost
dag
error
event
execution: Execution recording data model for workflow history tracking.
file_execution_store: File-system-backed ExecutionStore implementation.
helpers
llm_bridge
loader: YAML/JSON workflow loader.
node
orch_config: Orchestrator configuration system.
resume
schema
skill: Skill data model and SKILL.md parser.
state: State diffing for recurring workflows.
templates: Built-in workflow templates embedded at compile time.
tool_registry
traits
validation: Agent validation utilities for workflow nodes.
workflow

Structs§

AcpCapabilities: Capabilities exposed by an ACP client handler.
AcpNodeConfig: Configuration for an ACP (Agent Coding Protocol) agent node.
AgentConfig: Configuration for an Agent node.
AgentIssue: A single validation issue associated with a workflow node.
CancellationToken: A token that can be used to cancel a running workflow from an external context.
Checkpoint: Snapshot of a running workflow’s progress, persisted after each AcpNode success so the workflow can be resumed from the last completed node.
ComposeRef: A compose reference that pulls another skill into a specific location.
ConditionBranch: A single branch in a ConditionNode: a JSON pointer path, comparison operator, and value.
ConditionConfig: Configuration for a Condition node.
ConditionResumeState: State needed to replay a condition node’s branch selection.
CostEstimate: Aggregated cost estimate for an entire workflow.
DiffResult: The result of comparing a new value against a previously stored value.
Edge: A directed edge in the workflow graph.
ErrorSummary: Summary of a recurring error.
ExecutionFilter: Filter criteria for querying execution records.
ExecutionObserver: Observer that listens to WorkflowEvents and automatically builds and persists an ExecutionRecord.
ExecutionRecord: Complete record of a single workflow execution.
ExecutionStats: Aggregated statistics across multiple workflow executions.
FileAccessConfig: File access configuration for an ACP agent.
FileExecutionStore: File-system-backed ExecutionStore that stores one JSON file per execution and one checkpoint file per in-flight execution.
FileStateStore: A StateStore backed by JSON files on the local filesystem.
FileSystemSkillProvider: Loads skills from the filesystem.
HumanConfig: Configuration for a Human gate node.
HumanResponse: Response from a human input provider.
LlmCallRecord: Record of a single LLM invocation within a node execution.
LlmResponse: Response from an LLM call, including content and token usage.
LoopConfig: Configuration for a Loop node.
LoopResumeState: State needed to resume a loop from a specific iteration.
McpServerConfig: Configuration for an MCP server to inject into the ACP agent.
Message: A single message in a multi-turn conversation.
ModelPricing: Pricing information for an LLM model.
Node: A single node in a workflow DAG.
NodeCostEstimate: Cost estimate for a single node.
NodeOutput: Output of a single node execution.
NodeRecord: Record of a single node’s execution within a workflow run.
OrchestratorConfig: Top-level orchestrator configuration.
ResumeToken: A serializable token that captures the state of a paused workflow, allowing it to be resumed later (potentially in a different session).
RetryPolicy: Configurable retry behavior for a node.
Runtime: The workflow execution engine.
SessionStore: Minimal file-based session_id persistence for Persistent mode.
SkillDef: A parsed skill definition.
SkillEntry: A single entry in the skill index.
SkillResolver: Resolves skills by name, handling extends inheritance and compose fragment injection.
SubWorkflowConfig: Configuration for a SubWorkflow node (nested workflow composition).
SwarmConfig: Configuration for a Swarm node in the DAG.
SwarmWorkerConfig: Configuration for a worker in a swarm node.
TokenUsage: Granular token usage for a single node, including individual LLM call records.
ToolCallRecord: Record of a single tool invocation made by a node.
ToolCallRequest: A single tool call requested by the LLM.
ToolDefinition: Definition of a tool that can be passed to the LLM.
ToolRegistry: A registry of named tools that can be resolved by agent nodes at runtime.
TransformConfig: Configuration for a Transform node (pure function, async function, or external script).
Workflow: A workflow is a DAG of nodes connected by edges.
WorkflowBuilder
WorkflowContext: Thread-safe shared state for a workflow execution. Stores node outputs and arbitrary key-value data.
WorkflowResult: Result of a complete workflow execution.
WorkflowStats: Per-workflow aggregated statistics.

Enums§

AcpFallback: Fallback behavior when an ACP agent is unavailable.
AcpSessionMode: Session mode for an ACP agent node.
AgencySkill: A skill that an ACP agent can use.
AgentResponse: Response from a workflow LLM call, wrapping motosan_agent_loop::LlmResponse with per-call token tracking that the workflow engine needs for budgeting and cost estimation.
ConditionOp: Comparison operators for condition evaluation.
ExecutionStatus: Overall status of a workflow execution.
FailureMode: What to do when a node exhausts all retries.
ForeachErrorMode: How to handle errors in individual foreach items.
Format: The serialization format for workflow definitions.
IssueSeverity: Severity level of a validation issue.
MessageContent: The content of a message, which may be text, tool calls, or a tool result.
MessageRole: The role of a message sender.
NodeKind: The kind of a workflow node.
NodeStatus: Status of an individual node execution.
SkillSelectStrategy: Strategy for automatic skill selection.
SkillType: The category of a skill.
StopReason: The reason the LLM stopped generating.
SwarmCompletionCriteria: Completion criteria for a swarm node.
TriggerType: How a workflow execution was triggered.
WorkflowError
WorkflowEvent: Events emitted during workflow execution.
WorkflowStatus: The terminal status of a workflow execution.

Traits§

ExecutionStore: Pluggable storage backend for execution records.
HumanInputProvider: Trait for providing human input to HumanNode gates.
IntoInputIds: Trait that allows input_from() to accept both a single string and a collection of strings.
LlmClient: Trait for LLM clients. Implement this to connect to your LLM provider.
SkillProvider: A source that can load skill definitions by name.
StateStore: Persistent key-value store for workflow state.
ToolExecutor: Trait for executing tools requested by the LLM during multi-turn conversations.
WorkflowLlmClient: Thin wrapper trait on top of motosan_agent_loop::LlmClient that adds per-call token tracking required by the workflow engine.

Functions§

auto_select: Run the full auto-select flow.
build_system_prompt: Build a combined system prompt from an optional skill and context files.
builtin_workflow: Load a single built-in workflow template by name.
builtin_workflows: Load all built-in workflow templates.
diff_and_store: Compare value against the previously stored value for key, store the new value, and return a DiffResult describing what changed.
estimate_cost: Estimate cost for a workflow before execution.
load_skill_index: Load a skill index from all .md files in dir.
load_workflow: Load a workflow from a file path. The format is detected from the file extension.
load_workflow_from_str: Load a workflow from a string in the specified format.
load_workflow_with_base: Load a workflow from a file path, resolving $ref paths relative to base_dir.
parse_skill_md: Parse a SKILL.md string into a SkillDef.
resolve_skill_content: Resolve an AgencySkill variant to its markdown content string.
select_by_keyword: Select the best skill using simple keyword matching (offline, no LLM).
select_by_llm: Select the best skill using an LLM routing call.
validate_agents: Validate all agent nodes in workflow and return any issues found.
validate_condition_paths: Check that input_from references on condition-routed target nodes are ancestors of the condition node itself.
workflow_fingerprint: Compute a SHA-256 fingerprint from a workflow’s structural identity.
write_skill_tempfile: Write prompt content to a temporary file and return its TempPath.

Type Aliases§

AsyncTransformFn: The type of an async transform function — supports HTTP calls, file I/O, etc.
Result
TransformFn: The type of a synchronous transform function.

Crate motosan_workflow_core

Crate motosan_workflow_core Copy item path

§motosan-workflow-core

§Quick Start

§Node Types

§Features

§Feature Flags

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate motosan_workflow_core