chore: import upstream snapshot with attribution

surfaces/interactive_shell/runtime/background/__init__.py

@@ -0,0 +1 @@
+"""Background runtime support for interactive shell."""

surfaces/interactive_shell/runtime/background/notifications.py

@@ -0,0 +1,47 @@
+"""Background RCA notification helpers."""
+
+from __future__ import annotations
+
+from surfaces.interactive_shell.session.background_investigations import (
+    BackgroundInvestigationRecord,
+)
+
+
+def deliver_background_notifications(
+    *,
+    record: BackgroundInvestigationRecord,
+    channels: tuple[str, ...],
+) -> dict[str, str]:
+    """Send configured notifications for a completed background RCA."""
+    # Imported lazily: email delivery only fires on background-RCA completion, so
+    # the SMTP client must not load into the base REPL boot import path.
+    from integrations.smtp.delivery import format_background_rca_email, send_smtp_report
+
+    results: dict[str, str] = {}
+    from integrations.catalog import resolve_effective_integrations
+
+    effective_integrations = resolve_effective_integrations()
+
+    for channel in channels:
+        if channel != "email":
+            results[channel] = "unsupported"
+            continue
+
+        smtp_integration = effective_integrations.get("smtp")
+        smtp_config = smtp_integration.get("config") if isinstance(smtp_integration, dict) else None
+        if not isinstance(smtp_config, dict):
+            results["email"] = "missing smtp integration"
+            continue
+
+        subject, body = format_background_rca_email(
+            task_id=record.task_id,
+            command=record.command,
+            root_cause=record.root_cause,
+            top_analysis=record.top_analysis,
+            next_steps=record.next_steps,
+            stats=record.stats,
+        )
+        ok, error = send_smtp_report(report=body, subject=subject, smtp_ctx=smtp_config)
+        results["email"] = "sent" if ok else f"failed: {error}"
+
+    return results

surfaces/interactive_shell/runtime/background/runner.py

@@ -0,0 +1,236 @@
+"""Helpers for launching session-local background investigations."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from contextlib import nullcontext
+from typing import Any
+from uuid import uuid4
+
+from prompt_toolkit.patch_stdout import patch_stdout
+from rich.console import Console
+from rich.markup import escape
+
+from platform.analytics.cli import track_investigation
+from platform.analytics.source import EntrypointSource, TriggerMode
+from platform.common.errors import OpenSREError
+from surfaces.interactive_shell.runtime import (
+    BackgroundInvestigationRecord,
+    Session,
+    TaskKind,
+)
+from surfaces.interactive_shell.runtime.background.notifications import (
+    deliver_background_notifications,
+)
+from surfaces.interactive_shell.ui import DIM, ERROR, HIGHLIGHT, WARNING
+from surfaces.interactive_shell.utils.error_handling.exception_reporting import report_exception
+
+BackgroundRunFn = Callable[..., dict[str, Any]]
+
+
+def _safe_console_print(console: Console, message: str) -> None:
+    isatty = getattr(console.file, "isatty", None)
+    stdout_context = patch_stdout(raw=True) if callable(isatty) and isatty() else nullcontext()
+    with stdout_context:
+        console.print(message)
+
+
+def drain_background_notices(session: Session, console: Console) -> None:
+    """Print queued background investigation status lines on the main REPL thread."""
+    for message in session.terminal.drain_background_notices():
+        _safe_console_print(console, message)
+
+
+def _build_record(
+    *,
+    task_id: str,
+    command: str,
+    investigation_id: str,
+) -> BackgroundInvestigationRecord:
+    return BackgroundInvestigationRecord(
+        task_id=task_id,
+        status="running",
+        command=command,
+        investigation_id=investigation_id,
+    )
+
+
+def _top_analysis(final_state: dict[str, Any]) -> tuple[str, ...]:
+    claims = final_state.get("validated_claims", [])
+    if not isinstance(claims, list):
+        return ()
+    lines: list[str] = []
+    for entry in claims:
+        if not isinstance(entry, dict):
+            continue
+        claim = str(entry.get("claim") or "").strip()
+        if claim:
+            lines.append(claim)
+        if len(lines) >= 3:
+            break
+    return tuple(lines)
+
+
+def _next_steps(final_state: dict[str, Any]) -> tuple[str, ...]:
+    steps = final_state.get("remediation_steps", [])
+    if not isinstance(steps, list):
+        return ()
+    values: list[str] = []
+    for step in steps[:3]:
+        text = str(step).strip()
+        if text:
+            values.append(text)
+    return tuple(values)
+
+
+def _stats(final_state: dict[str, Any]) -> dict[str, Any]:
+    tool_calls = final_state.get("evidence_entries", [])
+    loops = final_state.get("investigation_loop_count", 0)
+    validity = final_state.get("validity_score", 0.0)
+    return {
+        "tool_call_count": len(tool_calls) if isinstance(tool_calls, list) else 0,
+        "investigation_loop_count": int(loops) if isinstance(loops, int | float) else 0,
+        "validity_score": float(validity) if isinstance(validity, int | float) else 0.0,
+    }
+
+
+def _start_background_investigation(
+    *,
+    session: Session,
+    console: Console,
+    display_command: str,
+    run_fn: BackgroundRunFn,
+    kwargs: dict[str, Any],
+    investigation_target: str = "",
+    input_path: str | None = None,
+) -> str:
+    investigation_id = str(uuid4())
+    session.last_investigation_id = investigation_id
+    task = session.task_registry.create(TaskKind.INVESTIGATION, command=display_command)
+    task.mark_running()
+    record = _build_record(
+        task_id=task.task_id,
+        command=display_command,
+        investigation_id=investigation_id,
+    )
+    session.terminal.background_investigations[task.task_id] = record
+
+    def _worker() -> None:
+        try:
+            with track_investigation(
+                entrypoint=EntrypointSource.CLI_REPL_FILE,
+                trigger_mode=TriggerMode.FILE,
+                input_path=input_path,
+                interactive=True,
+                investigation_id=investigation_id,
+                investigation_target=investigation_target or None,
+                session=session,
+            ) as tracker:
+                final_state = run_fn(cancel_requested=task.cancel_requested, **kwargs)
+                tracker.record_loop_metrics_from_state(final_state)
+            root = str(final_state.get("root_cause") or "")
+            record.status = "completed"
+            record.root_cause = root
+            record.top_analysis = _top_analysis(final_state)
+            record.next_steps = _next_steps(final_state)
+            record.stats = _stats(final_state)
+            record.final_state = dict(final_state)
+            record.notification_results = deliver_background_notifications(
+                record=record,
+                channels=session.terminal.background_notification_preferences.channels,
+            )
+            task.mark_completed(result=root)
+            session.terminal.enqueue_background_notice(
+                f"[{HIGHLIGHT}]background investigation complete[/] "
+                f"[{DIM}]— task {escape(task.task_id)} ready; "
+                f"use[/] [{HIGHLIGHT}]/background show {escape(task.task_id)}[/]",
+            )
+        except KeyboardInterrupt:
+            record.status = "cancelled"
+            task.mark_cancelled()
+            session.terminal.enqueue_background_notice(
+                f"[{WARNING}]background investigation cancelled[/] "
+                f"[{DIM}]for task {escape(task.task_id)}.[/]",
+            )
+        except OpenSREError as exc:
+            record.status = "failed"
+            task.mark_failed(str(exc))
+            session.terminal.enqueue_background_notice(
+                f"[{ERROR}]background investigation failed[/] "
+                f"[{DIM}]for task {escape(task.task_id)}:[/] {escape(str(exc))}",
+            )
+        except Exception as exc:  # noqa: BLE001
+            record.status = "failed"
+            task.mark_failed(str(exc))
+            report_exception(exc, context="surfaces.interactive_shell.background_investigation")
+            session.terminal.enqueue_background_notice(
+                f"[{ERROR}]background investigation failed[/] "
+                f"[{DIM}]for task {escape(task.task_id)}:[/] {escape(str(exc))}",
+            )
+
+    thread = threading.Thread(
+        target=_worker,
+        daemon=True,
+        name=f"background-investigation-{task.task_id}",
+    )
+    thread.start()
+    _safe_console_print(
+        console,
+        f"[{DIM}]background investigation started — task[/] [bold]{escape(task.task_id)}[/bold]. "
+        f"[{HIGHLIGHT}]/background list[/] [{DIM}]to monitor, "
+        f"[/][{HIGHLIGHT}]/cancel {escape(task.task_id)}[/] [{DIM}]to stop.[/]",
+    )
+    return task.task_id
+
+
+def start_background_text_investigation(
+    *,
+    alert_text: str,
+    session: Session,
+    console: Console,
+    display_command: str = "background free-text investigation",
+    investigation_target: str = "",
+) -> str:
+    from surfaces.interactive_shell.runtime.investigation_adapter import (
+        run_investigation_for_session_background,
+    )
+
+    return _start_background_investigation(
+        session=session,
+        console=console,
+        display_command=display_command,
+        run_fn=run_investigation_for_session_background,
+        kwargs={
+            "alert_text": alert_text,
+            "context_overrides": session.accumulated_context or None,
+        },
+        investigation_target=investigation_target,
+        input_path=display_command,
+    )
+
+
+def start_background_template_investigation(
+    *,
+    template_name: str,
+    session: Session,
+    console: Console,
+    display_command: str,
+    investigation_target: str = "",
+) -> str:
+    from surfaces.interactive_shell.runtime.investigation_adapter import (
+        run_sample_alert_for_session_background,
+    )
+
+    return _start_background_investigation(
+        session=session,
+        console=console,
+        display_command=display_command,
+        run_fn=run_sample_alert_for_session_background,
+        kwargs={
+            "template_name": template_name,
+            "context_overrides": session.accumulated_context or None,
+        },
+        investigation_target=investigation_target,
+        input_path=f"template:{template_name}",
+    )

surfaces/interactive_shell/runtime/background/workers.py

@@ -0,0 +1,127 @@
+"""Background task lifecycle for the interactive REPL runtime."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from rich.console import Console
+
+from core.domain.alerts import inbox as _alert_inbox
+from surfaces.interactive_shell.runtime.background.runner import drain_background_notices
+from surfaces.interactive_shell.runtime.core.state import ReplState, SpinnerState
+from surfaces.interactive_shell.session import Session
+from surfaces.interactive_shell.ui.alerts import drain_and_render_incoming
+
+log = logging.getLogger(__name__)
+
+
+class BackgroundTaskManager:
+    """Start background workers and drain their user-visible output."""
+
+    def __init__(
+        self,
+        session: Session,
+        state: ReplState,
+        spinner: SpinnerState,
+        inbox: _alert_inbox.AlertInbox | None,
+        prompt_invalidator: Callable[[], None],
+    ) -> None:
+        self.session = session
+        self.state = state
+        self.spinner = spinner
+        self.inbox = inbox
+        self.prompt_invalidator = prompt_invalidator
+        self.tasks: list[tuple[str, asyncio.Task[None]]] = []
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._sampler_started = False
+
+    def start_all(
+        self,
+        processor_coro: Callable[[], Coroutine[Any, Any, None]],
+    ) -> list[tuple[str, asyncio.Task[None]]]:
+        # The fleet sampler (and its psutil dependency) is intentionally NOT
+        # started here: local-agent monitoring only runs once the user actually
+        # opens /fleet, via ``ensure_fleet_sampler_started``.
+        self._loop = asyncio.get_running_loop()
+        self.tasks = [
+            ("processor", asyncio.create_task(processor_coro())),
+            ("alert watcher", asyncio.create_task(self._alert_watcher())),
+            ("spinner ticker", asyncio.create_task(self._spinner_ticker())),
+        ]
+        return self.tasks
+
+    def ensure_fleet_sampler_started(self) -> None:
+        """Start the fleet sampler on demand (first live ``/fleet`` use).
+
+        Safe to call from any thread: a shell turn (and thus the ``/fleet``
+        handler) runs in a worker thread via ``asyncio.to_thread``, so sampler
+        task creation is marshalled back onto the REPL event loop. Idempotent.
+        """
+        loop = self._loop
+        if loop is None:
+            return
+        loop.call_soon_threadsafe(self._start_sampler_task)
+
+    def _start_sampler_task(self) -> None:
+        if self._sampler_started:
+            return
+        # Imported lazily so base REPL startup does not pull the sampler +
+        # psutil into the import path.
+        from tools.system.fleet_monitoring.sampler import start_sampler
+
+        self._sampler_started = True
+        self.tasks.append(("sampler", start_sampler()))
+
+    def drain_turn_start_output(self, console: Console) -> None:
+        if self.inbox is not None:
+            try:
+                drain_and_render_incoming(self.session, console, self.inbox)
+            except Exception as exc:
+                log.warning("Error draining alerts at turn start: %s", exc)
+        try:
+            drain_background_notices(self.session, console)
+        except Exception as exc:
+            log.warning("Error draining background notices at turn start: %s", exc)
+
+    async def _alert_watcher(self) -> None:
+        if self.inbox is None:
+            return
+        alert_console = Console(
+            highlight=False,
+            force_terminal=True,
+            color_system="truecolor",
+            legacy_windows=False,
+        )
+        drain_and_render_incoming(self.session, alert_console, self.inbox)
+        while not self.state.exit_requested:
+            try:
+                await asyncio.to_thread(self.inbox.pending_event.wait, timeout=1)
+            except asyncio.CancelledError:
+                return
+            try:
+                drain_and_render_incoming(self.session, alert_console, self.inbox)
+            except Exception as exc:
+                log.warning("Error draining incoming alerts: %s", exc)
+
+    async def _spinner_ticker(self) -> None:
+        # prompt_async's refresh_interval alone is not guaranteed to drive
+        # visible prompt redraws while patch_stdout(raw=True) is active and
+        # the LLM stream is writing rapidly. This task explicitly invalidates
+        # the prompt at 100 ms intervals so the braille glyph cycles smoothly.
+        tick_s = 0.1
+        was_streaming = False
+        while not self.state.exit_requested:
+            try:
+                await asyncio.sleep(tick_s)
+            except asyncio.CancelledError:
+                return
+            streaming = self.spinner.streaming
+            # Invalidate while streaming, plus one extra tick on the
+            # streaming->idle edge so the prompt repaints without the stale
+            # spinner/phase label instead of waiting for unrelated I/O.
+            if streaming or was_streaming:
+                self.prompt_invalidator()
+            was_streaming = streaming