a3s-code-core 5.2.2

A3S Code Core - Embeddable AI agent library with tool execution
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! Verification runtime for host-controlled checks.
//!
//! Verification is completion evidence for a harness-driven coding session. This
//! module keeps command execution, report accumulation, summary formatting, and
//! autosave behavior together instead of scattering it across the public facade.

use super::{
    agent_loop_runtime::build_agent_loop, session_persistence::SessionPersistenceContext,
    AgentSession,
};
use crate::agent::AgentLoop;
use crate::error::{read_or_recover, write_or_recover, Result};
use crate::tools::{ToolContext, ToolInvocation};
use crate::verification::{
    format_verification_summary, verification_presets_for_workspace, VerificationCommand,
    VerificationPreset, VerificationReport, VerificationSummary,
};
use std::path::PathBuf;
use std::sync::{Arc, RwLock};

pub(super) struct VerificationRuntime {
    workspace: PathBuf,
    agent_loop: AgentLoop,
    tool_context: ToolContext,
    session_id: String,
    session_cancel: tokio_util::sync::CancellationToken,
    reports: Arc<RwLock<Vec<VerificationReport>>>,
    persistence: SessionPersistenceContext,
}

impl VerificationRuntime {
    pub(super) fn from_session(session: &AgentSession) -> Self {
        Self {
            workspace: session.workspace.clone(),
            agent_loop: build_agent_loop(session),
            tool_context: session.tool_context.clone(),
            session_id: session.session_id.clone(),
            session_cancel: session.session_cancel.clone(),
            reports: Arc::clone(&session.verification_reports),
            persistence: SessionPersistenceContext::from_session(session),
        }
    }

    pub(super) fn reports(&self) -> Vec<VerificationReport> {
        read_or_recover(&self.reports).clone()
    }

    pub(super) fn summary(&self) -> VerificationSummary {
        VerificationSummary::from_reports(&self.reports())
    }

    pub(super) fn summary_text(&self) -> String {
        format_verification_summary(&self.summary())
    }

    pub(super) fn record(&self, reports: impl IntoIterator<Item = VerificationReport>) {
        write_or_recover(&self.reports).extend(reports);
    }

    pub(super) async fn verify_commands(
        &self,
        subject: &str,
        commands: &[VerificationCommand],
    ) -> Result<VerificationReport> {
        let mut checks = Vec::with_capacity(commands.len());

        for command in commands {
            let mut args = serde_json::json!({ "command": command.command });
            if let Some(timeout_ms) = command.timeout_ms {
                args["timeout"] = serde_json::json!(timeout_ms);
            }

            let cancellation = self.session_cancel.child_token();
            let result = self
                .agent_loop
                .invoke_host_tool(
                    ToolInvocation::host_direct(
                        format!("verification-bash-{}", uuid::Uuid::new_v4()),
                        "bash",
                        args,
                    ),
                    &self.session_id,
                    &None,
                    &cancellation,
                    &self.tool_context,
                )
                .await;
            let exit_code = result
                .metadata
                .as_ref()
                .and_then(|metadata| metadata.get("exit_code"))
                .and_then(|value| value.as_i64())
                .and_then(|value| i32::try_from(value).ok())
                .unwrap_or(result.exit_code);
            let execution_error = governed_execution_error(&result);
            let check = command.check_from_execution(
                exit_code,
                result.metadata.as_ref(),
                execution_error.as_deref(),
            );
            checks.push(check);
        }

        let report = VerificationReport::new(subject, checks);
        self.record([report.clone()]);
        self.persistence.auto_save_if_enabled().await;

        Ok(report)
    }

    pub(super) fn presets(&self) -> Vec<VerificationPreset> {
        verification_presets_for_workspace(&self.workspace)
    }
}

/// Distinguish invocation-kernel failures from an ordinary non-zero command.
/// A real bash exit carries execution metadata and remains reported as a command
/// failure; pre-execution hook/budget/cancellation/queue failures do not.
fn governed_execution_error(result: &crate::tools::ToolResult) -> Option<String> {
    (result.exit_code != 0 && result.metadata.is_none()).then(|| result.output.clone())
}