Skip to main content

session_core/
compaction_op.rs

1//! A manual compaction or a tree navigation as the harness journals its operation (`runtime/lane.ts`
2//! `acceptCompaction` / `acceptNavigation`, `runtime/drive/structural.ts`): the preparation and the operation in
3//! `summary.deciding`, `summary.ready`, `summary.effect_pending` (before the request, with the request, then with
4//! its usage row), and the terminal transaction that commits the compaction entry (or the branch summary), moves
5//! the tip and records the result. A navigation without a summary is admitted at `navigation.ready_to_commit` and
6//! committed by its own terminal transaction (`commitNavigation`).
7
8use ai::retry::RetryPolicy;
9use serde_json::{Map, Value, json};
10use session_journal::ns::{
11    BRANCH_TIP, ENTRY_LABEL, LANE_CONFIG, LANE_STATE, OP_META, OP_PREPARATION, OP_RESULT, OP_STATE,
12};
13use session_journal::run::summary::{Scope, SummaryAttempt};
14use session_journal::run::{MAIN_LANE, OpAt, default_settings};
15use session_journal::{Session, Write};
16
17fn mint(session: &Session) -> String {
18    session_journal::lock_clock(&session.clock()).next_id()
19}
20
21fn now(session: &Session) -> i64 {
22    session_journal::lock_clock(&session.clock()).now()
23}
24
25/// A compaction's durable preparation (`ultron.op.preparation`): what it summarizes, keeps, and the settings it ran with.
26pub fn prepared_value(
27    preparation: &compaction::CompactionPreparation,
28    retained_tail: &[Value],
29    settings: &Value,
30) -> Value {
31    let file_ops = &preparation.file_ops;
32    json!({
33        "kind": "compaction",
34        "messagesToSummarize": preparation.messages_to_summarize,
35        "turnPrefixMessages": preparation.turn_prefix_messages,
36        "retainedTail": retained_tail,
37        "isSplitTurn": preparation.is_split_turn,
38        "tokensBefore": preparation.tokens_before,
39        "fileOps": {"read": file_ops.read, "written": file_ops.written, "edited": file_ops.edited},
40        "settings": settings,
41    })
42}
43
44/// One structural operation in progress: a compaction, or a navigation (with or without a branch summary).
45pub struct CompactionOp {
46    /// `compaction` or `navigation` (the intent and the result's kind).
47    kind: &'static str,
48    /// A navigation's target (`None`: the root) and the label it sets.
49    target: Option<String>,
50    label: Option<String>,
51    /// Where a navigation without a summary puts its label: the selected entry (AgentSession `navigateTree`).
52    label_entry: Option<String>,
53    operation_id: String,
54    task_id: String,
55    pub result_entry_id: String,
56    /// The summary request, once made, and the policy it retries under.
57    summary: Option<SummaryAttempt>,
58    retry: RetryPolicy,
59    source_tip: Option<String>,
60    started_at: i64,
61    last_operation_id: Value,
62    inbox: Value,
63    task: Value,
64}
65
66impl CompactionOp {
67    fn preparation_key(&self) -> String {
68        format!("{}:{}", self.operation_id, self.task_id)
69    }
70
71    pub fn operation_id(&self) -> &str {
72        &self.operation_id
73    }
74
75    /// The fields every state starts with. The control is the stored one: a cancel request ([`request_cancel`],
76    /// made on the actor while the summary runs off it) stays recorded in every later state, so a worker that dies
77    /// after it is settled `aborted`.
78    fn scope(&self, session: &Session) -> Scope {
79        let control = session
80            .value(OP_STATE, &self.operation_id)
81            .map(|state| state["control"].clone())
82            .filter(Value::is_object)
83            .unwrap_or_else(|| json!({"status": "running"}));
84        let mut base = Map::new();
85        base.insert("control".into(), control);
86        base.insert("settings".into(), default_settings());
87        base.insert("latestAssistantEntryId".into(), Value::Null);
88        Scope {
89            operation_id: self.operation_id.clone(),
90            base,
91            task: self.task.clone(),
92        }
93    }
94
95    fn state(&self, session: &Session, at: OpAt, extra: Vec<(&str, Value)>) -> Value {
96        self.scope(session).state(at, extra)
97    }
98
99    fn lane_state(&self, running: bool) -> Value {
100        if running {
101            json!({"currentOperationId": self.operation_id, "lastOperationId": self.last_operation_id, "inbox": self.inbox})
102        } else {
103            json!({"currentOperationId": null, "lastOperationId": self.operation_id, "inbox": self.inbox})
104        }
105    }
106
107    /// Admit the operation with its preparation (`retained_tail`: the kept messages): `summary.deciding`, where the
108    /// `session_before_compact` hook decides before any request ([`CompactionOp::request`]).
109    pub fn begin(
110        session: &mut Session,
111        preparation: &compaction::CompactionPreparation,
112        retained_tail: &[Value],
113        custom_instructions: Option<&str>,
114    ) -> Result<CompactionOp, String> {
115        let operation_id = mint(session);
116        let task_id = mint(session);
117        let lane = session.value(LANE_STATE, MAIN_LANE).cloned().unwrap_or(Value::Null);
118        let mut task = json!({"taskId": task_id, "reason": "manual"});
119        let mut intent = json!({"kind": "compaction"});
120        if let Some(instructions) = custom_instructions {
121            task["customInstructions"] = json!(instructions);
122            intent["customInstructions"] = json!(instructions);
123        }
124        task["boundary"] = json!({"kind": "finish"});
125        let op = CompactionOp {
126            kind: "compaction",
127            target: None,
128            label: None,
129            label_entry: None,
130            source_tip: session.branch_tip(MAIN_LANE).flatten(),
131            started_at: now(session),
132            last_operation_id: lane["lastOperationId"].clone(),
133            inbox: lane.get("inbox").cloned().unwrap_or_else(|| json!([])),
134            task,
135            result_entry_id: String::new(),
136            summary: None,
137            retry: RetryPolicy::default(),
138            operation_id,
139            task_id,
140        };
141        let prepared = prepared_value(preparation, retained_tail, &default_settings()["compaction"]);
142        let meta = json!({
143            "operationId": op.operation_id, "lane": MAIN_LANE, "sourceTipId": op.source_tip, "startedAt": op.started_at,
144            "intent": intent,
145        });
146        session.commit(&[
147            Write::set(OP_PREPARATION, &op.preparation_key(), prepared),
148            Write::set(OP_META, &op.operation_id, meta),
149            Write::set(
150                OP_STATE,
151                &op.operation_id,
152                op.state(session, OpAt::SummaryDeciding, vec![]),
153            ),
154            Write::set(LANE_STATE, MAIN_LANE, op.lane_state(true)),
155        ])?;
156        Ok(op)
157    }
158
159    fn navigation(session: &Session, target: Option<&str>, label: Option<&str>, task: Value) -> CompactionOp {
160        let lane = session.value(LANE_STATE, MAIN_LANE).cloned().unwrap_or(Value::Null);
161        CompactionOp {
162            kind: "navigation",
163            target: target.map(str::to_string),
164            label: label.map(str::to_string),
165            label_entry: target.map(str::to_string),
166            source_tip: session.branch_tip(MAIN_LANE).flatten(),
167            started_at: now(session),
168            last_operation_id: lane["lastOperationId"].clone(),
169            inbox: lane.get("inbox").cloned().unwrap_or_else(|| json!([])),
170            task,
171            result_entry_id: String::new(),
172            summary: None,
173            retry: RetryPolicy::default(),
174            operation_id: String::new(),
175            task_id: String::new(),
176        }
177    }
178
179    fn navigation_meta(&self, summarize: bool, custom_instructions: Option<&str>) -> Value {
180        let mut intent = json!({"kind": "navigation", "targetId": self.target, "summarize": summarize});
181        if let Some(label) = &self.label {
182            intent["label"] = json!(label);
183        }
184        if let Some(instructions) = custom_instructions {
185            intent["customInstructions"] = json!(instructions);
186        }
187        json!({
188            "operationId": self.operation_id, "lane": MAIN_LANE, "sourceTipId": self.source_tip,
189            "startedAt": self.started_at, "intent": intent,
190        })
191    }
192
193    /// The navigation task's `commit_navigation` boundary, with the instructions and label it runs with.
194    fn navigation_task(&self, custom_instructions: Option<&str>) -> Value {
195        let mut task = json!({"taskId": self.task_id});
196        if let Some(instructions) = custom_instructions {
197            task["customInstructions"] = json!(instructions);
198        }
199        let mut boundary = json!({"kind": "commit_navigation", "targetId": self.target});
200        if let Some(label) = &self.label {
201            boundary["label"] = json!(label);
202        }
203        task["boundary"] = boundary;
204        task
205    }
206
207    /// Admit a summarized navigation to `target` with its preparation (`preparation`: the branch left, as
208    /// `prepareBranchEntries` reduces it): `summary.deciding` with a `commit_navigation` boundary, where the
209    /// `session_before_tree` hook decides before any request.
210    pub fn begin_navigation(
211        session: &mut Session,
212        target: Option<&str>,
213        preparation: &compaction::BranchPreparation,
214        custom_instructions: Option<&str>,
215        label: Option<&str>,
216    ) -> Result<CompactionOp, String> {
217        let mut op = CompactionOp::navigation(session, target, label, Value::Null);
218        op.operation_id = mint(session);
219        op.task_id = mint(session);
220        op.task = op.navigation_task(custom_instructions);
221        let ops = &preparation.file_ops;
222        let prepared = json!({
223            "kind": "branch_summary", "messages": preparation.messages,
224            "fileOps": {"read": ops.read, "written": ops.written, "edited": ops.edited},
225            "totalTokens": preparation.total_tokens,
226        });
227        session.commit(&[
228            Write::set(OP_PREPARATION, &op.preparation_key(), prepared),
229            Write::set(OP_META, &op.operation_id, op.navigation_meta(true, custom_instructions)),
230            Write::set(
231                OP_STATE,
232                &op.operation_id,
233                op.state(session, OpAt::SummaryDeciding, vec![]),
234            ),
235            Write::set(LANE_STATE, MAIN_LANE, op.lane_state(true)),
236        ])?;
237        Ok(op)
238    }
239
240    /// Admit a navigation without a summary: `navigation.ready_to_commit` ([`CompactionOp::commit_navigation`]);
241    /// its label goes on `label_entry` (default: the target).
242    pub fn begin_direct_navigation(
243        session: &mut Session,
244        target: Option<&str>,
245        label: Option<&str>,
246        label_entry: Option<&str>,
247    ) -> Result<CompactionOp, String> {
248        let mut op = CompactionOp::navigation(session, target, label, Value::Null);
249        op.label_entry = label_entry.map(str::to_string).or_else(|| op.target.clone());
250        op.operation_id = mint(session);
251        let mut extra = vec![("targetId", json!(op.target))];
252        if let Some(label) = &op.label {
253            extra.push(("label", json!(label)));
254            // AgentSession labels the selected entry; the tip goes before it when it is a user message.
255            if op.label_entry != op.target {
256                extra.push(("labelEntryId", json!(op.label_entry)));
257            }
258        }
259        session.commit(&[
260            Write::set(OP_META, &op.operation_id, op.navigation_meta(false, None)),
261            Write::set(
262                OP_STATE,
263                &op.operation_id,
264                op.state(session, OpAt::NavigationReadyToCommit, extra),
265            ),
266            Write::set(LANE_STATE, MAIN_LANE, op.lane_state(true)),
267        ])?;
268        Ok(op)
269    }
270
271    /// Commit a navigation without a summary: the tip moves to the target (labelled) and the operation ends.
272    pub fn commit_navigation(self, session: &mut Session) -> Result<Option<String>, String> {
273        let mut writes = vec![Write::set(
274            BRANCH_TIP,
275            MAIN_LANE,
276            self.target.clone().map_or(Value::Null, Value::from),
277        )];
278        if let (Some(entry), Some(label)) = (&self.label_entry, &self.label) {
279            writes.push(Write::set(ENTRY_LABEL, entry, label.clone().into()));
280        }
281        writes.extend(self.terminal(session, "completed", self.target.as_deref(), None));
282        session.commit(&writes)?;
283        Ok(self.target)
284    }
285
286    /// Commit the branch summary `entry` (without id, parent and `fromId`) under the target as the new tip, its
287    /// label on the summary (AgentSession `navigateTree`), and end the operation; `usage`: a hook's summary usage,
288    /// recorded as a usage row (a model summary's row was recorded with its response).
289    pub fn complete_navigation(
290        mut self,
291        session: &mut Session,
292        mut entry: Map<String, Value>,
293        hook_usage: Option<Value>,
294    ) -> Result<String, String> {
295        if self.result_entry_id.is_empty() {
296            self.result_entry_id = mint(session);
297        }
298        let mut writes: Vec<Write> = hook_usage
299            .map(|usage| Write::usage(&mint(session), usage, None))
300            .into_iter()
301            .collect();
302        let id = self.result_entry_id.clone();
303        let target = self.target.clone().map_or(Value::Null, Value::from);
304        let mut fields = Map::new();
305        fields.insert("type".into(), "branch_summary".into());
306        fields.insert(
307            "fromId".into(),
308            self.source_tip.clone().map_or(Value::Null, Value::from),
309        );
310        fields.append(&mut entry);
311        writes.extend([
312            Write::set(BRANCH_TIP, MAIN_LANE, target),
313            Write::entry(&id, self.target.as_deref(), fields),
314            Write::set(BRANCH_TIP, MAIN_LANE, id.clone().into()),
315        ]);
316        if let Some(label) = &self.label {
317            writes.push(Write::set(ENTRY_LABEL, &id, label.clone().into()));
318        }
319        writes.extend(self.terminal(session, "completed", Some(&id), None));
320        session.commit(&writes)?;
321        Ok(id)
322    }
323
324    /// End the operation `declined` (a `session_before_tree` hook cancelled the navigation); the branch is
325    /// unchanged.
326    pub fn decline(self, session: &mut Session) -> Result<(), String> {
327        let writes = self.terminal(session, "declined", self.source_tip.as_deref(), None);
328        session.commit(&writes).map(drop)
329    }
330
331    /// Prepare the summary request under `retry`: `summary.ready`, `summary.effect_pending`, and the request with
332    /// its usage id.
333    pub fn request(&mut self, session: &mut Session, retry: RetryPolicy) -> Result<(), String> {
334        self.result_entry_id = mint(session);
335        self.retry = retry;
336        let configuration = session.value(LANE_CONFIG, MAIN_LANE).cloned().unwrap_or(Value::Null);
337        let mut attempt = SummaryAttempt::new(&self.result_entry_id, configuration, retry.journal_value());
338        let scope = self.scope(session);
339        attempt.start(session, &scope)?;
340        self.summary = Some(attempt);
341        Ok(())
342    }
343
344    /// The summary task's id (the harness's retry `step`).
345    pub fn task_id(&self) -> &str {
346        &self.task_id
347    }
348
349    /// The summary attempt in progress (1-based).
350    pub fn attempt(&self) -> u64 {
351        self.summary.as_ref().map_or(1, SummaryAttempt::attempt)
352    }
353
354    /// A retryable failed attempt (`publishAttemptResult`): its response's usage row (when it reported one) and
355    /// `summary.retry_wait` until `not_before` with the next attempt and the error.
356    pub fn retry_wait(
357        &mut self,
358        session: &mut Session,
359        usage: Option<&Value>,
360        error: &str,
361        not_before: i64,
362    ) -> Result<(), String> {
363        let Some(attempt) = &self.summary else {
364            return Ok(());
365        };
366        let writes = attempt.retry_wait(&self.scope(session), usage, error, not_before);
367        session.commit(&writes).map(drop)
368    }
369
370    /// The wait ended (`runStructuralRetryWait`): the next attempt's `summary.ready`, `summary.effect_pending` and
371    /// request.
372    pub fn retry(&mut self, session: &mut Session) -> Result<(), String> {
373        let scope = self.scope(session);
374        match self.summary.as_mut() {
375            Some(attempt) => attempt.retry(session, &scope),
376            None => Ok(()),
377        }
378    }
379
380    /// The summary response arrived: its usage row, with the state that lists it.
381    pub fn record_usage(&self, session: &mut Session, usage: &Value) -> Result<(), String> {
382        let Some(attempt) = &self.summary else {
383            return Ok(());
384        };
385        let writes = attempt.record_usage(&self.scope(session), usage);
386        if writes.is_empty() {
387            return Ok(());
388        }
389        session.commit(&writes).map(drop)
390    }
391
392    fn terminal(&self, session: &Session, status: &str, tip: Option<&str>, error: Option<&str>) -> Vec<Write> {
393        let mut result = json!({
394            "operationId": self.operation_id, "kind": self.kind, "status": status, "fromTipId": self.source_tip,
395            "tipId": tip, "startedAt": self.started_at, "endedAt": now(session),
396        });
397        if let Some(message) = error {
398            let code = if self.kind == "compaction" {
399                "compaction_failed"
400            } else {
401                "summarization_failed"
402            };
403            result["error"] = json!({"code": code, "message": message});
404        }
405        let mut writes = vec![
406            Write::delete(OP_META, &self.operation_id),
407            Write::delete(OP_STATE, &self.operation_id),
408        ];
409        // A navigation without a summary has no preparation.
410        if !self.task.is_null() {
411            writes.push(Write::delete(OP_PREPARATION, &self.preparation_key()));
412        }
413        writes.extend([
414            Write::set(OP_RESULT, &self.operation_id, result),
415            Write::set(LANE_STATE, MAIN_LANE, self.lane_state(false)),
416        ]);
417        writes
418    }
419
420    /// Commit the compaction entry (`entry` without id and parent) as the new tip and end the operation.
421    pub fn complete(self, session: &mut Session, entry: Map<String, Value>) -> Result<String, String> {
422        let id = self.result_entry_id.clone();
423        let mut writes = vec![
424            Write::entry(&id, self.source_tip.as_deref(), entry),
425            Write::set(BRANCH_TIP, MAIN_LANE, id.clone().into()),
426        ];
427        writes.extend(self.terminal(session, "completed", Some(&id), None));
428        session.commit(&writes)?;
429        Ok(id)
430    }
431
432    /// End the operation as aborted (a cancel request, or a hook that cancelled it); the branch is unchanged.
433    pub fn abort(self, session: &mut Session) -> Result<(), String> {
434        let writes = self.terminal(session, "aborted", self.source_tip.as_deref(), None);
435        session.commit(&writes).map(drop)
436    }
437
438    /// End the operation as failed; the branch is unchanged.
439    pub fn fail(self, session: &mut Session, message: &str) -> Result<(), String> {
440        let writes = self.terminal(session, "failed", self.source_tip.as_deref(), Some(message));
441        session.commit(&writes).map(drop)
442    }
443}
444
445/// A cancel request for the lane's compaction or navigation operation in progress (`requestOperationAbort`): its state's control
446/// becomes `cancel_requested`, so a worker that dies before the terminal transaction is settled `aborted`.
447pub fn request_cancel(session: &mut Session, requested_at: i64) -> Result<(), String> {
448    let Some(operation) = session
449        .value(LANE_STATE, MAIN_LANE)
450        .and_then(|lane| lane["currentOperationId"].as_str().map(str::to_string))
451    else {
452        return Ok(());
453    };
454    if session
455        .value(OP_META, &operation)
456        .is_none_or(|meta| !matches!(meta["intent"]["kind"].as_str(), Some("compaction" | "navigation")))
457    {
458        return Ok(());
459    }
460    let Some(mut state) = session.value(OP_STATE, &operation).cloned() else {
461        return Ok(());
462    };
463    if state["control"]["status"] == "cancel_requested" {
464        return Ok(());
465    }
466    state["control"] = json!({"status": "cancel_requested", "requestedAt": requested_at});
467    session.commit(&[Write::set(OP_STATE, &operation, state)]).map(drop)
468}