# bob-runtime

[![crates.io](https://img.shields.io/crates/v/bob-runtime.svg)](https://crates.io/crates/bob-runtime)
[![docs.rs](https://docs.rs/bob-runtime/badge.svg)](https://docs.rs/bob-runtime)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Runtime orchestration layer for the [Bob Agent Framework](https://github.com/longcipher/bob).

## Overview

`bob-runtime` provides the orchestration layer that coordinates agent execution:

- **Scheduler**: Finite state machine for agent turn execution
- **Action Parser**: Parses LLM responses into structured actions
- **Prompt Builder**: Constructs prompts with tool definitions and context
- **Composite Tool Port**: Aggregates multiple tool sources

This crate depends **only** on `bob-core` port traits — never on concrete adapters.

## Architecture

```text
┌─────────────────────────────────────────┐
│         AgentRuntime (trait)            │
├─────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌───────┐ │
│  │Scheduler │→ │Prompt    │→ │Action │ │
│  │  FSM     │  │Builder   │  │Parser │ │
│  └──────────┘  └──────────┘  └───────┘ │
└─────────────────────────────────────────┘
         ↓ uses ports from bob-core
```

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
bob-runtime = "0.2.1"
```

### Example: Creating a Runtime

```rust
use bob_runtime::{AgentBootstrap, AgentRuntime, RuntimeBuilder};
use bob_core::{
    ports::{LlmPort, ToolPort, SessionStore, EventSink},
    types::TurnPolicy,
};
use std::sync::Arc;

fn create_runtime(
    llm: Arc<dyn LlmPort>,
    tools: Arc<dyn ToolPort>,
    store: Arc<dyn SessionStore>,
    events: Arc<dyn EventSink>,
) -> Result<Arc<dyn AgentRuntime>, bob_core::error::AgentError> {
    RuntimeBuilder::new()
        .with_llm(llm)
        .with_tools(tools)
        .with_store(store)
        .with_events(events)
        .with_default_model("openai:gpt-4o-mini")
        .with_policy(TurnPolicy::default())
        .build()
}
```

### Running an Agent Turn

```rust
use bob_core::types::AgentRequest;

let request = AgentRequest {
    input: "Summarize this document in three bullet points".to_string(),
    session_id: "session-123".to_string(),
    model: None,
    context: Default::default(),
    cancel_token: None,
};

let result = runtime.run(request).await?;
```

## Features

- **Finite State Machine**: Robust turn execution with state tracking
- **Streaming Support**: Real-time event streaming via `run_stream()`
- **Tool Composition**: Aggregate multiple MCP servers or tool sources
- **Turn Policies**: Configurable limits for steps, timeouts, and retries
- **Health Monitoring**: Built-in health check endpoints
- **AgentLoop Facade**: Unified slash-command + runtime orchestration for interactive clients

## Modules

- **`scheduler`**: Core FSM implementation for agent execution
- **`action`**: Action types and parser for LLM responses
- **`prompt`**: Prompt construction and tool definition formatting
- **`composite`**: Multi-source tool aggregation

## Documentation

Full API documentation is available at [docs.rs/bob-runtime](https://docs.rs/bob-runtime).

## Related Crates

- **[bob-core](https://crates.io/crates/bob-core)** - Domain types and ports
- **[bob-adapters](https://crates.io/crates/bob-adapters)** - Concrete implementations
- **[bob-cli](https://github.com/longcipher/bob)** - CLI application

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](../../LICENSE.md) for details.
