Skip to content

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

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

refactor(session): consolidate session and agent runtime loops#688
xiami762 wants to merge 31 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.
  • Preserve replay-safe model requests, memory bootstrap, model failover, queued-input priority, goal continuation, abort handling, and single terminal-error semantics.
  • Harden lifecycle boundaries so continuation persistence failures surface as session errors, failover remains abortable, final lease release survives repeated cancellation, and settled sessions do not rerun UserPromptSubmit hooks.
  • Limit cached model requests to the active assistant attempt instead of retaining an ever-growing request history.
  • Fix the default TUI /review command to use the selected primary agent instead of assuming an unavailable oracle agent.
  • Merge the latest dev baseline (9d3810a3).

Runtime architecture

SessionLoop
    -> LoopContext
    -> AgentLoop
        -> StepEngine

Lifecycle hooks and continuation

  • Run session.start once and user.prompt.before once per real logical user turn.
  • Check whether the latest user message is already settled before routing and prompt hooks, preventing repeated side effects when a completed session is reopened.
  • 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.
  • Propagate continuation read, lifecycle-lock, and synthetic-message persistence failures instead of converting them into a normal stop.
  • 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.

Model execution and cancellation safety

  • Freeze the exact provider-bound ModelRequest and reuse it for same-model retries, then release it when the assistant attempt finishes.
  • Retain hook-provided stream replacement metadata with the frozen request.
  • Keep the full candidate/failover chain abort-aware, including cleanup, event publication, and provider switching.
  • Shield final session release so repeated cancellation cannot leave an in-process lease permanently busy.
  • 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.

Split scope

  • Delegation migration (task/subtask to delegate_task, permissions, TUI tool registry, API schema, generated SDK, workflows, and compatibility tests) remains isolated in refactor(delegation): migrate legacy task flows to delegate_task #716. This PR contains no task-to-delegate rewrites or delegation product-surface migration; its SessionLoop replacement only removes the retired private subtask execution branch together with the old loop.
  • Prompt assembly and agent prompt guidance remain isolated in refactor(session): centralize prompt context assembly #720. Shared test files in this PR only adapt runtime references from SessionRunner to StepEngine; prompt builders, prompt composition, token accounting, and prompt-specific assertions are unchanged from dev.
  • This PR continues to use the current dev prompt APIs and registered task compatibility alias.

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

  • 512 affected Python tests passed; two unchanged dev baseline failures were explicitly deselected.
  • The TUI /review regression test passed in an isolated Flocks root.
  • Ruff passed for every changed Python file.
  • 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