sliceagent 0.1.0__py3-none-any.whl

sliceagent/context_overflow.py

@@ -0,0 +1,227 @@
+"""Context-overflow classification — pure stdlib, never imports openai.
+
+Provides:
+  - the `_CONTEXT_OVERFLOW_PATTERNS` message table
+  - the cause-walk `_extract_status_code` (max depth 5)
+  - the 400 / 413 / `context_length_exceeded` overflow rules
+
+The moat: sliceagent always has a slice it can TIGHTEN, so there is NO
+session-size / token-count heuristic here — a generic-400 + large-session
+proxy is deliberately avoided. Overflow is decided purely from the
+error's text and HTTP status.
+
+Public surface (pinned in adopt_plan.md sec 1):
+    class ContextOverflow(Exception)
+    def is_context_overflow(error: Exception) -> bool
+    def classify(error: Exception) -> dict  # {retryable, is_context_overflow, status}
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# ── Pattern table ───────────────────────────────────────────────────────────
+# Matched against str(error).lower().
+_CONTEXT_OVERFLOW_PATTERNS = (
+    "context length",
+    "context size",
+    "maximum context",
+    "token limit",
+    "too many tokens",
+    "reduce the length",
+    "exceeds the limit",
+    "context window",
+    "prompt is too long",
+    "prompt exceeds max length",
+    "maximum number of tokens",
+    # vLLM / local inference server patterns
+    "exceeds the max_model_len",
+    "max_model_len",
+    "prompt length",  # "engine prompt length X exceeds"
+    "input is too long",
+    "maximum model length",
+    # Ollama patterns
+    "context length exceeded",
+    "truncating input",
+    # llama.cpp / llama-server patterns
+    "slot context",  # "slot context: N tokens, prompt N tokens"
+    "n_ctx_slot",
+    # Chinese error messages (some providers return these)
+    "超过最大长度",
+    "上下文长度",
+    # AWS Bedrock Converse API error patterns
+    "input is too long",
+    "max input token",
+    "exceeds the maximum number of input tokens",
+    # NOTE: bare "input token" was removed — it matched OpenAI's TPM rate-limit text
+    # ("Limit: 30000 input tokens per minute"), misclassifying a 429 as a hard overflow.
+)
+
+# Structured error codes that unambiguously mean overflow.
+_CONTEXT_OVERFLOW_CODES = frozenset({
+    "context_length_exceeded",
+    "max_tokens_exceeded",
+})
+
+# Payload-too-large message patterns — a 413 surfaced in the message text
+# when no status_code attr is present.
+_PAYLOAD_TOO_LARGE_PATTERNS = (
+    "request entity too large",
+    "payload too large",
+    "error code: 413",
+)
+
+
+# A parameter / validation error (e.g. "unsupported parameter 'max_tokens'") is NOT a context
+# overflow even though it may name a token param — reading it as overflow would wrongly trigger the
+# slice-tighten/rebuild loop. Root-cause guard: exclude param errors regardless of which param.
+# (Kept SPECIFIC: a real OpenAI overflow is type invalid_request_error / code context_length_exceeded,
+# so we must NOT exclude on those — only on explicit "unsupported/invalid parameter" wording.)
+_NOT_OVERFLOW_MARKERS = (
+    "unsupported parameter",
+    "unsupported_parameter",
+    "is not supported with this model",
+    "unknown parameter",
+    "invalid parameter",
+    "parameter is invalid",   # "the prompt length parameter is invalid" — a validation error, NOT overflow
+    "invalid value",
+    "invalid input token",    # "invalid input token format" — not a context-size overflow
+)
+
+
+def _error_text(error: Exception) -> str:
+    """Lowercased message text for pattern matching."""
+    return str(error).lower()
+
+
+def _extract_status_code(error: Exception) -> Optional[int]:
+    """Walk the error and its cause chain to find an HTTP status code.
+
+    Max depth 5 to bound the walk. Checks `.status_code` (int) then `.status`
+    (sane int) on each node, following `__cause__`/`__context__`.
+    """
+    current: Optional[BaseException] = error
+    for _ in range(5):  # max depth to prevent infinite loops
+        if current is None:
+            break
+        code = getattr(current, "status_code", None)
+        if isinstance(code, int):
+            return code
+        # Some SDKs use .status instead of .status_code
+        code = getattr(current, "status", None)
+        if isinstance(code, int) and 100 <= code < 600:
+            return code
+        # Walk cause chain
+        cause = getattr(current, "__cause__", None) or getattr(current, "__context__", None)
+        if cause is None or cause is current:
+            break
+        current = cause
+    return None
+
+
+def _extract_error_code(error: Exception) -> str:
+    """Best-effort structured error-code string from a `.code`/`.body` attr.
+
+    Defensive and pure-stdlib: never imports an SDK, never raises. Returns ''
+    when no usable code is found.
+    """
+    # Direct attribute (many SDK exceptions expose .code)
+    code = getattr(error, "code", None)
+    if isinstance(code, str) and code.strip():
+        return code.strip().lower()
+
+    body = getattr(error, "body", None)
+    if isinstance(body, dict):
+        err_obj = body.get("error")
+        if isinstance(err_obj, dict):
+            nested = err_obj.get("code") or err_obj.get("type") or ""
+            if isinstance(nested, str) and nested.strip():
+                return nested.strip().lower()
+        top = body.get("code") or body.get("error_code") or ""
+        if isinstance(top, str) and top.strip():
+            return top.strip().lower()
+    return ""
+
+
+def is_context_overflow(error: Exception) -> bool:
+    """True when `error` is (or wraps) a context-overflow signal.
+
+    An overflow is recognised when ANY of the following hold:
+      - the lowercased message matches `_CONTEXT_OVERFLOW_PATTERNS`;
+      - a structured error code is `context_length_exceeded`/`max_tokens_exceeded`;
+      - the cause chain carries HTTP 413 (payload-too-large => compress);
+      - a 413 phrased in the message text (`_PAYLOAD_TOO_LARGE_PATTERNS`).
+
+    A bare 400/404 is NOT treated as overflow unless its TEXT matches the
+    overflow table — many non-overflow errors also use 400/404, and sliceagent
+    uses no session-size proxy (we always have a slice to tighten).
+    """
+    msg = _error_text(error)
+    if "rate limit" in msg or "too many requests" in msg or "tokens per min" in msg:
+        return False  # a TPM/RPM RATE LIMIT (429) must back off + retry, NOT trigger slice-destroying overflow handling
+    if any(m in msg for m in _NOT_OVERFLOW_MARKERS):
+        return False  # a parameter/validation error is never a context overflow
+    if any(p in msg for p in _CONTEXT_OVERFLOW_PATTERNS):
+        return True
+    if any(p in msg for p in _PAYLOAD_TOO_LARGE_PATTERNS):
+        return True
+
+    code = _extract_error_code(error)
+    if code in _CONTEXT_OVERFLOW_CODES:
+        return True
+
+    status = _extract_status_code(error)
+    if status == 413:
+        return True
+
+    return False
+
+
+def classify(error: Exception) -> dict:
+    """Classify `error` for the retry/rebuild loop.
+
+    Returns `{retryable, is_context_overflow, status}`:
+      - `is_context_overflow`: result of `is_context_overflow(error)`;
+      - `status`: HTTP status from the cause-walk, or None;
+      - `retryable`: True for transient transport errors (5xx, 408, 429) and
+        for timeout/connection wording; False for context overflow (the slice
+        must be TIGHTENED, not blindly retried) and for non-transient 4xx.
+
+    Overflow is intentionally `retryable=False` here: the caller rebuilds a
+    smaller slice (see W5 errors.classify glue / loop overflow-rebuild loop)
+    rather than re-sending the identical oversized request.
+    """
+    overflow = is_context_overflow(error)
+    status = _extract_status_code(error)
+
+    if overflow:
+        return {"retryable": False, "is_context_overflow": True, "status": status}
+
+    msg = _error_text(error)
+    retryable = False
+    if status is not None:
+        # 5xx server errors + 408 request-timeout + 429 rate-limit are transient.
+        if status >= 500 or status in (408, 429):
+            retryable = True
+    else:
+        # No status code: fall back to transient transport wording.
+        if any(
+            p in msg
+            for p in ("timeout", "timed out", "connection", "temporarily unavailable")
+        ):
+            retryable = True
+
+    return {"retryable": retryable, "is_context_overflow": False, "status": status}
+
+
+class ContextOverflow(Exception):
+    """Raised by the LLM adapter when a request overflows the context window.
+
+    Carries the original provider error so the retry/rebuild loop can inspect
+    it. `status_code` is the HTTP status if one was extractable, else None.
+    """
+
+    def __init__(self, original: Exception, *, status_code: Optional[int] = None):
+        self.original = original
+        self.status_code = status_code
+        super().__init__(str(original))

sliceagent/envspec.py

@@ -0,0 +1,129 @@
+"""Single source of truth for every sliceagent environment variable.
+
+Before this, 28 env vars were scattered across llm.py / cli.py / config.py / hooks.py with no discovery and
+no validation (a typo'd AGENT_POLICY silently used the default). This module centralizes them so:
+  * `sliceagent config --list` can show every knob, its group, default, and current value;
+  * `validate_env()` warns on a misspelled enum value at startup instead of silently defaulting;
+  * a coverage test asserts no AGENT_*/LLM_*/SLICEAGENT_* var is read in the code without being documented here.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EnvVar:
+    name: str
+    group: str
+    desc: str
+    default: str = ""
+    choices: tuple = ()          # if set AND validate=True, an out-of-set value warns at startup
+    secret: bool = False         # value is masked in `config --list`
+    validate: bool = False       # run startup validation against `choices`
+    aliases: tuple = ()          # extra accepted values not shown as the canonical choice set
+
+
+REGISTRY: list[EnvVar] = [
+    # ── agent behaviour ───────────────────────────────────────────────────────────────────────
+    EnvVar("AGENT_MODEL", "agent", "LLM model id to drive the agent. REQUIRED — no default; set it here "
+           "or pick a provider+model via `sliceagent init`.", ""),
+    EnvVar("AGENT_MODEL_FALLBACK", "agent", "Larger-context model to switch to ONCE if the context overflows "
+           "even after compaction (secondary net; the bounded slice is the primary).", ""),
+    EnvVar("AGENT_PROVIDER", "agent", "Default provider id to use from the config's [providers.<id>] tables "
+           "(overrides [agent].default_provider).", ""),
+    EnvVar("AGENT_POLICY", "agent", "Permission mode: baby-sitter (confirm all) | teenager (auto edits, "
+           "confirm commands) | let-it-go (auto, blocks catastrophic). All block catastrophic moves.",
+           "teenager", choices=("baby-sitter", "teenager", "let-it-go"),
+           aliases=("guard", "allow", "readonly", "ask", "babysitter", "teen", "letgo", "letitgo", "yolo", "baby"),
+           validate=True),
+    EnvVar("AGENT_ROUTER", "agent", "Topic router: lexical (instant, no LLM) or llm (classifier round-trip).",
+           "lexical", choices=("lexical", "llm"), validate=True),
+    EnvVar("AGENT_REASONING", "agent", "Reasoning effort: full=provider default, fast=minimal, high/max=more.",
+           "full", choices=("full", "fast", "high", "max"), validate=True),
+    EnvVar("AGENT_THINKING", "agent", "Set to 'off' to disable reasoning (alias for AGENT_REASONING=fast).", ""),
+    EnvVar("AGENT_MINE", "agent", "Lesson-mining mode for end-of-session consolidation.", "deterministic"),
+    EnvVar("AGENT_SUBAGENT_DEPTH", "agent", "Max delegation depth for spawn_subagent/spawn_explore (0=off).", "1"),
+    EnvVar("AGENT_EXPLORER_REASONING", "agent", "Reasoning effort for read-only explorer children.", "fast"),
+    EnvVar("AGENT_AUTO_APPROVE", "agent", "Comma-separated globs of pre-approved safe commands (skip prompt).", ""),
+    EnvVar("AGENT_VERIFY_CMD", "agent", "Oracle verify command run after a turn (e.g. 'pytest -q').", ""),
+    EnvVar("AGENT_MAX_TOKENS", "agent", "Per-session token budget (parks the turn when exhausted).", ""),
+    EnvVar("AGENT_COMPLETION_TOKENS", "agent", "Per-REQUEST completion cap (max output tokens); distinct from the AGENT_MAX_TOKENS turn budget.", "8192"),
+    EnvVar("AGENT_MAX_STEPS", "agent", "Per-turn step ceiling (runaway backstop); raise for deep analysis.", "60"),
+    EnvVar("AGENT_SELFCHECK_MAX", "agent", "Max grounded done-gate verification rounds before accepting 'done'.", "3"),
+    EnvVar("AGENT_TOOL_TIMEOUT", "agent", "Per-tool wall-clock deadline in seconds (0/unset = off).", ""),
+    EnvVar("AGENT_ROOT", "agent", "Workspace root override (defaults to the current directory).", ""),
+    EnvVar("AGENT_ALLOW_PLUGINS", "agent", "Set truthy to load project/user plugins.", ""),
+    EnvVar("AGENT_SANDBOX", "agent", "Tool sandbox backend.", "local", choices=("local", "docker"), validate=True),
+    EnvVar("AGENT_WEB", "agent", "Enable the web tools (fetch_url + web_search, DuckDuckGo, no key); set "
+           "0/off to disable network egress from the agent.", "1"),
+    # ── provider / network ────────────────────────────────────────────────────────────────────
+    EnvVar("LLM_API_KEY", "provider", "API key for the LLM provider (REQUIRED).", "", secret=True),
+    EnvVar("LLM_BASE_URL", "provider", "OpenAI-compatible endpoint (e.g. https://api.moonshot.cn/v1).", ""),
+    EnvVar("LLM_TIMEOUT", "provider", "Per-request timeout in seconds.", ""),
+    EnvVar("LLM_TIMEOUT_SEC", "provider", "Alias for LLM_TIMEOUT.", ""),
+    EnvVar("AGENT_PROXY", "provider", "HTTP proxy URL for LLM calls; 'none'/'off' forces direct. Unset = direct (no proxy).", ""),
+    EnvVar("OPENAI_API_KEY", "provider", "Legacy alias for LLM_API_KEY.", "", secret=True),
+    EnvVar("MOONSHOT_API_KEY", "provider", "Legacy alias for LLM_API_KEY (Moonshot).", "", secret=True),
+    EnvVar("OPENAI_BASE_URL", "provider", "Legacy alias for LLM_BASE_URL.", ""),
+    # ── UI ────────────────────────────────────────────────────────────────────────────────────
+    EnvVar("AGENT_TUI", "ui", "UI mode: rich (default inline), live (pinned box), off (plain).",
+           "rich", choices=("rich", "live", "off"),
+           aliases=("1", "on", "true", "yes", "0", "false", "no")),
+    EnvVar("AGENT_SPINNER", "ui", "Animated in-place status spinner during a turn (a Rich live region). "
+           "Set off to drop just the spinner; all other Rich formatting stays.",
+           "on", choices=("on", "off"), aliases=("1", "true", "yes", "0", "false", "no")),
+    EnvVar("SHOW_SLICE", "ui", "Set truthy to print the rebuilt slice each turn (debug view).", ""),
+    # ── memory ────────────────────────────────────────────────────────────────────────────────
+    EnvVar("SLICEAGENT_VAULT", "memory", "sliceagent's STATE vault (episodic cache + task-state records).", ""),
+    EnvVar("MEMEM_VAULT", "memory", "memem's lesson vault (markdown long-term memories), if memem is installed.", ""),
+    EnvVar("SLICEAGENT_SKILLS_DIR", "memory", "Extra directory to discover skills from.", ""),
+    EnvVar("AGENT_BACKGROUND_REVIEW", "agent", "Set truthy to run an off-thread reviewer that consolidates "
+           "lessons after each turn.", ""),
+    EnvVar("SLICEAGENT_CACHE_DIR", "memory", "Directory for the episodic cache / durable log.", ""),
+    EnvVar("AGENT_EXPERIMENTAL_ALL", "debug", "Master switch: set truthy to enable ALL experimental flags "
+           "(per-flag AGENT_EXPERIMENTAL_<ID> overrides).", ""),
+    # ── monitoring / debug ────────────────────────────────────────────────────────────────────
+    EnvVar("AGENT_METRICS", "monitor", "Set truthy to print per-turn fresh-token (moat) metrics at exit.", ""),
+    EnvVar("AGENT_TIMING", "monitor", "Set truthy to print a per-turn latency breakdown (slice build vs model).", ""),
+    EnvVar("AGENT_MONITOR", "monitor", "Set truthy to enable the live monitor server.", ""),
+    EnvVar("AGENT_MONITOR_PORT", "monitor", "Port for the monitor server.", ""),
+    EnvVar("SLICEAGENT_MONITOR_DIR", "monitor", "Directory the monitor writes slice snapshots to.", ""),
+    EnvVar("SLICEAGENT_DEBUG_TRACE", "debug", "Set truthy to print tracebacks for parked/hook errors.", ""),
+    EnvVar("SLICEAGENT_NO_CLOSURE", "debug", "Debug flag: disable the turn closeout call.", ""),
+    EnvVar("SLICEAGENT_PROMPT_FILE", "debug", "A/B experiment seam: path to a full SYSTEM_PROMPT template "
+           "(must keep the {{MEMORY_MODEL}} marker) to override the prompt for a measurement run "
+           "(evals/prompt_ab). Unset → the production prompt.", ""),
+]
+
+BY_NAME: dict[str, EnvVar] = {e.name: e for e in REGISTRY}
+GROUPS = ("agent", "provider", "ui", "memory", "monitor", "debug")
+
+
+def validate_env(env: dict | None = None) -> list[str]:
+    """Return a list of human-readable warnings for any enum var set to an out-of-set value. Non-fatal:
+    the caller prints them and continues on defaults (mature CLIs validate; they don't silently misbehave)."""
+    env = env if env is not None else os.environ
+    warnings = []
+    for e in REGISTRY:
+        if not (e.validate and e.choices):
+            continue
+        raw = env.get(e.name)
+        if raw is None or raw == "":
+            continue
+        if raw.strip().lower() not in {c.lower() for c in e.choices} | {a.lower() for a in e.aliases}:
+            warnings.append(f"{e.name}={raw!r} is not one of {{{', '.join(e.choices)}}} — using default "
+                            f"{e.default!r}")
+    return warnings
+
+
+def current_value(name: str, env: dict | None = None) -> str:
+    """The effective value of a var for display, masked if it is a secret."""
+    env = env if env is not None else os.environ
+    e = BY_NAME.get(name)
+    raw = env.get(name)
+    if raw is None:
+        return ""
+    if e and e.secret and raw:
+        return f"*** ({len(raw)} chars)"     # never reveal any of a secret (not even the 'sk-' prefix)
+    return raw

sliceagent/errors.py

@@ -0,0 +1,167 @@
+"""Error classification + retry.
+
+`classify` maps an exception to structured recovery hints; `with_retry` does
+abort-aware jittered backoff on retryable errors.
+
+The backoff is jittered: a
+lock-guarded monotonic counter seeds a per-call RNG so concurrent sessions
+hitting the same rate-limited provider don't all retry at the same instant
+(decorrelated uniform jitter).
+"""
+from __future__ import annotations
+
+import random
+import threading
+import time
+from enum import Enum
+from typing import Callable
+
+from .context_overflow import is_context_overflow
+from .events import ApiRetry, Dispatcher
+
+
+class ErrorKind(str, Enum):
+    """Typed failure taxonomy. str-based so it stays
+    backward-compatible: `classify(e)["kind"] == "rate_limit"` still works, and it's JSON-serializable for
+    telemetry. ALL members let the metrics layer pre-register a counter per kind."""
+    CONTEXT_OVERFLOW = "context_overflow"
+    AUTH = "auth"
+    EMPTY_RESPONSE = "empty_response"
+    RATE_LIMIT = "rate_limit"
+    SERVER = "server"
+    TIMEOUT = "timeout"
+    CONNECTION = "connection"
+    UNKNOWN = "unknown"
+
+
+class EmptyResponseError(Exception):
+    """The provider returned a degenerate completion — no content AND no tool calls. Some
+    providers/proxies occasionally emit an empty body; returning it stalls the loop. Classified
+    RETRYABLE so `with_retry` re-rolls instead."""
+
+
+# Monotonic counter for jitter-seed uniqueness within the same process.
+# Lock-guarded to avoid races in concurrent retry paths.
+_jitter_counter = 0
+_jitter_lock = threading.Lock()
+
+
+def jittered_backoff(
+    attempt: int,
+    *,
+    base_delay: float = 0.5,
+    max_delay: float = 5.0,
+    jitter_ratio: float = 0.5,
+) -> float:
+    """Compute a jittered exponential backoff delay.
+
+    Args:
+        attempt: 1-based retry attempt number.
+        base_delay: Base delay in seconds for attempt 1.
+        max_delay: Maximum delay cap in seconds.
+        jitter_ratio: Fraction of the computed delay to use as random jitter
+            range. 0.5 means jitter is uniform in [0, 0.5 * delay].
+
+    Returns:
+        Delay in seconds: min(base * 2^(attempt-1), max_delay) + jitter.
+
+    The jitter decorrelates concurrent retries so multiple sessions hitting the
+    same provider don't all retry at the same instant.
+    """
+    global _jitter_counter
+    with _jitter_lock:
+        _jitter_counter += 1
+        tick = _jitter_counter
+
+    exponent = max(0, attempt - 1)
+    if exponent >= 63 or base_delay <= 0:
+        delay = max_delay
+    else:
+        delay = min(base_delay * (2 ** exponent), max_delay)
+
+    # Seed from time + counter for decorrelation even with coarse clocks.
+    seed = (time.time_ns() ^ (tick * 0x9E3779B9)) & 0xFFFFFFFF
+    rng = random.Random(seed)
+    jitter = rng.uniform(0, jitter_ratio * delay)
+
+    return delay + jitter
+
+
+def classify(error: Exception) -> dict:
+    msg = str(error).lower()
+    status = getattr(error, "status_code", None) or getattr(error, "status", None)
+    overflow = is_context_overflow(error)
+    empty = isinstance(error, EmptyResponseError)
+    retryable = False
+    if status == 429 or "rate limit" in msg or "too many requests" in msg or "overloaded" in msg or "503" in msg:
+        retryable = True
+    if isinstance(status, int) and 500 <= status < 600:
+        retryable = True
+    if "timeout" in msg or "timed out" in msg or "connection error" in msg or "econn" in msg:
+        retryable = True
+    if empty:
+        retryable = True  # degenerate empty completion — re-roll
+    if status in (401, 403):
+        retryable = False  # auth — never retry
+    if overflow:
+        retryable = False  # tighten the slice, don't blindly re-send the oversized request
+    # Bucket the failure for telemetry (orthogonal to `retryable`; lets the metrics layer count
+    # rate-limit vs timeout vs overflow vs empty).
+    if overflow:
+        kind = ErrorKind.CONTEXT_OVERFLOW
+    elif status in (401, 403):
+        kind = ErrorKind.AUTH
+    elif empty:
+        kind = ErrorKind.EMPTY_RESPONSE
+    elif status == 429 or "rate limit" in msg or "too many requests" in msg or "overloaded" in msg:
+        kind = ErrorKind.RATE_LIMIT
+    elif (isinstance(status, int) and 500 <= status < 600) or "503" in msg:
+        kind = ErrorKind.SERVER
+    elif "timeout" in msg or "timed out" in msg:
+        kind = ErrorKind.TIMEOUT
+    elif "connection" in msg or "econn" in msg:
+        kind = ErrorKind.CONNECTION
+    else:
+        kind = ErrorKind.UNKNOWN
+    return {"retryable": retryable, "is_context_overflow": overflow, "status": status, "kind": kind}
+
+
+def _retry_after_seconds(error: Exception) -> "float | None":
+    """Best-effort: a 429/503 may carry a Retry-After (SDK `.retry_after` or a response header) telling us
+    EXACTLY how long to wait — honor it instead of guessing. Returns seconds, or None to fall back to
+    backoff (incl. when Retry-After is an HTTP-date, which we don't parse). Never raises."""
+    try:
+        val = getattr(error, "retry_after", None)
+        if val is None:
+            hdrs = getattr(getattr(error, "response", None), "headers", None)
+            if hdrs is not None:
+                val = hdrs.get("retry-after") or hdrs.get("Retry-After")
+        if val is None:
+            return None
+        secs = float(val)
+        return secs if secs >= 0 else None
+    except (TypeError, ValueError):
+        return None
+
+
+def with_retry(
+    fn: Callable[[], object],
+    *,
+    max_attempts: int = 3,
+    is_retryable: Callable[[Exception], bool] | None = None,
+    dispatch: Dispatcher | None = None,
+):
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return fn()
+        except Exception as e:
+            retry = is_retryable(e) if is_retryable else classify(e)["retryable"]
+            if not retry or attempt == max_attempts:
+                raise
+            if dispatch:
+                dispatch(ApiRetry(attempt=attempt, error=str(e)[:200]))
+            delay = jittered_backoff(attempt)
+            ra = _retry_after_seconds(e)
+            if ra is not None:
+                delay = max(delay, min(ra, 60.0))   # honor server Retry-After, capped so a huge value can't stall the turn
+            time.sleep(delay)

sliceagent/events.py

@@ -0,0 +1,96 @@
+"""Event system: the loop's ONLY output path.
+
+The core never prints or writes files — it dispatches events. The host composes a
+dispatcher from sinks (slice-updater, durable log, CLI/TUI, SDK). Sink failures are
+contained so a frontend can't break the loop.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass
+class Event:
+    pass
+
+
+@dataclass
+class StepBegin(Event):
+    step: int
+
+
+@dataclass
+class StepEnd(Event):
+    step: int
+    usage: dict
+    stop_reason: str
+
+
+@dataclass
+class SliceBuilt(Event):
+    rendered: str  # the volatile user message this turn (for debugging/inspection)
+    messages: list | None = None  # the FULL model-visible messages [system, user] (monitor/inspection)
+
+
+@dataclass
+class AssistantText(Event):
+    content: str
+
+
+@dataclass
+class ToolStarted(Event):
+    name: str
+    args: dict
+
+
+@dataclass
+class ToolResult(Event):
+    name: str
+    args: dict
+    output: str
+    failing: bool
+
+
+@dataclass
+class ApiRetry(Event):
+    attempt: int
+    error: str
+
+
+@dataclass
+class SliceTightened(Event):
+    level: int
+    reason: str = "context_overflow"
+
+
+@dataclass
+class TurnEnd(Event):
+    stop_reason: str
+    steps: int
+    usage: dict
+
+
+@dataclass
+class TurnInterrupted(Event):
+    reason: str  # "aborted" | "max_steps" | "error"
+    message: str | None = None
+
+
+@dataclass
+class LessonSaved(Event):
+    title: str
+    content: str  # the lesson mined into memem (write side of the memory loop)
+
+
+Dispatcher = Callable[[Event], None]
+
+
+def make_dispatcher(*sinks: Callable[[Event], None]) -> Dispatcher:
+    def dispatch(event: Event) -> None:
+        for sink in sinks:
+            try:
+                sink(event)
+            except Exception:
+                pass  # a sink/listener failure must not affect the loop
+    return dispatch