sliceagent 0.1.0__py3-none-any.whl

sliceagent/session.py

@@ -0,0 +1,222 @@
+"""Session — host-side topic manager (MEMORY-SPEC step 3, mechanical core).
+
+Holds one bounded Slice per topic; switching PARKS the current and activates another. Within a
+session, parked topic-slices stay in memory (lossless — switching back returns the same Slice);
+a durable checkpoint is ALSO written on park when the memory is durable, so a topic can be resumed
+in a future session (distilled from the vault, files re-read live). A topic not in the live set is
+resumed via memory.load_task.
+
+This is the host layer — it never touches the loop/slice core. The remaining half of step 3 (the
+model-facing new_topic/switch_topic TOOLS and the OTHER OPEN THREADS render tier) layers on top of
+this. NullMemory works fine: the in-memory topic dict gives full within-session switching; only
+cross-session resume needs a durable vault.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import uuid
+
+from .interfaces import TaskRef
+from .pfc import Slice
+from .regions import capture_user_report
+from .text_utils import one_line
+from .taskstate import slice_to_task_state, task_state_to_slice
+
+
+def _mint_task_id() -> str:
+    return "t-" + uuid.uuid4().hex[:8]
+
+
+class Session:
+    def __init__(self, memory, session_id: str | None = None):
+        self.memory = memory
+        self.session_id = session_id or ("s-" + uuid.uuid4().hex[:12])
+        self.tasks: dict[str, Slice] = {}     # task_id -> live bounded slice (in-session)
+        self.active_id: str | None = None
+
+    def active(self) -> Slice:
+        return self.tasks[self.active_id]
+
+    def _park(self, status: str = "parked") -> None:
+        """Durably checkpoint the active topic (for cross-session resume); a no-op under NullMemory.
+        The live Slice stays in self.tasks regardless, so within-session switching is lossless."""
+        if self.active_id is None:
+            return
+        if getattr(self.memory, "is_durable", False):
+            self.memory.checkpoint_task(slice_to_task_state(
+                self.tasks[self.active_id], self.active_id,
+                session_id=self.session_id, status=status))
+
+    def new_topic(self, goal: str) -> str:
+        """Park the current topic and start a fresh one. Returns the new task_id."""
+        self._park()
+        tid = _mint_task_id()
+        s = Slice()
+        s.reset(goal)
+        self.tasks[tid] = s
+        self.active_id = tid
+        return tid
+
+    def switch_topic(self, task_id: str) -> Slice:
+        """Park the current topic and activate another — from the live set if present, else resumed
+        from the durable vault (distilled). Raises KeyError if neither has it."""
+        self._park()
+        if task_id not in self.tasks:
+            ts = self.memory.load_task(task_id)
+            if ts is None:
+                raise KeyError(f"unknown topic {task_id}")
+            self.tasks[task_id] = task_state_to_slice(ts)   # cross-session: distilled + since_edit=0
+        self.active_id = task_id
+        return self.tasks[task_id]
+
+    def open_threads(self, *, include_active: bool = False) -> list[TaskRef]:
+        """The OTHER OPEN THREADS source: live topics (parked by default; the active one optional)."""
+        out: list[TaskRef] = []
+        for tid, s in self.tasks.items():
+            if not include_active and tid == self.active_id:
+                continue
+            out.append(TaskRef(task_id=tid, title=one_line(s.goal, 60),
+                               status="active" if tid == self.active_id else "parked"))
+        return out
+
+    def continue_topic(self, message: str, *, resume: bool = False) -> Slice:
+        """Continue the active topic with a NEW directive: set the goal, start a fresh action epoch
+        but KEEP the durable context — findings and the working set — so the follow-up builds on
+        what's already done.
+
+        I3 WS2 — DEMOTE the anti-loop epoch, don't wipe it. Clearing action_log every directive let a
+        completed sub-step re-run with no REPEATED warning (turn 14 ran the same command twice). Instead
+        we mark prior entries non-failing (a NEW directive shouldn't carry a stale failure) but KEEP
+        their counts, so a genuinely-repeated command still trips REPEATED-with-no-progress. since_edit
+        is still cleared (a fresh convergence epoch).
+
+        I3 OPEN USER REPORT — if this follow-up looks like a FAILURE REPORT, capture it as a blocker;
+        it is NOT cleared by continue_topic (a new directive does not mean the user retracted the
+        report — only verifying the fix, or a real topic change, clears it)."""
+        s = self.active()
+        # SEAL the prior loop at this turn boundary: the finished loop was archived on TurnEnd; start the
+        # next loop fresh — CARRY the distilled context (findings + edited change-set + conversation), SEAL
+        # the raw trajectory (recent/step-cache/exploratory reads → recall-on-demand). This is what keeps
+        # per-turn cost flat across a long session (the moat) while within-loop info stays complete.
+        s.seal()
+        if not resume:
+            s.goal = message   # a RESUME cue ("go back to the auth task") must NOT replace the topic's defining goal
+        s.last_error = ""
+        # demote (don't clear): keep counts, drop the failing flag — see WS2 above
+        for sig, a in s.action_log.items():
+            a["failing"] = False
+        s.since_edit = 0
+        s.reviewed = []          # new directive → the history ratchet resets (re-allow fresh lookbacks)
+        capture_user_report(s, message)   # a failure report rides forward as an OPEN USER REPORT blocker
+        return s
+
+
+def route_topic(llm, message: str, session: "Session") -> tuple[str, str]:
+    """Classify a new user message against the session: ('continue'|'new'|'resume', task_id). ONE
+    cheap LLM call, biased to 'continue', safe defaults on any parse failure. No topic is mutated
+    here — the host applies the result — so there are no junk topics. (Provider-agnostic: uses the
+    LLMClient contract.)"""
+    if session.active_id is None:
+        return ("new", "")
+    threads = session.open_threads(include_active=False)
+    parked = "\n".join(f"- {t.task_id}: {t.title}" for t in threads) or "(none)"
+    sys_msg = (
+        "You route a user's new message in a coding session into ONE action. Reply with ONLY a JSON "
+        'object: {"action":"continue|new|resume","task_id":"<a parked id, or empty>"}. '
+        "continue = it continues or refines the ACTIVE task. new = a different, unrelated task. "
+        "resume = it asks to return to one of the PARKED topics (give that topic's id). "
+        "Bias to 'continue' when unsure.")
+    usr = (f"ACTIVE TASK: {session.active().goal or '(none)'}\nPARKED TOPICS:\n{parked}\n"
+           f"NEW MESSAGE: {message}")
+    try:
+        resp = llm.complete([{"role": "system", "content": sys_msg},
+                             {"role": "user", "content": usr}], [])
+        m = re.search(r"\{.*\}", resp.content or "", re.S)
+        d = json.loads(m.group(0)) if m else {}
+        action = d.get("action", "continue")
+        if action == "resume":
+            tid = d.get("task_id", "")
+            return ("resume", tid) if any(t.task_id == tid for t in threads) else ("continue", "")
+        if action in ("new", "continue"):
+            return (action, "")
+    except Exception:
+        pass
+    return ("continue", "")
+
+
+_RESUME_CUES = ("go back", "going back", "back to", "return to", "returning to", "resume",
+                "switch back", "switch to", "revisit", "pick up where", "pick back up")
+
+
+def route_topic_lexical(message: str, session: "Session") -> tuple[str, str]:
+    """Routing WITHOUT an LLM round-trip (the moat-aligned default): the dominant 'continue' case pays
+    nothing, and the host never *guesses* 'new' — a genuinely new task is the agent's call via its own
+    new_topic tool (make_topic_tools), which is recoverable and parks the old topic. The host only acts
+    on an UNAMBIGUOUS resume signal: an explicit parked task_id in the message, or a resume cue
+    ('go back to…') plus a title-keyword match. Everything else → continue. Same signature/return contract
+    as route_topic, so it's a drop-in. See memory route-topic-hidden-llm-call for why this exists."""
+    if session.active_id is None:
+        return ("new", "")
+    threads = session.open_threads(include_active=False)
+    if threads:
+        msg_l = message.lower()
+        for t in threads:                                  # explicit parked id mentioned → resume it
+            if t.task_id.lower() in msg_l:
+                return ("resume", t.task_id)
+        if any(cue in msg_l for cue in _RESUME_CUES):      # resume cue → best title-keyword overlap
+            msg_words = set(re.findall(r"[a-z0-9]+", msg_l))
+            best, score = "", 0
+            for t in threads:
+                kw = {w for w in re.findall(r"[a-z0-9]+", (t.title or "").lower()) if len(w) > 3}
+                overlap = len(kw & msg_words)
+                if overlap > score:
+                    best, score = t.task_id, overlap
+            if best and score >= 1:
+                return ("resume", best)
+    return ("continue", "")
+
+
+def route(llm, message: str, session: "Session") -> tuple[str, str]:
+    """The configured topic router. DEFAULT = lexical (zero LLM round-trips — moat-aligned: a follow-up
+    no longer pays a per-message provider call before the turn even starts). Set AGENT_ROUTER=llm to
+    restore the classifier (tighter automatic 'new'-task detection, at one round-trip per follow-up).
+    Measured (evals/route_accuracy.py): lexical == llm on continue+resume (15/15); they differ only on
+    'new', which lexical defers to the agent's new_topic tool. Single call site for both UI paths."""
+    if os.environ.get("AGENT_ROUTER", "lexical").strip().lower() == "llm":
+        return route_topic(llm, message, session)
+    return route_topic_lexical(message, session)
+
+
+def make_topic_tools(session: "Session"):
+    """Model-facing tools so the agent can route topics itself. Default behaviour is CONTINUE (no
+    call); a switch/new is an explicit, recoverable action. Returns ToolEntry list for the registry."""
+    from .registry import ToolEntry
+
+    def _new(args: dict) -> str:
+        tid = session.new_topic(args["goal"])
+        return f"Started new topic [{tid}]: {one_line(args['goal'], 80)}. Previous topic parked (resumable)."
+
+    def _switch(args: dict) -> str:
+        try:
+            s = session.switch_topic(args["task_id"])
+        except KeyError:
+            return (f"Error: no open topic {args.get('task_id')!r}. Pick a task_id from "
+                    "OTHER OPEN THREADS.")
+        return f"Switched to topic [{args['task_id']}]: {one_line(s.goal, 80)} (its state is restored)."
+
+    new_schema = {"type": "function", "function": {
+        "name": "new_topic",
+        "description": ("Start a NEW, unrelated task as its own topic — parks the current one (you can "
+                        "return to it later via switch_topic). Use ONLY when the request is a different "
+                        "task, not a continuation of the current one."),
+        "parameters": {"type": "object", "properties": {"goal": {"type": "string"}}, "required": ["goal"]}}}
+    switch_schema = {"type": "function", "function": {
+        "name": "switch_topic",
+        "description": ("Resume a PARKED topic listed in OTHER OPEN THREADS — restores its state. Use "
+                        "only to return to earlier work, not to start something new."),
+        "parameters": {"type": "object", "properties": {"task_id": {"type": "string"}},
+                       "required": ["task_id"]}}}
+    return [ToolEntry(name="new_topic", schema=new_schema, handler=_new, source="builtin"),
+            ToolEntry(name="switch_topic", schema=switch_schema, handler=_switch, source="builtin")]

sliceagent/skill_provenance.py

@@ -0,0 +1,71 @@
+"""Skill write-origin provenance (item 13) — distinguishes consolidation-AUTHORED skills
+from user-authored ones, so a future curator prunes ONLY auto skills, never the user's.
+
+A ContextVar carries the write origin, paired with the frontmatter provenance field from
+skill_usage.py. sliceagent has no foreground tool that writes skills today —
+consolidate.render_skill is the ONLY writer — so we mark provenance two ways, belt-and-braces:
+
+  1. A `provenance:` frontmatter field on auto-written SKILL.md (durable, survives a sidecar
+     wipe; readable by the loader and any future curator without a side channel).
+  2. A ContextVar (`set_authoring_origin`) the writer can set, so a future foreground
+     skill-write tool inherits the right default without each call passing a flag.
+
+NO-TRANSCRIPT INVARIANT: provenance is a property of the durable SKILL.md store, never of any
+message history. The ContextVar is process-local control state, not context.
+
+PUBLIC SIGNATURES (pinned):
+    AUTO = "consolidation"
+    USER = "user"
+    set_authoring_origin(origin: str) -> Token
+    reset_authoring_origin(token: Token) -> None
+    current_authoring_origin() -> str          # default USER (a bare write is the user's)
+    frontmatter_line(origin: str) -> str        # "provenance: <origin>"
+    provenance_of(meta: dict) -> str            # read it back from parsed frontmatter
+    is_auto(meta: dict) -> bool                 # only auto skills are curator-prunable
+"""
+from __future__ import annotations
+
+import contextvars
+
+AUTO = "consolidation"
+USER = "user"
+
+_origin: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "skill_authoring_origin", default=USER
+)
+
+
+def set_authoring_origin(origin: str) -> contextvars.Token:
+    """Bind the active skill-authoring origin to the current context. Returns a Token the
+    caller MUST pass to reset_authoring_origin in a finally block."""
+    return _origin.set(origin or USER)
+
+
+def reset_authoring_origin(token: contextvars.Token) -> None:
+    _origin.reset(token)
+
+
+def current_authoring_origin() -> str:
+    """The active authoring origin. Default USER — a bare skill write belongs to the user
+    and must never be auto-pruned. neocortex.py sets AUTO around its render_skill writes."""
+    return _origin.get()
+
+
+def frontmatter_line(origin: str) -> str:
+    """The frontmatter line to embed in an auto-written SKILL.md."""
+    return f"provenance: {origin or USER}"
+
+
+def provenance_of(meta: dict) -> str:
+    """Read provenance back from parsed frontmatter (skills.parse_frontmatter output).
+    Missing field → USER (legacy/user-authored skills predate the field; never prune them)."""
+    if not isinstance(meta, dict):
+        return USER
+    v = (meta.get("provenance") or "").strip().lower()
+    return v or USER
+
+
+def is_auto(meta: dict) -> bool:
+    """True iff this skill was authored by consolidation (curator-prunable). User skills,
+    and any skill missing the field, return False — safe by default."""
+    return provenance_of(meta) == AUTO

sliceagent/skill_usage.py

@@ -0,0 +1,123 @@
+"""Skill usage sidecar (item 13) — per-skill last-used + use-count telemetry in ONE JSON
+file, so neocortex.py can frequency-weight skills the way it already weights pitfalls and
+procedures, and a future curator can prune stale AUTO skills.
+
+Design:
+  - sidecar (`.usage.json`) keyed by skill name, NOT frontmatter — keeps telemetry out of
+    user-authored SKILL.md content (frontmatter carries only provenance, which is durable
+    intent; usage is mutable observability).
+  - atomic write (tempfile + os.replace).
+  - best-effort everywhere: a broken sidecar never breaks a skill load.
+Deliberately omitted: lifecycle states, hub/bundled manifests, archive/restore, file locking
+(sliceagent has no concurrent-process skill writes today — add fcntl only if that changes).
+
+NO-TRANSCRIPT INVARIANT: the sidecar is a durable store; it feeds consolidate's frequency
+weight, never the slice.
+
+PUBLIC SIGNATURES (pinned):
+    usage_path(skills_dir: str) -> str
+    load_usage(skills_dir: str) -> dict[str, dict]
+    bump_use(skills_dir: str, name: str) -> None         # loader calls this on skill load
+    record(skills_dir: str, name: str) -> dict           # one skill's record (defaults backfilled)
+    use_count(skills_dir: str, name: str) -> int         # consolidate frequency weight
+    last_used_at(skills_dir: str, name: str) -> str | None
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+from datetime import datetime, timezone
+
+_USAGE_FILE = ".usage.json"
+_BUMP_LOCK = threading.Lock()   # the skill tool declares no access → concurrent skill() calls run in parallel
+#                                 threads; serialize load→increment→save so an increment isn't lost.
+
+
+def usage_path(skills_dir: str) -> str:
+    return os.path.join(skills_dir, _USAGE_FILE)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _empty_record() -> dict:
+    return {"use_count": 0, "last_used_at": None}
+
+
+def load_usage(skills_dir: str) -> dict:
+    """Read the whole sidecar map. Returns {} on missing/corrupt (never raises)."""
+    path = usage_path(skills_dir)
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return {str(k): v for k, v in data.items() if isinstance(v, dict)}
+
+
+def _save_usage(skills_dir: str, data: dict) -> None:
+    """Atomic write. Best-effort — errors are swallowed (telemetry must never break a load)."""
+    path = usage_path(skills_dir)
+    try:
+        os.makedirs(skills_dir, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(dir=skills_dir, prefix=".usage_", suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, sort_keys=True, ensure_ascii=False)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except Exception:
+        pass
+
+
+def bump_use(skills_dir: str, name: str) -> None:
+    """Increment use_count and stamp last_used_at for `name`. Called by the SkillManager
+    when a skill body is loaded into the slice. Best-effort."""
+    if not name:
+        return
+    try:
+        with _BUMP_LOCK:   # atomic read-modify-write so parallel skill() threads don't lose an increment
+            data = load_usage(skills_dir)
+            rec = data.get(name)
+            if not isinstance(rec, dict):
+                rec = _empty_record()
+            rec["use_count"] = int(rec.get("use_count") or 0) + 1
+            rec["last_used_at"] = _now_iso()
+            data[name] = rec
+            _save_usage(skills_dir, data)
+    except Exception:
+        pass
+
+
+def record(skills_dir: str, name: str) -> dict:
+    """Return `name`'s record with defaults backfilled (never None)."""
+    rec = dict(_empty_record())
+    raw = load_usage(skills_dir).get(name)
+    if isinstance(raw, dict):
+        rec.update({k: raw.get(k, rec[k]) for k in rec})
+        for k, v in raw.items():
+            rec.setdefault(k, v)
+    return rec
+
+
+def use_count(skills_dir: str, name: str) -> int:
+    try:
+        return int(record(skills_dir, name).get("use_count") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def last_used_at(skills_dir: str, name: str) -> str | None:
+    return record(skills_dir, name).get("last_used_at")

sliceagent/skills.py

@@ -0,0 +1,209 @@
+"""Skills — reusable procedure prompt-packs.
+
+A skill is a SKILL.md: frontmatter (name + description required) + a markdown body of
+instructions. Progressive disclosure: the `skill` tool's *description* carries the cheap
+catalog (name + one-line description); calling `skill(name=...)` returns the full body,
+which slice_sink folds into the slice's ACTIVE SKILL tier (slice.add_skill) where it
+PERSISTS across turns — the sliceagent-specific adaptation (no transcript to hold a one-shot
+injection). Skills are instructions the model then follows with its existing tools; they
+are NOT code.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shlex
+from dataclasses import dataclass
+
+from .registry import ToolEntry, ToolText
+from .text_utils import one_line
+
+_MAX_SCAN_DEPTH = 8   # bound skill-root walk depth — defensive vs deep trees
+
+
+def expand_skill_args(body: str, argstr: str) -> str:
+    """Substitute a skill's parameter placeholders: `$ARGUMENTS` → the full
+    arg string, `$1`/`$2`/… → positional tokens (shell-split). A skill with no placeholders is returned
+    unchanged, so existing skills are unaffected."""
+    if "$ARGUMENTS" not in body and not re.search(r"\$\d", body):
+        return body
+    argstr = argstr or ""
+    try:
+        parts = shlex.split(argstr)
+    except ValueError:                      # unbalanced quotes → fall back to whitespace split
+        parts = argstr.split()
+    # ONE regex pass over the original body. The old sequential `replace(f"${i}", tok)` loop was buggy:
+    #   • $10 corrupted (replacing $1 first also matched the "$1" inside "$10")
+    #   • re-expansion (a token containing "$N" got substituted again by a later iteration)
+    #   • unfilled placeholders LEAKED as literal "$N"
+    # \d+ matches the whole index ($10 before $1), and re.sub never re-scans substituted text.
+    def _sub(m: "re.Match") -> str:
+        tok = m.group(0)
+        if tok == "$ARGUMENTS":
+            return argstr
+        idx = int(tok[1:])                  # $N → 1-based positional
+        return parts[idx - 1] if 1 <= idx <= len(parts) else ""   # unfilled → blank (no leak)
+
+    return re.sub(r"\$ARGUMENTS|\$\d+", _sub, body)
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    body: str
+    path: str
+    provenance: str = "user"   # "user" | "consolidation" (item 13); from `provenance:` frontmatter
+    root: str = ""             # the discovery root this skill came from (where its .usage.json lives)
+    when_to_use: str = ""      # from `when-to-use:` frontmatter — shown in the catalog to improve routing
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Minimal '---' fenced frontmatter → (meta, body). No YAML dependency: only simple
+    `key: value` lines are read (enough for name/description/when-to-use)."""
+    if not text.startswith("---"):
+        return {}, text
+    rest = text[3:]
+    end = rest.find("\n---")
+    if end == -1:
+        return {}, text
+    fm, body = rest[:end], rest[end + 4:].lstrip("\n")
+    meta: dict = {}
+    for line in fm.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or ":" not in line:
+            continue
+        k, _, v = line.partition(":")
+        meta[k.strip().lower()] = v.strip().strip('"').strip("'")
+    return meta, body
+
+
+def _default_roots() -> list[str]:
+    # project skills win over user skills (discovery order = first-wins)
+    return [
+        os.path.join(os.getcwd(), ".sliceagent", "skills"),
+        os.path.join(os.path.expanduser("~"), ".sliceagent", "skills"),
+    ]
+
+
+class SkillManager:
+    def __init__(self, roots: list[str] | None = None):
+        self.roots = roots if roots is not None else _default_roots()
+        self._skills: dict[str, Skill] = {}
+        self.discover()
+
+    def discover(self) -> "SkillManager":
+        self._skills = {}
+        for root in self.roots:
+            if not os.path.isdir(root):
+                continue
+            for dp, _dirs, files in os.walk(root):           # followlinks=False → no symlink cycles
+                if dp[len(root):].count(os.sep) > _MAX_SCAN_DEPTH:
+                    _dirs[:] = []                            # bound depth
+                    continue
+                for fn in files:
+                    if fn == "SKILL.md" or (fn.endswith(".md") and dp == root):
+                        self._load(os.path.join(dp, fn), root)
+        return self
+
+    def _load(self, path: str, root: str = "") -> None:
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                text = f.read()
+        except OSError:
+            return
+        meta, body = parse_frontmatter(text)
+        name = (meta.get("name") or "").strip().lower()
+        if not name and os.path.basename(path) != "SKILL.md":
+            name = os.path.splitext(os.path.basename(path))[0].lower()
+        when = (meta.get("when-to-use") or meta.get("when_to_use") or "").strip()
+        desc = (meta.get("description") or when or "").strip()
+        if not name or not body.strip():
+            return
+        prov = (meta.get("provenance") or "user").strip().lower() or "user"
+        self._skills.setdefault(name, Skill(name, desc, body.strip(), path, provenance=prov,
+                                            root=root, when_to_use=when))  # first-wins
+
+    def add(self, name: str, body: str, description: str = "") -> None:
+        """Register an in-memory skill (e.g. contributed by a plugin). First-wins, so a
+        disk skill of the same name takes precedence."""
+        name = (name or "").strip().lower()
+        if name and body and body.strip():
+            self._skills.setdefault(name, Skill(name, description.strip(), body.strip(), "<plugin>"))
+
+    def names(self) -> list[str]:
+        return sorted(self._skills)
+
+    def catalog(self) -> list[tuple[str, str]]:
+        return [(n, self._skills[n].description) for n in self.names()]
+
+    def load(self, name: str) -> str | None:
+        s = self._skills.get((name or "").lower())
+        if s is None:
+            return None
+        self._bump_usage(s)   # item 13: last-used sidecar feeds consolidate's frequency weight
+        return s.body
+
+    def _bump_usage(self, s: "Skill") -> None:
+        """Bump the .usage.json sidecar in the skill's discovery root. Best-effort: a sidecar
+        hiccup, or a plugin/in-memory skill with no root, never breaks the skill load."""
+        if not s.root or not os.path.isdir(s.root):
+            return
+        try:
+            from .skill_usage import bump_use
+            bump_use(s.root, s.name)
+        except Exception:
+            pass
+
+
+def make_skill_tool(manager: SkillManager) -> ToolEntry | None:
+    """A ToolEntry for the `skill` tool — or None when no skills are discovered. The tool
+    description IS the catalog (progressive disclosure); the handler returns the body, which
+    slice_sink folds into the ACTIVE SKILL tier."""
+    cat = manager.catalog()
+    if not cat:
+        return None
+    names = [n for n, _ in cat]
+
+    def _line(n: str, d: str) -> str:                       # show when-to-use to improve routing
+        s = manager._skills.get(n)
+        w = (s.when_to_use if s else "") or ""
+        base = f"- {n}: {one_line(d, 140)}"
+        return base + (f" (when: {one_line(w, 80)})" if w and w != d else "")
+
+    listing = "\n".join(_line(n, d) for n, d in cat)
+    desc = (
+        "Load a SKILL: a reusable procedure whose detailed instructions are added to your "
+        "working context and PERSIST for the rest of the task. Call it BEFORE starting work "
+        "when a task matches one of these skills. Pass `arguments` to fill a parameterized skill "
+        "($ARGUMENTS / $1 $2 in its body). Available skills:\n" + listing
+    )
+    schema = {
+        "type": "function",
+        "function": {
+            "name": "skill", "description": desc,
+            "parameters": {"type": "object",
+                           "properties": {
+                               "name": {"type": "string", "enum": names},
+                               "arguments": {"type": "string", "description": "Optional. Substituted "
+                                             "into the skill's $ARGUMENTS / $1 $2 placeholders."}},
+                           "required": ["name"]},
+        },
+    }
+
+    def handler(args: dict) -> str:
+        body = manager.load(args.get("name", ""))
+        if body is None:
+            # ok=False ⟺ genuine failure → event.failing is True → slice_sink does NOT fold this error
+            # string into the ACTIVE SKILLS tier as a persistent fake skill (it would survive every rebuild).
+            return ToolText(f"Error: no skill named {args.get('name')!r}. Available: {', '.join(names)}", ok=False)
+        # expand $ARGUMENTS / $N placeholders (no-op for skills without them); slice_sink folds the
+        # result into the ACTIVE SKILL tier (persists across turns).
+        return expand_skill_args(body, args.get("arguments") or "")
+
+    return ToolEntry(name="skill", schema=schema, handler=handler,
+                     accesses=lambda _a: [], source="skill")
+
+
+def make_skill_manager(roots: list[str] | None = None) -> SkillManager:
+    return SkillManager(roots)