forge-flowers

use forge_flowers;

#[cfg(not(target_arch = "wasm32"))]
pub mod client;

pub mod error;

#[cfg(not(target_arch = "wasm32"))]
pub mod handler;

#[cfg(not(target_arch = "wasm32"))]
pub mod interceptor;

#[cfg(not(target_arch = "wasm32"))]
pub mod plan;

#[cfg(not(target_arch = "wasm32"))]
pub mod state;

#[cfg(not(target_arch = "wasm32"))]
pub use client::FlowersClient;

pub use error::{ForgeBridgeError, ForgeBridgeResult};

#[cfg(not(target_arch = "wasm32"))]
pub use handler::{BrewWorkflowHandler, ForgeAgentFactory, ForgeWorkflowHandler};

#[cfg(not(target_arch = "wasm32"))]
pub use interceptor::{JournaledProvider, JournaledToolExecutor};

#[cfg(not(target_arch = "wasm32"))]
pub use plan::{execution_info_from_plan, plan_to_workflow_id};

#[cfg(not(target_arch = "wasm32"))]
pub use state::{flowers_state_to_forge, forge_state_to_flowers};

pub struct FlowersClient {

}

pub fn new(runtime: FlowersRuntime) -> Self;

pub async fn submit_agent_run(
        &self,
        config: AgentConfig,
        prompt: impl Into<String>,
        factory: Arc<dyn ForgeAgentFactory>,
    ) -> ForgeBridgeResult<ExecutionId>;

pub async fn submit_brew_run(
        &self,
        plan: ResolvedBrewPlan,
        provider: Arc<dyn LanguageModel>,
    ) -> ForgeBridgeResult<ExecutionId>;

pub async fn get_execution(
        &self,
        id: &ExecutionId,
    ) -> ForgeBridgeResult<Option<ExecutionInfo>>;

pub async fn cancel_execution(&self, id: &ExecutionId) -> ForgeBridgeResult<()>;

pub async fn signal_execution(
        &self,
        id: &ExecutionId,
        name: &str,
        payload: serde_json::Value,
    ) -> ForgeBridgeResult<()>;

pub async fn list_executions(&self) -> ForgeBridgeResult<Vec<ExecutionInfo>>;

#[must_use]
pub fn runtime(&self) -> &FlowersRuntime;

#[derive(Debug, Error)]
pub enum ForgeBridgeError {
    /// The bridge failed to create a Forge agent via the factory.
    ///
    /// This typically indicates a misconfiguration: the factory could not
    /// construct an agent with the given journaled provider and tool registry.
    #[error("handler creation failed for agent '{agent_name}': {reason}")]
    HandlerCreationFailed {
        /// The agent name that was being constructed.
        agent_name: String,
        /// Why construction failed.
        reason: String,
    },

    /// A Brew node failed during execution within the workflow handler.
    ///
    /// Contains the node ID so the caller can identify which step in the
    /// Brew plan caused the failure.
    #[error("node '{node_id}' execution failed: {reason}")]
    NodeExecutionFailed {
        /// The node that failed.
        node_id: String,
        /// Why execution failed.
        reason: String,
    },

    /// The bridge could not map a `ResolvedBrewPlan` to a Flowers workflow.
    ///
    /// This indicates a structural problem with the plan: missing entry nodes,
    /// empty execution order, or an invalid graph topology.
    #[error("plan mapping failed for brew '{brew_id}': {reason}")]
    PlanMappingFailed {
        /// The brew ID of the plan that could not be mapped.
        brew_id: String,
        /// Why the mapping failed.
        reason: String,
    },

    /// During replay, the bridge detected that the input to a journaled call
    /// does not match the cached input from the original execution.
    ///
    /// This is a hard error by default (fail closed). The execution must be
    /// cancelled and restarted if the agent's inputs have changed.
    #[error("replay input mismatch at interface '{interface}' method '{method}': {reason}")]
    ReplayInputMismatch {
        /// The WIT interface of the mismatched call.
        interface: String,
        /// The method of the mismatched call.
        method: String,
        /// Description of what differed.
        reason: String,
    },

    /// The bridge encountered a `ResolvedNodeKind` that it does not know how
    /// to execute in the current version.
    #[error("unsupported node kind '{kind}' in node '{node_id}': {reason}")]
    UnsupportedNodeKind {
        /// The node ID containing the unsupported kind.
        node_id: String,
        /// The kind name that is not supported.
        kind: String,
        /// Additional context.
        reason: String,
    },

    /// An error propagated from the Flowers runtime.
    #[cfg(not(target_arch = "wasm32"))]
    #[error("flowers runtime error: {0}")]
    Flowers(#[from] flowers::FlowersError),

    /// A serialization or deserialization error during bridging.
    #[error("serialization error in bridge: {0}")]
    Serialization(#[from] serde_json::Error),

    /// An error propagated from the Forge agent layer.
    #[error("forge agent error: {0}")]
    ForgeAgent(String),
}

pub type ForgeBridgeResult<T> = Result<T, ForgeBridgeError>;

pub trait ForgeAgentFactory: Send + Sync {
    /// Creates a Forge agent whose LLM calls and tool invocations are
    /// routed through the Flowers execution context for journaling.
    ///
    /// # Arguments
    ///
    /// * `ctx` - The Flowers execution context for this workflow execution.
    ///
    /// # Returns
    ///
    /// A boxed [`Agent`] ready for execution within a Flowers workflow.
    ///
    /// # Errors
    ///
    /// Returns [`ForgeBridgeError::HandlerCreationFailed`] if agent
    /// construction fails (e.g., missing configuration, provider not found).
    fn build(&self, ctx: &ExecutionContext) -> Result<Box<dyn Agent>, ForgeBridgeError>;
}

pub struct ForgeWorkflowHandler {

}

pub fn new(
        factory: Arc<dyn ForgeAgentFactory>,
        config: AgentConfig,
        prompt: impl Into<String>,
    ) -> Self;

#[must_use]
pub fn config(&self) -> &AgentConfig;

#[must_use]
pub fn prompt(&self) -> &str;

pub struct BrewWorkflowHandler {

}

pub fn new(plan: ResolvedBrewPlan, provider: Arc<dyn LanguageModel>) -> Self;

#[must_use]
pub fn plan(&self) -> &ResolvedBrewPlan;

#[must_use]
pub fn with_tool_registry(mut self, tool_registry: ToolRegistry) -> Self;

#[must_use]
pub fn with_approval_handler(mut self, approval: Arc<dyn ApprovalHandler>) -> Self;

#[must_use]
pub fn with_sub_plan(mut self, plan: ResolvedBrewPlan) -> Self;

#[must_use]
pub fn with_sub_plans(mut self, plans: Vec<ResolvedBrewPlan>) -> Self;

pub struct JournaledProvider<'ctx> {

}

pub fn new(inner: Arc<dyn LanguageModel>, ctx: &'ctx ExecutionContext) -> Self;

pub fn model_id(&self) -> &str;

pub fn provider(&self) -> &str;

pub async fn generate(
        &self,
        messages: &[ModelMessage],
        tools: &[ToolDefinition],
        options: &GenerateOptions,
    ) -> Result<GenerateResult, FlowersError>;

pub async fn stream(
        &self,
        messages: &[ModelMessage],
        tools: &[ToolDefinition],
        options: &GenerateOptions,
    ) -> Result<Vec<StreamChunk>, FlowersError>;

pub struct JournaledToolExecutor<'ctx> {

}

pub fn new(ctx: &'ctx ExecutionContext) -> Self;

pub async fn execute<F, Fut>(
        &self,
        tool_id: &str,
        parameters: serde_json::Value,
        execute_fn: F,
    ) -> Result<serde_json::Value, FlowersError>
    where
        F: FnOnce(serde_json::Value) -> Fut + Send,
        Fut: std::future::Future<Output = Result<serde_json::Value, FlowersError>> + Send,;

#[cfg(not(target_arch = "wasm32"))]
pub mod client;

pub mod error;

#[cfg(not(target_arch = "wasm32"))]
pub mod handler;

#[cfg(not(target_arch = "wasm32"))]
pub mod interceptor;

#[cfg(not(target_arch = "wasm32"))]
pub mod plan;

#[cfg(not(target_arch = "wasm32"))]
pub mod state;

#[cfg(not(target_arch = "wasm32"))]
pub use client::FlowersClient;

pub use error::{ForgeBridgeError, ForgeBridgeResult};

#[cfg(not(target_arch = "wasm32"))]
pub use handler::{BrewWorkflowHandler, ForgeAgentFactory, ForgeWorkflowHandler};

#[cfg(not(target_arch = "wasm32"))]
pub use interceptor::{JournaledProvider, JournaledToolExecutor};

#[cfg(not(target_arch = "wasm32"))]
pub use plan::{execution_info_from_plan, plan_to_workflow_id};

#[cfg(not(target_arch = "wasm32"))]
pub use state::{flowers_state_to_forge, forge_state_to_flowers};

#[must_use]
pub fn plan_to_workflow_id(plan: &ResolvedBrewPlan) -> WorkflowId;

pub fn execution_info_from_plan(plan: &ResolvedBrewPlan) -> ForgeBridgeResult<ExecutionInfo>;

#[must_use]
pub fn forge_state_to_flowers(forge_state: LifecycleState) -> ExecutionState;

#[must_use]
pub fn flowers_state_to_forge(flowers_state: ExecutionState) -> LifecycleState;