Skip to content

refactor(session): consolidate session and agent runtime loops - #688

Open
xiami762 wants to merge 22 commits into
devfrom
refactor/agent-runtime-session-host
Open

refactor(session): consolidate session and agent runtime loops#688
xiami762 wants to merge 22 commits into
devfrom
refactor/agent-runtime-session-host

Conversation

@xiami762

@xiami762 xiami762 commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Consolidate session execution into SessionLoop, LoopContext, AgentLoop, and StepEngine with explicit preparation, execution, continuation, and finalization boundaries.
  • Centralize per-turn runtime prompt context and system-prompt assembly while preserving the existing public prompt-building APIs.
  • Align session lifecycle dispatch with the canonical hook stages while keeping legacy hook method aliases compatible.
  • Migrate built-in workflow, TUI, and permission configuration references from task to delegate_task, while retaining task as a non-native compatibility alias for older workflows.
  • Preserve replay-safe requests, memory bootstrap, model failover, abort handling, queued-input priority, and single terminal-error semantics.

Runtime architecture

SessionLoop
    -> LoopContext
    -> AgentLoop
        -> StepEngine

Prompt assembly

  • Build system prompts as ordered SystemPromptBlock values and compose the final provider prompt at the session boundary.
  • Carry turn-scoped runtime context separately from stable prompt content so synthetic goal continuations do not reset real-user-turn state.
  • Keep Rex and Hephaestus prompt builders compatible while removing the retired task/subtask prompt branches.

Lifecycle hooks and continuation

  • Run session.start once and user.prompt.before once per real logical user turn.
  • Keep queued real user messages ahead of synthetic goal continuations, including messages that arrive while terminal hooks are running.
  • Treat turn.after as an observational terminal hook. Hook output cannot create a synthetic continuation or override a goal that is waiting for user input.
  • Keep goal continuation owned by ContinuationPolicy, with abort and step-limit safeguards.
  • Fail closed when the LLM before-hook or hook-stage probe fails, so unprocessed requests are never sent to the provider.
  • Emit one llm.call.after event per logical model request and aggregate failed same-model retry attempts into its terminal payload.

LLM request and streaming safety

  • Freeze the exact provider-bound ModelRequest and reuse it for same-model retries.
  • Retain hook-provided stream replacement metadata with the frozen request.
  • Restore redacted placeholders in streamed text, reasoning, and reasoning metadata, including placeholders split across chunks and cached-request retries.
  • Keep observability inputs redacted while persisting and returning restored assistant output.
  • Combine provider-observed prompt usage with post-observation tool-result and later-message deltas before making overflow and cleanup decisions.

Delegation compatibility

  • Use delegate_task in the built-in host-forensics workflow, TUI agent flows, prompts, and permission configuration.
  • Keep task registered as a non-native compatibility alias that forwards to delegate_task, so older workflows continue to run.
  • Canonicalize legacy task permissions to delegate_task in Python and TUI configuration, preserving deny precedence.

Compatibility

  • SessionLoop remains the public entry point.
  • Toolset and callable-tool selection semantics are unchanged.
  • Legacy lifecycle hook method names continue to resolve through compatibility aliases.
  • No database schema or migration changes.

Validation

  • 92 affected Python regression tests passed after merging the latest dev; four known unrelated existing cases were excluded.
  • 21 targeted TUI configuration and provider-usage tests passed.
  • Ruff checks passed for all changed Python files.
  • git diff --check passed.

@xiami762 xiami762 changed the title refactor(agent): separate session host from agent runtime loop refactor(session): consolidate session and agent runtime loops Aug 7, 2026
@xiami762
xiami762 requested a review from duguwanglong August 13, 2026 03:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant