Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

8.7 KB
Raw Blame
//! Entry points for the lifecycle moments that are not tool calls.
//!
//! Tool events reach the engine through
//! [`bridge`](super::bridge) — the harness already had a seam there. The
//! moments in this module have no such seam, so each is a small function a call
//! site invokes directly. Each one is cheap when nothing is configured: it asks
//! [`HookEngine::has_hooks`](super::engine::HookEngine::has_hooks) first and
//! returns without building an envelope.

use crate::core::runtime::DispatchCtx;
use std::path::PathBuf;
use std::time::Duration;

use tinyagents_hooks::command::context::{
    build_input, set_host_context, HostContext, TurnIdentity,
};
use tinyagents_hooks::command::types::{
    CompactPayload, HookEvent, HookPayload, PromptPayload, SessionPayload, SubagentPayload,
    TextPayload,
};

/// Bring the hook system up: resolve host facts, read every `hooks.json`, and
/// install the harness bridge.
///
/// Safe to call again — a reload replaces the whole config and re-registers the
/// bridge by name rather than appending a second copy.
pub async fn init(ctx: &DispatchCtx, config: &crate::config::schema::Config) {
    let settings = &config.hooks;
    set_host_context(HostContext {
        workspace_roots: workspace_roots(config),
        version: env!("CARGO_PKG_VERSION").to_string(),
    });

    if !settings.enabled {
        crate::agent::hooks::replace_embedder_tool_hook("configured_hooks", None);
        super::host::engine()
            .install(tinyagents_hooks::command::HookConfig::default())
            .await;
        log::info!("[hooks] disabled by configuration");
        return;
    }

    super::host::engine()
        .set_default_timeout(Duration::from_secs(settings.default_timeout_secs))
        .await;
    let loaded = super::host::reload(
        ctx,
        Some(config.action_dir.clone()),
        Some(config.workspace_dir.clone()),
    )
    .await;
    if loaded.is_empty() {
        // Nothing configured: keep the bridge out of the harness entirely so an
        // unconfigured host pays not even a task-local lookup per tool call.
        crate::agent::hooks::replace_embedder_tool_hook("configured_hooks", None);
        return;
    }
    let hook: std::sync::Arc<
        dyn tinyagents_hooks::tool::ToolHook<crate::agent::tinyagents::host::OpenHumanRunContext>,
    > = super::host::engine().clone();
    crate::agent::hooks::replace_embedder_tool_hook("configured_hooks", Some(hook));
}

fn workspace_roots(config: &crate::config::schema::Config) -> Vec<PathBuf> {
    vec![config.action_dir.clone()]
}

/// Fire `sessionStart`, returning context the caller should append to the
/// session's system prompt.
pub async fn session_started(identity: TurnIdentity, entrypoint: Option<String>) -> Option<String> {
    let engine = super::host::engine();
    if !engine.has_hooks(HookEvent::SessionStart).await {
        return None;
    }
    let input = build_input(
        HookEvent::SessionStart,
        identity,
        HookPayload::Session(SessionPayload {
            entrypoint,
            reason: None,
            duration_ms: None,
        }),
    );
    engine
        .dispatch(HookEvent::SessionStart, input)
        .await
        .output
        .additional_context
}

/// Fire `sessionEnd` and release everything scoped to the session.
pub async fn session_ended(identity: TurnIdentity, reason: &str, duration_ms: Option<u64>) {
    let engine = super::host::engine();
    let session_id = identity.session_id.clone();
    if engine.has_hooks(HookEvent::SessionEnd).await {
        let input = build_input(
            HookEvent::SessionEnd,
            identity,
            HookPayload::Session(SessionPayload {
                entrypoint: None,
                reason: Some(reason.to_string()),
                duration_ms,
            }),
        );
        engine.dispatch(HookEvent::SessionEnd, input).await;
    }
    if let Some(session_id) = session_id {
        engine.forget_session(&session_id).await;
        tinyagents_hooks::command::followup::forget(&session_id).await;
    }
}

/// The verdict on a submitted prompt.
#[derive(Debug, Clone)]
pub enum PromptVerdict {
    /// Send it, optionally with context a hook wants prepended.
    Submit {
        /// Text a hook asked to add to the turn's context.
        additional_context: Option<String>,
    },
    /// Do not send it. The string is what the user should be told.
    Block(String),
}

/// Fire `beforeSubmitPrompt`.
///
/// Blocking is expressed two ways in Cursor — `continue: false` and
/// `permission: "deny"` — and both are honoured, because a hook author reaching
/// for the one they remember should not silently get a prompt that went through
/// anyway.
pub async fn prompt_submitted(
    identity: TurnIdentity,
    prompt: &str,
    attachments: Vec<String>,
) -> PromptVerdict {
    let engine = super::host::engine();
    if !engine.has_hooks(HookEvent::BeforeSubmitPrompt).await {
        return PromptVerdict::Submit {
            additional_context: None,
        };
    }
    let input = build_input(
        HookEvent::BeforeSubmitPrompt,
        identity,
        HookPayload::Prompt(PromptPayload {
            prompt: prompt.to_string(),
            attachments,
        }),
    );
    let outcome = engine.dispatch(HookEvent::BeforeSubmitPrompt, input).await;
    if outcome.is_deny() || outcome.output.continue_ == Some(false) {
        let reason = outcome
            .output
            .user_message
            .clone()
            .or_else(|| outcome.output.agent_message.clone())
            .unwrap_or_else(|| "a configured hook blocked this prompt".to_string());
        return PromptVerdict::Block(reason);
    }
    PromptVerdict::Submit {
        additional_context: outcome.output.additional_context,
    }
}

/// Fire `preCompact`, returning a message for the user if a hook set one.
pub async fn pre_compact(
    identity: TurnIdentity,
    trigger: &str,
    context_usage_percent: Option<f64>,
    message_count: Option<usize>,
) -> Option<String> {
    let engine = super::host::engine();
    if !engine.has_hooks(HookEvent::PreCompact).await {
        return None;
    }
    let input = build_input(
        HookEvent::PreCompact,
        identity,
        HookPayload::Compact(CompactPayload {
            trigger: trigger.to_string(),
            context_usage_percent,
            message_count,
        }),
    );
    engine
        .dispatch(HookEvent::PreCompact, input)
        .await
        .output
        .user_message
}

/// Fire `subagentStart`. `Err` carries the reason the child must not run.
pub async fn subagent_starting(
    identity: TurnIdentity,
    subagent_type: &str,
    task: &str,
) -> Result<(), String> {
    let engine = super::host::engine();
    if !engine.has_hooks(HookEvent::SubagentStart).await {
        return Ok(());
    }
    let input = build_input(
        HookEvent::SubagentStart,
        identity.clone(),
        HookPayload::Subagent(SubagentPayload {
            subagent_type: subagent_type.to_string(),
            task: task.to_string(),
            parent_conversation_id: identity.conversation_id,
            status: None,
            duration_ms: None,
        }),
    );
    let outcome = engine.dispatch(HookEvent::SubagentStart, input).await;
    match outcome.denial_reason() {
        Some(reason) => Err(reason.to_string()),
        None => Ok(()),
    }
}

/// Fire `subagentStop`, returning a follow-up the parent may act on.
pub async fn subagent_stopped(
    identity: TurnIdentity,
    subagent_type: &str,
    task: &str,
    status: &str,
    duration_ms: Option<u64>,
) -> Option<String> {
    let engine = super::host::engine();
    if !engine.has_hooks(HookEvent::SubagentStop).await {
        return None;
    }
    let input = build_input(
        HookEvent::SubagentStop,
        identity.clone(),
        HookPayload::Subagent(SubagentPayload {
            subagent_type: subagent_type.to_string(),
            task: task.to_string(),
            parent_conversation_id: identity.conversation_id,
            status: Some(status.to_string()),
            duration_ms,
        }),
    );
    engine
        .dispatch(HookEvent::SubagentStop, input)
        .await
        .output
        .followup_message
}

/// Fire `afterAgentThought`. Observational, so this returns as soon as the
/// hooks are scheduled.
pub async fn agent_thought(identity: TurnIdentity, text: &str, duration_ms: Option<u64>) {
    let engine = super::host::engine();
    if !engine.has_hooks(HookEvent::AfterAgentThought).await {
        return;
    }
    let input = build_input(
        HookEvent::AfterAgentThought,
        identity,
        HookPayload::Text(TextPayload {
            text: text.to_string(),
            duration_ms,
        }),
    );
    engine.dispatch(HookEvent::AfterAgentThought, input).await;
}