Migrating from Tirea

Awaken is a ground-up rewrite of tirea, not an incremental upgrade. This guide maps tirea 0.5 concepts to their awaken equivalents for developers porting existing agents.

The tirea 0.5 source is archived on the tirea-0.5 branch.

Crate Mapping

Key structural change: tirea had 16 crates; awaken has 13. Protocol crates were merged into awaken-server, the state derive macro was removed, and tirea-state + tirea-contract were unified into awaken-contract.

State Model

tirea used a derive-macro-based state system. Awaken uses a trait-based approach.

// tirea 0.5
#[derive(StateSlot)]
#[state(key = "my_plugin.counter", scope = "run")]
struct Counter(u32);

// awaken
use awaken::prelude::*;

pub struct Counter;

impl StateKey for Counter {
    const KEY: &'static str = "my_plugin.counter";
    const MERGE: MergeStrategy = MergeStrategy::Exclusive;
    type Value = u32;
    type Update = u32;

    fn apply(value: &mut u32, update: u32) {
        *value = update;
    }
}

Key change: State is never mutated directly. Hooks read from immutable snapshots and return StateCommand with updates. The runtime applies all updates atomically after the gather phase.

Action System

tirea used typed action enums per phase. Awaken uses ScheduledActionSpec with handlers.

// tirea 0.5
BeforeInferenceAction::AddContextMessage(
    ContextMessage::system("key", "content")
)

// awaken
use awaken::prelude::*;

let mut cmd = StateCommand::new();
cmd.schedule_action::<AddContextMessage>(
    ContextMessage::system("key", "content"),
)?;

See Scheduled Actions for the full list.

Plugin Trait

// tirea 0.5
impl Extension for MyPlugin {
    fn name(&self) -> &str { "my_plugin" }
    fn register(&self, ctx: &mut ExtensionContext) -> Result<()> {
        ctx.add_hook(Phase::BeforeInference, MyHook);
        Ok(())
    }
}

// awaken
impl Plugin for MyPlugin {
    fn descriptor(&self) -> PluginDescriptor {
        PluginDescriptor { name: "my_plugin" }
    }
    fn register(&self, r: &mut PluginRegistrar) -> Result<(), StateError> {
        r.register_phase_hook("my_plugin", Phase::BeforeInference, MyHook)?;
        r.register_key::<MyState>(StateKeyOptions::default())?;
        Ok(())
    }
}

Tool Trait

// tirea 0.5
#[async_trait]
impl TypedTool for MyTool {
    type Args = MyArgs;
    async fn call(&self, args: Self::Args, ctx: ToolContext) -> ToolOutput {
        ToolOutput::success(json!({"result": 42}))
    }
}

// awaken
#[async_trait]
impl Tool for MyTool {
    fn descriptor(&self) -> ToolDescriptor { ... }
    async fn execute(&self, args: Value, ctx: &ToolCallContext) -> Result<ToolOutput, ToolError> {
        Ok(ToolResult::success("my_tool", json!({"result": 42})).into())
    }
}

Runtime Builder

// tirea 0.5
let runtime = AgentOsBuilder::new()
    .agent(agent_spec)
    .tool("search", SearchTool)
    .extension(PermissionExtension::new(rules))
    .build()?;

// awaken
let runtime = AgentRuntimeBuilder::new()
    .with_agent_spec(agent_spec)
    .with_tool("search", Arc::new(SearchTool))
    .with_plugin("permissions", Arc::new(PermissionPlugin::new(rules)))
    .build()?;

Concepts Removed

The following tirea concepts have no awaken equivalent:

Concepts Added

Quick Checklist

• Replace tirea dependency with awaken in Cargo.toml
• Replace use tirea::* with use awaken::prelude::*
• Convert #[derive(StateSlot)] to impl StateKey for ...
• Convert Extension impls to Plugin impls with PluginRegistrar
• Convert TypedTool impls to Tool impls
• Replace action enum variants with cmd.schedule_action::<ActionType>(...)
• Replace AgentOsBuilder with AgentRuntimeBuilder
• Update store imports: tirea_store_adapters → awaken_stores
• Update server imports: protocol crates → awaken_server::protocols::*