096 NEW PLAN AROUND JIDO 03

Excellent. This is the logical next step: translating the conceptual architecture into a concrete, organized codebase within a single monorepo.

The goal is to structure the foundation repository so that it contains not just the “kernel” but also the “runtime” and “application” layers as distinct OTP applications within its lib/ directory. This creates a powerful, cohesive system that is easy to navigate, test, and extend.

Here is the proposed monorepo layout and a discussion of the rationale.

High-Level Monorepo Structure

We will structure the codebase into three primary OTP applications residing inside the foundation/lib/ directory. This creates a clear dependency hierarchy where higher layers depend on lower layers, but not the other way around.

• foundation/lib/foundation_kernel: Tier 1 (The Kernel) - The stable, generic infrastructure.
• foundation/lib/jido_runtime: Tier 2 (The Agent Runtime) - The programming model and execution engine for agents.
• foundation/lib/jido_mabeam: Tier 3 (The Application Logic) - The specific business and coordination logic implemented as agents.

Dependency Flow: jido_mabeam -> jido_runtime -> foundation_kernel

New foundation Monorepo Code Layout

foundation/
├── lib/
│   ├── foundation_kernel/      # TIER 1: The OS/Kernel
│   │   ├── application.ex      # Starts all Tier 1 services
│   │   ├── beam/
│   │   │   └── subsystem_supervisor.ex
│   │   ├── contracts/
│   │   │   ├── configurable.ex
│   │   │   ├── event_store.ex
│   │   │   └── telemetry.ex
│   │   ├── coordination/
│   │   │   └── primitives.ex
│   │   ├── infrastructure/
│   │   │   ├── circuit_breaker.ex
│   │   │   ├── connection_manager.ex
│   │   │   └── rate_limiter.ex
│   │   ├── process_registry/
│   │   │   ├── backend.ex
│   │   │   └── backends/
│   │   │       ├── ets.ex
│   │   │       └── horde.ex
│   │   ├── services/
│   │   │   ├── config_server.ex
│   │   │   ├── event_store.ex
│   │   │   └── telemetry_service.ex
│   │   └── types/
│   │       ├── config.ex
│   │       ├── error.ex
│   │       └── event.ex
│   │
│   ├── jido_runtime/           # TIER 2: The Jido Agent Runtime
│   │   ├── application.ex      # Starts the Signal Bus & Agent Supervisor
│   │   ├── agent.ex            # The "use Jido.Agent" macro and behavior
│   │   ├── action.ex           # The "use Jido.Action" macro and behavior
│   │   ├── instruction.ex      # The Instruction struct and helpers
│   │   ├── exec.ex             # The Action execution engine
│   │   ├── skill.ex            # The "use Jido.Skill" macro and behavior
│   │   ├── sensor.ex           # The "use Jido.Sensor" macro and behavior
│   │   ├── runner.ex           # The Runner behavior
│   │   ├── agent/              # Internal implementation of the agent server
│   │   │   └── server.ex
│   │   ├── action/             # Core actions and tool conversion
│   │   │   ├── basic_actions.ex
│   │   │   └── tool.ex
│   │   ├── signal/             # The messaging and eventing system
│   │   │   ├── bus.ex
│   │   │   ├── dispatch.ex
│   │   │   └── router.ex
│   │   ├── runner/             # Built-in runners
│   │   │   ├── simple.ex
│   │   │   └── chain.ex
│   │   ├── sensor/             # Built-in sensors
│   │   │   └── cron_sensor.ex
│   │   └── skill/              # Built-in skills
│   │       └── tasks_skill.ex
│   │
│   └── jido_mabeam/            # TIER 3: Business & Coordination Logic
│       ├── application.ex      # Starts all MABEAM-specific agents
│       ├── agents/
│       │   ├── auctioneer_agent.ex
│       │   ├── marketplace_agent.ex
│       │   └── load_balancer_agent.ex
│       ├── skills/
│       │   ├── auction_management_skill.ex
│       │   └── market_management_skill.ex
│       ├── actions/
│       │   ├── auction/
│       │   │   ├── create_auction.ex
│       │   │   └── place_bid.ex
│       │   └── market/
│       │       ├── list_service.ex
│       │       └── request_service.ex
│       └── types/
│           ├── auction.ex
│           └── market.ex
│
├── config/
│   └── config.exs
└── mix.exs

Discussion of the Hierarchy and Component Placement

Tier 1: foundation_kernel

This application is the stable core. Its existence justifies the entire architecture by providing a clear separation between infrastructure and application logic.

• Role: To provide a reliable, generic, and observable OTP platform. It knows nothing about “agents” or “actions.”
• Supervision: foundation_kernel/application.ex is the root supervisor. It starts the ProcessRegistry, ConfigServer, EventStore, TelemetryService, and any other foundational services.
• Why here?:
  • ProcessRegistry: It’s the DNS of the system. It must be stable and available before anything else.
  • Infrastructure/*: Resilience patterns like CircuitBreaker are generic. An Action in Tier 3 might use a circuit breaker to call an external LLM API, but the circuit breaker itself doesn’t know or care what an LLM is.
  • Services/*: These are singleton services essential for the entire system’s operation, like configuration and telemetry.

Tier 2: jido_runtime

This application is the heart of the agent programming model. It’s the fusion of the three original jido libraries into a single, cohesive unit.

• Role: To provide the tools and environment for building, running, and communicating between agents. It defines how an agent works.
• Supervision: jido_runtime/application.ex starts the services essential for the agent runtime, such as the Jido.Signal.Bus and a top-level DynamicSupervisor for managing all agents (Jido.Agent.Supervisor).
• Why here?:
  • agent.ex, action.ex, skill.ex: These files contain the use macros and behaviors that form the Developer Experience (DX) for creating new components. They are the public API of the runtime.
  • agent/server.ex: This is the GenServer implementation behind use Jido.Agent. It’s an internal detail of the runtime.
  • signal/*: This is the complete, self-contained nervous system for the agents. It is generic enough to pass any message but is conceptually part of the agent runtime.

Tier 3: jido_mabeam

This is where the domain-specific logic lives. We take the high-level concepts from the original mabeam library and implement them using the Jido Runtime primitives.

• Role: To implement the specific business logic and coordination strategies of the multi-agent system.
• Supervision: jido_mabeam/application.ex is responsible for starting the long-running “system agents” like the AuctioneerAgent and MarketplaceAgent.
• Why here?:
  • agents/auctioneer_agent.ex: Instead of a simple GenServer, this is now a full Jido.Agent. It holds the state for all active auctions.
  • skills/auction_management_skill.ex: This skill can be attached to the AuctioneerAgent. It bundles all the actions related to managing auctions. This promotes modularity and reuse.
  • actions/auction/create_auction.ex: A single, self-contained, testable Jido.Action that knows how to create an auction. It encapsulates the “verb” of the system.
  • types/auction.ex: The specific data structures (Auction, Bid, etc.) are now colocated with their domain logic, improving cohesion.

Component Migration Summary Table

This monorepo structure achieves the goals of a robust, multi-tier architecture. It enforces a strict separation of concerns, promotes high cohesion and low coupling, and provides a clear, scalable path for future development while leveraging the best parts of all the provided libraries.