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#[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 #[must_use]
43 pub const fn run_id(&self) -> RunId {
44 self.run_id
45 }
46
47 #[must_use]
49 pub const fn state(&self) -> RunState {
50 self.state
51 }
52
53 #[must_use]
55 pub const fn session(&self) -> &tea_session::MaterializedSessionState {
56 &self.session
57 }
58
59 #[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#[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 #[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 #[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 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 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 #[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 #[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)] 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 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 #[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 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 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 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 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 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}