tracer-cloud--opensre/surfaces/interactive_shell/runtime/AGENTS.md

Runtime package rules

Human summary

The runtime package holds the focused support modules for the interactive shell runtime. The top-level bootstrap and controller live one level up in interactive_shell/.

In simple terms:

• ../main.py starts the interactive session and handles process/bootstrap gates.
• startup/first_launch_github.py owns the first-launch GitHub sign-in gate.
• ../controller.py owns the InteractiveShellController orchestration class, including prompt input, submitted prompt handling, queued turn consumption, prompt-mediated confirmation waits, one-turn pipeline handoff, background output draining, and shutdown.
• core/prompt_manager.py owns prompt-toolkit setup and prompt rendering.
• input/ owns prompt input event conversion: EOF, Ctrl-C, CPR cleanup, and resume hints.
• utils/input_policy.py owns prompt stdin/spinner decisions for turns.
• startup/initial_input.py owns non-interactive initial-input replay.
• background/workers.py owns alert watching, spinner ticking, sampler startup, and turn-start background output drains.
• background/ also owns background investigation records, launchers, and completion notification delivery.
• core/ holds the core runtime engine:
  • state.py — shared runtime state (ReplState, SpinnerState)
  • turn_detection.py — pure text classifiers for cancel, confirm, and correction detection
• core.agent_harness.session.tasks owns the cross-session task registry surfaced via /tasks and /cancel.
• Reusable per-agent session state (Session) lives in core.agent_harness.session. Terminal runtime context assembly (ReplRuntimeContext, create_repl_runtime_context) lives in interactive_shell.runtime.context.

These instructions apply to interactive_shell/runtime/ and all subdirectories. Parent AGENTS.md files still apply.

Architectural intent (locked)

The runtime package is intentionally split into focused concerns:

• core/state.py — runtime state and transition helpers only.
• core/turn_detection.py — pure prompt text classification only.
• utils/input_policy.py — terminal stdin/spinner gating decisions only.
• agent_presentation.py — terminal presentation for the agent prompt only (agent lifecycle events, presentation-state reducer/renderer, ConsoleAgentEventSink).
• turn_host.py — terminal/runtime host for ShellAgent prompts only.
• ../controller.py — stable async entrypoint and async prompt runtime/event loop orchestration, submitted prompt handling, queued-turn consumption, prompt-mediated confirmation waits, turn telemetry, one-turn pipeline handoff, background output draining, and shutdown only.
• core/prompt_manager.py — prompt-toolkit setup and prompt rendering only.
• input/ — prompt input event conversion and terminal-input cleanup only.
• background/workers.py — background worker startup and turn-start drain hooks only.
• core.agent_harness.session.background — background investigation record and preferences only.
• background/runner.py — session-local background investigation launchers only.
• background/notifications.py — background RCA completion notification delivery only.
• ../main.py — process/bootstrap boundary only.
• startup/initial_input.py — scripted initial-input replay only.
• startup/first_launch_github.py — first-launch GitHub sign-in gate only.
• core.agent_harness.session.tasks — task registry + persistence only.
• core.agent_harness.accounting.token_accounting — session-scoped LLM token accounting and run metadata only.

Keep these boundaries strict. If a change crosses concerns, move code to the owner module instead of broadening module responsibilities.

Data flow contract (locked)

The interactive runtime must keep this shape:

1. interactive_shell.main.run_repl (synchronous entrypoint) sets up process-level concerns and calls run_repl_async.
2. interactive_shell.main.run_repl_async (async body) creates InteractiveShellController.
3. InteractiveShellController.start_interactive_shell owns prompt lifecycle, submitted input handling, queued-turn consumption, and per-turn task scheduling.
4. runtime.turn_host.run_agent_turn_queue consumes queued prompts through an injected run_turn callable, which in production is lambda text: run_agent_turn(self.turn_runtime, text).
5. runtime.turn_host.run_agent_turn(runtime, text) drives one submitted turn. AgentTurnRuntime is the immutable dependency bundle it operates on (session, state, spinner, invalidate_prompt, request_exit); run_agent_turn owns presentation setup, prompt-mediated confirmation, dispatch state, and per-turn execution.
6. interactive_shell.runtime.shell_turn_execution.execute_shell_turn binds shell adapters around core.agent_harness.turns.orchestrator.run_turn.
7. core.agent_harness owns one prompt's action/answer mechanics and accounting finalization. The terminal presentation for AgentEvent emissions lives in runtime/agent_presentation.py.

Do not invert this dependency direction.

Architecture diagram

flowchart TD
  runRepl["interactive_shell.main.run_repl"] --> replMain["interactive_shell.main.run_repl_async"]
  replMain --> controller["interactive_shell.controller.InteractiveShellController"]
  controller --> turnHost["runtime.turn_host.run_agent_turn(turn_runtime, text)"]
  turnHost --> turnEntry["interactive_shell.runtime.shell_turn_execution.execute_shell_turn"]
  turnEntry --> coreHarness["core.agent_harness.turns.orchestrator.run_turn"]
  coreHarness --> sideEffects["slash/help/agent/follow-up/investigation side effects"]
  controller --> replState["core.state.ReplState"]
  controller --> spinnerState["core.state.SpinnerState"]
  controller --> inputReader["input.PromptInputReader"]

State ownership rules

• ReplState is the single source of truth for:
  • active dispatch task
  • cancellation event
  • confirmation event/response lifecycle
  • exit requests
  • the explicit turn phase (TurnPhase: IDLE, DISPATCHING, AWAITING_CONFIRMATION, CANCELLING)
• Mutate turn state through the ReplState transition methods, never by poking raw fields from other modules:
  • start_dispatch / attach_turn_task / attach_cancel_event -> DISPATCHING
  • begin_confirmation -> AWAITING_CONFIRMATION; clear_confirmation returns to DISPATCHING/IDLE (and never clobbers an in-progress CANCELLING)
  • cancel_current_dispatch -> CANCELLING (only when there is something to cancel) then signals the cancel/confirm events and task.cancel
  • finish_dispatch / clear_current_task -> IDLE
• phase is authoritative for confirmation and cancelling. is_dispatch_running() stays derived from the asyncio task (the runtime truth of the in-flight turn); is_awaiting_confirmation() and is_cancelling() are derived from phase.
• Do not reorder the signaling inside cancel_current_dispatch or move the confirm_response reset after the confirm_event publish in begin_confirmation; both orderings are load-bearing for cancellation and confirmation race-safety.
• SpinnerState owns spinner rendering state only; it must not depend on runtime task management.

Turn execution rules

• Do not reintroduce dispatch.py, an AgentTurnRunner-style wrapper class, or any compatibility-only forwarding module.
• The terminal host lives in runtime/turn_host.py: run_agent_turn(runtime, text) owns shell presentation (StreamingConsole, spinner, recorder, progress scope), constructs a ConsoleAgentEventSink, owns dispatch state, and lazily imports + calls interactive_shell.runtime.shell_turn_execution.execute_shell_turn. AgentTurnRuntime is the immutable dependency bundle it operates on; the controller constructs it and passes a bound run_agent_turn coroutine into run_agent_turn_queue.
• The shell adapter entry lives in runtime/shell_turn_execution.py: execute_shell_turn composes the action-turn (runtime/action_turn.py), gather (runtime/integration_tool_gathering.py), and answer (runtime/answer_turn.py) adapters plus accounting around core.agent_harness.turns.orchestrator.run_turn. Each adapter owns its own binding; tests import them from their owning module (not shell_turn_execution).
• The reusable per-prompt loop lives in core.agent_harness: turn snapshots, observation reset, action/response routing, and core result construction stay surface-agnostic.
• Keep terminal side effects (spinner, prompt suppression, console.print, CPR drain) in ConsoleAgentEventSink — defined in runtime/agent_presentation.py — not in the turn-entry adapter or the core harness.
• Put cancel/confirm/correction text classifiers in core/turn_detection.py.
• Put stdin blocking and spinner decisions in utils/input_policy.py.
• Keep prompt-mediated confirmation waiting in runtime/core/confirmation.py.
• Turn accounting is consolidated behind ShellTurnAccounting in interactive_shell/runtime/core/turn_accounting.py, invoked from interactive_shell.runtime.shell_turn_execution.execute_shell_turn. It owns action-agent analytics, terminal-turn aggregate telemetry, prompt-recorder flush, conversational-turn persistence, and the final assistant-intent stamp. interactive_shell.runtime.action_turn.run_action_tool_turn returns facts only (ToolCallingTurnResult with accounting_status of completed / not_run) and emits no analytics itself. Do not re-scatter accounting back into run_action_tool_turn or standalone _record_* helpers.

Controller rules

• ../controller.py owns:
  • InteractiveShellController
  • start_interactive_shell shell lifecycle orchestration
  • alert listener setup/teardown
  • AgentTurnRuntime construction and shutdown
  • queued prompt submission
• turn_host.py owns:
  • run_input_loop (module-level) — read and handle user input until exit
  • run_agent_turn_queue (module-level) — consume queued prompts until exit (runs an injected run_turn)
  • run_agent_turn(runtime, text) (module-level) — presentation, dispatch state, prompt-mediated confirmation, and turn-entry invocation over an AgentTurnRuntime
  • ConsoleAgentEventSink (in runtime/agent_presentation.py) — terminal presentation for agent lifecycle events over _reduce_agent_presentation / _render_agent_presentation_transition
  • queued turn consumption
  • per-turn task lifecycle
  • dispatch start/finish state transitions
  • prompt-mediated confirmation waiting
  • turn telemetry and execute_shell_turn invocation
  • current turn cancellation helpers
  • coordination between prompt, background, and shutdown helpers
• core/prompt_manager.py owns:
  • prompt-toolkit wiring
  • prompt rendering callbacks
  • pending prompt defaults and autosubmit handling
• input/ owns:
  • prompt input event types
  • terminal EOF and Ctrl-C conversion
  • CPR cleanup for submitted prompt text
  • session resume hints when prompt input closes
• background/workers.py owns:
  • alert watcher lifecycle
  • spinner ticker lifecycle
  • sampler startup
  • background notice drains at turn start
• Keep prompt rendering concerns in runtime/prompting modules, not in dispatch/execution.

Main/bootstrap rules

• ../main.py owns:
  • startup sweep
  • TTY/non-TTY gate
  • banner display for interactive runs
  • async boundary (asyncio.run)
• ../controller.py owns alert listener setup/teardown because the inbox is part of the running shell lifecycle.
• Do not move per-turn dispatch/runtime logic back into startup bootstrap.

Compatibility surface policy

• runtime/__init__.py should be a thin export layer.
• Do not duplicate business logic in __init__.py.
• runtime/__init__.py exports Session from core.agent_harness.session and runtime-context helpers from interactive_shell.runtime.context. New shared runtime code should import session names directly from core.agent_harness.session.
• Do not re-add _xxx underscore aliases or wrapper functions for compatibility. Tests and callers should import canonical names from their owning submodule.

Test seam policy

• Prefer patching canonical module seams:
  • interactive_shell.controller.* for prompt-loop, queued-turn, confirmation behavior, one-turn pipeline execution, and side effects
  • interactive_shell.main.* for process/bootstrap behavior
  • runtime.core.state.* for state-specific behavior
• Avoid adding new tests that monkeypatch package-root internals in runtime.__init__ unless there is no stable canonical seam.

Refactor guardrails

• No behavior changes to action-planning policy should be introduced from runtime/ refactors.
• Keep interruption semantics unchanged:
  • Esc or bare cancel commands interrupt active dispatch
  • cancellation moves the turn to TurnPhase.CANCELLING and signals both the cancel event and any pending confirmation event before task.cancel
  • confirmation prompts are cancel-safe and never silently auto-confirm; a cancel during confirmation must not be downgraded back to DISPATCHING
• Preserve observability semantics (turn telemetry and turn summaries).