Skip to main content

tea_kernel/
kernel.rs

1use std::collections::BTreeSet;
2
3use tea_control::CancellationScope;
4use tea_model::ModelRouter;
5use tea_policy::{ApprovalRequest, ApprovalResolution, PolicyDecision, PolicyEngine, PolicyInput};
6use tea_protocol::{
7    AgentEvent, ApprovalId, CanonicalMessage, ContentBlock, ExecutionTarget, NextTurnAction,
8    ProtocolMetadata, RunId, RunStatus, SessionId, SessionRecord, StopReason, ToolCallId, TurnId,
9};
10use tea_session::{
11    AppendTransaction, ApprovalArtifactEntry, GrantJournalEntry, SessionSnapshot, SessionStore,
12};
13use tea_tools::{ToolRegistry, ValidatedToolInvocation};
14
15use crate::approval::{add_duration, request as approval_request};
16use crate::model_turn::{CompletedToolCall, ModelTurnOutput, stream_turn};
17use crate::observe::EventEmitter;
18use crate::policy::{denial_reason, durable_decision, selected_target};
19use crate::record::{envelopes, envelopes_at, envelopes_with_metadata, tool_audit_metadata};
20use crate::scheduler::{SchedulePlan, Scheduler};
21use crate::tool_call::{PreparedToolCall, prepare};
22use crate::tool_execution::{
23    CollectedExecution, ToolExecutionContext, ToolTerminal, collect_execution, execute,
24    failed_terminal,
25};
26use crate::{
27    KernelClock, KernelError, KernelErrorCode, KernelEventSink, KernelIdSource, KernelInputQueue,
28    KernelRunConfig, RunState, TurnRequestSnapshot,
29};
30
31/// Terminal result of one kernel invocation.
32#[derive(Debug, Clone, PartialEq)]
33pub struct KernelRunOutcome {
34    run_id: RunId,
35    state: RunState,
36    session: tea_session::MaterializedSessionState,
37    pending_approval_id: Option<ApprovalId>,
38}
39
40impl KernelRunOutcome {
41    /// Returns the stable run identity.
42    #[must_use]
43    pub const fn run_id(&self) -> RunId {
44        self.run_id
45    }
46
47    /// Returns terminal run state.
48    #[must_use]
49    pub const fn state(&self) -> RunState {
50        self.state
51    }
52
53    /// Returns the committed materialized session state.
54    #[must_use]
55    pub const fn session(&self) -> &tea_session::MaterializedSessionState {
56        &self.session
57    }
58
59    /// Returns the durable approval that paused this invocation.
60    #[must_use]
61    pub const fn pending_approval_id(&self) -> Option<ApprovalId> {
62        self.pending_approval_id
63    }
64}
65
66enum ToolProcessOutcome {
67    Continue(SessionSnapshot),
68    Waiting(KernelRunOutcome),
69}
70
71struct RunProgress {
72    tool_iterations: u32,
73    assistant_output_bytes: usize,
74    deadline: tea_protocol::ProtocolTimestamp,
75}
76
77impl RunProgress {
78    fn output_budget(&self, config: &KernelRunConfig) -> Result<usize, KernelError> {
79        config
80            .limits()
81            .max_assistant_output_bytes()
82            .checked_sub(self.assistant_output_bytes)
83            .ok_or_else(|| {
84                KernelError::new(
85                    KernelErrorCode::LimitExceeded,
86                    "assistant output byte limit was reached",
87                )
88            })
89    }
90
91    fn observe_output(&mut self, bytes: usize) -> Result<(), KernelError> {
92        self.assistant_output_bytes =
93            self.assistant_output_bytes
94                .checked_add(bytes)
95                .ok_or_else(|| {
96                    KernelError::new(
97                        KernelErrorCode::LimitExceeded,
98                        "assistant output byte count cannot advance",
99                    )
100                })?;
101        Ok(())
102    }
103
104    fn advance_tools(&mut self, config: &KernelRunConfig) -> Result<(), KernelError> {
105        self.tool_iterations = self.tool_iterations.checked_add(1).ok_or_else(|| {
106            KernelError::new(
107                KernelErrorCode::LimitExceeded,
108                "tool iteration count cannot advance",
109            )
110        })?;
111        if self.tool_iterations > config.limits().max_tool_iterations() {
112            return Err(KernelError::new(
113                KernelErrorCode::LimitExceeded,
114                "tool iteration limit was reached",
115            ));
116        }
117        Ok(())
118    }
119}
120
121/// Headless coordinator for model, tool, policy, session, and observation ports.
122#[derive(Debug)]
123pub struct AgentKernel<'a> {
124    models: &'a dyn ModelRouter,
125    tools: &'a ToolRegistry,
126    policy: &'a PolicyEngine,
127    sessions: &'a dyn SessionStore,
128    clock: &'a dyn KernelClock,
129    ids: &'a dyn KernelIdSource,
130    events: &'a dyn KernelEventSink,
131    input_queue: Option<&'a KernelInputQueue>,
132}
133
134impl<'a> AgentKernel<'a> {
135    /// Creates a kernel from replaceable inward-facing ports.
136    #[must_use]
137    pub const fn new(
138        models: &'a dyn ModelRouter,
139        tools: &'a ToolRegistry,
140        policy: &'a PolicyEngine,
141        sessions: &'a dyn SessionStore,
142        clock: &'a dyn KernelClock,
143        ids: &'a dyn KernelIdSource,
144        events: &'a dyn KernelEventSink,
145    ) -> Self {
146        Self {
147            models,
148            tools,
149            policy,
150            sessions,
151            clock,
152            ids,
153            events,
154            input_queue: None,
155        }
156    }
157
158    /// Attaches a bounded queue consumed only between durable turns.
159    #[must_use]
160    pub const fn with_input_queue(mut self, queue: &'a KernelInputQueue) -> Self {
161        self.input_queue = Some(queue);
162        self
163    }
164
165    /// Appends a manual compaction summary, replacing the compacted prefix in
166    /// the model-visible transcript with the supplied summary message.
167    ///
168    /// The summary must be an assistant message. `compacted_through_record_id`
169    /// must be a record on the active branch. Original records remain in the
170    /// durable log for audit and replay.
171    ///
172    /// # Errors
173    ///
174    /// Returns an error when the session cannot be loaded, the summary is not
175    /// an assistant message, the referenced record is not on the active
176    /// branch, or the append transaction fails.
177    pub async fn compact(
178        &self,
179        session_id: SessionId,
180        summary: CanonicalMessage,
181        compacted_through_record_id: tea_protocol::RecordId,
182    ) -> Result<tea_session::SessionSnapshot, KernelError> {
183        let snapshot = self
184            .sessions
185            .load(session_id)
186            .await
187            .map_err(KernelError::from)?;
188        let timestamp = self.clock.now()?;
189        let records = envelopes_at(
190            self.ids,
191            session_id,
192            snapshot.state().tail_sequence(),
193            snapshot.state().active_branch_id(),
194            timestamp,
195            [SessionRecord::SessionCompacted {
196                summary,
197                compacted_through_record_id,
198            }],
199        )?;
200        self.sessions
201            .append(
202                AppendTransaction::new(session_id, Some(snapshot.state().tail_sequence()), records)
203                    .with_expected_journal_revision(snapshot.journal_revision()),
204            )
205            .await
206            .map_err(KernelError::from)?;
207        self.sessions
208            .load(session_id)
209            .await
210            .map_err(KernelError::from)
211    }
212
213    /// Runs serial model/tool turns until completion or durable approval pause.
214    ///
215    /// # Errors
216    ///
217    /// Returns a typed failure for invalid durable state, adapter contract
218    /// violations, rejected events, policy/tool failures, cancellation, or
219    /// deterministic run limits.
220    pub async fn run(
221        &self,
222        session_id: SessionId,
223        config: &KernelRunConfig,
224        cancellation: CancellationScope,
225    ) -> Result<KernelRunOutcome, KernelError> {
226        let snapshot = self
227            .sessions
228            .load(session_id)
229            .await
230            .map_err(KernelError::from)?;
231        validate_new_run_state(&snapshot)?;
232        let run_id = self.ids.next_run_id()?;
233        let mut emitter = EventEmitter::new(
234            self.ids,
235            self.clock,
236            self.events,
237            session_id,
238            snapshot.state().tail_sequence(),
239            config.limits(),
240        );
241        emitter
242            .emit(Some(run_id), None, AgentEvent::RunStarted {})
243            .await?;
244
245        let deadline = add_duration(self.clock.now()?, config.limits().max_elapsed())?;
246        self.run_loop(
247            snapshot,
248            config,
249            cancellation,
250            run_id,
251            &mut emitter,
252            RunProgress {
253                tool_iterations: 0,
254                assistant_output_bytes: 0,
255                deadline,
256            },
257        )
258        .await
259    }
260
261    /// Resolves one persisted approval and continues its original run.
262    ///
263    /// The supplied resolution must contain the exact rich request snapshot
264    /// stored with the canonical pending approval. Tool arguments and resources
265    /// are always loaded from durable session state.
266    ///
267    /// # Errors
268    ///
269    /// Returns a typed failure for missing, stale, mismatched, expired, or
270    /// concurrently resolved approvals and for subsequent runtime failures.
271    #[allow(clippy::too_many_lines)]
272    pub async fn resume_approval(
273        &self,
274        session_id: SessionId,
275        resolution: &ApprovalResolution,
276        config: &KernelRunConfig,
277        cancellation: CancellationScope,
278    ) -> Result<KernelRunOutcome, KernelError> {
279        let snapshot = self
280            .sessions
281            .load(session_id)
282            .await
283            .map_err(KernelError::from)?;
284        let request = persisted_request(&snapshot, *resolution.request().approval_id())?.clone();
285        if &request != resolution.request()
286            || request.actor_id() != config.actor_id()
287            || request.workspace_id() != config.workspace_id()
288            || request.environment() != config.environment()
289        {
290            return Err(KernelError::new(
291                KernelErrorCode::PolicyFailure,
292                "approval resolution does not match persisted request context",
293            ));
294        }
295        let run_id = request.run_id().copied().ok_or_else(|| {
296            KernelError::new(
297                KernelErrorCode::InvalidState,
298                "persisted approval has no active run",
299            )
300        })?;
301        let turn_id = snapshot
302            .state()
303            .latest_checkpoint()
304            .filter(|checkpoint| {
305                checkpoint.run_id() == run_id
306                    && checkpoint.next_action() == NextTurnAction::WaitForApproval
307            })
308            .map(tea_session::TurnCheckpoint::turn_id)
309            .ok_or_else(|| {
310                KernelError::new(
311                    KernelErrorCode::InvalidState,
312                    "persisted approval has no matching wait checkpoint",
313                )
314            })?;
315        let tool = snapshot
316            .state()
317            .tool_calls()
318            .get(request.tool_call_id())
319            .ok_or_else(|| {
320                KernelError::new(
321                    KernelErrorCode::InvalidState,
322                    "persisted approval tool call is missing",
323                )
324            })?;
325        let call = CompletedToolCall {
326            tool_call_id: tool.tool_call_id(),
327            tool_name: tool.tool_name().to_owned(),
328            arguments: tool.arguments().clone(),
329        };
330        let invocation = match prepare(self.tools, &call) {
331            PreparedToolCall::Valid(invocation) => invocation,
332            PreparedToolCall::Rejected { .. } => {
333                return Err(KernelError::new(
334                    KernelErrorCode::ToolFailure,
335                    "persisted approval tool no longer validates",
336                ));
337            }
338        };
339        if invocation.name() != request.tool_name()
340            || invocation.spec().version() != request.tool_version()
341            || invocation.source() != request.tool_source()
342            || invocation.spec().effects() != request.effects()
343            || invocation.resources() != request.resources()
344        {
345            return Err(KernelError::new(
346                KernelErrorCode::PolicyFailure,
347                "persisted approval no longer matches registered tool context",
348            ));
349        }
350        let deadline = add_duration(self.clock.now()?, config.limits().max_elapsed())?;
351        let mut emitter = EventEmitter::new(
352            self.ids,
353            self.clock,
354            self.events,
355            session_id,
356            snapshot.state().tail_sequence(),
357            config.limits(),
358        );
359        let denied = matches!(resolution.decision(), tea_protocol::ApprovalDecision::Deny);
360        let snapshot = if denied {
361            self.commit_denied_resolution(snapshot, resolution, &call)
362                .await?
363        } else {
364            let snapshot = self
365                .commit_resolution(
366                    snapshot,
367                    resolution,
368                    &invocation,
369                    config.environment().target(),
370                )
371                .await?;
372            let terminal = match execute(
373                self.tools,
374                invocation,
375                cancellation.child(),
376                &mut ToolExecutionContext {
377                    emitter: &mut emitter,
378                    run_id,
379                    turn_id,
380                    clock: self.clock,
381                    deadline,
382                },
383            )
384            .await
385            {
386                Ok(terminal) => terminal,
387                Err(error) => {
388                    self.record_tool_interruption(
389                        &snapshot,
390                        &call,
391                        run_id,
392                        turn_id,
393                        &error,
394                        &mut emitter,
395                    )
396                    .await?;
397                    return Err(error);
398                }
399            };
400            self.commit_terminal(snapshot, &call, terminal).await?
401        };
402        let mut snapshot = snapshot;
403        for pending_call in remaining_tool_calls(&snapshot, call.tool_call_id) {
404            match self
405                .process_tool(
406                    snapshot,
407                    &pending_call,
408                    config,
409                    run_id,
410                    turn_id,
411                    cancellation.child(),
412                    &mut emitter,
413                    deadline,
414                )
415                .await?
416            {
417                ToolProcessOutcome::Continue(next) => snapshot = next,
418                ToolProcessOutcome::Waiting(outcome) => return Ok(outcome),
419            }
420        }
421        let snapshot = self
422            .checkpoint_model_request(snapshot, run_id, turn_id, &mut emitter)
423            .await?;
424        let tool_iterations = completed_tool_iterations(&snapshot, run_id);
425        let output_bytes = committed_assistant_output_bytes(&snapshot, run_id)?;
426        self.run_loop(
427            snapshot,
428            config,
429            cancellation,
430            run_id,
431            &mut emitter,
432            RunProgress {
433                tool_iterations,
434                assistant_output_bytes: output_bytes,
435                deadline,
436            },
437        )
438        .await
439    }
440
441    async fn checkpoint_model_request(
442        &self,
443        snapshot: SessionSnapshot,
444        run_id: RunId,
445        turn_id: TurnId,
446        emitter: &mut EventEmitter<'_>,
447    ) -> Result<SessionSnapshot, KernelError> {
448        let snapshot = self
449            .append_records(
450                &snapshot,
451                [SessionRecord::TurnCheckpointed {
452                    run_id,
453                    turn_id,
454                    next_action: NextTurnAction::ModelRequest,
455                }],
456            )
457            .await?;
458        emitter
459            .emit(Some(run_id), Some(turn_id), AgentEvent::TurnCheckpointed {})
460            .await?;
461        Ok(snapshot)
462    }
463
464    #[allow(clippy::too_many_lines)]
465    async fn run_loop(
466        &self,
467        mut snapshot: SessionSnapshot,
468        config: &KernelRunConfig,
469        cancellation: CancellationScope,
470        run_id: RunId,
471        emitter: &mut EventEmitter<'_>,
472        mut progress: RunProgress,
473    ) -> Result<KernelRunOutcome, KernelError> {
474        let mut auto_compacted = false;
475        loop {
476            if cancellation.is_cancelled() {
477                let error = KernelError::new(KernelErrorCode::Cancelled, "agent run was cancelled");
478                self.record_run_terminal(&snapshot, run_id, None, &error, emitter)
479                    .await?;
480                return Err(error);
481            }
482            snapshot = self.apply_queued_input(snapshot).await?;
483            let turn_id = self.ids.next_turn_id()?;
484            let model_ref = snapshot
485                .state()
486                .configuration()
487                .model_ref()
488                .ok_or_else(|| {
489                    KernelError::new(KernelErrorCode::InvalidModel, "session has no active model")
490                })?;
491            let provider = self
492                .models
493                .provider(model_ref.provider_id())
494                .ok_or_else(|| {
495                    KernelError::new(
496                        KernelErrorCode::InvalidModel,
497                        "active model provider is not registered",
498                    )
499                })?;
500            let model = self.models.model(model_ref).ok_or_else(|| {
501                KernelError::new(
502                    KernelErrorCode::InvalidModel,
503                    "active model is not advertised by its provider",
504                )
505            })?;
506            let request = TurnRequestSnapshot::build(snapshot.state(), config, self.tools, model)?;
507            let accountant = crate::ContextWindowAccountant::new(model);
508            let estimated = crate::ContextWindowAccountant::estimate_input_tokens(
509                config.compiled_prompt(),
510                config.system_prompt(),
511                request.request().tools(),
512                snapshot.state().messages(),
513            );
514            if let Err(error) = accountant.check_overflow(estimated) {
515                if !auto_compacted
516                    && config
517                        .compaction_policy()
518                        .should_compact(estimated, accountant.context_window().get())
519                    && let Some(summarizer) = config.compaction_summarizer()
520                {
521                    let summary = summarizer
522                        .summarize(snapshot.state().messages().to_vec())
523                        .await?;
524                    let tail = snapshot.state().tail_record_id();
525                    snapshot = self
526                        .compact(snapshot.state().session_id(), summary, tail)
527                        .await?;
528                    auto_compacted = true;
529                    continue;
530                }
531                self.record_run_terminal(&snapshot, run_id, Some(turn_id), &error, emitter)
532                    .await?;
533                return Err(error);
534            }
535            let output = match stream_turn(
536                provider,
537                request,
538                self.ids,
539                emitter,
540                run_id,
541                turn_id,
542                cancellation.child(),
543                self.clock,
544                progress.deadline,
545                progress.output_budget(config)?,
546                config.retry_policy(),
547            )
548            .await
549            {
550                Ok(output) => output,
551                Err(error) => {
552                    self.record_run_terminal(&snapshot, run_id, Some(turn_id), &error, emitter)
553                        .await?;
554                    return Err(error);
555                }
556            };
557            progress.observe_output(output.output_bytes)?;
558            if output.tool_calls.is_empty() {
559                if output.completion.stop_reason() == &StopReason::PauseTurn {
560                    if let Err(error) = progress.advance_tools(config) {
561                        self.record_run_terminal(&snapshot, run_id, Some(turn_id), &error, emitter)
562                            .await?;
563                        return Err(error);
564                    }
565                    snapshot = self
566                        .commit_declarations(snapshot, &output, run_id, turn_id, emitter)
567                        .await?;
568                    snapshot = self
569                        .append_records(
570                            &snapshot,
571                            [SessionRecord::TurnCheckpointed {
572                                run_id,
573                                turn_id,
574                                next_action: NextTurnAction::ModelRequest,
575                            }],
576                        )
577                        .await?;
578                    emitter
579                        .emit(Some(run_id), Some(turn_id), AgentEvent::TurnCheckpointed {})
580                        .await?;
581                    continue;
582                }
583                return self
584                    .finish(snapshot, output, run_id, turn_id, emitter)
585                    .await;
586            }
587            if let Err(error) = progress.advance_tools(config) {
588                self.record_run_terminal(&snapshot, run_id, Some(turn_id), &error, emitter)
589                    .await?;
590                return Err(error);
591            }
592            snapshot = self
593                .commit_declarations(snapshot, &output, run_id, turn_id, emitter)
594                .await?;
595            match self
596                .process_tool_turn(
597                    snapshot,
598                    &output,
599                    config,
600                    run_id,
601                    turn_id,
602                    cancellation.child(),
603                    emitter,
604                    progress.deadline,
605                )
606                .await?
607            {
608                ToolProcessOutcome::Continue(next) => snapshot = next,
609                ToolProcessOutcome::Waiting(outcome) => return Ok(outcome),
610            }
611            snapshot = self
612                .append_records(
613                    &snapshot,
614                    [SessionRecord::TurnCheckpointed {
615                        run_id,
616                        turn_id,
617                        next_action: NextTurnAction::ModelRequest,
618                    }],
619                )
620                .await?;
621            emitter
622                .emit(Some(run_id), Some(turn_id), AgentEvent::TurnCheckpointed {})
623                .await?;
624        }
625    }
626
627    async fn apply_queued_input(
628        &self,
629        snapshot: SessionSnapshot,
630    ) -> Result<SessionSnapshot, KernelError> {
631        let Some(queue) = self.input_queue else {
632            return Ok(snapshot);
633        };
634        let queued = queue.snapshot()?;
635        if queued.follow_ups.is_empty() && queued.steering.is_empty() {
636            return Ok(snapshot);
637        }
638        let mut records = Vec::with_capacity(queued.follow_ups.len() + 1);
639        if !queued.steering.is_empty() {
640            let text = queued
641                .steering
642                .iter()
643                .map(tea_protocol::CommandText::as_str)
644                .collect::<Vec<_>>()
645                .join("\n");
646            let message = CanonicalMessage::user(
647                self.ids.next_message_id()?,
648                vec![ContentBlock::text(text)?],
649                self.clock.now()?,
650            )?;
651            records.push(SessionRecord::MessageCommitted { message });
652        }
653        records.extend(
654            queued
655                .follow_ups
656                .iter()
657                .cloned()
658                .map(|message| SessionRecord::MessageCommitted { message }),
659        );
660        let snapshot = self.append_records(&snapshot, records).await?;
661        queue.acknowledge(&queued)?;
662        Ok(snapshot)
663    }
664
665    async fn commit_declarations(
666        &self,
667        snapshot: SessionSnapshot,
668        output: &ModelTurnOutput,
669        run_id: RunId,
670        turn_id: TurnId,
671        emitter: &mut EventEmitter<'_>,
672    ) -> Result<SessionSnapshot, KernelError> {
673        let mut records = Vec::with_capacity(output.tool_calls.len() + 1);
674        records.push((
675            ProtocolMetadata::default(),
676            SessionRecord::MessageCommitted {
677                message: output.message.clone(),
678            },
679        ));
680        for call in &output.tool_calls {
681            let metadata = match prepare(self.tools, call) {
682                PreparedToolCall::Valid(invocation) => tool_audit_metadata(&invocation)?,
683                PreparedToolCall::Rejected { .. } => ProtocolMetadata::default(),
684            };
685            records.push((
686                metadata,
687                SessionRecord::ToolCallRequested {
688                    tool_call_id: call.tool_call_id,
689                    tool_name: call.tool_name.clone(),
690                    arguments: call.arguments.clone(),
691                },
692            ));
693        }
694        let snapshot = self
695            .append_records_with_metadata(&snapshot, records)
696            .await?;
697        for call in &output.tool_calls {
698            emitter
699                .emit(
700                    Some(run_id),
701                    Some(turn_id),
702                    AgentEvent::ToolCallRequested {
703                        tool_call_id: call.tool_call_id,
704                        tool_name: call.tool_name.clone(),
705                        arguments: call.arguments.clone(),
706                    },
707                )
708                .await?;
709        }
710        Ok(snapshot)
711    }
712
713    /// Processes all tool calls declared by a model turn with effect-aware
714    /// parallel scheduling and source-order result commits.
715    #[allow(clippy::too_many_arguments)]
716    #[allow(clippy::too_many_lines)]
717    async fn process_tool_turn(
718        &self,
719        mut snapshot: SessionSnapshot,
720        output: &ModelTurnOutput,
721        config: &KernelRunConfig,
722        run_id: RunId,
723        turn_id: TurnId,
724        cancellation: CancellationScope,
725        emitter: &mut EventEmitter<'_>,
726        deadline: tea_protocol::ProtocolTimestamp,
727    ) -> Result<ToolProcessOutcome, KernelError> {
728        #[allow(clippy::large_enum_variant)] // Short-lived turn values avoid extra allocation.
729        enum Classified {
730            Rejected {
731                index: usize,
732                code: &'static str,
733                message: &'static str,
734            },
735            Denied {
736                index: usize,
737                reason: String,
738            },
739            Allow {
740                invocation: ValidatedToolInvocation,
741                target: ExecutionTarget,
742            },
743            Ask {
744                // An approval is rare and ends the turn. Keep its validated
745                // invocation out of the turn-wide classification enum.
746                invocation: Box<ValidatedToolInvocation>,
747                input: PolicyInput,
748                reason: String,
749            },
750        }
751
752        let mut classified: Vec<Classified> = Vec::with_capacity(output.tool_calls.len());
753        for (index, call) in output.tool_calls.iter().enumerate() {
754            match prepare(self.tools, call) {
755                PreparedToolCall::Rejected { code, message } => {
756                    classified.push(Classified::Rejected {
757                        index,
758                        code,
759                        message,
760                    });
761                }
762                PreparedToolCall::Valid(invocation) => {
763                    let grant_candidates = self
764                        .sessions
765                        .active_grants_for_actor(config.actor_id().clone())
766                        .await
767                        .map_err(KernelError::from)?;
768                    let input = PolicyInput::from_validated(
769                        config.actor_id().clone(),
770                        snapshot.state().configuration().profile_id().clone(),
771                        snapshot.state().session_id(),
772                        Some(run_id),
773                        config.workspace_id().cloned(),
774                        &invocation,
775                        config.environment().clone(),
776                        self.clock.now()?,
777                        grant_candidates,
778                    )
779                    .map_err(|error| {
780                        KernelError::new(KernelErrorCode::PolicyFailure, error.to_string())
781                    })?;
782                    let evaluation = self.policy.evaluate(&input);
783                    match evaluation.decision() {
784                        PolicyDecision::Allow | PolicyDecision::Redirect { .. } => {
785                            let target = selected_target(
786                                evaluation.decision(),
787                                config.environment().target(),
788                                invocation.source().kind(),
789                            );
790                            classified.push(Classified::Allow { invocation, target });
791                        }
792                        PolicyDecision::Deny { .. } | PolicyDecision::HardDeny { .. } => {
793                            let reason = denial_reason(evaluation.decision())
794                                .unwrap_or("policy denied tool");
795                            classified.push(Classified::Denied {
796                                index,
797                                reason: reason.to_owned(),
798                            });
799                        }
800                        PolicyDecision::Ask(requirement) => {
801                            classified.push(Classified::Ask {
802                                invocation: Box::new(invocation),
803                                input,
804                                reason: requirement.reason().to_owned(),
805                            });
806                            break;
807                        }
808                    }
809                }
810            }
811        }
812
813        let mut batch: Vec<(ValidatedToolInvocation, ExecutionTarget)> = Vec::new();
814        for entry in classified {
815            match entry {
816                Classified::Rejected {
817                    index,
818                    code,
819                    message,
820                } => {
821                    snapshot = self
822                        .flush_tool_batch(
823                            snapshot,
824                            &batch,
825                            run_id,
826                            turn_id,
827                            cancellation.child(),
828                            emitter,
829                            deadline,
830                        )
831                        .await?;
832                    batch.clear();
833                    let terminal = failed_terminal(code, message)?;
834                    snapshot = self
835                        .commit_denied(snapshot, &output.tool_calls[index], terminal)
836                        .await?;
837                }
838                Classified::Denied { index, reason } => {
839                    snapshot = self
840                        .flush_tool_batch(
841                            snapshot,
842                            &batch,
843                            run_id,
844                            turn_id,
845                            cancellation.child(),
846                            emitter,
847                            deadline,
848                        )
849                        .await?;
850                    let terminal = failed_terminal("policy_denied", &reason)?;
851                    snapshot = self
852                        .commit_denied(snapshot, &output.tool_calls[index], terminal)
853                        .await?;
854                }
855                Classified::Allow { invocation, target } => {
856                    batch.push((invocation, target));
857                }
858                Classified::Ask {
859                    invocation,
860                    input,
861                    reason,
862                } => {
863                    snapshot = self
864                        .flush_tool_batch(
865                            snapshot,
866                            &batch,
867                            run_id,
868                            turn_id,
869                            cancellation.child(),
870                            emitter,
871                            deadline,
872                        )
873                        .await?;
874                    return self
875                        .wait_for_approval(
876                            snapshot,
877                            &invocation,
878                            &input,
879                            &reason,
880                            config,
881                            run_id,
882                            turn_id,
883                            emitter,
884                        )
885                        .await
886                        .map(ToolProcessOutcome::Waiting);
887                }
888            }
889        }
890        snapshot = self
891            .flush_tool_batch(
892                snapshot,
893                &batch,
894                run_id,
895                turn_id,
896                cancellation.child(),
897                emitter,
898                deadline,
899            )
900            .await?;
901        Ok(ToolProcessOutcome::Continue(snapshot))
902    }
903
904    /// Executes a batch of policy-allowed invocations with effect-aware
905    /// scheduling, committing durable results in canonical source order.
906    #[allow(clippy::too_many_arguments)]
907    #[allow(clippy::too_many_lines)]
908    async fn flush_tool_batch(
909        &self,
910        snapshot: SessionSnapshot,
911        batch: &[(ValidatedToolInvocation, ExecutionTarget)],
912        run_id: RunId,
913        turn_id: TurnId,
914        cancellation: CancellationScope,
915        emitter: &mut EventEmitter<'_>,
916        deadline: tea_protocol::ProtocolTimestamp,
917    ) -> Result<SessionSnapshot, KernelError> {
918        if batch.is_empty() {
919            return Ok(snapshot);
920        }
921        let invocations: Vec<&ValidatedToolInvocation> =
922            batch.iter().map(|(invocation, _)| invocation).collect();
923        let plan = Scheduler.plan(&invocations)?;
924        // Commit policy decisions and durable starts in source order.
925        let start_records: Vec<SessionRecord> = batch
926            .iter()
927            .flat_map(|(invocation, target)| {
928                [
929                    SessionRecord::PolicyDecisionRecorded {
930                        tool_call_id: *invocation.tool_call_id(),
931                        decision: tea_protocol::PolicyDecision::Allow,
932                    },
933                    SessionRecord::ToolExecutionStarted {
934                        tool_call_id: *invocation.tool_call_id(),
935                        execution_target: *target,
936                        idempotency: invocation.spec().execution().idempotency(),
937                    },
938                ]
939            })
940            .collect();
941        let mut snapshot = self.append_records(&snapshot, start_records).await?;
942        // Execute lanes; collect per-invocation results keyed by tool-call id.
943        let mut results: std::collections::HashMap<ToolCallId, CollectedExecution> =
944            std::collections::HashMap::new();
945        let exec_result = self
946            .execute_schedule_lanes(&plan, &mut results, cancellation, deadline)
947            .await;
948        if let Err(error) = exec_result {
949            let interrupted: Vec<SessionRecord> = batch
950                .iter()
951                .filter(|(invocation, _)| !results.contains_key(invocation.tool_call_id()))
952                .map(|(invocation, _)| SessionRecord::ToolExecutionInterrupted {
953                    tool_call_id: *invocation.tool_call_id(),
954                    reason: error.message().to_owned(),
955                })
956                .collect();
957            if !interrupted.is_empty() {
958                snapshot = self.append_records(&snapshot, interrupted).await?;
959            }
960            self.record_run_terminal(&snapshot, run_id, Some(turn_id), &error, emitter)
961                .await?;
962            return Err(error);
963        }
964        // Emit collected progress in source order.
965        for (invocation, _) in batch {
966            if let Some(collected) = results.get(invocation.tool_call_id()) {
967                for progress in &collected.progress {
968                    emitter
969                        .emit(
970                            Some(run_id),
971                            Some(turn_id),
972                            AgentEvent::ToolExecutionProgress {
973                                tool_call_id: progress.tool_call_id,
974                                message: progress.message.clone(),
975                                completed_units: progress.completed_units,
976                                total_units: progress.total_units,
977                            },
978                        )
979                        .await?;
980                }
981            }
982        }
983        // Commit terminals and tool-result messages in source order.
984        let mut records: Vec<SessionRecord> = Vec::with_capacity(batch.len() * 2);
985        for (invocation, _) in batch {
986            let collected = results.get(invocation.tool_call_id()).ok_or_else(|| {
987                KernelError::new(
988                    KernelErrorCode::InvalidState,
989                    "parallel tool batch is missing a collected terminal",
990                )
991            })?;
992            let terminal = &collected.terminal;
993            let is_error = terminal.failure.is_some();
994            records.push(SessionRecord::ToolExecutionFinished {
995                tool_call_id: *invocation.tool_call_id(),
996                is_error,
997                content: terminal.content.clone(),
998                error: terminal.failure.clone(),
999                presentation: terminal.presentation.clone(),
1000            });
1001            let message_id = self.ids.next_message_id()?;
1002            let message = if let Some(failure) = &terminal.failure {
1003                CanonicalMessage::tool_result_failure(
1004                    message_id,
1005                    *invocation.tool_call_id(),
1006                    invocation.name().to_string(),
1007                    terminal.content.clone(),
1008                    failure.clone(),
1009                    self.clock.now()?,
1010                )?
1011            } else {
1012                CanonicalMessage::tool_result_success(
1013                    message_id,
1014                    *invocation.tool_call_id(),
1015                    invocation.name().to_string(),
1016                    terminal.content.clone(),
1017                    self.clock.now()?,
1018                )?
1019            };
1020            records.push(SessionRecord::MessageCommitted { message });
1021        }
1022        snapshot = self.append_records(&snapshot, records).await?;
1023        Ok(snapshot)
1024    }
1025
1026    /// Runs every lane of a schedule, filling `results` keyed by tool-call id.
1027    ///
1028    /// The parallel lane runs concurrently via `join_all`; serial and exclusive
1029    /// lanes run one invocation at a time. The first execution error aborts the
1030    /// remaining work; the caller records interruptions for started-but-
1031    /// unterminated invocations.
1032    async fn execute_schedule_lanes(
1033        &self,
1034        plan: &SchedulePlan<'_>,
1035        results: &mut std::collections::HashMap<ToolCallId, CollectedExecution>,
1036        cancellation: CancellationScope,
1037        deadline: tea_protocol::ProtocolTimestamp,
1038    ) -> Result<(), KernelError> {
1039        for lane in plan.lanes() {
1040            if lane.allows_parallel() {
1041                let invocations = lane.invocations().to_vec();
1042                let futures = invocations.iter().map(|invocation| {
1043                    collect_execution(
1044                        self.tools,
1045                        (*invocation).clone(),
1046                        cancellation.child(),
1047                        self.clock,
1048                        deadline,
1049                    )
1050                });
1051                let lane_results = futures_util::future::join_all(futures).await;
1052                for (invocation, collected) in invocations.into_iter().zip(lane_results) {
1053                    let collected = collected?;
1054                    results.insert(*invocation.tool_call_id(), collected);
1055                }
1056            } else {
1057                for invocation in lane.invocations() {
1058                    let collected = collect_execution(
1059                        self.tools,
1060                        (*invocation).clone(),
1061                        cancellation.child(),
1062                        self.clock,
1063                        deadline,
1064                    )
1065                    .await?;
1066                    results.insert(*invocation.tool_call_id(), collected);
1067                }
1068            }
1069        }
1070        Ok(())
1071    }
1072
1073    #[allow(clippy::too_many_arguments)]
1074    async fn process_tool(
1075        &self,
1076        snapshot: SessionSnapshot,
1077        call: &CompletedToolCall,
1078        config: &KernelRunConfig,
1079        run_id: RunId,
1080        turn_id: TurnId,
1081        cancellation: CancellationScope,
1082        emitter: &mut EventEmitter<'_>,
1083        deadline: tea_protocol::ProtocolTimestamp,
1084    ) -> Result<ToolProcessOutcome, KernelError> {
1085        match prepare(self.tools, call) {
1086            PreparedToolCall::Rejected { code, message } => {
1087                let terminal = failed_terminal(code, message)?;
1088                self.commit_denied(snapshot, call, terminal)
1089                    .await
1090                    .map(ToolProcessOutcome::Continue)
1091            }
1092            PreparedToolCall::Valid(invocation) => {
1093                self.process_validated(
1094                    snapshot,
1095                    call,
1096                    invocation,
1097                    config,
1098                    run_id,
1099                    turn_id,
1100                    cancellation,
1101                    emitter,
1102                    deadline,
1103                )
1104                .await
1105            }
1106        }
1107    }
1108
1109    #[allow(clippy::too_many_arguments)]
1110    async fn process_validated(
1111        &self,
1112        snapshot: SessionSnapshot,
1113        call: &CompletedToolCall,
1114        invocation: ValidatedToolInvocation,
1115        config: &KernelRunConfig,
1116        run_id: RunId,
1117        turn_id: TurnId,
1118        cancellation: CancellationScope,
1119        emitter: &mut EventEmitter<'_>,
1120        deadline: tea_protocol::ProtocolTimestamp,
1121    ) -> Result<ToolProcessOutcome, KernelError> {
1122        let grant_candidates = self
1123            .sessions
1124            .active_grants_for_actor(config.actor_id().clone())
1125            .await
1126            .map_err(KernelError::from)?;
1127        let input = PolicyInput::from_validated(
1128            config.actor_id().clone(),
1129            snapshot.state().configuration().profile_id().clone(),
1130            snapshot.state().session_id(),
1131            Some(run_id),
1132            config.workspace_id().cloned(),
1133            &invocation,
1134            config.environment().clone(),
1135            self.clock.now()?,
1136            grant_candidates,
1137        )
1138        .map_err(|error| KernelError::new(KernelErrorCode::PolicyFailure, error.to_string()))?;
1139        let evaluation = self.policy.evaluate(&input);
1140        match evaluation.decision() {
1141            PolicyDecision::Allow | PolicyDecision::Redirect { .. } => {
1142                let target = selected_target(
1143                    evaluation.decision(),
1144                    config.environment().target(),
1145                    invocation.source().kind(),
1146                );
1147                let snapshot = self
1148                    .append_records(
1149                        &snapshot,
1150                        [
1151                            SessionRecord::PolicyDecisionRecorded {
1152                                tool_call_id: call.tool_call_id,
1153                                decision: durable_decision(evaluation.decision()),
1154                            },
1155                            SessionRecord::ToolExecutionStarted {
1156                                tool_call_id: call.tool_call_id,
1157                                execution_target: target,
1158                                idempotency: invocation.spec().execution().idempotency(),
1159                            },
1160                        ],
1161                    )
1162                    .await?;
1163                let terminal = match execute(
1164                    self.tools,
1165                    invocation,
1166                    cancellation,
1167                    &mut ToolExecutionContext {
1168                        emitter,
1169                        run_id,
1170                        turn_id,
1171                        clock: self.clock,
1172                        deadline,
1173                    },
1174                )
1175                .await
1176                {
1177                    Ok(terminal) => terminal,
1178                    Err(error) => {
1179                        self.record_tool_interruption(
1180                            &snapshot, call, run_id, turn_id, &error, emitter,
1181                        )
1182                        .await?;
1183                        return Err(error);
1184                    }
1185                };
1186                self.commit_terminal(snapshot, call, terminal)
1187                    .await
1188                    .map(ToolProcessOutcome::Continue)
1189            }
1190            PolicyDecision::Deny { .. } | PolicyDecision::HardDeny { .. } => {
1191                let reason = denial_reason(evaluation.decision()).unwrap_or("policy denied tool");
1192                let terminal = failed_terminal("policy_denied", reason)?;
1193                self.commit_denied(snapshot, call, terminal)
1194                    .await
1195                    .map(ToolProcessOutcome::Continue)
1196            }
1197            PolicyDecision::Ask(requirement) => self
1198                .wait_for_approval(
1199                    snapshot,
1200                    &invocation,
1201                    &input,
1202                    requirement.reason(),
1203                    config,
1204                    run_id,
1205                    turn_id,
1206                    emitter,
1207                )
1208                .await
1209                .map(ToolProcessOutcome::Waiting),
1210        }
1211    }
1212
1213    #[allow(clippy::too_many_arguments)]
1214    async fn wait_for_approval(
1215        &self,
1216        snapshot: SessionSnapshot,
1217        invocation: &ValidatedToolInvocation,
1218        input: &PolicyInput,
1219        reason: &str,
1220        config: &KernelRunConfig,
1221        run_id: RunId,
1222        turn_id: TurnId,
1223        emitter: &mut EventEmitter<'_>,
1224    ) -> Result<KernelRunOutcome, KernelError> {
1225        let approval_id = self.ids.next_approval_id()?;
1226        let created_at = self.clock.now()?;
1227        let request = approval_request(
1228            approval_id,
1229            input,
1230            reason,
1231            created_at,
1232            config.approval_ttl(),
1233        )?;
1234        let records = envelopes_at(
1235            self.ids,
1236            snapshot.state().session_id(),
1237            snapshot.state().tail_sequence(),
1238            snapshot.state().active_branch_id(),
1239            created_at,
1240            [
1241                SessionRecord::PolicyDecisionRecorded {
1242                    tool_call_id: *input.tool_call_id(),
1243                    decision: tea_protocol::PolicyDecision::RequireApproval,
1244                },
1245                SessionRecord::ApprovalRequested {
1246                    approval_id,
1247                    tool_call_id: *input.tool_call_id(),
1248                    expires_at: request.expires_at(),
1249                },
1250                SessionRecord::TurnCheckpointed {
1251                    run_id,
1252                    turn_id,
1253                    next_action: NextTurnAction::WaitForApproval,
1254                },
1255            ],
1256        )?;
1257        let approval_record_id = records
1258            .get(1)
1259            .map(tea_protocol::RecordEnvelope::record_id)
1260            .ok_or_else(|| {
1261                KernelError::new(
1262                    KernelErrorCode::InvalidState,
1263                    "approval transaction is missing its request record",
1264                )
1265            })?;
1266        self.sessions
1267            .append(
1268                AppendTransaction::new(
1269                    snapshot.state().session_id(),
1270                    Some(snapshot.state().tail_sequence()),
1271                    records,
1272                )
1273                .with_expected_journal_revision(snapshot.journal_revision())
1274                .with_approval_artifacts([ApprovalArtifactEntry::Requested {
1275                    record_id: approval_record_id,
1276                    request: request.clone(),
1277                }]),
1278            )
1279            .await
1280            .map_err(KernelError::from)?;
1281        let snapshot = self
1282            .sessions
1283            .load(snapshot.state().session_id())
1284            .await
1285            .map_err(KernelError::from)?;
1286        let capabilities = request
1287            .effects()
1288            .iter()
1289            .map(|effect| effect.as_str().to_owned())
1290            .collect();
1291        let mut resources = request.presentation().resources().to_vec();
1292        if resources.is_empty() {
1293            resources.push(format!("tool:{}", request.tool_name().as_str()));
1294        }
1295        self.emit_tool_preview(invocation, run_id, turn_id, emitter)
1296            .await?;
1297        emitter
1298            .emit(
1299                Some(run_id),
1300                Some(turn_id),
1301                AgentEvent::ApprovalRequested {
1302                    approval_id,
1303                    tool_call_id: *input.tool_call_id(),
1304                    capabilities,
1305                    resources,
1306                    expires_at: request.expires_at(),
1307                },
1308            )
1309            .await?;
1310        emitter
1311            .emit(Some(run_id), Some(turn_id), AgentEvent::TurnCheckpointed {})
1312            .await?;
1313        Ok(KernelRunOutcome {
1314            run_id,
1315            state: RunState::WaitingApproval,
1316            session: snapshot.state().clone(),
1317            pending_approval_id: Some(approval_id),
1318        })
1319    }
1320
1321    async fn emit_tool_preview(
1322        &self,
1323        invocation: &ValidatedToolInvocation,
1324        run_id: RunId,
1325        turn_id: TurnId,
1326        emitter: &mut EventEmitter<'_>,
1327    ) -> Result<(), KernelError> {
1328        let Some(presentation) = self.tools.preview_validated(invocation) else {
1329            return Ok(());
1330        };
1331        emitter
1332            .emit(
1333                Some(run_id),
1334                Some(turn_id),
1335                AgentEvent::ToolExecutionPreview {
1336                    tool_call_id: *invocation.tool_call_id(),
1337                    presentation,
1338                },
1339            )
1340            .await
1341    }
1342
1343    async fn commit_denied_resolution(
1344        &self,
1345        snapshot: SessionSnapshot,
1346        resolution: &ApprovalResolution,
1347        call: &CompletedToolCall,
1348    ) -> Result<SessionSnapshot, KernelError> {
1349        let terminal =
1350            failed_terminal("approval_denied", "tool invocation was denied by approval")?;
1351        let message = CanonicalMessage::tool_result_failure(
1352            self.ids.next_message_id()?,
1353            call.tool_call_id,
1354            call.tool_name.clone(),
1355            terminal.content.clone(),
1356            terminal.failure.clone().ok_or_else(|| {
1357                KernelError::new(
1358                    KernelErrorCode::InvalidState,
1359                    "approval denial has no failure",
1360                )
1361            })?,
1362            resolution.decided_at(),
1363        )?;
1364        let records = envelopes_at(
1365            self.ids,
1366            snapshot.state().session_id(),
1367            snapshot.state().tail_sequence(),
1368            snapshot.state().active_branch_id(),
1369            resolution.decided_at(),
1370            [
1371                SessionRecord::ApprovalResolved {
1372                    approval_id: *resolution.request().approval_id(),
1373                    decision: resolution.decision(),
1374                },
1375                SessionRecord::ToolExecutionFinished {
1376                    tool_call_id: call.tool_call_id,
1377                    is_error: true,
1378                    content: terminal.content,
1379                    error: terminal.failure,
1380                    presentation: None,
1381                },
1382                SessionRecord::MessageCommitted { message },
1383            ],
1384        )?;
1385        let record_id = records[0].record_id();
1386        self.sessions
1387            .append(
1388                AppendTransaction::new(
1389                    snapshot.state().session_id(),
1390                    Some(snapshot.state().tail_sequence()),
1391                    records,
1392                )
1393                .with_expected_journal_revision(snapshot.journal_revision())
1394                .with_approval_artifacts([ApprovalArtifactEntry::Resolved {
1395                    record_id,
1396                    resolution: resolution.clone(),
1397                }]),
1398            )
1399            .await
1400            .map_err(KernelError::from)?;
1401        self.sessions
1402            .load(snapshot.state().session_id())
1403            .await
1404            .map_err(KernelError::from)
1405    }
1406
1407    async fn commit_resolution(
1408        &self,
1409        snapshot: SessionSnapshot,
1410        resolution: &ApprovalResolution,
1411        invocation: &ValidatedToolInvocation,
1412        target: tea_policy::PolicyExecutionTarget,
1413    ) -> Result<SessionSnapshot, KernelError> {
1414        let allowed = matches!(
1415            resolution.decision(),
1416            tea_protocol::ApprovalDecision::AllowOnce
1417                | tea_protocol::ApprovalDecision::AllowSession
1418        );
1419        let mut facts = vec![SessionRecord::ApprovalResolved {
1420            approval_id: *resolution.request().approval_id(),
1421            decision: resolution.decision(),
1422        }];
1423        if allowed {
1424            facts.push(SessionRecord::ToolExecutionStarted {
1425                tool_call_id: *resolution.request().tool_call_id(),
1426                execution_target: selected_target(
1427                    &PolicyDecision::Allow,
1428                    target,
1429                    invocation.source().kind(),
1430                ),
1431                idempotency: invocation.spec().execution().idempotency(),
1432            });
1433        }
1434        let records = envelopes_at(
1435            self.ids,
1436            snapshot.state().session_id(),
1437            snapshot.state().tail_sequence(),
1438            snapshot.state().active_branch_id(),
1439            resolution.decided_at(),
1440            facts,
1441        )?;
1442        let resolution_record_id = records
1443            .first()
1444            .map(tea_protocol::RecordEnvelope::record_id)
1445            .ok_or_else(|| {
1446                KernelError::new(
1447                    KernelErrorCode::InvalidState,
1448                    "approval resolution transaction is empty",
1449                )
1450            })?;
1451        let mut transaction = AppendTransaction::new(
1452            snapshot.state().session_id(),
1453            Some(snapshot.state().tail_sequence()),
1454            records,
1455        )
1456        .with_expected_journal_revision(snapshot.journal_revision())
1457        .with_approval_artifacts([ApprovalArtifactEntry::Resolved {
1458            record_id: resolution_record_id,
1459            resolution: resolution.clone(),
1460        }]);
1461        if let Some(grant) = resolution.issued_grant() {
1462            transaction = transaction.with_grant_entries([GrantJournalEntry::Issued {
1463                approval_record_id: resolution_record_id,
1464                grant: grant.clone(),
1465            }]);
1466        }
1467        self.sessions
1468            .append(transaction)
1469            .await
1470            .map_err(KernelError::from)?;
1471        self.sessions
1472            .load(snapshot.state().session_id())
1473            .await
1474            .map_err(KernelError::from)
1475    }
1476
1477    async fn commit_denied(
1478        &self,
1479        snapshot: SessionSnapshot,
1480        call: &CompletedToolCall,
1481        terminal: ToolTerminal,
1482    ) -> Result<SessionSnapshot, KernelError> {
1483        self.commit_terminal_with_prefix(
1484            snapshot,
1485            call,
1486            terminal,
1487            Some(SessionRecord::PolicyDecisionRecorded {
1488                tool_call_id: call.tool_call_id,
1489                decision: tea_protocol::PolicyDecision::Deny,
1490            }),
1491        )
1492        .await
1493    }
1494
1495    async fn commit_terminal(
1496        &self,
1497        snapshot: SessionSnapshot,
1498        call: &CompletedToolCall,
1499        terminal: ToolTerminal,
1500    ) -> Result<SessionSnapshot, KernelError> {
1501        self.commit_terminal_with_prefix(snapshot, call, terminal, None)
1502            .await
1503    }
1504
1505    async fn commit_terminal_with_prefix(
1506        &self,
1507        snapshot: SessionSnapshot,
1508        call: &CompletedToolCall,
1509        terminal: ToolTerminal,
1510        prefix: Option<SessionRecord>,
1511    ) -> Result<SessionSnapshot, KernelError> {
1512        let mut records = Vec::with_capacity(3);
1513        records.extend(prefix);
1514        let is_error = terminal.failure.is_some();
1515        records.push(SessionRecord::ToolExecutionFinished {
1516            tool_call_id: call.tool_call_id,
1517            is_error,
1518            content: terminal.content.clone(),
1519            error: terminal.failure.clone(),
1520            presentation: terminal.presentation.clone(),
1521        });
1522        let message_id = self.ids.next_message_id()?;
1523        let message = if let Some(failure) = terminal.failure {
1524            CanonicalMessage::tool_result_failure(
1525                message_id,
1526                call.tool_call_id,
1527                call.tool_name.clone(),
1528                terminal.content,
1529                failure,
1530                self.clock.now()?,
1531            )?
1532        } else {
1533            CanonicalMessage::tool_result_success(
1534                message_id,
1535                call.tool_call_id,
1536                call.tool_name.clone(),
1537                terminal.content,
1538                self.clock.now()?,
1539            )?
1540        };
1541        records.push(SessionRecord::MessageCommitted { message });
1542        self.append_records(&snapshot, records).await
1543    }
1544
1545    async fn finish(
1546        &self,
1547        snapshot: SessionSnapshot,
1548        output: ModelTurnOutput,
1549        run_id: RunId,
1550        turn_id: TurnId,
1551        emitter: &mut EventEmitter<'_>,
1552    ) -> Result<KernelRunOutcome, KernelError> {
1553        let snapshot = self
1554            .append_records(
1555                &snapshot,
1556                [
1557                    SessionRecord::MessageCommitted {
1558                        message: output.message,
1559                    },
1560                    SessionRecord::TurnCheckpointed {
1561                        run_id,
1562                        turn_id,
1563                        next_action: NextTurnAction::FinishRun,
1564                    },
1565                ],
1566            )
1567            .await?;
1568        emitter
1569            .emit(Some(run_id), Some(turn_id), AgentEvent::TurnCheckpointed {})
1570            .await?;
1571        emitter
1572            .emit(
1573                Some(run_id),
1574                None,
1575                AgentEvent::RunFinished {
1576                    status: RunStatus::Completed,
1577                    usage: output.completion.usage().cloned(),
1578                    cost: output.completion.cost().cloned(),
1579                },
1580            )
1581            .await?;
1582        Ok(KernelRunOutcome {
1583            run_id,
1584            state: RunState::Completed,
1585            session: snapshot.state().clone(),
1586            pending_approval_id: None,
1587        })
1588    }
1589
1590    async fn record_tool_interruption(
1591        &self,
1592        snapshot: &SessionSnapshot,
1593        call: &CompletedToolCall,
1594        run_id: RunId,
1595        turn_id: TurnId,
1596        error: &KernelError,
1597        emitter: &mut EventEmitter<'_>,
1598    ) -> Result<(), KernelError> {
1599        let snapshot = self
1600            .append_records(
1601                snapshot,
1602                [SessionRecord::ToolExecutionInterrupted {
1603                    tool_call_id: call.tool_call_id,
1604                    reason: error.message().to_owned(),
1605                }],
1606            )
1607            .await?;
1608        self.record_run_terminal(&snapshot, run_id, Some(turn_id), error, emitter)
1609            .await
1610    }
1611
1612    async fn record_run_terminal(
1613        &self,
1614        snapshot: &SessionSnapshot,
1615        run_id: RunId,
1616        turn_id: Option<TurnId>,
1617        error: &KernelError,
1618        emitter: &mut EventEmitter<'_>,
1619    ) -> Result<(), KernelError> {
1620        let (record, status) = if error.code() == KernelErrorCode::Cancelled {
1621            (SessionRecord::RunCancelled { run_id }, RunStatus::Cancelled)
1622        } else {
1623            let turn_id = turn_id.ok_or_else(|| {
1624                KernelError::new(
1625                    KernelErrorCode::InvalidState,
1626                    "interrupted run has no active turn",
1627                )
1628            })?;
1629            (
1630                SessionRecord::RunInterrupted {
1631                    run_id,
1632                    turn_id,
1633                    reason: error.message().to_owned(),
1634                },
1635                RunStatus::Interrupted,
1636            )
1637        };
1638        self.append_records(snapshot, [record]).await?;
1639        emitter
1640            .emit(
1641                Some(run_id),
1642                None,
1643                AgentEvent::RunFinished {
1644                    status,
1645                    usage: None,
1646                    cost: None,
1647                },
1648            )
1649            .await
1650    }
1651
1652    async fn append_records(
1653        &self,
1654        snapshot: &SessionSnapshot,
1655        records: impl IntoIterator<Item = SessionRecord>,
1656    ) -> Result<SessionSnapshot, KernelError> {
1657        let records = envelopes(
1658            self.ids,
1659            self.clock,
1660            snapshot.state().session_id(),
1661            snapshot.state().tail_sequence(),
1662            snapshot.state().active_branch_id(),
1663            records,
1664        )?;
1665        self.sessions
1666            .append(AppendTransaction::new(
1667                snapshot.state().session_id(),
1668                Some(snapshot.state().tail_sequence()),
1669                records,
1670            ))
1671            .await
1672            .map_err(KernelError::from)?;
1673        self.sessions
1674            .load(snapshot.state().session_id())
1675            .await
1676            .map_err(KernelError::from)
1677    }
1678
1679    async fn append_records_with_metadata(
1680        &self,
1681        snapshot: &SessionSnapshot,
1682        records: impl IntoIterator<Item = (ProtocolMetadata, SessionRecord)>,
1683    ) -> Result<SessionSnapshot, KernelError> {
1684        let records = envelopes_with_metadata(
1685            self.ids,
1686            self.clock,
1687            snapshot.state().session_id(),
1688            snapshot.state().tail_sequence(),
1689            snapshot.state().active_branch_id(),
1690            records,
1691        )?;
1692        self.sessions
1693            .append(AppendTransaction::new(
1694                snapshot.state().session_id(),
1695                Some(snapshot.state().tail_sequence()),
1696                records,
1697            ))
1698            .await
1699            .map_err(KernelError::from)?;
1700        self.sessions
1701            .load(snapshot.state().session_id())
1702            .await
1703            .map_err(KernelError::from)
1704    }
1705}
1706
1707fn validate_new_run_state(snapshot: &SessionSnapshot) -> Result<(), KernelError> {
1708    if !snapshot.state().pending_approvals().is_empty() {
1709        return Err(KernelError::new(
1710            KernelErrorCode::InvalidState,
1711            "session has a pending approval; resume it explicitly",
1712        ));
1713    }
1714    if snapshot
1715        .state()
1716        .tool_calls()
1717        .values()
1718        .any(|tool| tool.result_message_id().is_none())
1719    {
1720        return Err(KernelError::new(
1721            KernelErrorCode::InvalidState,
1722            "session has an incomplete or uncertain tool outcome",
1723        ));
1724    }
1725    Ok(())
1726}
1727
1728fn remaining_tool_calls(
1729    snapshot: &SessionSnapshot,
1730    completed_call_id: tea_protocol::ToolCallId,
1731) -> Vec<CompletedToolCall> {
1732    let mut after_completed = false;
1733    snapshot
1734        .records()
1735        .iter()
1736        .filter_map(|record| match record.record() {
1737            SessionRecord::ToolCallRequested { tool_call_id, .. }
1738                if *tool_call_id == completed_call_id =>
1739            {
1740                after_completed = true;
1741                None
1742            }
1743            SessionRecord::ToolCallRequested {
1744                tool_call_id,
1745                tool_name,
1746                arguments,
1747            } if after_completed
1748                && snapshot
1749                    .state()
1750                    .tool_calls()
1751                    .get(tool_call_id)
1752                    .is_some_and(|tool| {
1753                        tool.policy_decision().is_none()
1754                            && matches!(
1755                                tool.execution(),
1756                                tea_session::ToolExecutionState::NotStarted
1757                            )
1758                    }) =>
1759            {
1760                Some(CompletedToolCall {
1761                    tool_call_id: *tool_call_id,
1762                    tool_name: tool_name.clone(),
1763                    arguments: arguments.clone(),
1764                })
1765            }
1766            SessionRecord::SessionCreated { .. }
1767            | SessionRecord::MessageCommitted { .. }
1768            | SessionRecord::ConfigurationChanged { .. }
1769            | SessionRecord::ToolCallRequested { .. }
1770            | SessionRecord::PolicyDecisionRecorded { .. }
1771            | SessionRecord::ApprovalRequested { .. }
1772            | SessionRecord::ApprovalResolved { .. }
1773            | SessionRecord::ToolExecutionStarted { .. }
1774            | SessionRecord::ToolExecutionFinished { .. }
1775            | SessionRecord::ToolExecutionInterrupted { .. }
1776            | SessionRecord::RunInterrupted { .. }
1777            | SessionRecord::RunCancelled { .. }
1778            | SessionRecord::BranchCreated { .. }
1779            | SessionRecord::ActiveBranchChanged { .. }
1780            | SessionRecord::SessionCompacted { .. }
1781            | SessionRecord::TurnCheckpointed { .. } => None,
1782        })
1783        .collect()
1784}
1785
1786fn completed_tool_iterations(snapshot: &SessionSnapshot, run_id: RunId) -> u32 {
1787    snapshot
1788        .records()
1789        .iter()
1790        .filter_map(|record| match record.record() {
1791            SessionRecord::TurnCheckpointed {
1792                run_id: checkpoint_run,
1793                turn_id,
1794                ..
1795            } if *checkpoint_run == run_id => Some(*turn_id),
1796            _ => None,
1797        })
1798        .collect::<BTreeSet<_>>()
1799        .len()
1800        .try_into()
1801        .unwrap_or(u32::MAX)
1802}
1803
1804fn committed_assistant_output_bytes(
1805    snapshot: &SessionSnapshot,
1806    run_id: RunId,
1807) -> Result<usize, KernelError> {
1808    let mut segment_bytes = 0usize;
1809    let mut run_bytes = 0usize;
1810    for record in snapshot.records() {
1811        match record.record() {
1812            SessionRecord::MessageCommitted {
1813                message: CanonicalMessage::Assistant { content, .. },
1814            } => segment_bytes = checked_content_bytes(segment_bytes, content)?,
1815            SessionRecord::TurnCheckpointed {
1816                run_id: checkpoint_run,
1817                ..
1818            } => {
1819                if *checkpoint_run == run_id {
1820                    run_bytes = run_bytes
1821                        .checked_add(segment_bytes)
1822                        .ok_or_else(byte_count_error)?;
1823                }
1824                segment_bytes = 0;
1825            }
1826            _ => {}
1827        }
1828    }
1829    Ok(run_bytes)
1830}
1831
1832fn checked_content_bytes(initial: usize, content: &[ContentBlock]) -> Result<usize, KernelError> {
1833    content.iter().try_fold(initial, |total, block| {
1834        let bytes = match block {
1835            ContentBlock::Text { text } | ContentBlock::Thinking { text } => text.len(),
1836            ContentBlock::Image { .. } | ContentBlock::ToolCall { .. } => 0,
1837            ContentBlock::HostedTool { .. } | ContentBlock::Citation { .. } => {
1838                serde_json::to_vec(block)
1839                    .map_err(|_| byte_count_error())?
1840                    .len()
1841            }
1842        };
1843        total.checked_add(bytes).ok_or_else(byte_count_error)
1844    })
1845}
1846
1847fn byte_count_error() -> KernelError {
1848    KernelError::new(
1849        KernelErrorCode::LimitExceeded,
1850        "assistant output byte count cannot be reconstructed",
1851    )
1852}
1853
1854fn persisted_request(
1855    snapshot: &SessionSnapshot,
1856    approval_id: ApprovalId,
1857) -> Result<&ApprovalRequest, KernelError> {
1858    snapshot
1859        .approval_artifacts()
1860        .iter()
1861        .find_map(|entry| match entry {
1862            ApprovalArtifactEntry::Requested { request, .. }
1863                if request.approval_id() == &approval_id =>
1864            {
1865                Some(request)
1866            }
1867            ApprovalArtifactEntry::Requested { .. } | ApprovalArtifactEntry::Resolved { .. } => {
1868                None
1869            }
1870        })
1871        .ok_or_else(|| {
1872            KernelError::new(
1873                KernelErrorCode::PolicyFailure,
1874                "persisted approval request is missing",
1875            )
1876        })
1877}
1878
1879impl From<tea_session::SessionStoreError> for KernelError {
1880    fn from(error: tea_session::SessionStoreError) -> Self {
1881        Self::new(KernelErrorCode::SessionFailure, error.to_string())
1882    }
1883}