loom-code 0.1.1__py3-none-any.whl

loom_code/rules.py

@@ -0,0 +1,267 @@
+"""Project rules file (``AGENTS.md``) — bootstrap + safe rule appending.
+
+loom-code already *reads* a context file (``CLAUDE.md`` / ``AGENTS.md`` /
+``.loom/context.md`` — see :mod:`loom_code.project`) into the system
+prompt every session. This module *writes* to it:
+
+* :func:`init_agents_md` — create a starter ``AGENTS.md`` when the repo
+  has no context file yet (the ``/init-loom`` command).
+* :func:`add_rule` — append a durable rule the user stated in chat into a
+  clearly-delimited **managed block**, with dedup + supersession so the
+  block stays small and contradiction-free (the ``remember_rule`` tool).
+
+The guardrail (matches Claude Code's split): the agent only ever curates
+the **managed block** between the markers; everything the human writes
+*outside* it is never touched. And the block is kept tidy at write-time —
+duplicates are skipped, a superseding rule removes the one it replaces —
+so it doesn't bloat the way an append-only log would.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from loomflow import tool
+from loomflow.tools.registry import Tool
+
+# Same order loom_code.project reads, so the file we WRITE is the file
+# that gets READ back into the prompt.
+_CONTEXT_FILENAMES = ("CLAUDE.md", "AGENTS.md", ".loom/context.md")
+# When no context file exists yet, this is the one we create — the
+# cross-tool open standard (read by loom-code and every AGENTS.md-aware
+# agent), not a loom-only file.
+_DEFAULT_RULES_FILE = "AGENTS.md"
+
+# Markers delimiting the agent-curated block. The human's content lives
+# OUTSIDE these; the agent only edits BETWEEN them.
+BLOCK_START = (
+    "<!-- loom:rules (auto-added from chat — edit or delete freely) -->"
+)
+BLOCK_END = "<!-- /loom:rules -->"
+
+# Soft cap on managed rules: past this we nudge (never auto-drop).
+SOFT_CAP = 50
+
+_STARTER_TEMPLATE = """\
+# AGENTS.md
+
+Instructions for AI coding agents working on this project (loom-code and
+any AGENTS.md-aware tool). This file is read into the agent's context
+each session — keep it concise (aim under ~200 lines).
+
+## Overview
+<what this project is — a line or two>
+
+## Conventions
+- <coding standards, e.g. indentation / naming>
+
+## Commands
+- install: <...>
+- test: <...>
+- lint: <...>
+
+## Rules
+{block_start}
+{block_end}
+"""
+
+
+def detect_rules_file(root: Path | str) -> Path | None:
+    """Return the existing context file (first by priority), or None."""
+    base = Path(root)
+    for name in _CONTEXT_FILENAMES:
+        fp = base / name
+        if fp.is_file():
+            return fp
+    return None
+
+
+def target_rules_file(root: Path | str) -> Path:
+    """The file rules are written to: an existing context file if one is
+    present, else ``AGENTS.md`` at the repo root."""
+    return detect_rules_file(root) or (Path(root) / _DEFAULT_RULES_FILE)
+
+
+def current_rules_text(root: Path | str) -> str:
+    """Full text of the active rules file, or '' if none exists."""
+    fp = detect_rules_file(root)
+    if fp is None:
+        return ""
+    try:
+        return fp.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def project_rules_block(root: Path | str) -> str:
+    """Framed body for the per-turn ``project_rules`` working block.
+
+    The active rules file, re-read FRESH each turn so a mid-session edit
+    applies on the next turn (no restart) — unlike the static
+    startup-baked path. Empty string when there's no rules file."""
+    fp = detect_rules_file(root)
+    if fp is None:
+        return ""
+    try:
+        text = fp.read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+    if not text:
+        return ""
+    return (
+        f"# Project rules ({fp.name})\n"
+        "House rules for this project — conventions, and things to do or "
+        "AVOID. Follow them in everything you do and delegate.\n\n"
+        f"{text}"
+    )
+
+
+def init_agents_md(root: Path | str) -> tuple[Path, bool]:
+    """Create a starter ``AGENTS.md`` if the repo has no context file.
+
+    Returns ``(path, created)`` — ``created=False`` means a context file
+    already existed and was left untouched."""
+    existing = detect_rules_file(root)
+    if existing is not None:
+        return existing, False
+    fp = Path(root) / _DEFAULT_RULES_FILE
+    fp.write_text(
+        _STARTER_TEMPLATE.format(block_start=BLOCK_START, block_end=BLOCK_END),
+        encoding="utf-8",
+    )
+    return fp, True
+
+
+def _normalize(rule: str) -> str:
+    """Compare-key for dedup/supersede: lowercased, whitespace-collapsed,
+    trailing punctuation dropped. Two rules that say the same thing in
+    slightly different wording collapse to the same key."""
+    return " ".join(rule.lower().split()).rstrip(".!").strip()
+
+
+def _ensure_block(text: str) -> str:
+    """Guarantee the managed block markers exist, appending an empty one
+    (under a ## Rules heading) when absent."""
+    if BLOCK_START in text and BLOCK_END in text:
+        return text
+    suffix = "" if text.endswith("\n") or text == "" else "\n"
+    return f"{text}{suffix}\n## Rules\n{BLOCK_START}\n{BLOCK_END}\n"
+
+
+def _read_managed_rules(text: str) -> list[str]:
+    """The ``- `` bullet lines currently inside the managed block."""
+    start = text.find(BLOCK_START)
+    end = text.find(BLOCK_END)
+    if start == -1 or end == -1 or end < start:
+        return []
+    inner = text[start + len(BLOCK_START):end]
+    out: list[str] = []
+    for line in inner.splitlines():
+        s = line.strip()
+        if s.startswith("- "):
+            out.append(s[2:].strip())
+    return out
+
+
+def _write_managed_rules(text: str, rules: list[str]) -> str:
+    """Replace the managed block's body with ``rules`` (preserving
+    everything outside the markers verbatim)."""
+    start = text.find(BLOCK_START)
+    end = text.find(BLOCK_END)
+    body = "".join(f"- {r}\n" for r in rules)
+    new_block = f"{BLOCK_START}\n{body}{BLOCK_END}"
+    return text[:start] + new_block + text[end + len(BLOCK_END):]
+
+
+def add_rule(
+    root: Path | str, rule: str, *, supersedes: str | None = None
+) -> str:
+    """Append a durable rule to the managed block. Dedup (skip if already
+    present) + supersede (drop the rule ``supersedes`` matches before
+    adding). Creates the file if absent. Returns a human-readable status
+    (the tool relays it). Best-effort write; the human's content outside
+    the managed block is never modified."""
+    rule = " ".join((rule or "").split()).strip()
+    if not rule:
+        return "remember_rule: empty rule — nothing recorded."
+
+    fp = target_rules_file(root)
+    try:
+        if fp.is_file():
+            text = fp.read_text(encoding="utf-8")
+        else:
+            text = _STARTER_TEMPLATE.format(
+                block_start=BLOCK_START, block_end=BLOCK_END
+            )
+        text = _ensure_block(text)
+        rules = _read_managed_rules(text)
+
+        norm = _normalize(rule)
+
+        # Supersede: drop any managed rule the new one replaces.
+        superseded: str | None = None
+        if supersedes:
+            sup_norm = _normalize(supersedes)
+            for existing in list(rules):
+                en = _normalize(existing)
+                if en == sup_norm or sup_norm in en or en in sup_norm:
+                    rules.remove(existing)
+                    superseded = existing
+                    break
+
+        # Dedup: already present (and not a supersede) → no-op.
+        if any(_normalize(r) == norm for r in rules):
+            if superseded is not None:
+                text = _write_managed_rules(text, rules)
+                fp.write_text(text, encoding="utf-8")
+                return (
+                    f"Removed superseded rule ({superseded!r}); "
+                    f"the new rule was already recorded."
+                )
+            return f"Already recorded in {fp.name}: {rule!r}."
+
+        rules.append(rule)
+        text = _write_managed_rules(text, rules)
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(text, encoding="utf-8")
+    except OSError as exc:
+        return f"remember_rule: could not write {fp.name}: {exc}"
+
+    msg = (
+        f"Saved to {fp.name}: {rule!r}"
+        + (f" (replaced {superseded!r})" if superseded else "")
+        + ". It applies from the next session; I'll keep following it now too."
+    )
+    if len(rules) > SOFT_CAP:
+        msg += (
+            f" Note: {len(rules)} rules are tracked — consider pruning "
+            f"{fp.name} (the long file weakens adherence)."
+        )
+    return msg
+
+
+def remember_rule_tool(root: Path | str) -> Tool:
+    """Build the ``remember_rule`` tool for the coordinator. The model
+    calls it when the user states a DURABLE project rule, so the rule is
+    persisted to ``AGENTS.md`` (always-in-prompt next session) instead of
+    relying on probabilistic memory recall."""
+    base = Path(root)
+
+    async def remember_rule(rule: str, supersedes: str = "") -> str:
+        """Persist a durable, user-stated rule to AGENTS.md."""
+        return add_rule(base, rule, supersedes=supersedes or None)
+
+    return tool(
+        name="remember_rule",
+        description=(
+            "Persist a DURABLE project rule the user explicitly stated "
+            "(e.g. 'never edit X', 'always run Y before commit', "
+            "'don't use Z') to AGENTS.md, so it survives future sessions "
+            "instead of relying on memory recall. Args: rule (the rule, "
+            "as a short imperative); supersedes (optional — the text of "
+            "an earlier rule this one reverses/updates; pass it so the "
+            "old rule is removed instead of leaving a contradiction). "
+            "Only call this for standing rules the user states, NOT for "
+            "one-off task requests. Duplicates are skipped automatically."
+        ),
+    )(remember_rule)

loom_code/sandboxed_bash.py

@@ -0,0 +1,176 @@
+"""Kernel-sandboxed bash for the coder — Claude-Code-style.
+
+The coder's ``bash`` runs arbitrary shell, the one genuinely dangerous
+tool (``edit`` / ``write`` only write where the model says, gated by the
+approval prompt). So — like Claude Code, and unlike the framework's
+``OSSandbox`` which ships a *Python function* to a child — we sandbox at
+the **command** boundary: wrap the shell command string in the
+platform's isolation wrapper.
+
+* macOS  -> ``sandbox-exec -p '<profile>' /bin/bash -lc "<cmd>"``
+* Linux  -> ``bwrap <binds> /bin/bash -lc "<cmd>"``
+* else   -> plain bash + a one-time warning (no kernel backend).
+
+The policy: **deny writes outside the project root, deny network by
+default.** Reads stay broad (a build/test needs to read system libs).
+This is the right risk model — arbitrary shell can't exfiltrate or
+tamper outside the workspace, while the structured file tools keep their
+existing approval gate.
+
+Wrapping the command (not a pickled callable) sidesteps the
+picklability constraint that makes ``OSSandbox`` unsuitable for
+loom-code's closure-based builtin tools.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+import anyio
+from loomflow import tool
+from loomflow.tools.registry import Tool
+
+
+def _detect_backend() -> str:
+    """``"seatbelt"`` | ``"bubblewrap"`` | ``"none"`` for this host."""
+    if sys.platform == "darwin" and shutil.which("sandbox-exec"):
+        return "seatbelt"
+    if sys.platform.startswith("linux") and shutil.which("bwrap"):
+        return "bubblewrap"
+    return "none"
+
+
+def _seatbelt_profile(root: Path, allow_network: bool) -> str:
+    """Deny-by-default Seatbelt profile: read anywhere, write only under
+    ``root`` + the OS temp dir, network gated by the flag.
+
+    Mirrors loomflow's OSSandbox profile (read-broad is required so the
+    shell + build tools can load system libs; the enforced properties
+    are no-write-outside-root + network control)."""
+    tmp = Path(tempfile.gettempdir()).resolve()
+    lines = [
+        "(version 1)",
+        ";; loom-code sandboxed bash — deny by default.",
+        "(deny default)",
+        ";; Reads broad: shell + build/test tools must load system libs.",
+        "(allow file-read*)",
+        "(allow process-fork)",
+        "(allow process-exec)",
+        "(allow sysctl-read)",
+        "(allow mach-lookup)",
+        "(allow signal (target self))",
+        f'(allow file-write* (subpath "{root}"))',
+        f'(allow file-write* (subpath "{tmp}"))',
+        # /dev/null and friends — writes the shell expects.
+        '(allow file-write* (subpath "/dev"))',
+    ]
+    lines.append(
+        "(allow network*)" if allow_network
+        else ";; network denied (default)."
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _bubblewrap_argv(root: Path, allow_network: bool) -> list[str]:
+    """``bwrap`` argv: fresh namespace, read-only system, read-write
+    bind for ``root`` + a private /tmp, network dropped unless allowed."""
+    argv = [
+        "bwrap",
+        "--die-with-parent",
+        "--unshare-pid",
+        "--ro-bind", "/usr", "/usr",
+        "--ro-bind", "/bin", "/bin",
+        "--ro-bind", "/lib", "/lib",
+        "--proc", "/proc",
+        "--dev", "/dev",
+        "--tmpfs", "/tmp",
+    ]
+    if Path("/lib64").exists():
+        argv += ["--ro-bind", "/lib64", "/lib64"]
+    if Path("/etc").exists():
+        argv += ["--ro-bind", "/etc", "/etc"]
+    argv += ["--bind", str(root), str(root)]
+    if not allow_network:
+        argv += ["--unshare-net"]
+    return argv
+
+
+def sandboxed_bash_tool(
+    root: str | Path,
+    *,
+    allow_network: bool = False,
+    timeout: float = 300.0,
+) -> Tool:
+    """A ``bash`` tool whose command runs under OS isolation.
+
+    Drop-in replacement for ``loomflow.tools.bash_tool`` on the coder:
+    same name/signature, but the command executes inside ``sandbox-exec``
+    (macOS) / ``bwrap`` (Linux) with writes confined to ``root`` and
+    network denied unless ``allow_network=True``. On a host with no
+    backend it degrades to plain bash and warns once.
+    """
+    root_path = Path(root).resolve()
+    backend = _detect_backend()
+
+    @tool(name="bash")
+    async def sandboxed_bash(command: str) -> str:
+        """Run a shell command. It executes inside an OS sandbox:
+        it may read anywhere but can only WRITE under the project
+        root, and has NO network access (unless the session enabled
+        it). Use it for builds, tests, git, and file inspection."""
+        if backend == "seatbelt":
+            profile = _seatbelt_profile(root_path, allow_network)
+            fd, prof_path = tempfile.mkstemp(suffix=".sb", prefix="loomsb-")
+            import os
+
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(profile)
+            argv = [
+                "sandbox-exec", "-f", prof_path,
+                "/bin/bash", "-lc", command,
+            ]
+        elif backend == "bubblewrap":
+            prof_path = None
+            argv = [
+                *_bubblewrap_argv(root_path, allow_network),
+                "/bin/bash", "-lc", command,
+            ]
+        else:
+            # No kernel backend (Windows / Linux w/o bwrap). Run plain
+            # bash; the output is prefixed with a not-isolated warning
+            # in the result-assembly below so the model + user know.
+            prof_path = None
+            argv = ["/bin/bash", "-lc", command]
+
+        try:
+            with anyio.fail_after(timeout):
+                proc = await anyio.run_process(
+                    argv, check=False, cwd=str(root_path)
+                )
+        except TimeoutError:
+            return f"[sandboxed bash] timed out after {timeout}s"
+        finally:
+            if prof_path is not None:
+                import os
+
+                try:
+                    os.unlink(prof_path)
+                except OSError:
+                    pass
+
+        out = (proc.stdout or b"").decode("utf-8", "replace")
+        err = (proc.stderr or b"").decode("utf-8", "replace")
+        body = out + (("\n" + err) if err else "")
+        if backend == "none":
+            body = (
+                "[warning: no OS sandbox backend on this host — command "
+                "ran WITHOUT kernel isolation]\n" + body
+            )
+        if proc.returncode != 0:
+            body = f"[exit {proc.returncode}]\n{body}"
+        return body
+
+    return sandboxed_bash

loom_code/scribe.py

@@ -0,0 +1,88 @@
+"""Small utility helpers that wrap loomflow Agent for one-shot
+text generation. Today: ``generate_commit_message``.
+
+These live in loom-code (not in loomflow framework) because they
+encode a specific opinionated voice — conventional commits, no
+preamble, terse imperative. The framework stays neutral; loom-code
+is where the opinions live.
+
+Anyone calling these gets a Pythonic ``await fn(input) -> str``
+shape — no streaming, no event subscription, no agent loop.
+Internally we still go through ``loomflow.Agent`` because that
+gives us model-string resolution + retry policy + adapter
+handling for free, but the caller doesn't see any of it.
+"""
+
+from __future__ import annotations
+
+from loomflow import Agent
+
+# Default model: small + fast + cheap. Commit-message generation
+# is a pure-function-of-diff task; no need for a top-tier model.
+# Caller can override via ``model=`` if they want different
+# voice (e.g. claude-sonnet-4-6 for longer-body messages).
+_DEFAULT_MODEL = "claude-haiku-4-5"
+
+
+_COMMIT_SYSTEM_PROMPT = """\
+You write conventional-commit messages from git diffs.
+
+Format:
+- First line: under 50 chars, imperative mood, ``type(scope): subject``
+- Types: feat, fix, refactor, docs, test, chore, perf, style, ci, build
+- Subject in imperative mood: "add" not "added" or "adds"
+- Lowercase subject, no trailing period
+- Optional body separated by a blank line, wrapped at 72 chars,
+  explains WHY (not what)
+- No marketing fluff, no AI-disclosure trailers, no markdown fences
+  in the output
+
+Examples:
+  feat(auth): add JWT validator with RS256 support
+
+  fix(memory): close fact-store connection on agent teardown
+
+  docs: explain the prompt-caching opt-in shape
+
+  refactor(sidecar): extract git ops into _git_run helper
+
+Reply with ONLY the commit message — no preamble, no quoting, no
+markdown fences, no "Here is your commit message" lines."""
+
+
+async def generate_commit_message(
+    diff: str,
+    *,
+    model: str | None = None,
+) -> str:
+    """Generate a conventional-commit message from a git diff.
+
+    One-shot call to a small/fast model. No tools, no memory, no
+    workspace — deliberately stateless because commit-message
+    generation is a pure function of the diff.
+
+    Args:
+        diff: The git diff text. Typically the output of
+            ``git diff --cached`` (the staged changes).
+        model: Override the default model. Pass any string
+            loomflow's model resolver understands (e.g.
+            ``"gpt-4.1-nano"``, ``"claude-sonnet-4-6"``).
+
+    Returns:
+        The suggested commit message as plain text — already
+        stripped of leading/trailing whitespace. Empty diff in →
+        an empty string out (caller should guard the empty case).
+
+    Raises:
+        Whatever the underlying loomflow model adapter raises on
+        provider errors (missing API key, network, etc.). The
+        caller is responsible for surfacing those.
+    """
+    if not diff or not diff.strip():
+        return ""
+    scribe = Agent(
+        _COMMIT_SYSTEM_PROMPT,
+        model=model or _DEFAULT_MODEL,
+    )
+    result = await scribe.run(diff)
+    return (result.output or "").strip()

loom_code/skills/__init__.py

@@ -0,0 +1,16 @@
+"""Built-in skills shipped with loom-code.
+
+Each subdirectory under here is a loomflow skill — ``SKILL.md``
+(frontmatter + body) plus optional ``tools.py`` for Mode B Python
+tools. Loomflow's :class:`SkillRegistry` discovers them from a
+directory path; ``loom_code.agent.build_agent`` points at this
+package's resource path so all bundled skills are wired into the
+coordinator's surface automatically.
+
+Shipped today:
+
+* ``graphify/`` — knowledge-graph extraction over the project,
+  using graphify's Python primitives directly (no subprocess,
+  no MCP). Build / query / path / explain tools, prefixed
+  ``graphify__*`` once loaded.
+"""

loom_code/skills/graphify/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: graphify
+description: Build + query a knowledge graph of this project's code. Reach for it on STRUCTURAL questions (cross-file deps, paths between concepts, which file/module everything connects through) that grep can't traverse — never for single-file questions grep wins on.
+---
+
+# graphify
+
+Turn the project's source files into a knowledge graph: nodes are
+symbols and files, edges are imports / calls / references / shared
+data. Persisted to ``.loom/graphify/graph.json`` so queries are
+cheap across runs. AST-only extraction — deterministic, no LLM
+cost, no provider key required.
+
+## Tools (after `load_skill`)
+
+**IMPORTANT — these are PYTHON @tool FUNCTIONS, not shell
+commands.** Call them via the model's tool-call mechanism, the
+same way you call ``read`` / ``edit`` / ``grep``. Do NOT pass
+them to ``bash`` — there is no ``graphify__build`` executable on
+disk, only a registered tool with that name. If you try
+``bash graphify__build ...`` you'll get "command not found"
+because graphify__build is an in-process Python function, not a
+CLI. Use tool-call syntax exclusively.
+
+* ``graphify__build(path=".")`` — walk the project, extract,
+  cluster, write ``.loom/graphify/graph.json``. Idempotent and
+  incremental: re-running on an unchanged repo is fast (file
+  hashes gate re-extraction). Run this ONCE per project (or after
+  major refactors) before the query tools below; the post-commit
+  hook keeps it current every 5 commits afterward.
+
+* ``graphify__query(question, path=".")`` — three-tier search
+  that surfaces the WHOLE subsystem around a keyword, not just
+  literal name matches. Returns results grouped by tier:
+
+    - **DIRECT** — nodes whose label or source file literally
+      matches the query keywords (the narrow case grep would also
+      catch).
+    - **NEIGHBOR** — 1-hop graph neighbours of any direct match.
+      Surfaces callers / callees / dependencies whose names DON'T
+      contain the keyword but participate in the same call
+      structure. (Example: querying ``auth`` surfaces
+      ``validate_token``, ``check_credentials``,
+      ``require_login`` — all of which grep would miss.)
+    - **COMMUNITY** — other nodes in the same Leiden cluster as
+      a direct match. Surfaces the rest of the subsystem when
+      the query is a concept name (``auth``, ``runtime``,
+      ``memory``) rather than a specific symbol.
+
+  Use for "what's involved in X" / "how does Y work in this
+  codebase" / "what's the auth subsystem look like" — questions
+  about a CONCEPT spanning files, not a single name lookup. For
+  literal "where is foo defined" use grep directly.
+
+* ``graphify__path(a, b, path=".")`` — shortest path between two
+  named concepts. Returns the hop-by-hop trail with edge labels.
+  Use for "how does A get to B" / "what's the connection between
+  X and Y" — exactly what grep can't answer.
+
+* ``graphify__explain(node, path=".")`` — plain-language
+  explanation of one node: what it is, its source file/line, its
+  immediate neighbors, the community/cluster it belongs to. Use
+  when the user asks about a specific symbol or file.
+
+## When to reach for graphify
+
+Use the graph tools when the question is **structural** — about
+how things connect across files. Concrete trigger shapes:
+
+* "What connects A to B?"
+* "Where is the auth code used?"
+* "What are the dependencies of foo?"
+* "Show me the path between X and Y."
+* "Which file is central to this codebase?" → ``graphify__query("god nodes")`` returns highest-degree symbols.
+
+**Do NOT reach for graphify when:**
+
+* The question is about ONE file's content — use ``read`` /
+  ``grep`` directly. Graph queries waste tokens on one-file
+  answers.
+* You haven't run ``graphify__build`` yet — call it first, then
+  query. If ``.loom/graphify/graph.json`` doesn't exist any
+  graph_* call returns an error pointing here.
+* The user wants raw source text — that's a ``read`` / ``grep``
+  job, not a graph job. The graph holds *structure*, not bodies.
+
+## Cost shape
+
+* ``graphify__build``: ~5-30s on typical loom-code-sized
+  projects (100-500 files). Up to 2 min on monorepos. Pure
+  Python, no LLM call. AST-only — code files only; docs / PDFs /
+  images need the standalone ``/graphify`` skill in Claude Code,
+  not this one.
+
+* ``graphify__query`` / ``graphify__path`` / ``graphify__explain``:
+  milliseconds. They load ``graph.json`` once and traverse in
+  memory.