Skip to main content

Runtime Architecture

High-Level Shape​

Odyssey now has four architectural layers:

CLI / TUI / HTTP / embedded app
            |
       OdysseyRuntime
            |
  ---------------------------------------------
  BundleStore  SessionStore  Scheduler  Tools
  Models  Memory  Approvals  Sandbox runtimes
            |
   Native executors     WASM component host
            |                  |
  AutoAgents react/v1     Rust agent module.wasm

The key split is:

  • Odyssey owns execution, persistence, tools, memory, policy, and orchestration.
  • AutoAgents remains the internal Rust execution engine.
  • The WASM agent module is a behavior module that steers the next step through the runner bridge.

Execution Path​

For a kind: wasm agent run, Odyssey executes the following flow:

  1. Resolve bundle_ref + agent_id.
  2. Build the session history view from prior turns.
  3. Select tools allowed for the agent.
  4. Build the real host-side autoagents-llm provider with Odyssey model resolution.
  5. Instantiate the WASM agent component in Wasmtime.
  6. Call the component run entrypoint once with the prompt, system prompt, history, metadata payload, and resolved host tool catalog.
  7. Serve component model calls through Odyssey host bindings backed by the host-built provider.
  8. Serve component tool calls through Odyssey brokers, approvals, and sandbox policy.
  9. Forward component AutoAgents events back into Odyssey's CLI/TUI/HTTP event stream.
  10. Persist the completed turn into session history.

The runtime still returns a normal Odyssey response and event stream to CLI, TUI, and HTTP callers.

Why AutoAgents Stays Inside​

Odyssey is not replacing AutoAgents. It is hosting it in two places:

AutoAgents still provides:

  • the ReAct loop
  • model/tool execution choreography
  • stream/event plumbing
  • memory integration points

Odyssey adds:

  • bundle resolution
  • multi-agent bundle selection
  • runtime-owned host bindings
  • runtime-owned session persistence
  • sandbox and approval policy
  • tool registry and capability binding

For Rust-authored agents, odyssey-rs-agent-sdk is the stable integration layer on top of those host bindings. It injects the resolved host tool catalog into the AutoAgents executor and lets agent crates add Rust-defined custom tools without duplicating the built-in tool declarations from agent.yaml.

WASM Runner Boundary​

The WASM host is embedded inside odyssey-rs-runtime. The bridge is intentionally narrow:

  • Odyssey sends one JSON run request into the component.
  • The component runs real AutoAgents Rust code inside the component.
  • The component imports model, tool, and event services from Odyssey through WIT host bindings.
  • Odyssey owns credentials, provider construction, approvals, and sandboxing.

This keeps the agent module away from direct model credentials and direct tool execution while still allowing most AutoAgents Rust code to compile into the bundle.

Security Boundary​

The trusted runtime boundary is still Odyssey, not the agent module.

The agent module does not receive:

  • direct model credentials
  • direct tool handles
  • ambient filesystem access through the runtime bridge
  • ambient network access through the runtime bridge

Privileged effects remain runtime-owned and brokered.

Current Limits​

  • Rust is the only supported WASM authoring path today.
  • One agent is executed per run, even though a bundle may package many agents.
  • Child-run spawning is not yet wired through the host-binding model.
  • Wasm execution is runtime-owned and in-process; stronger execution limits and cancellation remain the next hardening step.