loom-code 0.1.1__py3-none-any.whl

loom_code/trust.py

@@ -0,0 +1,216 @@
+"""Trust gating for project-scope hooks.
+
+A user-scope hook (``~/.loom-code/settings.toml``) is something YOU
+wrote — it runs without ceremony. A project-scope hook
+(``<repo>/.loom/settings.toml``) is a stranger's code: clone a repo,
+open it in loom-code, and its hooks would otherwise run shell commands
+on your machine automatically. That's a real code-execution vector, so
+project hooks are gated:
+
+* The first time loom-code sees a repo's project hooks — or whenever
+  the set of commands changes — it shows you the commands and asks
+  whether to trust them.
+* Your answer is remembered (keyed by repo path + a fingerprint of the
+  hook commands) in ``~/.loom-code/trusted_hooks.json``, so you're
+  asked again only if the hooks change.
+
+Skills and subagents are NOT gated here: they run only when the model
+invokes them, and every tool they call still goes through the normal
+approval gate. Hooks are the one thing that fires automatically, so
+they're the one thing that needs up-front consent.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable
+from pathlib import Path
+
+from .extensions import Extensions, HookSpec, McpEntry
+from .extensions import discover as _discover
+
+_DEFAULT_TRUST_STORE = Path.home() / ".loom-code" / "trusted_hooks.json"
+
+
+def deny_untrusted(_specs: list[HookSpec]) -> bool:
+    """A non-interactive trust prompt that always declines.
+
+    The secure default for callers that can't show a prompt (the
+    desktop sidecar, scripts, ``build_agent``'s self-discovery path):
+    project hooks run ONLY if already recorded as trusted; everything
+    not-yet-trusted is dropped rather than auto-run."""
+    return False
+
+
+def discover_trusted(
+    project_root: Path,
+    *,
+    prompt: Callable[[list[HookSpec]], bool] = deny_untrusted,
+    user_dir: Path | None = None,
+    trust_store: Path | None = None,
+) -> Extensions:
+    """Discover ``.loom`` extensions and apply the project-hook trust
+    gate in one call.
+
+    The convenience entry every non-REPL caller should use: it returns
+    a bundle whose project hooks are already trust-filtered. ``prompt``
+    defaults to :func:`deny_untrusted` (secure, non-interactive); pass
+    an interactive callback to ask the user."""
+    ext = _discover(project_root, user_dir=user_dir)
+    return filter_trusted_hooks(
+        ext,
+        project_root=project_root,
+        prompt=prompt,
+        trust_store=trust_store,
+    )
+
+
+def filter_trusted_hooks(
+    extensions: Extensions,
+    *,
+    project_root: Path,
+    prompt: Callable[[list[HookSpec]], bool],
+    trust_store: Path | None = None,
+) -> Extensions:
+    """Return ``extensions`` with untrusted project hooks removed.
+
+    User-scope hooks always pass through. Project-scope hooks pass only
+    when their fingerprint is already recorded as trusted for
+    ``project_root``, or when ``prompt(project_specs)`` returns True
+    (in which case the fingerprint is recorded so we don't ask again).
+    On denial the project hooks are dropped — skills, subagents, and
+    user hooks are kept untouched.
+
+    Project-scope MCP servers are gated the SAME way: connecting one runs
+    external code / hits an external endpoint, so a cloned repo's MCP
+    servers load only if the repo is trusted. Trust is one decision over
+    the combined (hooks + MCP) fingerprint; on denial both project hooks
+    and project MCP are dropped.
+
+    ``trust_store`` overrides the on-disk record path (tests pass a tmp
+    file)."""
+    project_hooks = [
+        h for h in extensions.hook_specs if h.source == "project"
+    ]
+    project_mcp = [
+        m for m in extensions.mcp_specs if m.source == "project"
+    ]
+    if not project_hooks and not project_mcp:
+        return extensions
+
+    if is_trusted(
+        project_root, project_hooks, project_mcp, trust_store=trust_store
+    ):
+        return extensions  # already trusted, unchanged
+
+    if prompt(project_hooks):
+        record_trust(
+            project_root,
+            project_hooks,
+            project_mcp,
+            trust_store=trust_store,
+        )
+        return extensions
+
+    # Denied — strip project hooks AND project MCP, keep everything else
+    # (skills, subagents, user-scope hooks + MCP).
+    kept_hooks = [h for h in extensions.hook_specs if h.source != "project"]
+    kept_mcp = [m for m in extensions.mcp_specs if m.source != "project"]
+    return Extensions(
+        skill_paths=extensions.skill_paths,
+        agent_specs=extensions.agent_specs,
+        hook_specs=kept_hooks,
+        mcp_specs=kept_mcp,
+    )
+
+
+def is_trusted(
+    project_root: Path,
+    project_hooks: list[HookSpec],
+    project_mcp: list[McpEntry] | None = None,
+    *,
+    trust_store: Path | None = None,
+) -> bool:
+    """Has the user already trusted *exactly* this repo's gated config
+    (project hooks AND MCP servers)?
+
+    True when the combined fingerprint matches the recorded one for
+    ``project_root`` (or when there's nothing gated to trust). Lets an
+    async caller (the desktop sidecar) decide whether to prompt without
+    going through the sync ``filter_trusted_hooks`` callback. ``project_mcp``
+    defaults to ``None`` so existing hook-only callers are unchanged."""
+    if not project_hooks and not project_mcp:
+        return True
+    store = trust_store if trust_store is not None else _DEFAULT_TRUST_STORE
+    key = str(project_root.resolve())
+    return _load(store).get(key) == _fingerprint(project_hooks, project_mcp)
+
+
+def record_trust(
+    project_root: Path,
+    project_hooks: list[HookSpec],
+    project_mcp: list[McpEntry] | None = None,
+    *,
+    trust_store: Path | None = None,
+) -> None:
+    """Record the user's decision to trust exactly this repo's gated
+    config (project hooks AND MCP servers), so they aren't re-prompted
+    until either changes."""
+    if not project_hooks and not project_mcp:
+        return
+    store = trust_store if trust_store is not None else _DEFAULT_TRUST_STORE
+    _record(
+        store,
+        str(project_root.resolve()),
+        _fingerprint(project_hooks, project_mcp),
+    )
+
+
+def _fingerprint(
+    specs: list[HookSpec], mcp: list[McpEntry] | None = None
+) -> str:
+    """A stable hash over a repo's gated executable surface — hooks AND
+    MCP servers. Changing any hook command/matcher/event/timeout, or any
+    MCP server's name/transport/command/args/url, invalidates trust
+    (re-prompts); reordering does not. ``mcp`` defaults to ``None`` so
+    existing hook-only callers keep the same fingerprint."""
+    hook_payload = sorted(
+        ("hook", s.event, s.matcher, s.command, s.timeout) for s in specs
+    )
+    mcp_payload = sorted(
+        (
+            "mcp",
+            m.spec.name,
+            m.spec.transport,
+            m.spec.command or "",
+            tuple(m.spec.args),
+            m.spec.url or "",
+        )
+        for m in (mcp or [])
+    )
+    return hashlib.sha256(
+        repr(hook_payload + mcp_payload).encode("utf-8")
+    ).hexdigest()
+
+
+def _load(store: Path) -> dict[str, str]:
+    if not store.exists():
+        return {}
+    try:
+        data = json.loads(store.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _record(store: Path, key: str, fingerprint: str) -> None:
+    data = _load(store)
+    data[key] = fingerprint
+    try:
+        store.parent.mkdir(parents=True, exist_ok=True)
+        store.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except OSError:
+        # A failed write just means we'll ask again next time — never
+        # fatal to the session.
+        pass

loom_code/turn.py

@@ -0,0 +1,169 @@
+"""Shared per-turn pipeline pieces — ONE home for the learning loop.
+
+loom-code has two frontends that each run their own turn loop: the
+terminal REPL (``repl.py``) and loomflow-desktop's sidecar. Per-turn
+behaviour written inside either frontend exists only there and the
+copies drift — the desktop shipped with active recall present but the
+credit signal dormant, exactly that failure. Anything that should
+happen "around every turn" regardless of surface belongs HERE; the
+frontends keep only their surface-specific concerns (console output,
+RPC events, pending-state storage).
+
+Current residents:
+
+* :func:`learned_notes_block` / :func:`inject_learned_notes` — ACTIVE
+  recall: surface the top success-credited notebook notes relevant to
+  this prompt as the ``learned_notes`` working block.
+* :func:`attribute_turn` — the credit signal: flush a finished turn's
+  cited note slugs (+ file touches) to the workspace / file history.
+  Frontends decide *when* (explicit /good–/bad, or the moved-on
+  heuristic: a new task arriving without complaint credits the last
+  turn); this owns *what crediting means*.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import file_history
+
+# Bounded injection: top-3 proven notes, snippet-length excerpts —
+# a few hundred tokens, not a notebook dump.
+_RECALL_LIMIT = 8
+_INJECT_TOP = 3
+
+
+async def learned_notes_block(
+    workspace: Any, prompt: str, *, user_id: str | None
+) -> str:
+    """Render the ``learned_notes`` working-block body for ``prompt``.
+
+    Empty string when no PROVEN note matches — callers must still
+    write the empty block so stale advice from a prior prompt never
+    lingers. Slugs are shown so the agent can ``read_note(slug)`` for
+    full detail, which also keeps the citation-credit chain alive.
+    """
+    matches = await workspace.search_notes(
+        prompt,
+        user_id=user_id,
+        boost_relevance=True,
+        limit=_RECALL_LIMIT,
+    )
+    proven = [m for m in matches if m.summary.success_count > 0][
+        :_INJECT_TOP
+    ]
+    if not proven:
+        return ""
+    lines = [
+        "# Learned notes (proven on past turns)",
+        "Notes from earlier work on THIS project that were used in "
+        "turns the user accepted. Trust but verify — "
+        "`read_note(slug)` for the full note.",
+        "",
+    ]
+    lines.extend(
+        f"- [{m.summary.slug}] (worked "
+        f"{m.summary.success_count}x) {m.snippet}"
+        for m in proven
+    )
+    return "\n".join(lines)
+
+
+async def update_block_if_changed(
+    memory: Any,
+    name: str,
+    content: str,
+    *,
+    user_id: str | None,
+    block_hashes: dict[str, str] | None,
+) -> None:
+    """Write a working block only when its content changed since the
+    last write this session — the one dirty-check both the REPL and
+    :func:`inject_learned_notes` share.
+
+    ``block_hashes`` (caller-owned) is the per-session content-hash
+    map; ``None`` disables the check (always writes). The hash is
+    recorded only AFTER a successful write, so a failed write can't
+    convince a later turn the block is up to date. Rationale: skips a
+    redundant sqlite write + the churn of re-serialising an unchanged
+    block every turn (loomflow's update_block is a plain UPSERT)."""
+    if block_hashes is None:
+        await memory.update_block(name, content, user_id=user_id)
+        return
+    import hashlib
+
+    h = hashlib.sha1(content.encode("utf-8")).hexdigest()
+    if block_hashes.get(name) == h:
+        return
+    await memory.update_block(name, content, user_id=user_id)
+    block_hashes[name] = h
+
+
+async def inject_learned_notes(
+    workspace: Any,
+    memory: Any,
+    prompt: str,
+    *,
+    user_id: str | None,
+    block_hashes: dict[str, str] | None = None,
+) -> None:
+    """Write this turn's active-recall block into ``memory``.
+
+    Best-effort by contract: memory/workspace I/O failing must never
+    kill a turn, so callers can ``await`` this bare. ``block_hashes``
+    (optional) enables the shared dirty-check — see
+    :func:`update_block_if_changed`."""
+    try:
+        body = await learned_notes_block(
+            workspace, prompt, user_id=user_id
+        )
+        await update_block_if_changed(
+            memory,
+            "learned_notes",
+            body,
+            user_id=user_id,
+            block_hashes=block_hashes,
+        )
+    except Exception:  # noqa: BLE001 — recall is best-effort
+        pass
+
+
+async def attribute_turn(
+    workspace: Any,
+    root: Path | str,
+    *,
+    success: bool,
+    slugs: list[str],
+    files: list[str],
+    user_id: str | None,
+) -> int:
+    """Flush one finished turn's learning signal.
+
+    * ``files`` — paths the turn wrote; their file-history records
+      are revised from "unknown" to the now-known outcome
+      (independent of the slug path: a turn can edit files without
+      citing notes).
+    * ``slugs`` — notes the agent read during the turn (the run
+      result's ``cited_slugs``); each gets ``cited_count`` += 1 and,
+      when ``success``, ``success_count`` += 1 — which is what makes
+      it eligible for future active recall.
+
+    Returns the number of notes credited/debited (0 on failure —
+    best-effort by contract)."""
+    if files:
+        try:
+            file_history.update_last_outcome(
+                root, files, "success" if success else "fail"
+            )
+        except Exception:  # noqa: BLE001 — history is best-effort
+            pass
+    if not slugs:
+        return 0
+    try:
+        n = await workspace.attribute_outcome(
+            success=success, slugs=slugs, user_id=user_id
+        )
+        return int(n or 0)
+    except Exception:  # noqa: BLE001 — crediting is best-effort
+        return 0