devops-bot-sdk 1.6.6__tar.gz → 1.6.10__tar.gz

{devops_bot_sdk-1.6.6 → devops_bot_sdk-1.6.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.6
+Version: 1.6.10
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.6 → devops_bot_sdk-1.6.10}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.6
+Version: 1.6.10
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.6 → devops_bot_sdk-1.6.10}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ sdk/local_exec.py
 sdk/platform_compat.py
 sdk/py.typed
 sdk/run_auto.py
+sdk/scheduler.py
 sdk/sse.py
 sdk/test.py
 sdk/test_pipeline.py
@@ -37,6 +38,7 @@ sdk/agents/prompt_studio.py
 sdk/agents/prompt_template.py
 sdk/agents/prompt_vars.py
 sdk/agents/run_log.py
+sdk/agents/schedules.py
 sdk/agents/secrets.py
 sdk/agents/ticket_run.py
 sdk/agents/usage.py
@@ -88,6 +90,7 @@ sdk/ui/static/default-agents.html
 sdk/ui/static/index.html
 sdk/ui/static/login.html
 sdk/ui/static/runs.html
+sdk/ui/static/schedules.html
 sdk/ui/static/setup.html
 sdk/ui/static/styles.css
 sdk/ui/static/tickets.html
@@ -97,10 +100,17 @@ tests/test_agent_listing.py
 tests/test_agent_prompt_async.py
 tests/test_agent_prompt_models.py
 tests/test_agent_run_ticket.py
+tests/test_agent_schedules.py
+tests/test_agent_workspace_settings.py
 tests/test_agents_connectors_builder.py
+tests/test_allowed_tools_config.py
 tests/test_git_action.py
 tests/test_github_ingest.py
 tests/test_health.py
 tests/test_otp_login.py
+tests/test_run_outputs.py
+tests/test_schedule_api.py
+tests/test_scheduler.py
+tests/test_update_timer.py
 tests/test_updater_extras.py
 tests/test_vps_health.py

{devops_bot_sdk-1.6.6 → devops_bot_sdk-1.6.10}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.6
+Version: 1.6.10
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -30,7 +30,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.6"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.10"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.6.6 → devops_bot_sdk-1.6.10}/sdk/agents/chat.py

@@ -41,6 +41,16 @@ def _tee_events(log_path, on_event: "EventHandler | None") -> "EventHandler":
 EventHandler = Callable[[dict], Awaitable[None]]
 
 
+class AgentLookupUnavailable(LookupError):
+    """The agent could not be found, but at least one source could not be READ.
+
+    Distinct from a plain ``LookupError`` (which means the agent genuinely is not
+    there) because the two deserve opposite treatment unattended: a renamed or
+    deleted agent should stop its schedule, while a backend outage must not — three
+    flaky minutes would otherwise disable every schedule on the box.
+    """
+
+
 def _find_agent(name: str) -> AgentManifest | None:
     """A LOCAL manifest by name (``~/.agentos/agents``), or None."""
     return next((m for m in load_agents() if m.name == name), None)
@@ -71,6 +81,7 @@ async def resolve_agent(name: str, client=None) -> AgentManifest:
         client = BackendClient.from_config()
 
     reasons: list[str] = []
+    unreadable = False
     for label, attr in (("your agents", "list_custom_agents"),
                         ("department defaults", "list_department_agents")):
         fetch = getattr(client, attr, None)
@@ -79,6 +90,7 @@ async def resolve_agent(name: str, client=None) -> AgentManifest:
         try:
             rows = await fetch() or []
         except Exception as exc:  # noqa: BLE001 — a fetch failure is not "not found"
+            unreadable = True
             reasons.append(f"{label} could not be fetched ({str(exc) or type(exc).__name__})")
             continue
         for row in rows:
@@ -94,7 +106,8 @@ async def resolve_agent(name: str, client=None) -> AgentManifest:
     detail = "; ".join(reasons) if reasons else (
         "not in ~/.agentos/agents/, your backend agents, or your department defaults"
     )
-    raise LookupError(f"no agent named '{name}' — {detail}")
+    message = f"no agent named '{name}' — {detail}"
+    raise AgentLookupUnavailable(message) if unreadable else LookupError(message)
 
 
 def _render_conversation(history: list[dict] | None, message: str) -> str:
@@ -196,6 +209,10 @@ async def run_agent(
     on_event: EventHandler | None = None,
     project_path: str | None = None,
     scope: str = "custom",
+    persist_vars: bool = True,
+    trigger: str = "",
+    kind: str = "run",
+    client=None,
 ) -> dict:
     """Run an agent once against its own standing prompt — NOT a chat turn.
 
@@ -206,11 +223,21 @@ async def run_agent(
     (custom agents) or the host environment (department agents), exactly as in
     :func:`chat_with_agent`.
 
+    ``persist_vars=False`` skips writing the values to the prefill store. A
+    SCHEDULED run must pass this: the store exists to remember what a HUMAN last
+    typed into the Run form, and a nightly cron would otherwise overwrite that
+    person's values every night with its own.
+
+    ``trigger`` / ``kind`` are recorded in the run's output file so a reader can
+    tell a cron firing from someone pressing Run. ``client`` lets a caller that
+    already has a :class:`BackendClient` reuse it instead of having one built per
+    run (see :func:`resolve_agent`).
+
     Returns the engine's normalized result dict. Raises ``ValueError`` if any
     ``{{variable}}`` is left unfilled — the UI gates the Run button on this, and
     this is the server-side backstop.
     """
-    manifest = await resolve_agent(name)
+    manifest = await resolve_agent(name, client)
 
     skills = load_skills()
     skill_text = resolve_skill_text(manifest, skills)
@@ -233,11 +260,14 @@ async def run_agent(
 
     # Remember these values so the next run can PREFILL them ("show previous
     # ones"); the user can still change them every run. Not secret — see varstore.
-    agent_varstore.save_vars(manifest.name, variables)
+    # Skipped for scheduled runs, which carry their own stored values and must not
+    # clobber what the human last typed.
+    if persist_vars:
+        agent_varstore.save_vars(manifest.name, variables)
 
     log_path = run_log.start_run(
-        manifest.name, scope=scope, engine=manifest.engine, kind="run",
-        variables=variables,
+        manifest.name, scope=scope, engine=manifest.engine, kind=kind,
+        variables=variables, trigger=trigger,
     )
     teed = _tee_events(log_path, on_event)
 

devops_bot_sdk-1.6.10/sdk/agents/engines/claude_code.py

@@ -0,0 +1,122 @@
+"""claude_code engine -- a thin adapter from an agent manifest onto ``sdk.local_exec.run_claude_local``."""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+from sdk import config
+from sdk.local_exec import run_claude_local
+
+if TYPE_CHECKING:
+    from sdk.agents.manifest import AgentManifest
+
+logger = logging.getLogger("sdk.agents.engines.claude_code")
+
+# Same shape as sdk.local_exec.EventHandler -- kept local so this module doesn't
+# need to reach into local_exec for a type alias.
+EventHandler = Callable[[dict], Awaitable[None]]
+
+# Directory every agent without a real code workspace runs in.
+AGENT_RUNS_DIR = Path.home() / ".agentos" / "runs"
+
+
+def ensure_agent_workspace(agent_name: str) -> Path:
+    """The working directory for ``agent_name``, with its Claude settings in place.
+
+    Returns ``~/.agentos/runs/<agent>`` and makes sure
+    ``<that>/.claude/settings.json`` grants the configured tools
+    (``config.get_allowed_tools()``) under ``permissions.allow``.
+
+    Why write it at all when ``run_claude_local`` already passes
+    ``--allowedTools``: that flag covers the headless run, but the run directory IS
+    a Claude Code project, so anything reading project settings — a resumed
+    session, a nested/interactive invocation, a hook — sees the same grants instead
+    of falling back to prompting in a place where nobody can answer.
+
+    MERGES rather than overwrites: existing keys and any extra entries already in
+    ``permissions.allow`` are preserved, so a hand-added rule survives, and a tool
+    added to the configured list later shows up on the next run. Best-effort — a
+    write failure is logged and the run proceeds on ``--allowedTools`` alone.
+
+    Applies to CUSTOM and DEPARTMENT agents alike: both arrive as prompt-based
+    backend rows and both run through here.
+    """
+    workspace = AGENT_RUNS_DIR / agent_name
+    workspace.mkdir(parents=True, exist_ok=True)
+
+    settings_path = workspace / ".claude" / "settings.json"
+    try:
+        settings: dict = {}
+        if settings_path.exists():
+            try:
+                loaded = json.loads(settings_path.read_text(encoding="utf-8"))
+                if isinstance(loaded, dict):
+                    settings = loaded
+            except (OSError, json.JSONDecodeError) as exc:
+                # A corrupt file silently disables ALL settings from it, so replace
+                # it rather than leave the agent running with none.
+                logger.warning("rewriting unparseable %s: %s", settings_path, exc)
+
+        permissions = settings.get("permissions")
+        if not isinstance(permissions, dict):
+            permissions = {}
+        allow = [t for t in (permissions.get("allow") or []) if isinstance(t, str)]
+        for tool in config.get_allowed_tools():
+            if tool not in allow:
+                allow.append(tool)
+        permissions["allow"] = allow
+        settings["permissions"] = permissions
+
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    except OSError as exc:
+        logger.warning("could not write %s: %s", settings_path, exc)
+
+    return workspace
+
+
+async def run(
+    manifest: "AgentManifest",
+    skill_text: str,
+    mcp_config: dict[str, Any] | None,
+    project_path: str | None = None,
+    on_event: EventHandler | None = None,
+    extra_env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Run a custom agent's manifest through the local ``claude`` CLI.
+
+    This does not reimplement any of ``run_claude_local``'s subprocess handling,
+    stream-json parsing, or crucial-hook logic -- it only assembles the prompt
+    and a working directory, then delegates.
+
+    ``skill_text`` is expected to already be the resolved skill body (see
+    ``sdk.agents.manifest.resolve_skill_text``), concatenated by the caller
+    where needed. To be safe, the final prompt is (re-)assembled here from
+    ``manifest.prompt`` plus, when ``skill_text`` is truthy, two newlines and
+    the skill body.
+    """
+    full_prompt = manifest.prompt
+    if skill_text:
+        full_prompt = f"{full_prompt}\n\n{skill_text}"
+
+    if project_path is None:
+        # Most custom agents (e.g. "summarise my PRs daily") have no real code
+        # workspace -- Claude Code still needs a valid current-working-directory
+        # to run in, so fall back to a per-agent scratch directory.
+        project_path = str(ensure_agent_workspace(manifest.name))
+
+    # mcp_config: accepted here for forward compatibility only. Wiring an
+    # --mcp-config flag into run_claude_local's subprocess command is a later
+    # follow-up, once run_claude_local itself grows an mcp_config parameter --
+    # this module does not attempt to work around that in the meantime, so the
+    # argument is currently unused.
+
+    return await run_claude_local(
+        prompt=full_prompt,
+        project_path=project_path,
+        allowed_tools=manifest.allowed_tools or None,
+        on_event=on_event,
+        extra_env=extra_env,
+    )

devops_bot_sdk-1.6.10/sdk/agents/run_log.py

@@ -0,0 +1,383 @@
+"""Per-run output files for custom / default / common agent executions.
+
+Every agent run — from the control panel, `agentos agent chat/run`, a schedule, or
+the background daemon — writes one Markdown file recording what ran, what it did,
+and what it said. Files live in a folder PER AGENT:
+
+    ~/.agentos/agent_outputs/<Agent Name>/2026-08-05 18-15-42 PKT — <Agent Name>.md
+
+so "show me what this agent has been doing" is one directory listing. The folder is
+browsable from the control panel (Schedules page) and by `agentos agent logs`.
+
+Two naming choices worth stating, because both were deliberate:
+
+* **Pakistan time in the filename.** Timestamps everywhere else in the SDK are UTC
+  (``sdk.agents.usage``, ``sdk.github_ingest``), and local time in a filename is
+  normally a trap because it breaks name-sorting across a DST change. PKT is a
+  fixed UTC+5 with no DST, so here name-sort still equals time-sort. The file body
+  additionally carries the UTC instant, so nothing downstream has to guess.
+* **``agent_outputs``, not ``agent_runs``.** ``~/.agentos/runs/<agent>/`` already
+  exists and means something different — it is the working DIRECTORY the agent
+  executes in (see ``sdk.agents.engines.claude_code.ensure_agent_workspace``), and
+  holds whatever files the agent itself created. Keeping the two a rename apart
+  would have been a permanent source of confusion.
+
+Everything here is best-effort: a logging failure must never break an agent run.
+Legacy ``<scope>__<name>__<UTC>.log`` files in the old flat ``~/.agentos/logs/agents``
+directory are still listed and read, so history from before this change is intact.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+logger = logging.getLogger("sdk.agents.run_log")
+
+# Pakistan Standard Time. Fixed UTC+5, no DST — see the module docstring. The
+# ZoneInfo lookup is preferred (it is the source of truth) but falls back to the
+# fixed offset, because slim containers ship without tzdata and a missing timezone
+# database must not cost us the run record. Same guard as sdk/local_exec.py:155.
+_PKT_FALLBACK = timezone(timedelta(hours=5), "PKT")
+
+
+def _pkt() -> timezone:
+    try:
+        from zoneinfo import ZoneInfo
+        return ZoneInfo("Asia/Karachi")            # type: ignore[return-value]
+    except Exception:                              # noqa: BLE001
+        return _PKT_FALLBACK
+
+
+def _outputs_root() -> Path:
+    """Root of the per-agent output folders (override with AGENTOS_AGENT_OUTPUT_DIR)."""
+    base = os.getenv("AGENTOS_AGENT_OUTPUT_DIR")
+    return Path(base) if base else Path.home() / ".agentos" / "agent_outputs"
+
+
+def _legacy_dir() -> Path:
+    """The pre-per-agent flat directory. Read-only now, but never orphaned."""
+    base = os.getenv("AGENTOS_LOG_DIR") or str(Path.home() / ".agentos" / "logs")
+    return Path(base) / "agents"
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]+", "-", (text or "agent").strip()) or "agent"
+
+
+def _folder_name(agent_name: str) -> str:
+    """Folder name for an agent — the REAL name, minus only path-unsafe characters.
+
+    Readability matters here in a way it does not for the schedule/secret stores:
+    this folder is shown to the user and browsed by hand, so "AI Research Agent"
+    must not become "AI-Research-Agent-3f9c1a02". Only characters that could escape
+    the root or break a filesystem are replaced.
+    """
+    cleaned = re.sub(r'[\x00-\x1f/\\<>:"|?*]+', "-", (agent_name or "").strip())
+    cleaned = cleaned.strip(". ")
+    return cleaned or "agent"
+
+
+def agent_dir(agent_name: str) -> Path:
+    """The output folder for one agent (created on demand)."""
+    return _outputs_root() / _folder_name(agent_name)
+
+
+def _pkt_stamp(when: datetime | None = None) -> str:
+    """``2026-08-05 18-15-42 PKT`` — human-readable, filename-safe, sorts by time."""
+    dt = (when or datetime.now(timezone.utc)).astimezone(_pkt())
+    return dt.strftime("%Y-%m-%d %H-%M-%S PKT")
+
+
+def _pkt_human(when: datetime | None = None) -> str:
+    """``2026-08-05 06:15:42 PM PKT`` — for reading inside the file."""
+    dt = (when or datetime.now(timezone.utc)).astimezone(_pkt())
+    return dt.strftime("%Y-%m-%d %I:%M:%S %p PKT")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _max_output_chars() -> int:
+    try:
+        return max(1000, int(os.getenv("AGENTOS_RUN_OUTPUT_MAX_CHARS", "") or 200_000))
+    except ValueError:
+        return 200_000
+
+
+def _free_path(folder: Path, stamp: str, agent: str) -> Path:
+    """A path that no other run already owns.
+
+    The stamp has second resolution, so two runs of the same agent in the same
+    second — "Run now" firing next to a cron tick, or two quick manual runs — would
+    otherwise open the SAME file in append mode and interleave into one unreadable
+    record. A ``(2)`` suffix keeps them separate and still readable.
+    """
+    base = f"{stamp} — {agent}"
+    path = folder / f"{base}.md"
+    n = 2
+    while path.exists() and n < 1000:
+        path = folder / f"{base} ({n}).md"
+        n += 1
+    return path
+
+
+def _fmt_duration(seconds: float) -> str:
+    seconds = max(0.0, float(seconds))
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    mins, secs = divmod(int(seconds), 60)
+    if mins < 60:
+        return f"{mins}m {secs}s"
+    hours, mins = divmod(mins, 60)
+    return f"{hours}h {mins}m {secs}s"
+
+
+# ── Writing ─────────────────────────────────────────────────────────────────
+
+def start_run(agent_name: str, *, scope: str = "custom", engine: str = "",
+              kind: str = "run", variables: dict | None = None,
+              trigger: str = "") -> Path | None:
+    """Open this run's output file and write its front matter. Returns the path.
+
+    ``scope`` is ``custom`` | ``default`` | ``common``; ``kind`` is
+    ``run`` | ``chat`` | ``ticket`` | ``scheduled``. Variable NAMES are recorded,
+    never their values — a value can be sensitive and this file is browsable.
+    ``trigger`` is free text describing what caused the run (e.g. the cron
+    expression), shown in the header.
+    """
+    try:
+        started = datetime.now(timezone.utc)
+        d = agent_dir(agent_name)
+        d.mkdir(parents=True, exist_ok=True)
+        path = _free_path(d, _pkt_stamp(started), _folder_name(agent_name))
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(f"# {agent_name} — {_pkt_human(started)}\n\n")
+            fh.write(f"- **Started:** {_pkt_human(started)}  \n")
+            fh.write(f"- **Kind:** {kind} · **Scope:** {scope}"
+                     + (f" · **Engine:** {engine}" if engine else "") + "  \n")
+            if trigger:
+                fh.write(f"- **Trigger:** {trigger}  \n")
+            if variables:
+                fh.write(f"- **Inputs:** {', '.join(sorted(variables.keys()))}  \n")
+            # Machine-readable anchors, parsed back by finish_run. Kept as HTML
+            # comments so they stay out of the rendered Markdown.
+            fh.write(f"\n<!-- started_utc: {started.isoformat(timespec='seconds')} -->\n")
+            fh.write("\n## Activity\n\n```\n")
+        return path
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("run_log.start failed: %s", exc)
+        return None
+
+
+def log_line(path: Path | None, text: str) -> None:
+    """Append a raw line to the activity block (best-effort, no-op if path is None)."""
+    if not path:
+        return
+    try:
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(f"[{_now()}] {text}\n")
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("run_log.line failed: %s", exc)
+
+
+def log_event(path: Path | None, event: dict) -> None:
+    """Record one streamed engine event (tool call / assistant text) compactly."""
+    if not path or not isinstance(event, dict):
+        return
+    try:
+        etype = event.get("type", "")
+        summary = ""
+        if etype == "assistant":
+            for c in event.get("message", {}).get("content", []) or []:
+                if c.get("type") == "tool_use":
+                    summary = f"tool_use {c.get('name', '')}"
+                    break
+                if c.get("type") == "text":
+                    summary = "text: " + " ".join(str(c.get("text", "")).split())[:200]
+                    break
+        elif etype == "result":
+            summary = "result"
+        else:
+            summary = json.dumps(event, ensure_ascii=False)[:200]
+        log_line(path, f"{etype}: {summary}" if summary else etype)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("run_log.event failed: %s", exc)
+
+
+_TOOL_RE = re.compile(r"tool_use (\S+)")
+_STARTED_RE = re.compile(r"<!-- started_utc: (.+?) -->")
+
+
+def _tool_counts(text: str) -> list[str]:
+    """``["WebSearch × 4", "Write × 1"]`` from the activity block, most-used first.
+
+    Recovered by re-reading the file rather than by holding counters in memory, so
+    a run whose process restarted still produces an honest summary and there is no
+    per-run state to leak.
+    """
+    counts: dict[str, int] = {}
+    for name in _TOOL_RE.findall(text):
+        counts[name] = counts.get(name, 0) + 1
+    return [f"{n} × {c}" if c > 1 else n
+            for n, c in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))]
+
+
+def finish_run(path: Path | None, result: dict | None) -> None:
+    """Close the activity block, then write "What it did" and the full response."""
+    if not path:
+        return
+    result = result or {}
+    try:
+        try:
+            existing = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            existing = ""
+
+        started = None
+        m = _STARTED_RE.search(existing)
+        if m:
+            try:
+                started = datetime.fromisoformat(m.group(1))
+            except ValueError:
+                started = None
+        ended = datetime.now(timezone.utc)
+        duration = (ended - started).total_seconds() if started else 0.0
+
+        # `result` is only the LAST assistant message, so a long artifact followed
+        # by a short sign-off would be lost; local_exec keeps `longest_text` for
+        # exactly this. It is absent on timeout paths, hence the chained fallback.
+        body = (str(result.get("result") or "").strip()
+                or str(result.get("longest_text") or "").strip()
+                or str(result.get("error") or "").strip()
+                or "(no output)")
+        cap = _max_output_chars()
+        if len(body) > cap:
+            body = body[:cap] + f"\n\n… truncated {len(body) - cap} more characters"
+
+        tools = _tool_counts(existing)
+        files = [str(f) for f in (result.get("files_changed") or [])]
+
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write("```\n\n")
+            fh.write("## What it did\n\n")
+            fh.write(f"- **Tools used:** {', '.join(tools) if tools else 'none'}\n")
+            if files:
+                fh.write(f"- **Files touched ({len(files)}):**\n")
+                for f in files[:50]:
+                    fh.write(f"  - `{f}`\n")
+                if len(files) > 50:
+                    fh.write(f"  - … and {len(files) - 50} more\n")
+            else:
+                fh.write("- **Files touched:** none\n")
+            fh.write(
+                f"- **Outcome:** {'ok' if result.get('ok') else 'FAILED'}"
+                f" · {_fmt_duration(duration)}"
+                f" · {result.get('input_tokens', 0):,} in / {result.get('output_tokens', 0):,} out"
+                f" · ${float(result.get('cost_usd', 0.0) or 0.0):.4f}\n"
+            )
+            if result.get("error"):
+                fh.write(f"- **Error:** {str(result.get('error'))[:2000]}\n")
+            fh.write(f"\n## Response\n\n{body}\n")
+            fh.write(f"\n---\n\n*Finished {_pkt_human(ended)} "
+                     f"({ended.isoformat(timespec='seconds')}).*\n")
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("run_log.finish failed: %s", exc)
+
+
+# ── Reading ─────────────────────────────────────────────────────────────────
+
+def list_runs(agent_name: str | None = None, limit: int = 50) -> list[Path]:
+    """Run output paths, newest first. Spans the per-agent folders AND legacy logs."""
+    found: list[Path] = []
+
+    root = _outputs_root()
+    try:
+        if agent_name:
+            d = root / _folder_name(agent_name)
+            if d.is_dir():
+                found += [p for p in d.iterdir() if p.is_file() and p.suffix in (".md", ".log")]
+        elif root.is_dir():
+            for d in root.iterdir():
+                if d.is_dir():
+                    found += [p for p in d.iterdir()
+                              if p.is_file() and p.suffix in (".md", ".log")]
+    except OSError:
+        pass
+
+    # Pre-per-agent-folder history stays visible.
+    legacy = _legacy_dir()
+    try:
+        if legacy.is_dir():
+            pattern = f"*__{_slug(agent_name)}__*.log" if agent_name else "*.log"
+            found += list(legacy.glob(pattern))
+    except OSError:
+        pass
+
+    try:
+        found.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    except OSError:
+        return found[:limit]
+    return found[:limit]
+
+
+def read_run(path: Path, max_chars: int = 20000) -> str:
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except Exception as exc:  # noqa: BLE001
+        return f"(could not read {path}: {exc})"
+    return text[-max_chars:]
+
+
+def resolve_run(agent_name: str, filename: str) -> Path | None:
+    """A named file inside one agent's folder, or None.
+
+    The ONLY way the API turns a caller-supplied filename into a path: the result
+    must be a real file that is a direct child of that agent's folder, so
+    ``../../.ssh/id_rsa`` and absolute paths resolve outside and are rejected.
+    """
+    try:
+        base = agent_dir(agent_name).resolve()
+        target = (base / filename).resolve()
+    except OSError:
+        return None
+    if target.parent != base or not target.is_file():
+        return None
+    return target
+
+
+# ── Retention ───────────────────────────────────────────────────────────────
+
+def prune(agent_name: str, keep: int = 100, max_age_days: int = 90) -> int:
+    """Delete this agent's oldest outputs; returns how many were removed.
+
+    BOTH bounds apply, because either alone leaks: a count-only rule lets a chatty
+    hourly agent grow without limit in bytes, and an age-only rule lets a rarely-run
+    agent keep nothing. Called from the scheduler tick rather than on write, so the
+    cost is amortised and a slow filesystem never delays a run.
+    """
+    d = agent_dir(agent_name)
+    if not d.is_dir():
+        return 0
+    try:
+        files = sorted((p for p in d.iterdir() if p.is_file() and p.suffix in (".md", ".log")),
+                       key=lambda p: p.stat().st_mtime, reverse=True)
+    except OSError:
+        return 0
+
+    cutoff = datetime.now(timezone.utc).timestamp() - (max_age_days * 86400)
+    removed = 0
+    for i, path in enumerate(files):
+        try:
+            too_many = i >= keep
+            too_old = path.stat().st_mtime < cutoff
+            if too_many or too_old:
+                path.unlink()
+                removed += 1
+        except OSError:
+            continue
+    return removed