Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

6.6 KB
Raw Blame
"""Global pause switch for the Executive's autonomous work.

One operator-level flag, persisted in the episodic DB, that every autonomous
loop checks at the top of each iteration:

- ``scheduler.runner.run_scheduler`` — claims nothing (briefs, nudges, alert
  review, monitoring, cadences, scheduled outbound messages all wait),
- ``integrations.email_poller.run_email_poller`` — leaves Gmail unread,
- ``workflows.resumer`` — applies no ``wait_for_human`` timeouts and resumes
  no answered runs.

Pausing holds work; it never cancels it. Due ``scheduled_actions`` stay
``pending`` and fire on the first tick after resume. Work already running
when the pause lands finishes. Inbound conversations (web chat, Slack,
Discord, Telegram, Google Chat) are deliberately NOT gated — pausing stops
what the Executive starts on its own, not its answers to people.

``is_paused`` fails CLOSED: a DB file or table that does not exist yet reads
as "running" (nothing was ever paused), but a read *error* on an existing DB
reads as "paused" — for a brake, the safe failure is holding work, never
silently releasing it while the UI still shows "paused". A broken DB would
stall ``claim_due_actions`` anyway; the hold is logged once per failure
streak. It is also read-only — it never creates the DB file or the table —
so loops running against an unconfigured or test DB leave no trace.

The table survives client-slot swaps (``clients.slots._GLOBAL_TABLES``): the
switch belongs to the operator, not to whichever client company is active.
"""
from __future__ import annotations

import logging
import sqlite3
from datetime import UTC, datetime
from pathlib import Path

from pydantic import BaseModel

logger = logging.getLogger(__name__)

TABLE = "executive_control"

_CREATE_SQL = f"""
CREATE TABLE IF NOT EXISTS {TABLE} (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    paused INTEGER NOT NULL DEFAULT 0,
    paused_at TEXT,
    paused_by TEXT,
    reason TEXT,
    updated_at TEXT
)
"""


class PauseState(BaseModel):
    paused: bool = False
    paused_at: str | None = None
    paused_by: str | None = None
    reason: str | None = None


def _db_path() -> Path:
    # Resolved at call time so tests that monkeypatch episodic.DB_PATH (and
    # EPISODIC_DB_PATH deployments) see the same file as scheduled_actions.
    from openexecutive.memory import episodic

    return Path(episodic.DB_PATH)


def _connect(path: Path) -> sqlite3.Connection:
    conn = sqlite3.connect(str(path))
    conn.row_factory = sqlite3.Row
    return conn


def initialize_pause_db(db_path: Path | None = None) -> None:
    """Create the control table if missing. Idempotent."""
    conn = _connect(db_path if db_path is not None else _db_path())
    try:
        conn.execute(_CREATE_SQL)
        conn.commit()
    finally:
        conn.close()


def get_pause_state() -> PauseState:
    """Current state. Raises on DB errors other than "nothing stored yet"."""
    path = _db_path()
    if not path.exists():
        return PauseState()
    conn = _connect(path)
    try:
        row = conn.execute(
            f"SELECT paused, paused_at, paused_by, reason FROM {TABLE} WHERE id = 1"  # noqa: S608 — constant table name
        ).fetchone()
    except sqlite3.OperationalError as exc:
        if "no such table" in str(exc):
            return PauseState()
        raise
    finally:
        conn.close()
    if row is None or not row["paused"]:
        return PauseState()
    return PauseState(
        paused=True,
        paused_at=row["paused_at"],
        paused_by=row["paused_by"],
        reason=row["reason"],
    )


# Log a read failure once per failure streak, not once per poll per loop.
_read_failing = False


def is_paused() -> bool:
    """True while the operator has paused autonomous work — or while the
    pause state cannot be read (fail closed). Never raises."""
    global _read_failing
    try:
        paused = get_pause_state().paused
    except Exception:
        if not _read_failing:
            logger.exception(
                "pause: could not read pause state — holding autonomous work "
                "until it can be read"
            )
            _read_failing = True
        return True
    _read_failing = False
    return paused


def pause(by: str, reason: str | None = None) -> PauseState:
    """Pause autonomous work. Idempotent: re-pausing keeps the original
    ``paused_at`` / ``paused_by`` so the UI keeps showing when it started."""
    now = datetime.now(UTC).isoformat()
    conn = _connect(_db_path())
    try:
        conn.execute(_CREATE_SQL)
        conn.execute(
            f"""
            INSERT INTO {TABLE} (id, paused, paused_at, paused_by, reason, updated_at)
            VALUES (1, 1, ?, ?, ?, ?)
            ON CONFLICT(id) DO UPDATE SET
                paused_at = CASE WHEN paused = 1 THEN paused_at ELSE excluded.paused_at END,
                paused_by = CASE WHEN paused = 1 THEN paused_by ELSE excluded.paused_by END,
                reason = CASE WHEN paused = 1 THEN reason ELSE excluded.reason END,
                paused = 1,
                updated_at = excluded.updated_at
            """,  # noqa: S608 — constant table name
            (now, by, reason, now),
        )
        conn.commit()
    finally:
        conn.close()
    logger.warning("pause: autonomous work PAUSED by %s (reason=%r)", by, reason)
    return get_pause_state()


def resume(by: str) -> PauseState:
    """Resume autonomous work. Idempotent."""
    now = datetime.now(UTC).isoformat()
    conn = _connect(_db_path())
    try:
        conn.execute(_CREATE_SQL)
        conn.execute(
            f"""
            INSERT INTO {TABLE} (id, paused, updated_at) VALUES (1, 0, ?)
            ON CONFLICT(id) DO UPDATE SET
                paused = 0, paused_at = NULL, paused_by = NULL, reason = NULL,
                updated_at = excluded.updated_at
            """,  # noqa: S608 — constant table name
            (now,),
        )
        conn.commit()
    finally:
        conn.close()
    logger.warning("pause: autonomous work RESUMED by %s", by)
    return get_pause_state()


def count_held_actions(now: datetime | None = None) -> int:
    """Pending scheduled actions already due — what fires on resume."""
    path = _db_path()
    if not path.exists():
        return 0
    at = (now or datetime.now(UTC)).isoformat()
    conn = _connect(path)
    try:
        row = conn.execute(
            "SELECT COUNT(*) FROM scheduled_actions WHERE status = 'pending' AND run_at <= ?",
            (at,),
        ).fetchone()
    except sqlite3.OperationalError as exc:
        if "no such table" in str(exc):
            return 0
        raise
    finally:
        conn.close()
    return int(row[0])