floret

Floret is a reusable Go engine designed for building interactive AI agents that can use tools. It owns the model loop and the complete admitted Agent lifecycle, handling canonical messages, threads, turns, runs, tools, approvals, todos, artifacts, context, SubAgents, recovery, provider state, prompt cache, and observable execution facts. The host application is responsible for product UI, credentials, provider profiles, resource authorization, routing, read state, uploads before admission, and transport diagnostics. Floret is explicitly not a graph workflow framework, a multi-agent orchestrator, or a product persistence layer. Key features include: - **Durable Lifecycle Management**: Manages thread, turn, and run identities with canonical journaling as the single source of truth. - **Tool Integration**: Supports local tool definitions, permissions, resources, effects, and results, including a secure public-text HTTP/HTTPS fetch tool (`web_fetch`). - **Context Handling**: Maintains canonical messages, references, and context items, supporting compaction and recovery. - **Provider Gateway**: Abstracts model providers through a `provider.Gateway` contract, with official constructors for OpenAI-compatible and DeepSeek providers. - **Storage Abstraction**: Provides opaque storage interfaces with official memory and SQLite implementations, supporting advanced storage integration via SPI. - **Observability**: Emits sanitized runtime events and host-facing projections for monitoring agent execution. - **SubAgents**: Supports hierarchical agent structures with explicit parent-child thread relationships. - **Approval & Interaction**: Manages user approvals, input requests, and interaction responses, including redacted secret handling. The runtime boundary is defined by `runtime.Host`, which provides typed lifecycle services for thread management, including create, fork, delete, send, respond, cancel, retry, and subscribe operations. Floret ensures consistent reads through canonical views and supports coordinated storage startup and restore for multi-store environments. It includes model metadata management via an offline models.dev snapshot and enforces strict model input validation with limited regeneration opportunities for invalid tool arguments.