vv-agent 0.7.0

VectorVein agent runtime, SDK, CLI, tools, and workspace backends
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

use std::collections::{BTreeMap, VecDeque};
use std::path::PathBuf;
use std::sync::{Arc, Mutex};

use serde_json::Value;

use crate::budget::{BudgetUsageSnapshot, HostCostMeter, RunBudgetLimits};
use crate::model::ModelProvider;
use crate::runtime::cancellation::CancellationToken;
use crate::runtime::checkpoint_resume::CheckpointController;
use crate::runtime::context::{ExecutionContext, StreamCallback};
use crate::runtime::sub_task_manager::SubTaskManager;
use crate::types::{CycleRecord, Message};
use crate::workspace::WorkspaceBackend;
use crate::{RunConfig, RunContext};

pub type RuntimeLogCallback = dyn FnMut(&str, &BTreeMap<String, Value>) + Send + Sync + 'static;
pub type RuntimeLogHandler = Arc<Mutex<Box<RuntimeLogCallback>>>;
pub type RuntimeEventHandler = Arc<dyn Fn(&str, &BTreeMap<String, Value>) + Send + Sync + 'static>;
pub type BeforeCycleMessageProvider =
    Arc<dyn Fn(u32, &[Message], &BTreeMap<String, Value>) -> Vec<Message> + Send + Sync + 'static>;
pub type InterruptionMessageProvider = Arc<dyn Fn() -> Vec<Message> + Send + Sync + 'static>;

#[doc(hidden)]
#[derive(Clone)]
pub struct CheckpointRuntimeControl {
    controller: CheckpointController,
}

impl CheckpointRuntimeControl {
    pub(crate) fn new(controller: CheckpointController) -> Self {
        Self { controller }
    }

    pub(crate) fn controller(&self) -> &CheckpointController {
        &self.controller
    }

    pub(crate) fn into_controller(self) -> CheckpointController {
        self.controller
    }
}

#[derive(Clone, Default)]
pub struct RuntimeRunControls {
    pub log_handler: Option<RuntimeEventHandler>,
    pub before_cycle_messages: Option<BeforeCycleMessageProvider>,
    pub interruption_messages: Option<InterruptionMessageProvider>,
    pub steering_queue: Option<Arc<Mutex<VecDeque<String>>>>,
    pub cancellation_token: Option<CancellationToken>,
    pub execution_context: Option<ExecutionContext>,
    pub workspace: Option<PathBuf>,
    pub workspace_backend: Option<Arc<dyn WorkspaceBackend>>,
    pub model_provider: Option<Arc<dyn ModelProvider>>,
    pub run_context: Option<RunContext>,
    pub sub_task_manager: Option<SubTaskManager>,
    pub budget_limits: Option<RunBudgetLimits>,
    pub host_cost_meter: Option<Arc<dyn HostCostMeter>>,
    #[doc(hidden)]
    pub background_parent_run_config: Option<RunConfig>,
    #[doc(hidden)]
    pub initial_messages: Option<Vec<Message>>,
    #[doc(hidden)]
    pub initial_shared_state: Option<BTreeMap<String, Value>>,
    #[doc(hidden)]
    pub initial_cycles: Option<Vec<CycleRecord>>,
    #[doc(hidden)]
    pub cycle_index_start: Option<u32>,
    #[doc(hidden)]
    pub cycle_count: Option<u32>,
    #[doc(hidden)]
    pub initial_budget_usage: Option<BudgetUsageSnapshot>,
    #[doc(hidden)]
    pub defer_terminal_on_max_cycles: bool,
    #[doc(hidden)]
    pub checkpoint_controller: Option<CheckpointRuntimeControl>,
}

impl RuntimeRunControls {
    pub(in crate::runtime::engine) fn effective_cancellation_token(
        &self,
    ) -> Option<CancellationToken> {
        self.cancellation_token.clone().or_else(|| {
            self.execution_context
                .as_ref()
                .and_then(|context| context.cancellation_token.clone())
        })
    }

    pub(in crate::runtime::engine) fn effective_stream_callback(&self) -> Option<StreamCallback> {
        self.execution_context
            .as_ref()
            .and_then(|context| context.stream_callback.clone())
    }

    pub(crate) fn effective_checkpoint_controller(&self) -> Option<&CheckpointController> {
        self.checkpoint_controller
            .as_ref()
            .map(CheckpointRuntimeControl::controller)
    }
}