Split cli/_handlers into a sub-package with agent-run logic extracted to _agent.py

- Promote _handlers.py to _handlers/ package, extracting agent-run
  lifecycle functions (execute_agent_task, resume, preflight, status,
  runs, show, approval handler) into _agent.py

Author: johnteee

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to TeaAgent are tracked here.
 - Split `teaagent/mcp_http.py` (575 → ~400 lines) by extracting OAuth endpoint handlers to `_oauth.py`.
 - Split `teaagent/telemetry.py` into a `teaagent/telemetry/` package with focused modules: `_availability.py`, `_config.py`, `_audit.py`, `_metrics.py`, and `_transport.py`.
 - Split `teaagent/code_mode.py` into a `teaagent/code_mode/` package with focused modules: `_types.py`, `_validation.py`, `_child_process.py`, and `_container.py`.
+- Split `teaagent/cli/_handlers.py` into a `teaagent/cli/_handlers/` package and extracted agent-run lifecycle logic into `_agent.py` while preserving command handler imports.
 - Made `teaagent.cli.main()` accept injectable `_adapter_factory`, `_serve_mcp_http`, `_check_graphqlite`, `_check_llm`, and `_run_model_conformance` keyword arguments, enabling handler extraction without breaking existing tests.
 - Split `teaagent/workspace_tools.py` into a `teaagent/workspace_tools/` package with four focused modules: `_config.py`, `_helpers.py`, `_shell.py`, `_files.py`. Backward-compatible public imports preserved via `__init__.py` re-exports.
 - Expanded audit string redaction with patterns for JWT tokens, AWS access keys (`AKIA...`), and GitHub personal access tokens (`ghp_...`, `github_pat_...`).

teaagent/cli/_handlers.py teaagent/cli/_handlers/__init__.pyteaagent/cli/_handlers.py renamed to teaagent/cli/_handlers/__init__.py

@@ -4,34 +4,39 @@
 import json
 import sys
 import time
-from typing import Any, Optional
+from typing import Any
 
-from teaagent.chat_agent import ChatAgentConfig, run_chat_agent
-from teaagent.graphqlite_store import (
-    GraphQLiteConfig,
-    GraphQLiteGraphStore,
-)
-from teaagent.intent import build_task_spec, clarify_task
-from teaagent.llm import (
-    LLMMessage,
-    LLMRequest,
-    available_providers,
-)
+from teaagent.graphqlite_store import GraphQLiteConfig, GraphQLiteGraphStore
+from teaagent.intent import clarify_task
+from teaagent.llm import LLMMessage, LLMRequest, available_providers
 from teaagent.mcp_http import is_loopback_host
 from teaagent.mcp_server import serve_mcp_stdio
 from teaagent.memory import MemoryCatalog
 from teaagent.model_routing import route_model
 from teaagent.policy import parse_permission_mode
-from teaagent.preflight import preflight
 from teaagent.run_store import RunStore
-from teaagent.runner import ApprovalRequest, RunResult
 from teaagent.tui import run_tui
 from teaagent.ultrawork import UltraworkStore
 from teaagent.workspace_tools import build_workspace_tool_registry
 
-# ---------------------------------------------------------------------------
-# Command handlers
-# ---------------------------------------------------------------------------
+from ._agent import (
+    agent_preflight_command as agent_preflight_command,
+)
+from ._agent import (
+    agent_resume_command as agent_resume_command,
+)
+from ._agent import (
+    agent_run_show as agent_run_show,
+)
+from ._agent import (
+    agent_run_task as agent_run_task,
+)
+from ._agent import (
+    agent_runs_list as agent_runs_list,
+)
+from ._agent import (
+    agent_status_command as agent_status_command,
+)
 
 
 def doctor_graphqlite(args: argparse.Namespace) -> int:
@@ -87,203 +92,6 @@ def memory_show_command(args: argparse.Namespace) -> int:
     return 0
 
 
-def agent_run_task(args: argparse.Namespace) -> int:
-    return _execute_agent_task(args, args.task)
-
-
-def agent_resume_command(args: argparse.Namespace) -> int:
-    store = RunStore(args.root)
-    try:
-        original_task = store.task_for_run(args.run_id)
-    except (FileNotFoundError, ValueError) as exc:
-        print_json({'status': 'error', 'message': str(exc)})
-        return 1
-
-    initial_observations: list[dict[str, Any]] = []
-    auto_approved: Optional[str] = None
-    if not args.fresh_restart:
-        initial_observations = store.observations_for_run(args.run_id)
-        pending = store.pending_approval_for_run(args.run_id)
-        if pending and pending['call_id'] not in args.approve_call_id:
-            args.approve_call_id = list(args.approve_call_id) + [pending['call_id']]
-            auto_approved = pending['call_id']
-
-    return _execute_agent_task(
-        args,
-        original_task,
-        resumed_from=args.run_id,
-        initial_observations=initial_observations,
-        auto_approved_call_id=auto_approved,
-    )
-
-
-def _execute_agent_task(
-    args: argparse.Namespace,
-    task: str,
-    *,
-    resumed_from: Optional[str] = None,
-    initial_observations: Optional[list[dict[str, Any]]] = None,
-    auto_approved_call_id: Optional[str] = None,
-) -> int:
-    task_spec = None
-    if args.clarify:
-        clarification = clarify_task(task)
-        if clarification.needs_clarification:
-            print_json(
-                {
-                    'status': 'needs_clarification',
-                    'clarification': clarification.to_dict(),
-                }
-            )
-            return 2
-        task_spec = build_task_spec(task, clarification)
-
-    routing = (
-        route_model(task, provider=args.provider, model=args.model)
-        if args.route_model
-        else None
-    )
-    selected_model = routing.model if routing else args.model
-    adapter = args._adapter_factory(args.provider, model=selected_model)  # type: ignore[attr-defined]
-    store = RunStore(args.root)
-    audit = store.audit_logger()
-
-    # --- OpenTelemetry wiring ---
-    _telemetry_sink = None
-    if getattr(args, 'telemetry_otlp_endpoint', None) or getattr(
-        args, 'telemetry_console', False
-    ):
-        try:
-            from teaagent.telemetry import (
-                TelemetryConfig,
-                TracingHTTPTransport,
-                configure_telemetry,
-            )
-
-            cfg = TelemetryConfig(
-                service_name=getattr(args, 'telemetry_service_name', 'teaagent'),
-                otlp_endpoint=getattr(args, 'telemetry_otlp_endpoint', None),
-                console=getattr(args, 'telemetry_console', False),
-            )
-            _telemetry_sink, tracer = configure_telemetry(cfg)
-            audit.add_sink(_telemetry_sink.handle_event)
-            adapter = args._adapter_factory(  # type: ignore[attr-defined]
-                args.provider,
-                model=selected_model,
-                transport=TracingHTTPTransport(adapter.transport, tracer),  # type: ignore[attr-defined]
-            )
-        except Exception as exc:
-            print(f'Telemetry setup failed: {exc}', file=sys.stderr)
-    # --- end telemetry wiring ---
-
-    approval_handler = cli_approval_handler if args.hitl_approval else None
-    result = run_chat_agent(
-        task=task,
-        adapter=adapter,
-        config=ChatAgentConfig.from_root(
-            args.root,
-            max_iterations=args.max_iterations,
-            max_tool_calls=args.max_tool_calls,
-            allow_destructive=args.allow_destructive,
-            model=selected_model,
-            permission_mode=parse_permission_mode(args.permission_mode),
-            approved_call_ids=frozenset(args.approve_call_id),
-            enable_subagent=args.subagent,
-            max_subagent_depth=args.max_subagent_depth,
-            heartbeat_seconds=args.heartbeat,
-            approval_handler=approval_handler,
-        ),
-        audit=audit,
-        task_spec=task_spec,
-        initial_observations=initial_observations,
-    )
-    store.logger_for_result(result, audit)
-    if _telemetry_sink is not None:
-        from contextlib import suppress
-
-        with suppress(Exception):
-            _telemetry_sink.force_flush()
-    payload = run_result_payload(result, routing=routing.to_dict() if routing else None)
-    if resumed_from:
-        payload['resumed_from'] = resumed_from
-        payload['task'] = task
-        if initial_observations:
-            payload['replayed_observations'] = len(initial_observations)
-        if auto_approved_call_id is not None:
-            payload['auto_approved_call_id'] = auto_approved_call_id
-    print_json(payload)
-    return 0 if result.status == 'completed' else 1
-
-
-def run_result_payload(
-    result: RunResult, *, routing: Optional[dict[str, Any]]
-) -> dict[str, Any]:
-    payload: dict[str, Any] = {
-        'run_id': result.run_id,
-        'status': result.status,
-        'iterations': result.iterations,
-        'tool_calls': result.tool_calls,
-        'routing': routing,
-        'final_answer': result.final_answer.content if result.final_answer else None,
-    }
-    if 'approval' in result.metadata:
-        payload['approval'] = result.metadata['approval']
-    return payload
-
-
-def cli_approval_handler(request: ApprovalRequest) -> bool:
-    print(
-        json.dumps(
-            {'status': 'approval_required', 'approval': request.to_dict()},
-            sort_keys=True,
-        ),
-        file=sys.stderr,
-    )
-    print(
-        f'Approve destructive tool call {request.call_id} ({request.tool_name})? [y/N] ',
-        end='',
-        file=sys.stderr,
-    )
-    answer = input()
-    return answer.strip().lower() in {'y', 'yes'}
-
-
-def agent_preflight_command(args: argparse.Namespace) -> int:
-    report = preflight(
-        args.task,
-        root=args.root,
-        provider=args.provider,
-        model=args.model,
-        permission_mode=parse_permission_mode(args.permission_mode),
-        route=args.route_model,
-        memory_limit=args.memory_limit,
-    )
-    print_json(report.to_dict())
-    return 0 if report.to_dict()['ready'] else 2
-
-
-def agent_status_command(args: argparse.Namespace) -> int:
-    store = RunStore(args.root)
-    try:
-        print_json(store.heartbeat_for_run(args.run_id))
-    except FileNotFoundError as exc:
-        print_json({'status': 'error', 'message': str(exc)})
-        return 1
-    return 0
-
-
-def agent_runs_list(args: argparse.Namespace) -> int:
-    store = RunStore(args.root)
-    print_json([summary.to_dict() for summary in store.list_runs(limit=args.limit)])
-    return 0
-
-
-def agent_run_show(args: argparse.Namespace) -> int:
-    store = RunStore(args.root)
-    print_json(store.show_run(args.run_id))
-    return 0
-
-
 def doctor_model(args: argparse.Namespace) -> int:
     ok, message = args._check_llm(args.provider)  # type: ignore[attr-defined]
     print(