tea-kernel 0.1.0

Headless model-tool agent state machine for tea-rs
Documentation
use crate::common;

use std::str::FromStr;
use std::sync::Arc;

use serde_json::{Value, json};
use tea_control::CancellationScope;
use tea_kernel::{AgentKernel, KernelRunConfig, RunState};
use tea_model::{
    ModelCompletion, ModelEvent, ModelResponseInfo, ModelStreamIndex, ProviderToolCallId,
    ToolCallCompleted, ToolCallStarted,
};
use tea_policy::{
    ActorId, ApprovalResolution, CodingWorkspacePolicy, ExecutionSurface, PolicyEngine,
    PolicyEnvironment, PolicyExecutionTarget,
};
use tea_protocol::{
    AgentEventType, ApprovalDecision, ProtocolMetadata, SessionRecord, StopReason, ToolIdempotency,
};
use tea_session::{ApprovalArtifactEntry, SessionStore};
use tea_testkit::{FakeReadTool, FakeWriteTool, ScriptedModelResponse};
use tea_tools::{
    ArgumentResourceResolver, ToolConcurrency, ToolEffect, ToolExecutionSemantics, ToolName,
    ToolRegistry, ToolResourceAccess, ToolRetrySafety, ToolSpec, ToolTimeout, ToolVersion,
};

use common::{EventCollector, FixedClock, TestIds, provider, session_id, store, timestamp};

fn config() -> KernelRunConfig {
    KernelRunConfig::new(
        ActorId::from_str("user:alice").unwrap(),
        PolicyEnvironment::new(
            ExecutionSurface::Test,
            PolicyExecutionTarget::Native,
            ProtocolMetadata::default(),
        ),
    )
}

fn tools(read: FakeReadTool, write: FakeWriteTool) -> ToolRegistry {
    let mut registry = ToolRegistry::new();
    registry
        .register(
            spec(
                "read_file",
                ToolEffect::FsRead,
                ToolIdempotency::Idempotent,
                json!({"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}),
                json!({"type":"object","properties":{"content":{"type":"string"}},"required":["content"]}),
            ),
            Arc::new(
                ArgumentResourceResolver::new("path", "file", ToolResourceAccess::Read).unwrap(),
            ),
            Arc::new(read),
        )
        .unwrap();
    registry
        .register(
            spec(
                "write_file",
                ToolEffect::FsWrite,
                ToolIdempotency::NonIdempotent,
                json!({"type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"}},"required":["path","content"]}),
                json!({"type":"object","properties":{"path":{"type":"string"},"writtenBytes":{"type":"integer"}},"required":["path","writtenBytes"]}),
            ),
            Arc::new(
                ArgumentResourceResolver::new("path", "file", ToolResourceAccess::Write).unwrap(),
            ),
            Arc::new(write),
        )
        .unwrap();
    registry
}

fn spec(
    name: &str,
    effect: ToolEffect,
    idempotency: ToolIdempotency,
    input: Value,
    output: Value,
) -> ToolSpec {
    ToolSpec::new(
        ToolName::from_str(name).unwrap(),
        ToolVersion::from_str("1.0.0").unwrap(),
        format!("Deterministic {name}."),
        input,
        output,
        [effect],
        ToolExecutionSemantics::new(
            idempotency,
            if idempotency == ToolIdempotency::Idempotent {
                ToolRetrySafety::Automatic
            } else {
                ToolRetrySafety::ExplicitOnly
            },
            ToolConcurrency::Serial,
            ToolTimeout::from_millis(1_000).unwrap(),
        )
        .unwrap(),
    )
    .unwrap()
}

fn tool_script(name: &str, arguments: Value, opaque_id: &str) -> ScriptedModelResponse {
    let index = ModelStreamIndex::new(0).unwrap();
    let provider_id = ProviderToolCallId::from_str(opaque_id).unwrap();
    ScriptedModelResponse::events([
        ModelEvent::Started(ModelResponseInfo::new()),
        ModelEvent::ToolCallStarted(
            ToolCallStarted::new(index, provider_id.clone(), name).unwrap(),
        ),
        ModelEvent::ToolCallCompleted(
            ToolCallCompleted::new(index, provider_id, name, arguments).unwrap(),
        ),
        ModelEvent::Completed(ModelCompletion::new(StopReason::ToolUse).unwrap()),
    ])
}

#[tokio::test]
#[allow(clippy::too_many_lines)]
async fn read_then_resumable_write_then_final_response() {
    let provider = provider([
        tool_script("read_file", json!({"path":"/notes.txt"}), "read-1"),
        tool_script(
            "write_file",
            json!({"path":"/summary.txt","content":"hello"}),
            "write-1",
        ),
        ScriptedModelResponse::text(["summary written"]),
    ]);
    let store = store().await;
    let write = FakeWriteTool::new();
    let tools = tools(
        FakeReadTool::new([("/notes.txt".to_owned(), "hello".to_owned())]),
        write.clone(),
    );
    let mut policy = PolicyEngine::new();
    policy.add_rule(CodingWorkspacePolicy).unwrap();
    let events = EventCollector::default();
    let first_ids = TestIds::default();

    let waiting = AgentKernel::new(
        &provider,
        &tools,
        &policy,
        &store,
        &FixedClock,
        &first_ids,
        &events,
    )
    .run(session_id(), &config(), CancellationScope::new())
    .await
    .unwrap();
    assert_eq!(waiting.state(), RunState::WaitingApproval);
    assert!(write.writes().unwrap().is_empty());

    let paused = store.load(session_id()).await.unwrap();
    let request = paused
        .approval_artifacts()
        .iter()
        .find_map(|entry| match entry {
            ApprovalArtifactEntry::Requested { request, .. } => Some(request.clone()),
            ApprovalArtifactEntry::Resolved { .. } => None,
        })
        .unwrap();
    let resolution =
        ApprovalResolution::new(&request, ApprovalDecision::AllowOnce, timestamp(), None).unwrap();

    let resume_ids = TestIds::with_start(200);
    let completed = AgentKernel::new(
        &provider,
        &tools,
        &policy,
        &store,
        &FixedClock,
        &resume_ids,
        &events,
    )
    .resume_approval(
        session_id(),
        &resolution,
        &config(),
        CancellationScope::new(),
    )
    .await
    .unwrap();

    assert_eq!(completed.state(), RunState::Completed);
    assert_eq!(
        write.writes().unwrap(),
        [("/summary.txt".to_owned(), "hello".to_owned())]
    );
    let requests = provider.captured_requests().unwrap();
    assert_eq!(requests.len(), 3);
    assert_eq!(
        requests
            .iter()
            .map(|request| request.messages().len())
            .collect::<Vec<_>>(),
        [1, 3, 5]
    );

    let snapshot = store.load(session_id()).await.unwrap();
    assert_eq!(snapshot.approval_artifacts().len(), 2);
    assert!(snapshot.state().pending_approvals().is_empty());
    assert!(matches!(
        snapshot.records().last().unwrap().record(),
        SessionRecord::TurnCheckpointed {
            next_action: tea_protocol::NextTurnAction::FinishRun,
            ..
        }
    ));
    let emitted = events.events();
    assert!(
        emitted
            .windows(2)
            .all(|events| events[0].sequence() < events[1].sequence())
    );
    let event_types = emitted
        .iter()
        .map(tea_protocol::EventEnvelope::event_type)
        .collect::<Vec<_>>();
    assert_eq!(event_types.first(), Some(&AgentEventType::RunStarted));
    assert_eq!(event_types.last(), Some(&AgentEventType::RunFinished));
    assert!(event_types.contains(&AgentEventType::ApprovalRequested));
    assert_eq!(
        event_types
            .iter()
            .filter(|event| **event == AgentEventType::RunStarted)
            .count(),
        1
    );
}