sliceagent 0.1.0__py3-none-any.whl

sliceagent/hooks.py

@@ -0,0 +1,334 @@
+"""Hooks: the policy seam. The loop calls these; the host supplies them.
+
+This is how policy stays OUT of the moat: the Oracle, permission gate, and token
+budget are all hooks, not hardcoded loop logic.
+
+Hook return conventions (all optional, return None to no-op):
+  before_step(step)                     -> {"block": bool, "reason": str} | None
+  record_step_usage(usage)              -> {"stop_turn": bool} | None
+  after_step(step, usage, stop_reason)  -> {"stop_turn": bool} | None
+  should_continue_after_stop(stop)      -> {"continue": bool} | None
+  authorize_tool(name, args)            -> ToolDecision
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .guardrails import ToolCallGuardrail
+from .guidance import DENIAL_NO_PROMPT, DENIAL_USER
+
+# Commands a wide AGENT_AUTO_APPROVE glob (e.g. "git *") must NEVER silently approve: destructive ops that
+# are not catastrophic (so the policy floor lets them through to ASK) yet discard work/data. These always
+# fall through to a confirmation even when a glob matches. The catastrophic floor is screened too (below).
+_DESTRUCTIVE_AUTO = [
+    re.compile(r"\bgit\b[^\n]*\b(reset|clean|checkout|restore|rebase|filter-branch)\b", re.I),
+    re.compile(r"\bgit\b[^\n]*\bbranch\b[^\n]*\s-D\b", re.I),
+    re.compile(r"\bgit\b[^\n]*\bstash\b[^\n]*\b(drop|clear)\b", re.I),
+    re.compile(r"\bgit\b[^\n]*\bpush\b[^\n]*(--force|--force-with-lease|\s-f\b)", re.I),
+    re.compile(r"\brm\b(?=[^|;&\n]*\s-[a-z]*r)", re.I),     # any recursive rm
+    re.compile(r"\b(shred|mkfs|wipefs)\b", re.I),
+]
+
+
+def _is_destructive_command(name: str, cmd: str) -> bool:
+    """True if `cmd` must never be silently auto-approved — catastrophic OR work-discarding."""
+    from . import policy   # deferred: policy imports hooks, so import here to avoid a cycle at load
+    if policy.no_dangerous_commands(name, {"command": cmd}) is not None:
+        return True
+    return any(p.search(cmd) for p in _DESTRUCTIVE_AUTO)
+
+
+@dataclass
+class ToolDecision:
+    allow: bool
+    reason: str = ""
+    ask: bool = False   # policy abstains to an interactive prompt (resolved by PermissionHook)
+    # Does this block count toward the per-turn STUCK floor (loop.py STUCK_BLOCK_BUDGET)? True for a genuine
+    # SPIN (a repeated failing call, a policy denial the model keeps retrying); FALSE for a harmless dedup
+    # (re-reading the same file → the guard just skips it). So a long, legit exploration that re-reads a file
+    # a few times is NOT killed as "stuck" — only real spinning is.
+    counts_as_stuck: bool = True
+
+
+ALLOW = ToolDecision(True)
+
+
+class Hooks:
+    def before_step(self, step: int):
+        return None
+
+    def record_step_usage(self, usage: dict):
+        return None
+
+    def after_step(self, step: int, usage: dict, stop_reason: str):
+        return None
+
+    def should_continue_after_stop(self, stop_reason: str):
+        return None
+
+    def authorize_tool(self, name: str, args: dict) -> ToolDecision:
+        return ALLOW
+
+    def reset_for_turn(self):
+        """Reset any per-turn state at the start of a user task (fires ONCE per turn,
+        not per step). Used by the guardrail to clear cross-step loop counters so they
+        do not bleed across tasks. No-op by default."""
+        return None
+
+    # --- mutating seams (events can't mutate; these can) ---
+    def prepare_messages(self, messages: list[dict]):
+        """Last chance to transform the model-visible messages before the LLM call
+        (e.g. inject context). Return new messages, or None to leave unchanged."""
+        return None
+
+    def transform_tool_result(self, name: str, args: dict, output: str):
+        """Rewrite a tool result before it enters the slice (e.g. redaction, formatting).
+        Return new output, or None to leave unchanged."""
+        return None
+
+
+class CompositeHooks(Hooks):
+    """Fan a single hook surface out over several hooks (first deny / any stop / any continue)."""
+
+    def __init__(self, *hooks: Hooks):
+        self.hooks = hooks
+
+    def before_step(self, step):
+        for h in self.hooks:
+            r = h.before_step(step)
+            if r and r.get("block"):
+                return r
+        return None
+
+    def record_step_usage(self, usage):
+        # materialize ALL results first — these callbacks have side effects (e.g. BudgetHook.spent +=), so a
+        # generator-fed any() that short-circuits on the first stop_turn would skip trailing hooks' observation.
+        flags = [(h.record_step_usage(usage) or {}).get("stop_turn") for h in self.hooks]
+        return {"stop_turn": True} if any(flags) else None
+
+    def after_step(self, step, usage, stop_reason):
+        flags = [(h.after_step(step, usage, stop_reason) or {}).get("stop_turn") for h in self.hooks]
+        return {"stop_turn": True} if any(flags) else None
+
+    def should_continue_after_stop(self, stop_reason):
+        for h in self.hooks:
+            r = h.should_continue_after_stop(stop_reason)
+            if r and r.get("continue"):
+                return r
+        return None
+
+    def authorize_tool(self, name, args):
+        for h in self.hooks:
+            d = h.authorize_tool(name, args)
+            if not d.allow:
+                return d
+        return ALLOW
+
+    def prepare_messages(self, messages):
+        changed = False
+        for h in self.hooks:
+            r = h.prepare_messages(messages)
+            if r is not None:
+                messages, changed = r, True
+        return messages if changed else None
+
+    def transform_tool_result(self, name, args, output):
+        changed = False
+        for h in self.hooks:
+            r = h.transform_tool_result(name, args, output)
+            if r is not None:
+                output, changed = r, True
+        return output if changed else None
+
+    def reset_for_turn(self):
+        for h in self.hooks:
+            h.reset_for_turn()
+
+
+# --- concrete hooks ---
+
+class OracleHook(Hooks):
+    """Verification gate: when the model declares done, run an oracle (tests/lint).
+    If it fails, record the failure into the slice and force another turn."""
+
+    def __init__(self, oracle, on_feedback):
+        self.oracle = oracle
+        self.on_feedback = on_feedback  # callable(output:str) -> records into the slice
+
+    def should_continue_after_stop(self, stop_reason):
+        if stop_reason != "end_turn":
+            return None
+        try:
+            ok, output = self.oracle.verify()
+        except Exception as e:  # noqa: BLE001 — a verify ERROR must FORCE another turn, never silently pass the done-gate
+            ok, output = False, f"verification could not run: {type(e).__name__}: {e}"
+        if ok:
+            return None
+        self.on_feedback(output)   # also record into the slice (for the NEXT turn's seed / durable cache)
+        # CRITICAL: the failure detail must ride the MESSAGE channel — under the accumulate loop the seed
+        # is built once and never re-rendered mid-turn, so a slice mutation (last_error) is invisible to
+        # THIS turn's retry. Put `output` in `feedback` so the loop appends it as the model's next input.
+        return {"continue": True, "feedback": f"Verification failed — fix this, then finish:\n{output}"}
+
+
+_SELF_CHECK = (
+    "STOP — definition-of-done check (required). Before you finish, verify your work against "
+    "the task's REAL acceptance criteria:\n"
+    "1) List EVERY concrete requirement: start from your STANDING REQUIREMENTS contract if you have one "
+    "(each open '[ ]' item is binding), and ALSO re-read the task for anything not yet recorded — the exact "
+    "output file path(s), required fields/values/format, each distinct sub-task, and any 'do not change X'.\n"
+    "2) For EACH requirement, CONFIRM it against the ACTUAL end-state right now — run a command or read "
+    "the real file (do NOT trust your memory, a note, or a schema-shape check): the required output "
+    "exists at the EXACT path, its contents/values are correct, every sub-task is done, and you changed "
+    "nothing you were told to leave alone. Call requirement_done(...) on each contract item you confirm.\n"
+    "3) If anything is unmet or unverified, fix it and re-check. When a value must match something that "
+    "already exists (a file, a git object, expected output), COPY it exactly — do not retype it.\n"
+    "Finish only when ALL requirements are confirmed against the real end-state. If everything already "
+    "checks out, just say so and finish — do not make changes for their own sake."
+)
+
+
+class SelfCheckHook(Hooks):
+    """GROUNDED definition-of-done gate for AUTONOMOUS runs (no human to catch a premature 'done'). When the
+    model declares done, force a verification round: re-derive the task's real acceptance criteria and
+    CONFIRM each against the actual end-state by RUNNING tools (not asserting). Crucially it accepts 'done'
+    only once the model has actually done verification WORK (a tool step) since the gate fired — a bare
+    re-assertion of 'done' re-fires the gate. Bounded to `max_fires` rounds (env AGENT_SELFCHECK_MAX) so it
+    can never loop. Moat-safe: appends a message (the proven feedback channel) + observes tool activity; the
+    agent does the real work. The no-oracle cousin of OracleHook — the agent self-sources its acceptance
+    check instead of declaring done blind. (Targets the measured premature-stop losses: produced-no-output,
+    incomplete sweeps, symptom-not-root fixes — make it verify before it is allowed to finish.)"""
+
+    def __init__(self, max_fires: int = 3):
+        import os
+        try:
+            self._max = max(1, int(os.environ.get("AGENT_SELFCHECK_MAX") or max_fires))
+        except (TypeError, ValueError):
+            self._max = max(1, max_fires)   # a non-numeric env value must not crash hook construction
+        self._fires = 0
+        self._acted = False   # did the model run a tool since the gate last fired?
+
+    def reset_for_turn(self):
+        self._fires = 0
+        self._acted = False
+
+    def after_step(self, step: int, usage: dict, stop_reason: str):
+        if stop_reason == "tool_use":   # the model actually ran verification/fix tools this round
+            self._acted = True
+        return None
+
+    def should_continue_after_stop(self, stop_reason):
+        if stop_reason != "end_turn":
+            return None
+        if self._fires > 0 and self._acted:
+            return None                  # verified-by-doing after a nudge → honest done, accept
+        if self._fires >= self._max:
+            return None                  # bounded → never loop
+        self._fires += 1
+        self._acted = False
+        return {"continue": True, "feedback": _SELF_CHECK}
+
+
+class PermissionHook(Hooks):
+    """Gate tool execution. `policy(name, args) -> ToolDecision`.
+
+    When a policy returns `ask`, resolve it interactively via `on_ask(name, args, reason)
+    -> 'yes'|'no'|'always'` (the host supplies a TTY prompt). Non-interactive hosts
+    (on_ask=None) deny an `ask` — safe by default.
+
+    'always' memorizes a session approval — but keyed by the CALL, not the bare tool name
+    (rule patterns). Approving one shell command must NOT bless every shell command:
+    run_command/execute_code are remembered by their exact command/code; other tools (already
+    gated by policy) are remembered by name. `auto_approve` pre-seeds fnmatch rules matched
+    against the command (e.g. ["git status*", "ls *"]) so safe read-only commands never prompt."""
+
+    _CMD_TOOLS = ("run_command", "execute_code", "proc_start", "terminal_open", "terminal_send")
+
+    def __init__(self, policy, on_ask=None, auto_approve=None):
+        self.policy = policy
+        self.on_ask = on_ask
+        self._approved: set[str] = set()        # exact approval keys (call patterns, not bare tool names)
+        self._rules: list[str] = list(auto_approve or [])   # pre-seeded fnmatch globs over the command
+
+    @classmethod
+    def _key(cls, name: str, args: dict) -> str:
+        # command-SPECIFIC for the dangerous tools — approving `npm test` must not auto-allow `rm -rf`.
+        if name in cls._CMD_TOOLS:
+            return f"{name}:{(args.get('command') or args.get('code') or args.get('input') or '').strip()}"
+        return name                             # name-level for the rest (policy already gates them)
+
+    def _pre_allowed(self, name: str, args: dict, key: str) -> bool:
+        if key in self._approved:
+            return True
+        cmd = (args.get("command") or args.get("code") or args.get("input") or "").strip()
+        if cmd and self._rules:
+            import fnmatch
+            if any(fnmatch.fnmatch(cmd, rule) for rule in self._rules):
+                # A broad glob must NOT silently green-light a destructive command — fall through to ask.
+                return not _is_destructive_command(name, cmd)
+        return False
+
+    def authorize_tool(self, name, args):
+        d = self.policy(name, args)
+        if not d.ask:
+            return d
+        key = self._key(name, args)
+        if self._pre_allowed(name, args, key):
+            return ALLOW
+        if self.on_ask is None:
+            return ToolDecision(False, DENIAL_NO_PROMPT)
+        verdict = (self.on_ask(name, args, d.reason) or "no").lower()
+        if verdict == "always":
+            self._approved.add(key)             # remember THIS call pattern, not the whole tool
+            return ALLOW
+        return ALLOW if verdict == "yes" else ToolDecision(False, DENIAL_USER)
+
+
+class BudgetHook(Hooks):
+    """Stop the turn once cumulative tokens cross a ceiling."""
+
+    def __init__(self, max_total_tokens: int):
+        self.max = max_total_tokens
+        self.spent = 0
+
+    def reset_for_turn(self):
+        # PER-TURN budget: reset the tally at the start of each user task (run_turn calls this). Without
+        # this, the cap silently became a whole-SESSION budget across the REPL. A true
+        # session-wide cap, if ever wanted, should be a separate named hook — not this one.
+        self.spent = 0
+
+    def record_step_usage(self, usage):
+        self.spent += int(usage.get("prompt_tokens", 0)) + int(usage.get("completion_tokens", 0))
+        return {"stop_turn": True} if self.spent >= self.max else None
+
+
+class GuardrailHook(Hooks):
+    """Cross-step loop guard: block a tool call that repeats an identical failing call,
+    or an idempotent call that keeps making no progress. State is per-turn (cleared by
+    `reset_for_turn`), so counters never bleed across user tasks."""
+
+    def __init__(self, config=None):
+        self.guard = ToolCallGuardrail(config)
+
+    def reset_for_turn(self):
+        self.guard.reset_for_turn()
+
+    def authorize_tool(self, name, args):
+        d = self.guard.before_call(name, args)
+        if not d.block:
+            return ALLOW
+        # Only a HARD spin counts toward STUCK: a repeated FAILING call, or no-edit-progress (failing edits).
+        # A deduped idempotent/result no-progress read is harmless — block (skip) it but DON'T kill the turn,
+        # so a long exploration that re-reads a file isn't falsely flagged as stuck.
+        hard = d.code in ("repeated_exact_failure", "no_edit_progress")
+        return ToolDecision(False, d.message, counts_as_stuck=hard)
+
+    def transform_tool_result(self, name, args, output):
+        # NEVER feed a guardrail/policy BLOCK back into the counters: a blocked call never ran, so counting
+        # its synthetic "Error: blocked by policy:" result as a real failure would advance the failing /
+        # no-edit-progress axes and falsely escalate a harmless soft-block into a hard 'stuck' turn-kill.
+        if isinstance(output, str) and output.startswith("Error: blocked by policy:"):
+            return None
+        self.guard.after_call(name, args, output)
+        return None

sliceagent/interfaces.py

@@ -0,0 +1,144 @@
+"""The contracts the core depends on — never the implementations.
+
+The moat (loop + tiers) talks only to these. Everything commodity (LLM I/O,
+retrieval, tool execution/sandbox, verification) lives behind them and is swappable.
+Policy (Oracle/permissions/budget) is supplied via hooks.py.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    args: dict
+
+
+@dataclass
+class AssistantMessage:
+    content: str | None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    usage: dict | None = None            # {"prompt_tokens": int, "completion_tokens": int}
+    finish_reason: str | None = None     # provider's raw finish reason → normalized by the loop
+
+
+@dataclass
+class Snippet:
+    path: str
+    text: str
+    score: float = 0.0
+
+
+@dataclass
+class PageRef:
+    """A bounded reference to one PAGE the PageTable can surface into the slice — the unified shape
+    every read/retrieval backend (code map, project-notes, cross-session episodes) returns from
+    PageTable.lookup(). Carries RAW text (`preview`); the renderer fences it (wrap_untrusted) so
+    injection-fencing stays at ONE layer. `handle` locates the page (a repo-map marker, a subtree
+    path, a session·turn locator); `untrusted` flags re-injected external content (default True)."""
+    handle: str
+    kind: str
+    preview: str
+    score: float = 0.0
+    untrusted: bool = True
+
+
+@dataclass
+class TaskRef:
+    """A bounded index row for the OTHER OPEN THREADS tier (Step 3)."""
+    task_id: str
+    title: str
+    status: str            # active | parked | done | abandoned
+    updated: str = ""
+
+
+@dataclass
+class TaskState:
+    """Resumable, distilled state for one task = the serializable Slice fields. Stores REFS
+    (file paths + anchors), never file contents — ground truth is re-read from disk on resume.
+    Transient tiers (recent, action_log, active_skills) are intentionally NOT serialized."""
+    task_id: str
+    session_id: str = ""
+    title: str = ""
+    status: str = "active"
+    goal: str = ""
+    findings: list[str] = field(default_factory=list)
+    finding_source: dict[str, str] = field(default_factory=dict)  # finding -> provenance tier (carried; else resume upgrades 'claim'→'tool-note')
+    requirements: list[dict] = field(default_factory=list)  # STANDING REQUIREMENTS contract (carried)
+    plan: list[dict] = field(default_factory=list)          # PLAN / TodoWrite steps + status (carried)
+    mission: str = ""                                       # MISSION north-star objective (carried)
+    open_report: str = ""                                   # OPEN USER REPORT blocker (carried; the "it's broken" push-back must survive resume)
+    world: dict = field(default_factory=dict)               # agent WORLD MODEL (carried; was dropped on resume)
+    active_files: list[str] = field(default_factory=list)
+    edited_files: list[str] = field(default_factory=list)   # list on the wire; a set in the Slice
+    edit_anchor: dict[str, str] = field(default_factory=dict)
+    last_error: str = ""
+    since_edit: int = 0
+    links: list[str] = field(default_factory=list)          # task-graph edges (Step 3)
+    tags: str = ""                                          # comma-joined (matches remember()/_tags)
+    resolution: str = ""
+
+
+@runtime_checkable
+class LLMClient(Protocol):
+    """Provider-agnostic completion + tool-calling. (implemented over an official LLM SDK)
+    May optionally expose `is_retryable(error) -> bool` for the retry policy."""
+    def complete(self, messages: list[dict], tools: list[dict]) -> AssistantMessage: ...
+
+
+@runtime_checkable
+class ToolHost(Protocol):
+    """Executes tools, ideally behind a sandbox. (backed by a container sandbox + MCP tools)"""
+    def schemas(self) -> list[dict]: ...
+    def run(self, name: str, args: dict) -> str: ...
+    def read_text(self, path: str) -> str: ...   # reconstruct the artifacts tier (raises if missing)
+    def accesses(self, name: str, args: dict) -> list: ...  # resource accesses for the scheduler
+
+
+@runtime_checkable
+class Retriever(Protocol):
+    """Code discovery for the RELATED CODE tier (repo search). (build: ripgrep + tree-sitter)"""
+    def retrieve(self, query: str, k: int = 6) -> list[Snippet]: ...
+
+
+@runtime_checkable
+class Memory(Protocol):
+    """Cross-session memory + the durable STATE VAULT (episodic cache, task-state, lessons).
+    Distinct from Retriever (memem indexes a curated vault, NOT source code). `is_durable` is the
+    structural no-op marker: NullMemory sets it False so hosts skip cache/checkpoint wiring (keeps
+    evals deterministic). The full surface is frozen here; implementations land incrementally.
+    NOTE: @runtime_checkable isinstance() verifies method-NAME presence only — not signatures or
+    return types; behavioral fidelity is enforced by the round-trip tests."""
+    is_durable: bool
+    # --- long-term lessons (exists) ---
+    def recall(self, query: str, k: int = 6, paths: list[str] | None = None) -> list[Snippet]: ...
+    def remember(self, content: str, *, title: str = "", scope: str = "default", tags: str = "",
+                 paths: list[str] | None = None) -> None: ...
+    # --- episodic cache (lossless; never recalled into the LLM context) ---
+    def append_episode(self, session_id: str, task_id: str, turn: int, record: dict) -> None: ...
+    # read side: the model's on-demand valve into the cold cache (recall_history tool). Returns
+    # raw line dicts ({v,session_id,task_id,turn,ts,record}); the host renders/bounds them.
+    def read_episodes(self, session_id: str, *, limit: int | None = None) -> list[dict]: ...
+    # cross-session FTS5 discovery over the durable episode index (item 12; additive).
+    # Returns bounded hit dicts; [] when the index is unavailable. Single-session reads use
+    # read_episodes; this is the ACROSS-sessions counterpart.
+    def search_episodes(self, query: str, *, limit: int = 5, exclude_session: str | None = None,
+                        only_session: str | None = None) -> list[dict]: ...
+    # --- task state / resume ---
+    def checkpoint_task(self, task: TaskState) -> None: ...
+    def load_task(self, task_id: str) -> TaskState | None: ...
+    def list_session_tasks(self, session_id: str) -> list[TaskRef]: ...
+    # --- consolidation / retrieval-feedback (declared now; implemented in later steps) ---
+    def mark_used(self, memory_id: str) -> None: ...
+    # llm = the abstract LLMClient contract (llm-agnostic — never a concrete provider type); returns a
+    # stats dict {lessons, skills, skills_rejected, errors} so callers report the truth, not a blind success.
+    def consolidate(self, session_id: str, *, llm=None, mode: str = "deterministic") -> dict: ...
+
+
+@runtime_checkable
+class Oracle(Protocol):
+    """Ground-truth verification independent of retrieval. (backed by the project's test/lint runners)"""
+    def verify(self) -> tuple[bool, str]: ...