supercode-harness 0.5.2

The optional native Volter Harness agent and tool harness
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
122
123
124
125
126
127
128
129
130
131
132

//! The default delivery tier of the mailbox: sessions supercode controls.
//!
//! A session supercode hosts as a runtime (any harness: Codex over
//! app-server, Claude Code over stream-json, pi, the ACP harnesses, OpenCode)
//! registers a live-runtime receipt ([`crate::live_runtime`]). Mail to such a
//! session goes through the runtime's own doors, the same ones every
//! frontend uses: `steer` while a turn runs, `send_input` to start one. No
//! hook, relay or per-harness code is involved; those are the degraded tier,
//! for sessions supercode does not control.
//!
//! The text delivered is the rendered envelope: who sent it, that it is not
//! the user, and how to answer.

use crate::frontend::{FrontendRuntime, FrontendTurnState, HttpFrontendRuntime};
use crate::live_runtime::{list_live_runtimes, resolve_live_runtime, LiveRuntimeRecord};

/// The live runtime supercode hosts for `harness`'s session `session_id`, if
/// it controls that session.
pub fn controlled_runtime(harness: &str, session_id: &str) -> Option<LiveRuntimeRecord> {
    list_live_runtimes().ok()?.into_iter().find(|record| {
        record.source.harness == harness
            && (record.source.session_id == session_id || record.runtime_session_id == session_id)
    })
}

/// Every session supercode controls on this machine.
pub fn controlled_runtimes() -> Vec<LiveRuntimeRecord> {
    list_live_runtimes().unwrap_or_default()
}

/// How a message entered a controlled session.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RuntimeDelivery {
    /// A turn was running; the message was steered into it.
    Steered,
    /// The session was idle; the message started a turn.
    Started,
    /// The session was idle and the sender asked not to wake it; nothing was
    /// delivered into the runtime.
    NotWoken,
}

/// The runtime's turn state right now.
pub async fn runtime_turn_state(record: &LiveRuntimeRecord) -> Result<FrontendTurnState, String> {
    let remote = connect(record).await?;
    FrontendRuntime::describe(remote.as_ref())
        .await
        .map(|descriptor| descriptor.turn_state)
        .map_err(|error| error.to_string())
}

/// Deliver `text` into a controlled session: steer a running turn, or start
/// one when `wake` (a `--queue` send leaves an idle session alone).
pub async fn deliver_to_runtime(
    record: &LiveRuntimeRecord,
    text: String,
    wake: bool,
) -> Result<RuntimeDelivery, String> {
    let remote = connect(record).await?;
    let descriptor = FrontendRuntime::describe(remote.as_ref())
        .await
        .map_err(|error| error.to_string())?;
    if descriptor.session_id != record.runtime_session_id {
        return Err("the live runtime's identity did not match its receipt".into());
    }
    match descriptor.turn_state {
        FrontendTurnState::Busy if descriptor.actions.steer => {
            FrontendRuntime::steer(remote.as_ref(), text)
                .await
                .map_err(|error| error.to_string())?;
            Ok(RuntimeDelivery::Steered)
        }
        FrontendTurnState::Busy => Err(
            "a turn is running and this runtime does not accept steering; the message was not \
             delivered into it"
                .into(),
        ),
        FrontendTurnState::Idle if wake => {
            FrontendRuntime::send_input_with_images(remote.clone(), text, Vec::new())
                .await
                .map_err(|error| error.to_string())?;
            Ok(RuntimeDelivery::Started)
        }
        FrontendTurnState::Idle => Ok(RuntimeDelivery::NotWoken),
    }
}

/// The runtime's answer to the message `message_id`: the text of its last
/// assistant message after the user message that carried that id, read from
/// the session's own transcript (a hosted runtime's attach history can be
/// empty; its harness's transcript never is). `None` until it has answered.
pub fn answer_to(
    homes: &crate::HarnessHomes,
    record: &LiveRuntimeRecord,
    message_id: &str,
) -> Option<String> {
    let query = crate::DiscoveryQuery {
        harnesses: vec![crate::HarnessId::new(record.source.harness.clone())],
        homes: homes.clone(),
        workspace: Some(record.source.workspace.clone()),
        ..Default::default()
    };
    let descriptor = crate::discover_sessions(&query)
        .ok()?
        .into_iter()
        .find(|descriptor| {
            descriptor.locator.session_id == record.source.session_id
                || descriptor.locator.session_id == record.runtime_session_id
        })?;
    let session =
        crate::sdk::load_session_with_fidelity(&descriptor.locator, crate::Fidelity::Semantic)
            .ok()?;
    let text = |message: &crate::ChatMessage| message.content.clone().unwrap_or_default();
    let asked = session.messages.iter().rposition(|message| {
        message.role == crate::Role::User && text(message).contains(message_id)
    })?;
    session.messages[asked + 1..]
        .iter()
        .rev()
        .find(|message| message.role == crate::Role::Assistant && !text(message).trim().is_empty())
        .map(text)
}

async fn connect(
    record: &LiveRuntimeRecord,
) -> Result<std::sync::Arc<HttpFrontendRuntime>, String> {
    let receipt = resolve_live_runtime(&record.endpoint, &record.source)
        .map_err(|error| error.to_string())?;
    HttpFrontendRuntime::connect(receipt.base_url, receipt.token)
        .await
        .map_err(|error| error.to_string())
}