teleo-infrastructure/scripts/apply_worker.py

#!/usr/bin/env python3
"""Event-driven worker that lands human-approved proposals into canonical state.

Stage 2-of-the-loop automation:  Leo proposes -> HUMAN approves -> WORKER applies
-> renderer runs -> Leo reads the new self.

This is the "natural evolution" engine: it makes an approval in Telegram surface
in Leo's identity without Leo ever applying its own work. It does NOT think, does
NOT approve, and does NOT create proposals -- it only acts on proposals a human
has already moved to ``status='approved'``.

Governance boundary (why this is safe)
--------------------------------------
* Proposer != applier. The worker fires ONLY on ``status='approved'``; it never
  touches ``pending_review`` and never auto-approves. The human approval stays the
  trigger, so "Leo proposes but does not self-apply" holds.
* It connects as the narrow ``kb_apply`` role (never superuser, never Leo's creds)
  and reuses ``apply_proposal.py`` verbatim as the apply path -- same transaction,
  same ``rowcount=1`` concurrency guard, same FK stamp. No new write logic here.
* It runs as an operator-side systemd unit, NOT inside the hermes harness.

Safety posture
--------------
* Gated OFF by default. Without ``--enable`` (or ``KB_APPLY_WORKER_ENABLED=1``) the
  worker only REPORTS what it would apply -- it performs no writes. Flip it on only
  after the first apply has been proven by hand.
* The render step is a configurable hook (``--render-cmd`` / ``KB_APPLY_RENDER_CMD``).
  Until the SOUL renderer (PR2) is deployed the hook is simply absent and the worker
  logs that render was skipped -- applying still works, Leo's canonical is correct,
  and the rendered SOUL.md just lags until the renderer exists.
"""

from __future__ import annotations

import argparse
import json
import os
import subprocess
import sys
from pathlib import Path
from typing import Any, Dict, List, Optional

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))

import apply_proposal as ap  # noqa: E402  (sibling module, reused verbatim)

# Types the worker is willing to auto-apply. Deliberately the same set the engine
# supports; a proposal type outside this list is ignored (never applied).
WORKER_TYPES = ("revise_strategy", "add_edge", "attach_evidence")

# Only a revise_strategy changes an agent's identity spine, so only it triggers a
# SOUL re-render. Evidence/edge applies change the graph but not the rendered self.
RENDER_TYPES = ("revise_strategy",)


# --------------------------------------------------------------------------- #
# Pure helpers (unit-tested without a DB)                                      #
# --------------------------------------------------------------------------- #
def build_candidate_query(types: tuple = WORKER_TYPES, limit: int = 20) -> str:
    """SELECT approved, applyable proposals that carry an apply_payload.

    Filters on status='approved' at the DB level -- this is the structural
    guarantee that the worker cannot act on anything a human has not approved.
    """
    type_list = ", ".join(ap.sql_literal(t) for t in types)
    return f"""select jsonb_build_object(
        'id', id::text,
        'proposal_type', proposal_type,
        'agent_id', payload->'apply_payload'->>'agent_id')::text
  from kb_stage.kb_proposals
 where status = 'approved'
   and proposal_type in ({type_list})
   and payload ? 'apply_payload'
 order by created_at asc
 limit {int(limit)};"""


def parse_candidates(psql_output: str) -> List[Dict[str, Any]]:
    """Parse newline-delimited JSON rows from psql -At output."""
    rows: List[Dict[str, Any]] = []
    for line in psql_output.splitlines():
        line = line.strip()
        if line:
            rows.append(json.loads(line))
    return rows


def build_render_command(render_cmd: Optional[str], agent_id: Optional[str]) -> Optional[List[str]]:
    """Expand the render-hook template for one agent, or None if no hook configured.

    ``render_cmd`` is a shell-word template, e.g. ``python3 render_soul.py --agent-id {agent_id}``.
    Returns a token list ready for subprocess, or None when unset (render skipped).
    """
    if not render_cmd:
        return None
    if not agent_id:
        return None
    import shlex

    return [tok.format(agent_id=agent_id) for tok in shlex.split(render_cmd)]


def load_failure_state(path: Optional[str]) -> Dict[str, int]:
    """Load the persisted {proposal_id: consecutive_failure_count} map.

    The worker runs oneshot per timer tick, so in-memory failure counts do not
    survive between ticks. A poison-pill proposal (deterministically failing but
    stuck at 'approved') would otherwise be re-selected and re-attempted every
    tick forever. Persisting the count on disk lets the ceiling actually bite.
    Missing/corrupt file -> empty map (fail open to "no known failures").
    """
    if not path:
        return {}
    p = Path(path)
    if not p.is_file():
        return {}
    try:
        data = json.loads(p.read_text(encoding="utf-8"))
        return {str(k): int(v) for k, v in data.items()} if isinstance(data, dict) else {}
    except Exception:  # noqa: BLE001  -- a bad state file must never wedge the worker
        return {}


def save_failure_state(path: Optional[str], state: Dict[str, int]) -> None:
    if not path:
        return
    p = Path(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(json.dumps(state, sort_keys=True), encoding="utf-8")


def partition_candidates(
    candidates: List[Dict[str, Any]],
    failure_counts: Dict[str, int],
    max_attempts: int,
    max_per_tick: int,
) -> Dict[str, List[Dict[str, Any]]]:
    """Split fetched candidates into what to apply now vs. skip.

    - ``poisoned``: already at/over the failure ceiling -> never re-attempted,
      surfaced loudly for the operator (needs a human fix, not another retry).
    - ``to_apply``: the first ``max_per_tick`` non-poisoned candidates -> capped
      so an enabled worker lands applies one-at-a-time and observably, rather
      than draining the whole approved queue in a single unobserved tick.
    """
    poisoned = [c for c in candidates if failure_counts.get(c["id"], 0) >= max_attempts]
    eligible = [c for c in candidates if failure_counts.get(c["id"], 0) < max_attempts]
    return {"poisoned": poisoned, "to_apply": eligible[: max(0, max_per_tick)]}


# --------------------------------------------------------------------------- #
# Side-effecting steps                                                         #
# --------------------------------------------------------------------------- #
def _psql_args(args: argparse.Namespace) -> argparse.Namespace:
    """Namespace shaped for ap.run_psql (reuses the kb_apply connection path)."""
    return argparse.Namespace(
        container=args.container, db=args.db, host=args.host, role=args.role
    )


def fetch_candidates(args: argparse.Namespace, password: str) -> List[Dict[str, Any]]:
    sql = build_candidate_query(limit=args.limit)
    out = ap.run_psql(_psql_args(args), sql, password)
    return parse_candidates(out)


def apply_one(args: argparse.Namespace, proposal_id: str) -> None:
    """Apply via the audited apply_proposal.py CLI -- same txn + rowcount guard."""
    cmd = [
        sys.executable, str(args.apply_script), proposal_id,
        "--applied-by", args.applied_by,
        "--secrets-file", args.secrets_file,
        "--container", args.container, "--db", args.db,
        "--host", args.host, "--role", args.role,
    ]
    result = subprocess.run(cmd, text=True, capture_output=True, check=False)
    if result.returncode != 0:
        raise RuntimeError(
            f"apply failed for {proposal_id}: {result.stdout.strip()} {result.stderr.strip()}"
        )


def render_one(args: argparse.Namespace, agent_id: Optional[str]) -> str:
    cmd = build_render_command(args.render_cmd, agent_id)
    if cmd is None:
        return "render skipped (no render-cmd configured; PR2 renderer not deployed)"
    result = subprocess.run(cmd, text=True, capture_output=True, check=False)
    if result.returncode != 0:
        raise RuntimeError(
            f"render failed for agent {agent_id}: {result.stdout.strip()} {result.stderr.strip()}"
        )
    return f"rendered agent {agent_id}"


# --------------------------------------------------------------------------- #
# Main                                                                         #
# --------------------------------------------------------------------------- #
def run(args: argparse.Namespace) -> int:
    password = ap.load_password(args.secrets_file)
    candidates = fetch_candidates(args, password)

    if not candidates:
        print("no approved+applyable proposals; nothing to do")
        return 0

    failure_counts = load_failure_state(args.failure_state_file)
    split = partition_candidates(candidates, failure_counts, args.max_attempts, args.max_per_tick)

    for c in split["poisoned"]:
        print(
            f"SKIP poison-pill {c['id']} ({c['proposal_type']}): failed "
            f"{failure_counts.get(c['id'], 0)}x >= max-attempts {args.max_attempts}; "
            f"needs a human fix, not another retry",
            file=sys.stderr,
        )

    enabled = args.enable or os.environ.get("KB_APPLY_WORKER_ENABLED") == "1"
    if not enabled:
        print(
            f"[report-only] worker disabled; {len(split['to_apply'])} proposal(s) would apply "
            f"this tick (cap {args.max_per_tick}):"
        )
        for c in split["to_apply"]:
            print(f"  would apply {c['id']} ({c['proposal_type']}) agent={c.get('agent_id')}")
        print("enable with --enable or KB_APPLY_WORKER_ENABLED=1 after the first manual apply is proven")
        return 0

    failures = 0
    for c in split["to_apply"]:
        pid, ptype, agent_id = c["id"], c["proposal_type"], c.get("agent_id")
        try:
            apply_one(args, pid)
            failure_counts.pop(pid, None)  # success clears any prior failure count
            print(f"applied {pid} ({ptype})")
            if ptype in RENDER_TYPES:
                print("  " + render_one(args, agent_id))
        except Exception as exc:  # noqa: BLE001  -- one bad proposal must not stop the batch
            failures += 1
            # Leave the proposal at 'approved' so a fixed one reapplies next tick
            # (the rowcount=1 guard makes reapply safe), but bump its failure count
            # so a deterministically-failing proposal hits the ceiling instead of
            # retrying forever. Surface loudly for the operator.
            failure_counts[pid] = failure_counts.get(pid, 0) + 1
            print(f"ERROR applying {pid} ({ptype}) [attempt {failure_counts[pid]}/"
                  f"{args.max_attempts}]: {exc}", file=sys.stderr)

    save_failure_state(args.failure_state_file, failure_counts)
    return 1 if failures else 0


def parse_args(argv: List[str]) -> argparse.Namespace:
    p = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    p.add_argument(
        "--enable", action="store_true",
        help="actually apply (default: report-only). Also honored via KB_APPLY_WORKER_ENABLED=1.",
    )
    p.add_argument("--limit", type=int, default=20, help="max candidates fetched per tick")
    p.add_argument(
        "--max-per-tick", type=int, default=1,
        help="max proposals actually APPLIED per tick (default 1: applies land "
        "one-at-a-time and observably, not a whole-queue drain)",
    )
    p.add_argument(
        "--max-attempts", type=int, default=3,
        help="consecutive apply failures before a proposal is treated as a "
        "poison pill and skipped (needs a human fix, not endless retries)",
    )
    p.add_argument(
        "--failure-state-file",
        default=os.environ.get("KB_APPLY_WORKER_STATE", "/opt/teleo-eval/logs/kb-apply-worker-failures.json"),
        help="persisted per-proposal failure counts (survives oneshot ticks so "
        "the poison-pill ceiling actually bites)",
    )
    p.add_argument(
        "--applied-by", default=ap.SERVICE_AGENT_HANDLE,
        help="handle recorded as applied_by (default: the kb-apply service agent)",
    )
    p.add_argument(
        "--apply-script", default=str(HERE / "apply_proposal.py"),
        help="path to the apply_proposal.py engine (the sole apply path)",
    )
    p.add_argument(
        "--render-cmd", default=os.environ.get("KB_APPLY_RENDER_CMD", ""),
        help="render hook template, e.g. 'python3 render_soul.py --agent-id {agent_id}'. "
        "Empty (default) skips render until the SOUL renderer is deployed.",
    )
    p.add_argument("--secrets-file", default=ap.DEFAULT_SECRETS_FILE)
    p.add_argument("--container", default=ap.DEFAULT_CONTAINER)
    p.add_argument("--db", default=ap.DEFAULT_DB)
    p.add_argument("--host", default=ap.DEFAULT_HOST)
    p.add_argument("--role", default=ap.DEFAULT_ROLE)
    return p.parse_args(argv)


def main(argv: Optional[List[str]] = None) -> int:
    return run(parse_args(sys.argv[1:] if argv is None else argv))


if __name__ == "__main__":
    raise SystemExit(main())