feat(harness): typed terminal outcomes and turn/message lifecycle events

crates/tinyagents-graph/src/agent_loop/driver.rs

@@ -20,6 +20,7 @@ use tinyagents_harness::ids::HarnessPhase;
 use tinyagents_harness::middleware::AgentRun;
 use tinyagents_harness::runtime::AgentHarness;
 use tinyagents_harness::steering::PauseState;
+use tinyagents_harness::terminal::{TerminalOutcome, TerminalReason};
 use tinyinference_llm::message::Message;
 
 use crate::command::{NodeResult, RouteTarget};
@@ -81,7 +82,10 @@ where
             messages: input,
             ..LoopState::default()
         };
+        ctx.reset_turn_tracker(loop_state.messages.len());
         let mut current: &str = node::PLAN;
+        let mut limit_stop = false;
+        let mut limit_kind = None;
 
         let outcome = loop {
             // Keeps `run.messages` a running snapshot of the transcript as
@@ -165,6 +169,9 @@ where
                             ));
                         }
                     };
+                    limit_stop |= loop_state.limit_stop;
+                    // Latch the first kind: a later command must not erase it.
+                    limit_kind = limit_kind.or(loop_state.limit_kind);
                     let Some(target) = command.goto.first() else {
                         break Err(TinyAgentsError::Validation(
                             "GraphLoopDriver: loop node's command carried no route".to_string(),
@@ -197,11 +204,81 @@ where
             }
         };
 
+        let terminal = match &outcome {
+            Ok(None) => {
+                let reason = if limit_stop {
+                    TerminalOutcome::limit_reached(
+                        limit_kind,
+                        format!(
+                            "stopped with the partial run: {} limit reached",
+                            limit_kind.map_or("run", |kind| kind.as_str())
+                        ),
+                    )
+                } else {
+                    TerminalOutcome::completed()
+                };
+                Some(reason.with_provider_started(ctx.provider_started()))
+            }
+            Ok(Some(interrupt)) => {
+                let reason = interrupt
+                    .payload
+                    .get("reason")
+                    .or_else(|| interrupt.payload.get("message"))
+                    .and_then(|value| value.as_str())
+                    .map(str::to_string);
+                let outcome = if let Some(summary) = ctx.take_halted_by_guard() {
+                    TerminalOutcome::halted(summary)
+                } else {
+                    TerminalOutcome::new(
+                        TerminalReason::Paused,
+                        reason
+                            .clone()
+                            .unwrap_or_else(|| format!("paused at node `{}`", interrupt.node)),
+                    )
+                };
+                Some(outcome.with_provider_started(ctx.provider_started()))
+            }
+            Err(error) => {
+                use tinyagents_harness::terminal::TimeoutPhase;
+                let in_model_call = ctx.model_call_failed() || ctx.active_model_call.is_some();
+                let site = if in_model_call && ctx.call_provider_started() {
+                    TimeoutPhase::Provider
+                } else if in_model_call {
+                    TimeoutPhase::BeforeProvider
+                } else if ctx.provider_started() {
+                    TimeoutPhase::AfterTurn
+                } else {
+                    TimeoutPhase::BeforeProvider
+                };
+                // A `LimitExceeded` carries only text; the cap that tripped was
+                // announced by a `LimitReached` event just before.
+                let kind = matches!(error, TinyAgentsError::LimitExceeded(_))
+                    .then(|| ctx.peek_last_limit())
+                    .flatten();
+                let mut outcome = TerminalOutcome::from_error(error, site).with_limit_kind(kind);
+                // A failed summarizer already received a provider response, though
+                // summarizer calls bypass the context's dispatch marker.
+                outcome.provider_started = ctx.provider_started()
+                    || matches!(error, TinyAgentsError::SummarizationUsage { .. });
+                Some(outcome)
+            }
+        };
+        run.terminal = terminal.clone();
         status.mark_running(HarnessPhase::Middleware);
-        harness
-            .middleware()
-            .run_after_agent(ctx, state, run)
-            .await?;
+        let after_agent = harness.middleware().run_after_agent(ctx, state, run).await;
+        if let Err(hook_error) = after_agent {
+            if outcome.is_err() {
+                // The originating node failure stays authoritative, as in the
+                // direct loop; the hook still ran for its cleanup.
+                tracing::warn!(
+                    target: "tinyagents::agent_loop",
+                    error = %hook_error,
+                    "[agent_loop] after_agent failed after a node error; keeping the node error"
+                );
+            } else {
+                return Err(hook_error);
+            }
+        }
 
         // `status.mark_completed`/`mark_interrupted`/`mark_failed` and (on
         // error) `AgentEvent::RunFailed` are applied centrally by
@@ -214,8 +291,15 @@ where
         // interrupt.
         match outcome {
             Ok(None) => {
+                // `after_agent` may have replaced the outcome; report the final one.
+                let outcome = run
+                    .terminal
+                    .clone()
+                    .or(terminal)
+                    .expect("terminal set before after_agent");
                 let record = ctx.emit(AgentEvent::RunCompleted {
                     run_id: ctx.run_id().clone(),
+                    outcome: Some(outcome),
                 });
                 status.set_last_event(record.id);
                 Ok(())
@@ -234,10 +318,15 @@ where
                         .unwrap_or_else(|| format!("paused at node `{}`", interrupt.node)),
                 });
                 status.set_last_event(record.id);
-                run.paused = Some(PauseState {
-                    reason,
-                    paused_at_checkpoint: 0,
-                });
+                if !matches!(
+                    run.terminal.as_ref().map(|outcome| outcome.reason),
+                    Some(TerminalReason::Halted)
+                ) {
+                    run.paused = Some(PauseState {
+                        reason,
+                        paused_at_checkpoint: 0,
+                    });
+                }
                 Ok(())
             }
             Err(error) => Err(error),

crates/tinyagents-graph/src/agent_loop/runtime.rs

@@ -116,11 +116,13 @@ impl<State: Send + Sync, Ctx: Send + Sync> ModelBaseCall<State, Ctx>
 {
     fn call<'a>(
         &'a self,
-        _ctx: &'a mut RunContext<Ctx>,
+        ctx: &'a mut RunContext<Ctx>,
         state: &'a State,
         request: ModelRequest,
     ) -> BoxModelFuture<'a> {
         Box::pin(async move {
+            // Reached only when the wrap onion elected to call the provider.
+            ctx.mark_provider_started();
             self.model
                 .invoke(state, request)
                 .await
@@ -304,6 +306,8 @@ where
             tinyagents_harness::limits::LimitBehavior::StopWithPartial
         ) {
             loop_state.finished = true;
+            loop_state.limit_stop = true;
+            loop_state.limit_kind = Some(tinyagents_harness::events::LimitKind::ModelCalls);
             if loop_state.final_text.is_none() {
                 loop_state.final_text = Some(last_assistant_text(&loop_state.messages));
             }
@@ -425,22 +429,36 @@ where
         model: model_name.clone(),
     });
     status.set_last_event(started_record.id);
+    status.active_model_call = Some(call_id.clone());
+    ctx.active_model_call = Some(call_id.clone());
+    ctx.begin_model_call();
 
     let base = DirectModelBase {
         model: binding.model.as_ref(),
     };
-    let (mut response, wrap_control) = harness
+    let wrapped = match harness
         .middleware()
         .run_wrapped_model(ctx, app_state, request, &base)
-        .await?
-        .into_response_with_control();
+        .await
+    {
+        Ok(wrapped) => wrapped,
+        Err(error) => {
+            status.active_model_call = None;
+            ctx.active_model_call = None;
+            ctx.mark_model_call_failed();
+            return Err(error);
+        }
+    };
+    let (mut response, wrap_control) = wrapped.into_response_with_control();
     if let Some(control) = wrap_control {
         ctx.request_control(control);
     }
 
     run.model_calls += 1;
     run.steps += 1;
     status.model_calls = run.model_calls;
+    status.active_model_call = None;
+    ctx.active_model_call = None;
     if let Some(usage) = response.usage {
         run.usage.record(usage);
         loop_state.usage = run.usage;
@@ -530,7 +548,30 @@ where
         &mut loop_state.messages,
         calls,
     )
-    .await?;
+    .await;
+    let outcome = match outcome {
+        Ok(outcome) => outcome,
+        Err(error)
+            if matches!(
+                harness.policy().limits.behavior,
+                tinyagents_harness::limits::LimitBehavior::StopWithPartial
+            ) && matches!(error, TinyAgentsError::LimitExceeded(_))
+                && ctx.peek_last_limit()
+                    == Some(tinyagents_harness::events::LimitKind::ToolCalls) =>
+        {
+            // Only the tool-cap admission announces `LimitReached(ToolCalls)`
+            // (and `record_tool_call` cleared any earlier kind first), so a
+            // `LimitExceeded` raised by middleware is not a partial stop.
+            loop_state.limit_stop = true;
+            loop_state.limit_kind = Some(tinyagents_harness::events::LimitKind::ToolCalls);
+            loop_state.finished = true;
+            if loop_state.final_text.is_none() {
+                loop_state.final_text = Some(last_assistant_text(&loop_state.messages));
+            }
+            return Ok(goto(loop_state, node::SETTLE));
+        }
+        Err(error) => return Err(error),
+    };
     loop_state.tool_calls = run.tool_calls;
     loop_state.executed_tools = run.executed_tools.clone();
     let _ = outcome;

crates/tinyagents-graph/src/agent_loop/types.rs

@@ -69,6 +69,14 @@ pub struct LoopState {
     /// How many output-validation retries have been spent so far (bounds
     /// [`tinyagents_harness::runtime::RunPolicy::output_retry`]).
     pub(crate) output_retry_attempts: u8,
+    /// Set when the run finished because a call cap tripped under
+    /// `LimitBehavior::StopWithPartial`, so the driver can report
+    /// `TerminalReason::LimitReached` instead of a plain completion.
+    #[serde(default)]
+    pub(crate) limit_stop: bool,
+    /// Which cap tripped when `limit_stop` is set (`None` when unknown).
+    #[serde(default)]
+    pub(crate) limit_kind: Option<tinyagents_harness::events::LimitKind>,
 }
 
 impl LoopState {

crates/tinyagents-harness/src/agent_loop/entry.rs

@@ -441,25 +441,78 @@ impl<State: Send + Sync, Ctx: Send + Sync> AgentHarness<State, Ctx> {
                 // `completed` is what made "paused for a human" look identical
                 // to "the model produced an empty final answer".
                 // A deferred run (A2) is resumable for the same reason.
-                let paused = terminal.run.paused.is_some() || terminal.run.deferred.is_some();
+                // The typed outcome is authoritative (middleware may have
+                // replaced it after the loop set the legacy fields); fall back
+                // to the legacy fields only when no outcome was recorded.
+                let paused = match terminal.run.terminal.as_ref() {
+                    Some(outcome) => outcome.class == TerminalClass::Suspended,
+                    None => terminal.run.paused.is_some() || terminal.run.deferred.is_some(),
+                };
+                // Only `Success` is a completion and `Suspended` is handled by
+                // `paused`; Failure, Timeout and Cancellation outcomes recorded
+                // by middleware on an `Ok` return must not read as completed.
+                let failed = terminal.run.terminal.as_ref().is_some_and(|outcome| {
+                    !matches!(
+                        outcome.class,
+                        TerminalClass::Success | TerminalClass::Suspended
+                    )
+                });
                 if paused {
                     status.mark_interrupted();
+                } else if failed {
+                    status.mark_failed("run ended with a non-success terminal outcome".to_string());
                 } else {
                     status.mark_completed();
                 }
                 PartialRunOutcome {
                     run: terminal.complete(
-                        !paused,
+                        !paused && !failed,
                         paused.then(|| "hosted turn paused before completion".to_string()),
                     ),
                     status,
                     error: None,
                 }
             }
             Err(error) => {
+                // Where the run stood when it failed decides the timeout phase
+                // and `provider_started`: an unfinished model call leaves
+                // `active_model_call` set, a completed one has bumped the
+                // run's call counter.
+                // A failure inside the model-call layer is `Provider` only if
+                // the provider was actually dispatched; a wrap middleware that
+                // rejected the call first never reached it.
+                let in_model_call = ctx.active_model_call.is_some() || ctx.model_call_failed();
+                let site = if in_model_call && ctx.call_provider_started() {
+                    TimeoutPhase::Provider
+                } else if in_model_call {
+                    TimeoutPhase::BeforeProvider
+                } else if terminal.run.model_calls > 0 {
+                    TimeoutPhase::AfterTurn
+                } else {
+                    TimeoutPhase::BeforeProvider
+                };
+                let last_limit = matches!(error, TinyAgentsError::LimitExceeded(_))
+                    .then(|| ctx.take_last_limit())
+                    .flatten();
+                let mut outcome =
+                    TerminalOutcome::from_error(&error, site).with_limit_kind(last_limit);
+                if outcome.reason == crate::terminal::TerminalReason::Timeout
+                    && outcome.timeout_phase.is_none()
+                {
+                    // A wall-clock kind filled in after classification.
+                    outcome = outcome.with_timeout_phase(site);
+                }
+                // `site` describes this failure; the run may still have reached
+                // the provider on an earlier call.
+                // A failed summarizer already received a provider response, though
+                // summarizer calls bypass the context's dispatch marker.
+                outcome.provider_started = ctx.provider_started()
+                    || matches!(&error, TinyAgentsError::SummarizationUsage { .. });
+                terminal.run.terminal = Some(outcome.clone());
                 let record = ctx.emit(AgentEvent::RunFailed {
                     run_id,
                     error: error.to_string(),
+                    outcome: Some(outcome),
                 });
                 status.set_last_event(record.id);
                 status.mark_failed(error.to_string());