sliceagent 0.1.0__py3-none-any.whl

sliceagent/swap.py

@@ -0,0 +1,182 @@
+"""SwapManager — single owner of the working-set PAGE lifecycle (file/dep/skill/ghost/reviewed); every page enters/
+leaves the slice THROUGH here. The memory plane of a DEMAND-PAGED SNAPSHOT MACHINE: the slice is a CACHE, not a log,
+so eviction is always safe (a re-fault re-reads from the durable store). DUCK-TYPED: imports nothing from pfc.py
+(reverse import circular — pfc.py imports the bounds below); only prefetch() reaches
+self.retriever. SELF-TUNING (automatic, no model): a re-read of a file still in the recency ring (a REFAULT) proves
+the budget was momentarily too tight, so the kernel grants ITSELF a brief reclaim-protection (Linux mm/workingset
+refault detection, scaled down) AND widens its OWN read budget one notch (s.read_budget, bounded by s.read_ceiling)
+— so the working set grows to TASK need, not to a fixed ceiling. hit/miss/refault/evict are counted (s.io) so the
+moat is MEASURED, not asserted."""
+from __future__ import annotations
+
+READ_BUDGET = 4    # FLOOR for the exploratory-read residue — the lean DEFAULT, NOT a hard cap. The kernel GROWS the
+                   # live budget (s.read_budget) on refault thrash up to READ_BUDGET_MAX. "Bounded" = no PASSIVE/
+                   # history-proportional growth (Markov current-state), never a fixed size ceiling. SINGLE owner
+                   # of this and every other bound below (pfc.py/seed.py import directly, no re-export chain).
+READ_BUDGET_MAX = 16  # per-slice DISASTER CEILING for refault-driven growth. A single COHERENT task rarely needs more
+                      # resident reads than this; genuine BREADTH ("review the repo") is delegated to the subagent SWARM
+                      # (each child a fresh lean slice), NOT served by inflating one slice toward the context window
+                      # (that invites context-rot / lost-in-the-middle — see auto-memory: kernel-architecture).
+# bound ≠ size: the change set + dependency closure are RELEVANCE sets, kept resident IN FULL (evict no
+# longer truncates them — see evict/prefetch). These two constants are now PHYSICAL fan-in backstops
+# (guard against a pathological 100s-of-callers symbol), generous and well above any coherent change —
+# NOT relevance caps. swap_tools.py reads them for the occupancy display; the real overflow handler is
+# the physical-context tighten ladder, not these.
+EDIT_CEILING = 32  # physical backstop on the change set (a coherent change is far smaller); not a relevance cap
+DEP_CEILING = 64   # per-symbol caller fan-out backstop — keep ALL direct callers that break on the change
+                   # (caller-first ranked in code_index.deps); generous physical guard, not a relevance cap.
+MAX_GHOSTS = 6     # GHOST INDEX ring — pointers to recently paged-out files/skills (also the refault recency window)
+MAX_ACTIVE_SKILLS = 2    # keep only the most-recently-loaded skills active
+MAX_SKILL_CHARS = 12000  # a loaded skill body before it enters the slice; bounded by COUNT (MAX_ACTIVE_SKILLS=2),
+# so this is generous — a half-read skill (helpers/examples/patterns in the tail lost) misleads more than it costs
+MAX_REVIEWED = 8         # bounded ring of history lookbacks done (the recall_history ratchet)
+HOT_TTL = 3              # steps a REFAULT-promoted file stays kernel-protected (self-tuning; not the model)
+HOT_CEILING = 4  # bound the kernel-granted soft-pin set — never an accumulating tier (decoupled from
+                 # DEP_CEILING so raising the dep ceiling doesn't widen the refault soft-pin set)
+
+
+class SwapManager:
+    """Owns the working set: file load/evict, dep prefetch, skill load/evict, reviewed ratchet, ghosts."""
+    def __init__(self, retriever=None):
+        self.retriever = retriever
+
+    def load(self, s, path: str, edited: bool = False) -> None:  # add/refresh a file, then evict to bounds
+        if not path:
+            return
+        io = getattr(s, "io", None)
+        if path in s.active_files:                       # already resident — a cache HIT
+            if io is not None:
+                io["hit"] += 1
+        elif self._is_ghost(s, "file", path):           # re-read of a recently-evicted page — a REFAULT
+            if io is not None:
+                io["refault"] += 1
+            self._promote(s, path)                       # budget was too tight → kernel grants a brief soft-pin
+            self._grow(s)                                # …and widens its OWN read budget one notch (bidirectional ladder)
+        elif io is not None:                             # first sight — a cold MISS
+            io["miss"] += 1
+        s.active_files = [p for p in s.active_files if p != path]
+        s.active_files.append(path)
+        self._ghost_drop(s, "file", path)   # it's back in the working set → no longer a ghost
+        if edited:
+            s.edited_files.add(path)
+        self.evict(s)
+
+    def evict(self, s) -> None:
+        """Keep the change set (edited) + HOT + the WHOLE dependency closure (relevance, not a count) +
+        most-recent read_budget exploratory reads; page the rest OUT — non-lossy, since every evicted
+        file leaves a GHOST recovery pointer and re-reads on demand (a REFAULT, which also widens the
+        budget). Edited/hot/deps never evict for a plain read (re-observation reach must cover them).
+        NOTE: whether OPEN FILES should evict at all within a loop is an OPEN design decision (see the
+        bound-is-relevance discussion); this is the re-faultable middle ground pending that call."""
+        edited_set = {p for p in s.active_files if p in s.edited_files}
+        hot_set = {p for p in s.active_files if p in getattr(s, "hot", {})} - edited_set
+        protect = edited_set | hot_set
+        deps_set = {p for p in s.active_files if p in s.protected_deps and p not in protect}
+        read_budget = getattr(s, "read_budget", READ_BUDGET)   # LIVE adaptive budget (grows on refault); floor = READ_BUDGET
+        reads = [p for p in s.active_files
+                 if p not in s.edited_files and p not in deps_set and p not in protect][-read_budget:]
+        keep = protect | deps_set | set(reads)
+        io = getattr(s, "io", None)
+        for p in s.active_files:
+            if p not in keep:
+                s.edit_anchor.pop(p, None)
+                s.edited_files.discard(p)
+                if io is not None:
+                    io["evict"] += 1
+                self._ghost_add(s, "file", p)   # paged out of OPEN FILES → leave a recovery pointer
+        s.active_files = [p for p in s.active_files if p in keep]
+
+    def prefetch(self, s) -> None:
+        """Refresh change-set protected DEPS from the code graph (recomputed once per turn at seed build).
+        Also AGE the kernel-granted soft-pins one notch (runs once per build = once per TURN) so refault
+        protection is temporary, never an accumulating tier. No graph → deps no-op; the hot decay still runs."""
+        if getattr(s, "hot", None):
+            s.hot = {p: t - 1 for p, t in s.hot.items() if t - 1 > 0}
+        r = self.retriever
+        # Snapshot pre-edit def-names of files READ but not yet edited, so we can later see what an edit
+        # REMOVED/MOVED (pre-edit defs - current defs). Cheap: reads the already-computed code graph
+        # (SENSORY CORTEX — a derived view, not a persisted store).
+        if hasattr(r, "def_names") and hasattr(s, "pre_defs"):
+            for p in s.active_files:
+                if p not in s.edited_files and p not in s.pre_defs:
+                    s.pre_defs[p] = r.def_names(p)
+        if hasattr(r, "deps") and s.edited_files:
+            edited = list(s.edited_files)   # the WHOLE change set (relevance, not a count) — materialize ONCE
+            deps: set = set()
+            for e in edited:
+                deps.update(r.deps(e, limit=DEP_CEILING))   # all direct callers that break on the change
+            s.protected_deps = deps - s.edited_files
+            # CHANGE-SET CLOSURE (symbol-aware): names the edits removed/moved, then the dependents whose
+            # CURRENT tokens still reference one — precise dangling call-sites. SILENT on feature-adds
+            # (nothing removed) so it never inflates non-refactor tasks; render_closure further filters to
+            # the UNOPENED ones (self-extinguishing once the model opens the site to fix/confirm).
+            if hasattr(r, "def_names") and hasattr(r, "ref_tokens") and hasattr(s, "stale_deps"):
+                removed: set = set()
+                for e in edited:
+                    removed |= (s.pre_defs.get(e, set()) - r.def_names(e))
+                s.stale_deps = ({d for d in s.protected_deps if r.ref_tokens(d) & removed}
+                                if removed else set())
+        elif not s.edited_files:
+            s.protected_deps = set()
+            if hasattr(s, "stale_deps"):
+                s.stale_deps = set()
+
+    def load_skill(self, s, name: str, body: str) -> None:  # fold a SKILL into the active tier; evict overflow
+        if not name or not body:
+            return
+        s.active_skills = [sk for sk in s.active_skills if sk["name"] != name]
+        s.active_skills.append({"name": name, "body": body[:MAX_SKILL_CHARS]})
+        self._ghost_drop(s, "skill", name)   # freshly loaded → not a ghost
+        if len(s.active_skills) > MAX_ACTIVE_SKILLS:
+            self.evict_skill(s)
+
+    def evict_skill(self, s) -> None:  # drop skills beyond MAX_ACTIVE_SKILLS (oldest first), each → a ghost
+        for sk in s.active_skills[:-MAX_ACTIVE_SKILLS]:
+            self._ghost_add(s, "skill", sk["name"])   # evicted skill → recovery pointer
+        s.active_skills = s.active_skills[-MAX_ACTIVE_SKILLS:]
+
+    def note_review(self, s, mark: str) -> None:  # RATCHET: record a history lookback (bounded) so it isn't re-done
+        if mark and mark not in s.reviewed:
+            s.reviewed.append(mark)
+            del s.reviewed[:-MAX_REVIEWED]
+
+    def _is_ghost(self, s, kind: str, ref: str) -> bool:  # is this ref currently in the (recency-bounded) ghost ring?
+        return any(g["kind"] == kind and g["ref"] == ref for g in s.ghosts)
+
+    def _promote(self, s, path: str) -> None:
+        """Kernel grants ITSELF a brief reclaim-protection for a thrashing (refaulted) page — refault-driven,
+        NO model involvement (the validated automatic-beats-active-asker path). Bounded by HOT_CEILING; decays
+        in prefetch (HOT_TTL steps), so it can never become an accumulating tier."""
+        hot = getattr(s, "hot", None)
+        if hot is None:
+            return
+        hot[path] = HOT_TTL
+        while len(hot) > HOT_CEILING:        # drop the oldest soft-pin (insertion-ordered) past the ceiling
+            hot.pop(next(iter(hot)))
+
+    def _grow(self, s) -> None:
+        """A REFAULT proves the resident read budget was momentarily too tight for THIS task (thrash).
+        The kernel widens its OWN live budget one notch — the BIDIRECTIONAL counterpart to the overflow
+        tighten ladder (which shrinks it). Bounded by the per-slice disaster ceiling (s.read_ceiling);
+        kernel-driven from MEASURED thrash (s.io refault), NO model involvement. Monotone within a
+        session (a task that needed N reads keeps needing ~N); never history-proportional, so the moat
+        holds — growth is TASK/refault-driven and window-bounded, and the kernel can always say no at
+        the ceiling. Same signal + same place as _promote: extend self-tuning from a per-file soft-pin
+        to the budget itself (Linux mm/workingset, scaled up)."""
+        cur = getattr(s, "read_budget", READ_BUDGET)
+        ceiling = getattr(s, "read_ceiling", READ_BUDGET_MAX)
+        if cur < ceiling:
+            s.read_budget = cur + 1
+
+    def _ghost_add(self, s, kind: str, ref: str) -> None:  # paged-out item → bounded recovery POINTER (~0 tokens)
+        if not ref:
+            return
+        s.ghosts = [g for g in s.ghosts if not (g["kind"] == kind and g["ref"] == ref)]
+        s.ghosts.append({"kind": kind, "ref": ref})
+        s.ghosts = s.ghosts[-MAX_GHOSTS:]
+
+    def _ghost_drop(self, s, kind: str, ref: str) -> None:  # back IN the slice → no longer a ghost
+        s.ghosts = [g for g in s.ghosts if not (g["kind"] == kind and g["ref"] == ref)]
+
+
+_DEFAULT_SWAP = SwapManager()   # retriever-free ops; touch_file/add_skill in pfc.py delegate here

sliceagent/taskstate.py

@@ -0,0 +1,57 @@
+"""Pure Slice <-> TaskState mappers (MEMORY-SPEC step 2).
+
+No I/O, no memem — keeps pfc.py (the moat) byte-identical. TaskState stores REFS (paths +
+anchors), never file contents; resume re-reads files live (ground truth = disk). Transient tiers
+(recent, action_log, active_skills) are intentionally NOT serialized — they're per-turn residue
+re-derived from ground truth. NOTE on resume: active_skills is dropped (skill bodies live on disk
+and re-load via the `skill` tool); since_edit is zeroed (a fresh action epoch — otherwise the
+restored counter could fire render_convergence's STOP nudge on turn 1). The `conversation` ring +
+`turns` counter are also intentionally NOT carried CROSS-session (they survive within a session via
+seal()): the durable distilled state (goal, findings, world, requirements, edited set) is what a
+resume rebuilds on, and short-range chat is re-grounded from the goal — carrying it would persist
+verbatim user text into the vault for marginal continuity gain.
+"""
+from __future__ import annotations
+
+from .interfaces import TaskState
+from .pfc import Slice
+from .text_utils import one_line
+
+
+def slice_to_task_state(s: Slice, task_id: str, *, session_id: str = "", title: str = "",
+                        status: str = "active", tags: str = "", resolution: str = "",
+                        links: list[str] | None = None) -> TaskState:
+    return TaskState(
+        task_id=task_id, session_id=session_id,
+        title=title or one_line(s.goal, 60), status=status, goal=s.goal,
+        findings=list(s.findings),
+        finding_source={k: v for k, v in s.finding_source.items() if k in set(s.findings)},  # provenance, bounded to live findings
+        requirements=[dict(r) for r in s.requirements],   # carry the standing contract across resume
+        plan=[dict(p) for p in s.plan],                   # carry the PLAN (TodoWrite) across resume
+        mission=s.mission,                                # carry the MISSION north-star across resume
+        open_report=getattr(s, "open_report", ""),        # carry the OPEN USER REPORT blocker (was silently lost)
+        world=dict(s.world),                              # carry the agent WORLD MODEL (was silently lost)
+        active_files=list(s.active_files),
+        edited_files=sorted(s.edited_files),                              # byte-stable across checkpoints
+        edit_anchor={p: a for p, a in s.edit_anchor.items() if p in s.active_files},  # consistency
+        last_error=s.last_error, since_edit=s.since_edit,                # serialized faithfully
+        links=list(links or []), tags=tags, resolution=resolution,
+    )
+
+
+def task_state_to_slice(ts: TaskState, s: Slice | None = None) -> Slice:
+    s = s or Slice()
+    s.reset(ts.goal)                 # zeroes transient tiers (recent/action_log/active_skills/...)
+    s.findings = list(ts.findings)
+    s.finding_source = dict(getattr(ts, "finding_source", {}))            # restore provenance (getattr: back-compat with old checkpoints)
+    s.requirements = [dict(r) for r in getattr(ts, "requirements", [])]   # restore the standing contract
+    s.plan = [dict(p) for p in getattr(ts, "plan", [])]                   # restore the PLAN (TodoWrite)
+    s.mission = getattr(ts, "mission", "")                                # restore the MISSION north-star
+    s.open_report = getattr(ts, "open_report", "")                        # restore the OPEN USER REPORT blocker
+    s.world = dict(getattr(ts, "world", {}))                              # restore the WORLD MODEL
+    s.active_files = list(ts.active_files)
+    s.edited_files = set(ts.edited_files)
+    s.edit_anchor = dict(ts.edit_anchor)
+    s.last_error = ts.last_error
+    s.since_edit = 0                 # resume = fresh action epoch (don't fire render_convergence)
+    return s

sliceagent/telemetry.py

@@ -0,0 +1,59 @@
+"""Reconstruction-quality telemetry — measures whether the slice KEEPS what the model needs, so the
+slice's central bet becomes a NUMBER instead of an anecdote.
+
+A pure OBSERVER sink: it consumes the loop's events and accumulates counters. It emits no events and
+mutates no slice — completely off the moat. Deterministic, bounded, zero LLM. Wire it into a
+dispatcher alongside slice_sink (the eval harness does this) and read `.summary()` after the run.
+
+Signals:
+  - re_reads : a read_file on a path ALREADY read within the last `window` steps. Within a turn the prior
+    read is still in the accumulated transcript, so a re-read signals the model isn't using its resident
+    context; across turns it's the reconstruction-MISS signal (the seed/seal didn't carry what it needed).
+  - recalls  : recall_history calls — recovery from the cold cache (the model knew it forgot).
+  - reads    : total successful read_file calls (the denominator for a re-read RATE).
+"""
+from __future__ import annotations
+
+from .events import Event, StepEnd, ToolResult
+
+RE_READ_WINDOW = 6          # a path re-read within this many steps counts as a likely reconstruction miss
+_MAX_TRACKED = 256          # bound the per-path last-seen map (never a transcript)
+
+
+class Telemetry:
+    """Callable event sink that counts reconstruction-cost signals. Read `.summary()` after a run."""
+
+    def __init__(self, window: int = RE_READ_WINDOW):
+        self.window = window
+        self.step = 0
+        self.reads = 0
+        self.re_reads = 0
+        self.recalls = 0
+        self._last_read: dict[str, int] = {}   # path -> step it was last read (bounded)
+
+    def __call__(self, e: Event) -> None:
+        if isinstance(e, StepEnd):
+            self.step += 1
+        elif isinstance(e, ToolResult) and not e.failing:
+            if e.name == "read_file":
+                self.reads += 1
+                path = (e.args or {}).get("path")
+                if path:
+                    last = self._last_read.get(path)
+                    if last is not None and (self.step - last) <= self.window:
+                        self.re_reads += 1          # read again soon after — slice didn't carry it
+                    self._last_read[path] = self.step
+                    if len(self._last_read) > _MAX_TRACKED:   # bound: drop the oldest entry
+                        del self._last_read[min(self._last_read, key=self._last_read.get)]
+            elif e.name == "recall_history":
+                self.recalls += 1
+
+    def summary(self) -> dict:
+        rate = round(self.re_reads / self.reads, 3) if self.reads else 0.0
+        return {"reads": self.reads, "re_reads": self.re_reads,
+                "re_read_rate": rate, "recalls": self.recalls}
+
+
+def make_telemetry_sink() -> Telemetry:
+    """A Telemetry instance IS the sink (it's callable) AND carries the counters to read afterward."""
+    return Telemetry()

sliceagent/terminal.py

@@ -0,0 +1,240 @@
+"""terminal — persistent interactive PTY sessions (the other half of the live-process gap).
+
+``Sandbox.run`` is one-shot and has no stdin, so a whole class of work is impossible: driving a
+REPL or text game through successive prompts, navigating a TUI, sending keys into vim, or just
+holding shell + env state (``cd``, ``export``, venv activation) across many tool calls. A
+``PtySession`` allocates a real pseudo-terminal (stdlib ``pty``), launches a shell (or any program)
+attached to it, and keeps it alive in a registry keyed by name so the agent can ``send`` keys,
+``read`` the live output, ``wait`` for an expected pattern (the "expect" primitive that makes
+interaction reliable), then ``close``.
+
+stdlib only — ``pty`` + ``select`` + ``fcntl`` (``pexpect`` isn't a dependency). The master fd is
+non-blocking; reads drain whatever the program has emitted (the output STREAM — not a rendered
+screen-buffer, so full-curses TUIs show raw escape codes, but REPLs / games / line tools read
+cleanly). Children run in their own process group so ``close`` takes down the whole tree.
+"""
+from __future__ import annotations
+
+import codecs
+import fcntl
+import os
+import pty
+import re
+import select
+import signal
+import subprocess
+import time
+
+from .sandbox import _scrub_env
+
+_READ_CHUNK = 65536
+_BUF_CAP = 200_000  # keep the tail of a chatty session bounded
+
+
+class _Session:
+    __slots__ = ("name", "cmd", "master", "popen", "buf", "_decoder")
+
+    def __init__(self, name, cmd, master, popen):
+        self.name = name
+        self.cmd = cmd
+        self.master = master
+        self.popen = popen
+        self.buf = ""  # output accumulated since the last read/wait returned it
+        # STATEFUL utf-8 decoder: a multibyte char split across two os.read() boundaries must not decode to
+        # U+FFFD on both halves — the decoder holds the partial sequence until its continuation bytes arrive.
+        self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+
+
+class SessionManager:
+    """Registry of live interactive PTY sessions. Single-threaded (the agent loop is)."""
+
+    def __init__(self, *, scrub_secrets: bool = True):
+        self.scrub_secrets = scrub_secrets
+        self._s: dict[str, _Session] = {}
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+    def open(self, name: str, *, cwd: str, command: str | None = None) -> str:
+        if name in self._s:
+            raise ValueError(f"session {name!r} is already open (close it first, or use another name)")
+        master, slave = pty.openpty()
+        env = _scrub_env() if self.scrub_secrets else dict(os.environ)
+        env["PYTHONUNBUFFERED"] = "1"
+        env.setdefault("TERM", "xterm")
+        try:
+            try:
+                popen = self._spawn_pty(command, cwd, env, slave)
+            finally:
+                os.close(slave)                   # parent keeps only the master end
+        except BaseException:
+            os.close(master)                      # #19: Popen failed — don't leak the master fd too
+            raise
+        try:   # a fcntl failure AFTER spawn must tear down both the master fd AND the orphaned child (#19)
+            flags = fcntl.fcntl(master, fcntl.F_GETFL)
+            fcntl.fcntl(master, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+        except BaseException:
+            try:
+                os.killpg(os.getpgid(popen.pid), signal.SIGKILL)
+            except Exception:  # noqa: BLE001
+                pass
+            os.close(master)
+            raise
+        self._s[name] = _Session(name, command or "(shell)", master, popen)
+        return name
+
+    def _spawn_pty(self, command, cwd, env, slave):
+        """Launch the PTY-attached process. OVERRIDABLE SEAM: a container variant relaunches the same
+        command through `docker exec -it` so the session lives INSIDE the task container (host path here)."""
+        if command:                               # run the given program directly on the PTY
+            return subprocess.Popen(command, shell=True, cwd=cwd, env=env,
+                                    stdin=slave, stdout=slave, stderr=slave,
+                                    start_new_session=True, close_fds=True)
+        shell = os.environ.get("SHELL") or "/bin/bash"   # interactive shell (holds cd/env across turns)
+        return subprocess.Popen([shell], cwd=cwd, env=env,
+                                stdin=slave, stdout=slave, stderr=slave,
+                                start_new_session=True, close_fds=True)
+
+    def send(self, name: str, keys: str, *, enter: bool = True, timeout: float = 30.0) -> str:
+        sess = self._get(name)
+        data = (keys + ("\n" if enter else "")).encode("utf-8", errors="replace")
+        # The master fd is O_NONBLOCK: one os.write may write only PART of a large payload (the rest would be
+        # silently dropped), and a FULL buffer raises BlockingIOError (EAGAIN) — back-pressure, not a dead
+        # session. Loop until every byte is written, waiting for writability on EAGAIN — but under an OVERALL
+        # deadline, so a child that has stopped reading stdin can't wedge the (possibly inline) loop thread
+        # forever. Reserve the "may have exited" error for a genuine OSError.
+        view = memoryview(data)
+        deadline = time.time() + timeout
+        try:
+            while view:
+                try:
+                    view = view[os.write(sess.master, view):]
+                except BlockingIOError:
+                    remaining = deadline - time.time()
+                    if remaining <= 0:
+                        raise ValueError(f"session {name!r} not writable within {timeout:g}s; the program "
+                                         "isn't reading its input (stdin) or its output buffer is full") from None
+                    select.select([], [sess.master], [], min(remaining, 5))   # wait for the PTY to drain, then retry
+        except OSError as e:
+            raise ValueError(f"session {name!r} is not writable ({e}); it may have exited") from None
+        # peek (NON-consuming) so the response is still there for a following read/wait — otherwise
+        # send would eat the very output the model is about to wait for.
+        return self.peek(name, timeout=0.4)
+
+    def read(self, name: str, *, timeout: float = 1.0) -> str:
+        sess = self._get(name)
+        self._drain(sess, hard=timeout)
+        out, sess.buf = sess.buf, ""
+        if not out:
+            return f"(no output; {self._status(sess)})"
+        return out
+
+    def peek(self, name: str, *, timeout: float = 0.6) -> str:
+        """Drain output and return it WITHOUT consuming — so a later read/wait still sees it.
+        Used right after open() so the program's first prompt isn't eaten by the banner read."""
+        sess = self._get(name)
+        self._drain(sess, hard=timeout)
+        return sess.buf or f"(no output yet; {self._status(sess)})"
+
+    def wait(self, name: str, pattern: str, *, timeout: float = 10.0) -> str:
+        """Drain until `pattern` (regex) appears or timeout — the reliable interaction primitive."""
+        sess = self._get(name)
+        # #20: bound the (model-supplied) pattern — cap its length to limit catastrophic-backtracking
+        # surface, and fail clearly on a bad regex instead of crashing the tool. (Python's re has no
+        # match timeout; the haystack is this subprocess's own output, so length-capping is the mitigation.)
+        if len(pattern) > 500:
+            raise ValueError("wait pattern too long (max 500 chars)")
+        try:
+            rx = re.compile(pattern)
+        except re.error as e:
+            raise ValueError(f"invalid wait pattern: {e}")
+        end = time.time() + timeout
+        # inspect already-buffered output at least once BEFORE the timeout loop — so timeout<=0 still polls
+        # (matches a buffered hit instead of false-negativing it and then clearing the buffer below).
+        self._drain(sess, hard=min(0.4, timeout) if timeout > 0 else 0.0)
+        m = rx.search(sess.buf)
+        while m is None and time.time() < end:
+            self._drain(sess, hard=0.4)
+            m = rx.search(sess.buf)
+            if m:
+                break
+            if sess.popen.poll() is not None:   # process died — one last drain, then stop
+                self._drain(sess, hard=0.2)
+                m = rx.search(sess.buf)
+                break
+        if m:                                   # expect semantics: consume up to the match, KEEP the rest
+            cut = m.end()
+            out, sess.buf = sess.buf[:cut], sess.buf[cut:]
+            return f"[{name}: matched; {self._status(sess)}]\n{out}"
+        out, sess.buf = sess.buf, ""            # timeout: return + clear everything seen
+        return f"[{name}: NO match for {pattern!r} before timeout; {self._status(sess)}]\n{out or '(no output)'}"
+
+    def close(self, name: str) -> str:
+        sess = self._get(name)
+        if sess.popen.poll() is None:
+            try:
+                os.killpg(os.getpgid(sess.popen.pid), signal.SIGTERM)
+            except OSError:
+                try:
+                    sess.popen.terminate()
+                except OSError:
+                    pass
+            try:
+                sess.popen.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                try:
+                    os.killpg(os.getpgid(sess.popen.pid), signal.SIGKILL)
+                except OSError:
+                    pass
+                try:
+                    sess.popen.wait(timeout=2)   # reap the SIGKILLed child so it isn't left a zombie at fd close
+                except (subprocess.TimeoutExpired, OSError):
+                    pass
+        try:
+            os.close(sess.master)
+        except OSError:
+            pass
+        self._s.pop(name, None)
+        return f"closed {name}"
+
+    def list(self) -> str:
+        if not self._s:
+            return "(no terminal sessions)"
+        return "\n".join(f"{n}: {self._status(s)} — {s.cmd}" for n, s in self._s.items())
+
+    def cleanup(self) -> None:
+        for n in list(self._s):
+            try:
+                self.close(n)
+            except Exception:  # noqa: BLE001 — best-effort teardown
+                pass
+
+    # ── internals ──────────────────────────────────────────────────────────
+    def _get(self, name: str) -> _Session:
+        s = self._s.get(name)
+        if s is None:
+            raise ValueError(
+                f"unknown session {name!r}. Open: {', '.join(self._s) or '(none)'}")
+        return s
+
+    def _drain(self, sess: _Session, *, hard: float) -> None:
+        """Read everything currently available, stopping on a short idle gap or `hard` cap."""
+        end = time.time() + hard
+        while time.time() < end:
+            r, _, _ = select.select([sess.master], [], [], min(0.15, hard))
+            if not r:
+                break  # no more output right now
+            try:
+                chunk = os.read(sess.master, _READ_CHUNK)
+            except (BlockingIOError, InterruptedError):
+                continue
+            except OSError:
+                break  # master closed / child gone
+            if not chunk:
+                break  # EOF
+            sess.buf += sess._decoder.decode(chunk)   # incremental: holds a partial multibyte tail across reads
+            if len(sess.buf) > _BUF_CAP:
+                sess.buf = "…[earlier output elided]…\n" + sess.buf[-_BUF_CAP:]
+
+    @staticmethod
+    def _status(sess: _Session) -> str:
+        rc = sess.popen.poll()
+        return "alive" if rc is None else f"exited {rc}"

sliceagent/text_utils.py

@@ -0,0 +1,56 @@
+"""Tiny shared text helpers — ONE home for the whitespace/timestamp normalizers that were copy-pasted
+across regions.py, skills.py, pagetable.py and hippocampus.py. Leaf module (no intra-package imports) so
+any module can use it without an import cycle. Behavior is byte-identical to the expressions it replaces.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+
+_WS = re.compile(r"\s+")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def normalize_ws(s) -> str:
+    """Collapse all runs of whitespace to a single space and strip. `None`/non-str -> ''."""
+    return _WS.sub(" ", str(s or "")).strip()
+
+
+def one_line(s, n: int = 80) -> str:
+    """`normalize_ws` truncated to `n` chars — a one-line, bounded rendering of arbitrary text."""
+    return normalize_ws(s)[:n]
+
+
+def format_ts(ts) -> str:
+    """ISO timestamp -> compact 'MM-DD HH:MM' (e.g. '06-16 12:30'); '' for empty/None."""
+    return (ts or "")[5:16].replace("T", " ")
+
+
+# Pure social/greeting messages that never imply work. The host answers these on a CHEAP path — no slice,
+# no tool schemas, a tiny prompt — so a "hi" or "thanks" doesn't pay the full per-turn token cost.
+_CHITCHAT = frozenset({
+    "hi", "hii", "hiya", "hello", "hey", "heya", "hey there", "hi there", "hello there", "yo", "sup",
+    "howdy", "good morning", "good afternoon", "good evening", "morning", "evening", "gm",
+    "how are you", "how are you?", "how's it going", "hows it going", "what's up", "whats up", "how's things",
+    "thanks", "thank you", "thanks!", "thank you!", "thx", "ty", "tysm", "cheers", "much appreciated",
+    "appreciate it", "thanks a lot", "thank you so much",
+    "ok", "okay", "k", "kk", "cool", "nice", "great", "awesome", "perfect", "got it", "sounds good",
+    "great thanks", "ok thanks", "okay thanks", "nice thanks", "perfect thanks",
+    "bye", "goodbye", "see you", "see ya", "later", "good night", "gn", "night",
+    "lol", "haha", "nice one", "well done", "good job", "good bot", "gg",
+})
+
+# Minimal system prompt for the chitchat fast-path — keep it tiny; the whole point is to spend few tokens.
+CHITCHAT_PROMPT = ("You are sliceagent, a coding agent. The user sent a brief greeting or social message. "
+                   "Reply in ONE short, warm line. Do not call tools, summarize, or start any work.")
+
+
+def is_chitchat(text) -> bool:
+    """True ONLY for a pure greeting/social message (high precision — never fires on a real request). The
+    whole message must match a known social phrase after trimming punctuation; a length cap guards against
+    anything substantive ('hi, can you fix X' is not chitchat)."""
+    t = str(text or "").strip().lower().rstrip("!.?,~ ")
+    return 0 < len(t) <= 40 and t in _CHITCHAT