chad-code 0.1.0__py3-none-any.whl

chad/session.py

@@ -0,0 +1,281 @@
+"""Conversation persistence so a session survives across runs (`cli.py --continue`,
+`--resume`, and the TUI `/resume` picker).
+
+Native Claude Code records every conversation, can list them, and can fork one; this is
+the local analogue, scoped per project directory (you almost always want to continue the
+work for *this* repo). Only the message list is persisted as JSON — NOT the KV cache: the
+next turn re-prefills the restored transcript (the system-prefix warm cache still
+applies), which is the price of a cold resume. Best-effort throughout: a failure to save
+or load never breaks a turn.
+
+Layout (plan 043):
+
+    ~/.chad/sessions/<cwdhash>/<session_id>.json   one file per session
+    ~/.chad/sessions/<cwdhash>/index.json          title/updated/turns per session
+
+`session_id` = `YYYYMMDD-HHMMSS-<4 hex>`, minted at Agent construction. Each save
+overwrites only *its own* session file, so resuming a session (which mints a fresh id and
+seeds the old messages) never rewrites the original — every resume is implicitly a fork.
+A legacy single-slot `~/.chad/sessions/<cwdhash>.json` file is adopted as one session the
+first time the directory is listed. Retention keeps the newest N per cwd, pruned on save.
+"""
+import hashlib
+import json
+import os
+import secrets
+import time
+
+SESS_DIR = os.path.expanduser("~/.chad/sessions")
+RETAIN = 20            # keep the newest N sessions per cwd; prune older on save
+_TITLE_LEN = 60        # first-user-message title truncation for the index / picker
+
+
+def _key(cwd: str) -> str:
+    return hashlib.sha1(os.path.abspath(cwd).encode("utf-8", "ignore")).hexdigest()[:16]
+
+
+def _dir(cwd: str) -> str:
+    """Per-cwd session directory."""
+    return os.path.join(SESS_DIR, _key(cwd))
+
+
+def _legacy_path(cwd: str) -> str:
+    """The pre-043 single-slot file (`<cwdhash>.json`), adopted on first listing."""
+    return os.path.join(SESS_DIR, _key(cwd) + ".json")
+
+
+def _session_path(cwd: str, session_id: str) -> str:
+    return os.path.join(_dir(cwd), session_id + ".json")
+
+
+def _index_path(cwd: str) -> str:
+    return os.path.join(_dir(cwd), "index.json")
+
+
+def new_session_id() -> str:
+    """A fresh session id: sortable timestamp + 4 random hex (collision-safe within a
+    second). Minted at Agent construction; a resume mints a new one → implicit fork."""
+    return time.strftime("%Y%m%d-%H%M%S") + "-" + secrets.token_hex(2)
+
+
+def _atomic_write_json(path: str, obj) -> bool:
+    """Write `obj` as JSON to `path` atomically at 0600. Returns True on success.
+
+    Create 0600 from the start so the conversation store (full tool args and results) is
+    never briefly world-readable; os.replace preserves the mode and is atomic on POSIX —
+    a reader never sees a half-written file."""
+    tmp = path + f".{os.getpid()}.tmp"
+    try:
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            json.dump(obj, f)
+        os.replace(tmp, path)
+        return True
+    except OSError:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+        return False
+
+
+def _load_path(path: str):
+    """Return a saved {cwd, updated, meta, messages, session_id} dict, or None."""
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path) as f:
+            data = json.load(f)
+        if isinstance(data, dict) and isinstance(data.get("messages"), list):
+            return data
+    except (OSError, json.JSONDecodeError, ValueError):
+        pass
+    return None
+
+
+def _first_user_title(messages: list, limit: int = _TITLE_LEN) -> str:
+    """The first user message, whitespace-collapsed and truncated — the session title."""
+    for m in messages:
+        if m.get("role") == "user":
+            c = m.get("content")
+            if isinstance(c, str) and c.strip():
+                t = " ".join(c.split())
+                return t[:limit] + ("…" if len(t) > limit else "")
+    return ""
+
+
+def _turns(messages: list) -> int:
+    return sum(1 for m in messages if m.get("role") == "user")
+
+
+# -- index (avoids parsing every session file just to list them) -------------
+
+def _load_index(cwd: str) -> dict:
+    """The per-cwd index, or an empty one if missing/corrupt (corrupt is tolerated —
+    `list_sessions` rebuilds it from the session files on disk)."""
+    try:
+        with open(_index_path(cwd)) as f:
+            data = json.load(f)
+        if isinstance(data, dict) and isinstance(data.get("sessions"), dict):
+            return data
+    except (OSError, json.JSONDecodeError, ValueError):
+        pass
+    return {"sessions": {}}
+
+
+def _write_index(cwd: str, sessions: dict) -> None:
+    _atomic_write_json(_index_path(cwd), {"sessions": sessions})
+
+
+def _update_index(cwd: str, session_id: str, messages: list, updated: float) -> None:
+    idx = _load_index(cwd)
+    idx["sessions"][session_id] = {
+        "title": _first_user_title(messages),
+        "updated": updated,
+        "turns": _turns(messages),
+    }
+    _write_index(cwd, idx["sessions"])
+
+
+def _adopt_legacy(cwd: str) -> None:
+    """Migrate a pre-043 `<cwdhash>.json` file into the sessioned store as one session,
+    then remove it so it is adopted exactly once. Best-effort."""
+    legacy = _legacy_path(cwd)
+    if not os.path.isfile(legacy):
+        return
+    try:
+        data = _load_path(legacy)
+        os.makedirs(_dir(cwd), exist_ok=True)
+        if data:
+            updated = data.get("updated") or time.time()
+            # Derive a stable id from the legacy file's own timestamp so re-listing is
+            # idempotent even if the write below races; -0000 marks the adopted slot.
+            sid = time.strftime("%Y%m%d-%H%M%S", time.localtime(updated)) + "-0000"
+            target = _session_path(cwd, sid)
+            if not os.path.exists(target):
+                _atomic_write_json(target, {
+                    "cwd": data.get("cwd", os.path.abspath(cwd)),
+                    "session_id": sid,
+                    "updated": updated,
+                    "meta": data.get("meta", {}),
+                    "messages": data["messages"],
+                })
+                _update_index(cwd, sid, data["messages"], updated)
+        os.remove(legacy)
+    except OSError:
+        pass
+
+
+def list_sessions(cwd: str, limit: int = None) -> list:
+    """Sessions for `cwd`, newest first: `[{session_id, title, updated, turns}, ...]`.
+
+    Adopts a legacy file first, then reconciles the index against the files actually on
+    disk — so a corrupt/lost index is rebuilt and orphaned index rows are dropped. Cheap:
+    the common path reads only the index."""
+    _adopt_legacy(cwd)
+    sessions = _load_index(cwd)["sessions"]
+    try:
+        names = os.listdir(_dir(cwd))
+    except OSError:
+        names = []
+    on_disk = set()
+    changed = False
+    for name in names:
+        if name == "index.json" or not name.endswith(".json") or name.endswith(".tmp"):
+            continue
+        sid = name[: -len(".json")]
+        on_disk.add(sid)
+        if sid not in sessions:  # file present but unindexed (corrupt index / crash)
+            data = _load_path(_session_path(cwd, sid))
+            if data:
+                sessions[sid] = {
+                    "title": _first_user_title(data["messages"]),
+                    "updated": data.get("updated", 0),
+                    "turns": _turns(data["messages"]),
+                }
+                changed = True
+    for sid in list(sessions):  # drop rows whose file was pruned/removed
+        if sid not in on_disk:
+            del sessions[sid]
+            changed = True
+    if changed:
+        _write_index(cwd, sessions)
+    items = [{"session_id": sid, **meta} for sid, meta in sessions.items()]
+    items.sort(key=lambda it: it.get("updated", 0), reverse=True)
+    return items[:limit] if limit else items
+
+
+def _prune(cwd: str, keep: int = RETAIN) -> None:
+    """Retention: keep the newest `keep` sessions, remove older files + index rows."""
+    sessions = _load_index(cwd)["sessions"]
+    if len(sessions) <= keep:
+        return
+    ordered = sorted(sessions.items(), key=lambda kv: kv[1].get("updated", 0), reverse=True)
+    for sid, _meta in ordered[keep:]:
+        try:
+            os.remove(_session_path(cwd, sid))
+        except OSError:
+            pass
+        sessions.pop(sid, None)
+    _write_index(cwd, sessions)
+
+
+def save_session(cwd: str, messages: list, meta: dict = None,
+                 session_id: str = None) -> str:
+    """Atomically persist the conversation for `cwd` to its own session file. Mints a
+    `session_id` if none is given. Updates the index and prunes old sessions (best-effort).
+    Returns the session file path, or '' on failure."""
+    try:
+        os.makedirs(_dir(cwd), exist_ok=True)
+        session_id = session_id or new_session_id()
+        updated = time.time()
+        path = _session_path(cwd, session_id)
+        ok = _atomic_write_json(path, {"cwd": os.path.abspath(cwd), "session_id": session_id,
+                                       "updated": updated, "meta": meta or {},
+                                       "messages": messages})
+        if not ok:
+            return ""
+        _update_index(cwd, session_id, messages, updated)
+        _prune(cwd)
+        return path
+    except OSError:
+        return ""
+
+
+def load_session(cwd: str, session_id: str = None):
+    """Return the saved {cwd, updated, meta, messages, session_id} dict. With `session_id`
+    that specific session; without one, the most recent (adopting a legacy file first).
+    None if there is nothing to resume."""
+    if session_id is None:
+        items = list_sessions(cwd, limit=1)
+        if not items:
+            return None
+        session_id = items[0]["session_id"]
+    return _load_path(_session_path(cwd, session_id))
+
+
+def _ago(age_s: int) -> str:
+    if age_s >= 3600:
+        return f"{age_s // 3600}h ago"
+    if age_s >= 60:
+        return f"{age_s // 60}m ago"
+    return "just now"
+
+
+def describe(item: dict) -> str:
+    """One-line label for a `list_sessions` entry (the picker / resume notice):
+    `2h ago · 14 turns · "fix the flaky retry test…"`."""
+    when = _ago(max(0, int(time.time() - item.get("updated", 0))))
+    turns = item.get("turns", 0)
+    title = item.get("title") or "(no title)"
+    return f'{when} · {turns} turn{"s" * (turns != 1)} · "{title}"'
+
+
+def session_summary(cwd: str) -> str:
+    """One-line description of the most recent session for `cwd` (the `-c` resume notice)."""
+    data = load_session(cwd)
+    if not data:
+        return ""
+    users = _turns(data["messages"])
+    when = _ago(max(0, int(time.time() - data.get("updated", 0))))
+    return f"{users} prior user turn{'s' * (users != 1)}, last active {when}"

chad/skills.py

@@ -0,0 +1,407 @@
+"""Agent Skills support (https://agentskills.io) — discovery, parsing, disclosure, activation.
+
+A *skill* is a directory containing a `SKILL.md` file: YAML frontmatter (at minimum
+`name` + `description`) followed by a markdown body of instructions, optionally
+bundling `scripts/`, `references/`, and `assets/`. This module implements the four
+client-side responsibilities from the spec's "adding skills support" guide:
+
+  1. Discover  — scan project- and user-level skill dirs for `SKILL.md` files.
+  2. Parse     — leniently extract frontmatter + body (warn, don't crash, on cosmetic
+                 issues; skip only when there's no usable description / unparseable YAML).
+  3. Disclose  — `catalog_block()` lists name+description+location for the system prompt
+                 (tier 1: ~50-100 tokens/skill, loaded at session start).
+  4. Activate  — `activate(name)` returns the full body wrapped in <skill_content> with a
+                 bundled-resource listing (tier 2: loaded only when the model asks).
+
+Progressive disclosure means the base context stays small: the model sees the catalog
+always, pulls a skill's instructions only when a task matches, and reads bundled
+resources (scripts/refs) on demand via the normal `read` tool.
+
+State (the cwd-keyed registry and the set of already-activated skills) lives at module
+level — same pattern as `tools._TODOS` — and is cleared by `reset_session()` when a new
+Agent / `/reset` starts so activations don't bleed across sessions.
+"""
+
+import os
+
+from .diag import log, warn_footer
+from .ignore import IGNORE_DIRS
+
+# Bound the discovery walk so a pathological tree (a skills dir nested in a huge repo)
+# can't stall startup. Mirrors the spec's "reasonable bounds" guidance.
+_MAX_DEPTH = 4
+_MAX_DIRS = 2000
+# Directories never worth descending into during a skill scan (shared canonical set).
+_SKIP_DIRS = set(IGNORE_DIRS)
+# Cap the bundled-resource listing returned at activation — a large skill dir shouldn't
+# flood the activation result; the model reads specific files on demand anyway.
+_MAX_RESOURCES = 50
+
+
+class Skill:
+    """One discovered skill: the parsed metadata plus where it lives on disk."""
+
+    __slots__ = ("name", "description", "location", "base_dir", "body",
+                 "frontmatter", "warnings")
+
+    def __init__(self, name, description, location, body, frontmatter, warnings):
+        self.name = name
+        self.description = description
+        self.location = location              # absolute path to SKILL.md
+        self.base_dir = os.path.dirname(location)
+        self.body = body                      # markdown after the frontmatter
+        self.frontmatter = frontmatter        # full parsed dict (license/compat/metadata…)
+        self.warnings = warnings              # lenient-validation diagnostics
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+def _split_frontmatter(text: str):
+    """Return (frontmatter_yaml, body) for a `---`-delimited file, or (None, text).
+
+    The opening `---` must be the first line; the closing `---` is the next line that
+    is exactly `---`. Everything between is YAML; everything after, trimmed, is the body.
+    """
+    # Tolerate a leading BOM / blank lines before the first delimiter.
+    stripped = text.lstrip("")
+    lines = stripped.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return None, text
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            fm = "".join(lines[1:i])
+            body = "".join(lines[i + 1:]).strip()
+            return fm, body
+    return None, text  # opened but never closed -> treat as bodyless/invalid
+
+
+def _quote_colon_values(fm: str) -> str:
+    """Best-effort fix for the most common cross-client YAML breakage: an unquoted
+    scalar whose value contains a colon-space (`description: Use when: foo`), which a
+    strict YAML parser rejects. Wrap such top-level values in double quotes and retry.
+    Only touches obvious `key: value` lines; leaves nested/structured YAML alone."""
+    out = []
+    for ln in fm.splitlines():
+        stripped = ln.strip()
+        # key at column 0 (no indent), value present, value contains a colon-space,
+        # and isn't already quoted / a block scalar / a mapping opener.
+        if (ln[:1] not in (" ", "\t", "#", "")
+                and ":" in stripped):
+            key, _, val = ln.partition(":")
+            val_s = val.strip()
+            if (val_s and ": " in val_s
+                    and val_s[0] not in ("'", '"', "|", ">", "[", "{")):
+                esc = val_s.replace("\\", "\\\\").replace('"', '\\"')
+                out.append(f'{key}: "{esc}"')
+                continue
+        out.append(ln)
+    return "\n".join(out)
+
+
+def parse_skill_text(text: str, location: str):
+    """Parse one SKILL.md's text. Returns (Skill, None) on success or (None, reason) when
+    the skill must be skipped (no usable description, or unparseable YAML). Lenient: a bad
+    `name` is repaired/derived and recorded as a warning rather than rejected."""
+    import yaml
+
+    fm_text, body = _split_frontmatter(text)
+    if fm_text is None:
+        return None, "no YAML frontmatter (missing or unterminated `---` block)"
+    try:
+        meta = yaml.safe_load(fm_text)
+    except yaml.YAMLError:
+        try:
+            meta = yaml.safe_load(_quote_colon_values(fm_text))
+        except yaml.YAMLError as e:
+            return None, f"unparseable YAML frontmatter: {e}"
+    if not isinstance(meta, dict):
+        return None, "frontmatter is not a key-value mapping"
+
+    warnings = []
+    desc = meta.get("description")
+    desc = desc.strip() if isinstance(desc, str) else ""
+    if not desc:
+        # A description is essential for disclosure — without it the model can never
+        # know when to activate the skill. Skip (the one hard failure besides bad YAML).
+        return None, "missing or empty `description`"
+    if len(desc) > 1024:
+        warnings.append(f"description exceeds 1024 chars ({len(desc)})")
+
+    dir_name = os.path.basename(os.path.dirname(location))
+    name = meta.get("name")
+    name = name.strip() if isinstance(name, str) else ""
+    if not name:
+        name = dir_name
+        warnings.append("missing `name`; using parent directory name")
+    if name != dir_name:
+        warnings.append(f"name {name!r} does not match directory {dir_name!r}")
+    if len(name) > 64:
+        warnings.append(f"name exceeds 64 chars ({len(name)})")
+
+    return Skill(name, desc, location, body, meta, warnings), None
+
+
+def parse_skill_file(location: str):
+    """Read and parse a SKILL.md at `location`. Returns (Skill, None) or (None, reason)."""
+    try:
+        with open(location, "r", errors="replace") as f:
+            text = f.read()
+    except OSError as e:
+        return None, f"cannot read: {e}"
+    return parse_skill_text(text, os.path.abspath(location))
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+def _scope_roots(cwd: str, home: str):
+    """The directories to scan, lowest precedence first. Project-level skills override
+    user-level ones (the universal convention), so projects come last and win on merge.
+    Both the cross-client `.agents/skills` convention and the pragmatic `.claude/skills`
+    location are scanned at each level."""
+    return [
+        ("user", os.path.join(home, ".claude", "skills")),
+        ("user", os.path.join(home, ".agents", "skills")),
+        ("project", os.path.join(cwd, ".claude", "skills")),
+        ("project", os.path.join(cwd, ".agents", "skills")),
+    ]
+
+
+def _find_skill_dirs(root: str):
+    """Yield directories under `root` that directly contain a `SKILL.md`, bounded by
+    depth and a total-dir cap so a huge tree can't stall the scan."""
+    if not os.path.isdir(root):
+        return
+    seen = 0
+    root_depth = root.rstrip(os.sep).count(os.sep)
+    for dirpath, dirnames, filenames in os.walk(root):
+        seen += 1
+        if seen > _MAX_DIRS:
+            log.warning("skills: hit %d-dir scan cap under %s; some skills may be missed",
+                        _MAX_DIRS, root)
+            return
+        depth = dirpath.rstrip(os.sep).count(os.sep) - root_depth
+        if depth >= _MAX_DEPTH:
+            dirnames[:] = []
+        # prune noise dirs in-place so os.walk doesn't descend into them
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        if "SKILL.md" in filenames:
+            yield os.path.join(dirpath, "SKILL.md")
+
+
+def discover(cwd: str = None, home: str = None):
+    """Scan all scopes and return (skills_by_name, order, warnings).
+
+    `skills_by_name` maps name -> Skill with project-over-user precedence applied;
+    `order` is the de-duplicated catalog order (stable: discovery order); `warnings`
+    collects per-skill diagnostics plus shadow/collision notes for surfacing in /skills.
+    """
+    cwd = cwd or os.getcwd()
+    home = home or os.path.expanduser("~")
+    by_name = {}
+    order = []
+    warnings = []
+    for scope, root in _scope_roots(cwd, home):
+        for location in sorted(_find_skill_dirs(root)):
+            skill, reason = parse_skill_file(location)
+            if skill is None:
+                log.warning("skills: skipping %s — %s", location, reason)
+                warnings.append(f"{location}: skipped ({reason})")
+                continue
+            for w in skill.warnings:
+                warnings.append(f"{skill.name}: {w}")
+            if skill.name in by_name:
+                prev = by_name[skill.name]
+                # Same name seen again. Project beats user; otherwise first-found wins.
+                prev_scope = "project" if _is_project(prev.location, cwd) else "user"
+                if scope == "project" and prev_scope == "user":
+                    warnings.append(
+                        f"{skill.name}: project skill shadows user skill at {prev.location}")
+                    by_name[skill.name] = skill  # replace in place; keep catalog position
+                    log.info("skills: %s (project) overrides user copy", skill.name)
+                else:
+                    warnings.append(
+                        f"{skill.name}: duplicate at {location} shadowed by {prev.location}")
+                    log.info("skills: %s duplicate at %s ignored", skill.name, location)
+                continue
+            by_name[skill.name] = skill
+            order.append(skill.name)
+    return by_name, order, warnings
+
+
+def _is_project(location: str, cwd: str) -> bool:
+    cwd_abs = os.path.abspath(cwd)
+    return os.path.abspath(location).startswith(cwd_abs + os.sep)
+
+
+# ---------------------------------------------------------------------------
+# Registry (cwd-cached) + session activation state
+# ---------------------------------------------------------------------------
+
+class _Registry:
+    def __init__(self, cwd):
+        self.cwd = cwd
+        self.by_name, self.order, self.warnings = discover(cwd)
+
+
+_registry = None      # cached _Registry for the current cwd
+_activated = set()    # names activated this session (for dedupe)
+
+
+def get_registry() -> "_Registry":
+    """The skill registry for the current cwd, discovered once and cached. Rebuilt
+    automatically if the working directory changed since the last call."""
+    global _registry
+    cwd = os.getcwd()
+    if _registry is None or _registry.cwd != cwd:
+        _registry = _Registry(cwd)
+        if _registry.order:
+            log.info("skills: discovered %d skill(s): %s",
+                     len(_registry.order), ", ".join(_registry.order))
+    return _registry
+
+
+def reset_session():
+    """Clear per-session state (activations) and force re-discovery. Called when a new
+    Agent / `/reset` starts so a prior session's activated skills don't leak forward."""
+    global _registry, _activated
+    _registry = None
+    _activated = set()
+
+
+def skill_names():
+    """Names of all available skills (used to constrain the activate_skill tool enum)."""
+    return list(get_registry().order)
+
+
+def has_skills() -> bool:
+    return bool(get_registry().order)
+
+
+# ---------------------------------------------------------------------------
+# Disclosure (tier 1) + activation (tier 2)
+# ---------------------------------------------------------------------------
+
+_CATALOG_INSTRUCTIONS = (
+    "# Skills\n"
+    "The following skills provide specialized instructions for specific tasks. Each "
+    "lists what it does and when to use it. When a task matches a skill's description, "
+    "call the `activate_skill` tool with the skill's `name` to load its full "
+    "instructions BEFORE proceeding — do not guess the procedure from the name alone. "
+    "A skill's instructions may reference bundled files (scripts/, references/, "
+    "assets/); read those on demand with the `read` tool, resolving relative paths "
+    "against the skill directory reported when you activate it.\n"
+)
+
+
+def catalog_block(cwd: str = None) -> str:
+    """The tier-1 skills section for the system prompt: behavioral instructions plus a
+    compact <available_skills> catalog (name + description + location). Returns "" when
+    no skills are installed, so an empty block never confuses the model."""
+    reg = get_registry() if cwd is None else _Registry(cwd)
+    if not reg.order:
+        return ""
+    lines = ["\n\n" + _CATALOG_INSTRUCTIONS, "<available_skills>"]
+    for name in reg.order:
+        s = reg.by_name[name]
+        lines.append("  <skill>")
+        lines.append(f"    <name>{name}</name>")
+        lines.append(f"    <description>{_one_line(s.description)}</description>")
+        lines.append(f"    <location>{s.location}</location>")
+        lines.append("  </skill>")
+    lines.append("</available_skills>")
+    return "\n".join(lines)
+
+
+def _one_line(text: str) -> str:
+    """Collapse whitespace so a multi-line description stays on one catalog line."""
+    return " ".join(text.split())
+
+
+def _list_resources(base_dir: str, skill_md: str):
+    """Relative paths of bundled files in the skill dir (excluding SKILL.md itself),
+    capped. These are surfaced to the model but NOT read — it loads them on demand."""
+    files = []
+    truncated = False
+    for dirpath, dirnames, filenames in os.walk(base_dir):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        for fn in sorted(filenames):
+            full = os.path.join(dirpath, fn)
+            if os.path.abspath(full) == os.path.abspath(skill_md):
+                continue
+            rel = os.path.relpath(full, base_dir)
+            files.append(rel)
+            if len(files) >= _MAX_RESOURCES:
+                truncated = True
+                break
+        if truncated:
+            break
+    return sorted(files), truncated
+
+
+def activate(name: str) -> str:
+    """Tier-2 activation: return the named skill's instructions wrapped in identifying
+    tags, with its directory and a bundled-resource listing. Frontmatter is stripped
+    (the body is the actionable part). Already-activated skills return a short note
+    instead of re-injecting the same instructions."""
+    reg = get_registry()
+    skill = reg.by_name.get(name)
+    if skill is None:
+        avail = ", ".join(reg.order) or "none installed"
+        return (f"[no skill named {name!r}. Available skills: {avail}. "
+                f"Call activate_skill with one of those exact names.]")
+    if name in _activated:
+        return (f"[skill '{name}' is already active earlier in this conversation — its "
+                f"instructions are still in effect; no need to re-activate.]")
+    _activated.add(name)
+    log.info("skills: activated %s (%s)", name, skill.location)
+
+    resources, truncated = _list_resources(skill.base_dir, skill.location)
+    parts = [f'<skill_content name="{name}">', skill.body, "",
+             f"Skill directory: {skill.base_dir}",
+             "Relative paths in this skill are relative to the skill directory; pass "
+             "absolute paths to tools."]
+    if resources:
+        parts.append("<skill_resources>")
+        parts += [f"  <file>{r}</file>" for r in resources]
+        if truncated:
+            parts.append(f"  <note>listing capped at {_MAX_RESOURCES} files; more exist</note>")
+        parts.append("</skill_resources>")
+    parts.append("</skill_content>")
+    return "\n".join(parts)
+
+
+# Marker that identifies an activated-skill tool result, so context compaction can
+# protect it from truncation/dropping (skill instructions are durable behavioral
+# guidance — silently losing them mid-session degrades the agent with no error).
+SKILL_CONTENT_MARKER = "<skill_content "
+
+
+def is_skill_message(msg: dict) -> bool:
+    """True if a conversation message carries activated skill instructions."""
+    return (msg.get("role") == "tool"
+            and (msg.get("name") == "activate_skill"
+                 or SKILL_CONTENT_MARKER in msg.get("content", "")))
+
+
+def summary_lines():
+    """Human-readable lines for the `/skills` command: one row per skill (name, an
+    `*active*` marker if already loaded, and a trimmed description), plus a footer of
+    any discovery warnings. Empty list message when no skills are installed."""
+    reg = get_registry()
+    if not reg.order:
+        return ["no skills installed. Add a SKILL.md under .agents/skills/ (project) or "
+                "~/.agents/skills/ (user). See https://agentskills.io"]
+    out = []
+    for name in reg.order:
+        s = reg.by_name[name]
+        desc = _one_line(s.description)
+        if len(desc) > 100:
+            desc = desc[:97] + "…"
+        active = " *active*" if name in _activated else ""
+        out.append(f"{name}{active} — {desc}")
+    out += warn_footer(reg.warnings)
+    return out