locode_engine/
session.rs

1//! The public driving API.
2
3use std::sync::Arc;
4
5use locode_protocol::{ContentBlock, Message, Report};
6use locode_provider::Provider;
7use locode_tools::Registry;
8use tokio_util::sync::CancellationToken;
9
10use crate::approve::{AllowAll, Approver};
11use crate::config::EngineConfig;
12use crate::sink::EventSink;
13
14/// One driven agent session. Owns the conversation history **across runs**: a
15/// second [`Session::run`] on the same session continues the same conversation
16/// (ADR-0016) — the exact call shape an interactive frontend needs for
17/// follow-up turns.
18///
19/// Construct with [`Session::new`], then call [`Session::run`] (or
20/// [`Session::run_text`]) to drive one run to a terminal state. `run` is
21/// **infallible** — every terminal condition (including provider and `Fatal` tool
22/// errors) is captured in the returned [`Report`]'s `status`/`error`, so a caller
23/// gets a structured result every time (`locode-exec` maps status → exit code).
24///
25/// Each [`Report`] is **per-run**: `turns`/`usage`/`tool_calls` count the current
26/// run only (a cumulative view is derivable from the event stream). Continuing
27/// after a failed run is allowed unconditionally — for `ModelError` the history
28/// simply didn't advance, and for `Error` the transcript was fully paired before
29/// the break; the pre-send pairing repair heals any residue on the next sample.
30pub struct Session {
31    pub(crate) provider: Arc<dyn Provider>,
32    pub(crate) registry: Registry,
33    pub(crate) preamble: Vec<Message>,
34    pub(crate) config: EngineConfig,
35    pub(crate) sink: Box<dyn EventSink>,
36    pub(crate) cancel: CancellationToken,
37    /// The conversation so far: preamble + every appended turn, across runs.
38    pub(crate) history: Vec<Message>,
39    /// Runs driven on this session; gates the once-per-session `Init` event.
40    pub(crate) turns_run: u32,
41    /// The pre-dispatch approval gate (ADR-0017); [`AllowAll`] by default.
42    pub(crate) approver: Arc<dyn Approver>,
43    /// Hash of the currently-applied project instructions (ADR-0023 per-turn rescan):
44    /// `None` = none apply, `Some(h)` = these apply. Drives the replace/remove banner.
45    pub(crate) last_instructions: Option<u64>,
46    /// The listing body from the most recent scan, injected on the next turn
47    /// (ADR-0025 §3.2 — scanning happens after a run, never at the top of one).
48    pub(crate) skills_body: Option<String>,
49}
50
51impl Session {
52    /// Assemble a session from its parts.
53    ///
54    /// `preamble` is the base `System` + `Developer` messages (the pack supplies
55    /// these); `provider`/`sink` are trait objects so the binary can select them at
56    /// runtime.
57    #[must_use]
58    pub fn new(
59        provider: Arc<dyn Provider>,
60        registry: Registry,
61        preamble: Vec<Message>,
62        config: EngineConfig,
63        sink: Box<dyn EventSink>,
64    ) -> Self {
65        Self {
66            provider,
67            registry,
68            history: preamble.clone(),
69            preamble,
70            config,
71            sink,
72            cancel: CancellationToken::new(),
73            turns_run: 0,
74            approver: Arc::new(AllowAll),
75            last_instructions: None,
76            skills_body: None,
77        }
78    }
79
80    /// Install an [`Approver`] consulted before every tool call (ADR-0017).
81    ///
82    /// Builder-style so [`Session::new`]'s signature stays intact. The default
83    /// is [`AllowAll`] — headless consumers are unchanged without this call.
84    #[must_use]
85    pub fn with_approver(mut self, approver: Arc<dyn Approver>) -> Self {
86        self.approver = approver;
87        self
88    }
89
90    /// The conversation so far: the preamble plus every appended turn across all
91    /// runs on this session (ADR-0016). Lets a frontend render the transcript
92    /// after a run without replaying the event stream.
93    #[must_use]
94    pub fn history(&self) -> &[Message] {
95        &self.history
96    }
97
98    /// The cancellation handle for the **current run** (ADR-0018).
99    ///
100    /// Clone it *before* calling [`Session::run`] (mandatory — `run` takes
101    /// `&mut self`, so nothing is callable mid-run) and move it into an Esc
102    /// handler, signal handler, or timeout. Firing it stops the run at the
103    /// next observation point — mid-sample (the in-flight request is
104    /// aborted), between batch calls (the rest of the batch is paired
105    /// synthetically), or at the loop top — and the run returns a report with
106    /// [`Status::Cancelled`](locode_protocol::Status). Partial work is
107    /// preserved: with session continuity, the next `run()` continues the
108    /// same conversation.
109    ///
110    /// The token is **per-run, replaced when `run` returns**: a cancel landing
111    /// after the run ended hits the retired token — a harmless no-op — so the
112    /// Esc-lands-late race is resolved by construction. Re-fetch the handle
113    /// each turn. `cancel()` is idempotent; there is no reset.
114    #[must_use]
115    pub fn cancel_handle(&self) -> CancellationToken {
116        self.cancel.clone()
117    }
118
119    /// Drive the loop to a terminal state and return the run's [`Report`].
120    pub async fn run(&mut self, user: Vec<ContentBlock>) -> Report {
121        self.drive(user).await
122    }
123
124    /// Convenience: drive with a plain-text user prompt.
125    pub async fn run_text(&mut self, prompt: impl Into<String>) -> Report {
126        self.run(vec![ContentBlock::Text {
127            text: prompt.into(),
128        }])
129        .await
130    }
131}
locode_engine/session.rs

locode_engine/
session.rs
