platformforge 0.1.0__py3-none-any.whl

platformforge/tokensave/estimate.py

@@ -0,0 +1,21 @@
+"""Token estimation — honest heuristic.
+
+~4 chars/token is the documented approximation for code+prose in English.
+Estimates are ALWAYS labeled `estimated`, never `observed` — provider token
+counts are only real when a host transcript supplies them.
+"""
+
+from __future__ import annotations
+
+CHARS_PER_TOKEN = 4.0
+
+
+def estimate_tokens(text: str | bytes) -> int:
+    if isinstance(text, bytes):
+        text = text.decode("utf-8", errors="replace")
+    return max(1, round(len(text) / CHARS_PER_TOKEN)) if text else 0
+
+
+def estimate_obj(obj) -> int:
+    import json
+    return estimate_tokens(json.dumps(obj, default=str))

platformforge/tokensave/index.py

@@ -0,0 +1,172 @@
+"""Local search index — SQLite FTS5, incremental by content hash.
+
+Indexes file content + extracted symbols. Unchanged files (same sha256) are
+never re-indexed. No embeddings, no external service.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.hashing import sha256_file, sha256_text
+from platformforge.core.redaction import redact_text_report, redaction_receipt
+
+IGNORE_DIRS = {".git", ".venv", "node_modules", ".platformforge", "vendor",
+               "__pycache__", "dist", "build", ".terraform", ".idea", ".vscode"}
+TEXT_EXT = {".py", ".tf", ".tfvars", ".yaml", ".yml", ".json", ".md", ".go",
+            ".ts", ".js", ".java", ".rb", ".rs", ".sh", ".toml", ".hcl",
+            ".sql", ".j2", ".tpl", ".rego", ".cel", ".xml", ".gradle",
+            ".properties", ".txt", ".cfg", ".ini", ".env.example"}
+MAX_FILE_BYTES = 2_000_000
+
+SYMBOL_PATTERNS = {
+    ".py": [re.compile(r"^\s*(?:class|def|async def)\s+([A-Za-z_][\w]*)", re.MULTILINE)],
+    ".go": [re.compile(r"^\s*func\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*)", re.MULTILINE),
+            re.compile(r"^\s*type\s+([A-Za-z_][\w]*)", re.MULTILINE)],
+    ".java": [re.compile(r"\b(?:class|interface|enum|record)\s+([A-Za-z_][\w]*)")],
+    ".tf": [re.compile(r'\bresource\s+"([^"]+)"\s+"([^"]+)"'),
+            re.compile(r'\bmodule\s+"([^"]+)"'),
+            re.compile(r'\b(?:variable|output|data|provider)\s+"?([A-Za-z_][\w]*)"?')],
+    ".hcl": [re.compile(r'\bresource\s+"([^"]+)"\s+"([^"]+)"')],
+    ".yaml": [re.compile(r"^\s*name:\s*([A-Za-z0-9_.\-/]+)", re.MULTILINE)],
+    ".yml": [re.compile(r"^\s*name:\s*([A-Za-z0-9_.\-/]+)", re.MULTILINE)],
+}
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS files(
+  path TEXT PRIMARY KEY, sha256 TEXT, kind TEXT, bytes INTEGER, symbols TEXT);
+CREATE TABLE IF NOT EXISTS facts_idx(
+  fact_id TEXT PRIMARY KEY, kind TEXT, location TEXT, doc TEXT);
+CREATE VIRTUAL TABLE IF NOT EXISTS content USING fts5(
+  path UNINDEXED, body, tokenize='porter unicode61');
+"""
+
+
+class SearchIndex:
+    def __init__(self, db_path: str | Path):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.db = sqlite3.connect(str(self.db_path))
+        self.db.executescript(SCHEMA)
+        self.db.commit()
+
+    def close(self) -> None:
+        self.db.close()
+
+    def __enter__(self) -> SearchIndex:  # noqa: PYI034 - typing.Self is 3.11+; no typing_extensions dep
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ── indexing ──────────────────────────────────────────────
+    def _iter_files(self, root: Path) -> Iterable[Path]:
+        for p in sorted(root.rglob("*")):
+            if not p.is_file() or any(part in IGNORE_DIRS for part in p.parts):
+                continue
+            if p.suffix in TEXT_EXT and p.stat().st_size <= MAX_FILE_BYTES:
+                yield p
+
+    def index_workspace(self, root: str | Path) -> dict[str, int]:
+        """Incremental: only changed/new files are parsed and re-indexed."""
+        root = Path(root)
+        stats = {"indexed": 0, "reused": 0, "removed": 0}
+        seen = set()
+        for p in self._iter_files(root):
+            rel = str(p.relative_to(root))
+            seen.add(rel)
+            sha = sha256_file(p)
+            row = self.db.execute(
+                "SELECT sha256 FROM files WHERE path=?", (rel,)).fetchone()
+            if row and row[0] == sha:
+                stats["reused"] += 1
+                continue
+            body = p.read_text(errors="replace")
+            # §17 — secrets are never stored raw in the context engine;
+            # the index keeps redacted text + a receipt of what was masked.
+            body, redactions = redact_text_report(body)
+            if redactions:
+                stats.setdefault("redactions", {})[rel] = redaction_receipt(
+                    rel, redactions)["redactions"]
+            symbols = sorted({m for pat in SYMBOL_PATTERNS.get(p.suffix, [])
+                              for m in pat.findall(body)
+                              for m in (m if isinstance(m, tuple) else (m,))})
+            self.db.execute(
+                "INSERT OR REPLACE INTO files VALUES(?,?,?,?,?)",
+                (rel, sha, p.suffix.lstrip("."), p.stat().st_size,
+                 " ".join(symbols)))
+            self.db.execute("DELETE FROM content WHERE path=?", (rel,))
+            self.db.execute("INSERT INTO content(path, body) VALUES(?,?)",
+                            (rel, body))
+            stats["indexed"] += 1
+        stale = {r[0] for r in self.db.execute(
+            "SELECT path FROM files")} - seen
+        for rel in stale:
+            self.db.execute("DELETE FROM files WHERE path=?", (rel,))
+            self.db.execute("DELETE FROM content WHERE path=?", (rel,))
+            stats["removed"] += 1
+        self.db.commit()
+        return stats
+
+    def index_fact(self, fact_id: str, kind: str, location: str, doc: str) -> None:
+        self.db.execute("INSERT OR REPLACE INTO facts_idx VALUES(?,?,?,?)",
+                        (fact_id, kind, location, doc))
+        self.db.commit()
+
+    # ── queries ───────────────────────────────────────────────
+    def search(self, query: str, limit: int = 20) -> list[dict[str, Any]]:
+        """FTS5 literal/phrase search."""
+        try:
+            rows = self.db.execute(
+                "SELECT path, snippet(content,1,'«','»','…',12) FROM content "
+                "WHERE content MATCH ? ORDER BY rank LIMIT ?",
+                (query, limit)).fetchall()
+        except sqlite3.OperationalError:
+            return []
+        return [{"path": p, "snippet": s} for p, s in rows]
+
+    def search_regex(self, pattern: str, limit: int = 50) -> list[dict[str, Any]]:
+        rx = re.compile(pattern)
+        hits = []
+        for path, in self.db.execute("SELECT path FROM files"):
+            body_rows = self.db.execute(
+                "SELECT body FROM content WHERE path=?", (path,)).fetchall()
+            if body_rows and rx.search(body_rows[0][0] or ""):
+                hits.append({"path": path})
+                if len(hits) >= limit:
+                    break
+        return hits
+
+    def symbol(self, name: str) -> list[dict[str, Any]]:
+        rows = self.db.execute(
+            "SELECT path, symbols FROM files WHERE symbols LIKE ?",
+            (f"%{name}%",)).fetchall()
+        return [{"path": p, "symbols": s.split() if s else []} for p, s in rows]
+
+    def by_path(self, glob: str) -> list[str]:
+        like = glob.replace("*", "%").replace("?", "_")
+        return [r[0] for r in self.db.execute(
+            "SELECT path FROM files WHERE path LIKE ?", (like,))]
+
+    def by_kind(self, kind: str) -> list[str]:
+        return [r[0] for r in self.db.execute(
+            "SELECT path FROM files WHERE kind=?", (kind,))]
+
+    def read(self, path: str) -> str | None:
+        row = self.db.execute(
+            "SELECT body FROM content WHERE path=?", (path,)).fetchone()
+        return row[0] if row else None
+
+    def stats(self) -> dict[str, int]:
+        files = self.db.execute("SELECT COUNT(*), COALESCE(SUM(bytes),0) "
+                                "FROM files").fetchone()
+        return {"files": files[0], "bytes": files[1]}
+
+    def fingerprint(self) -> str:
+        return sha256_text(",".join(
+            f"{r[0]}:{r[1]}" for r in self.db.execute(
+                "SELECT path, sha256 FROM files ORDER BY path")))

platformforge/tokensave/ledger.py

@@ -0,0 +1,121 @@
+"""Token ledger — append-only JSONL accounting per run.
+
+Records context requested/delivered/reused/skipped/compressed, provider tokens
+when observed, estimates when estimated, cache hits/misses. Three honesty
+states: observed | estimated | unknown.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class LedgerEntry:
+    """§29 — v2 fields: requested/candidate/selected/delivered/reused/
+    cached/compressed/skipped + essential/optional split. Provider-side
+    tokens stay None unless a host transcript observes them."""
+    operation: str
+    context_requested: int = 0      # estimated tokens requested
+    context_candidate: int = 0      # ranked candidates before budget
+    context_selected: int = 0       # selected after ranking
+    context_delivered: int = 0
+    context_reused: int = 0         # served from cache/content-address
+    context_cached: int = 0
+    context_skipped: int = 0
+    context_compressed: int = 0
+    essential_tokens: int = 0       # evidence that must not be dropped
+    optional_tokens: int = 0
+    input_tokens: int | None = None   # observed (provider transcript)
+    output_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    cost_usd: float | None = None
+    input_tokens_est: int | None = None  # estimated
+    output_tokens_est: int | None = None
+    cache_hits: int = 0
+    cache_misses: int = 0
+    # §42 — deterministic vs model split. Deterministic bytes are the local
+    # working set (never billed as model spend); model_context_* counts only
+    # the payload a model/agent receives. Provider counts stay None when no
+    # transcript observed them (`unknown`).
+    deterministic_input_bytes: int = 0
+    deterministic_fact_count: int = 0
+    model_context_bytes: int = 0
+    model_context_tokens: int | None = None
+    model_output_tokens: int | None = None
+    cache_tokens: int = 0
+    latency_ms: float = 0.0
+    token_basis: str = "unknown"   # closed vocab: observed|estimated|unknown
+    # an "observed" row must bind to the transcript that observed it —
+    # otherwise the count is unfalsifiable
+    transcript_ref: str | None = None
+    ts: float = field(default_factory=time.time)
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    _TOKEN_BASES = ("observed", "estimated", "unknown")
+
+    def __post_init__(self) -> None:
+        if self.token_basis not in self._TOKEN_BASES:
+            raise ValueError(
+                f"token_basis must be one of {self._TOKEN_BASES}, "
+                f"got {self.token_basis!r}")
+        observed = any(v is not None for v in
+                       (self.input_tokens, self.output_tokens,
+                        self.reasoning_tokens))
+        if observed and self.token_basis != "observed":
+            raise ValueError(
+                "provider token counts require token_basis='observed'")
+        if self.token_basis == "observed" and observed \
+                and not self.transcript_ref:
+            raise ValueError(
+                "observed token counts require transcript_ref — "
+                "unbindable numbers are fabricated")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class TokenLedger:
+    def __init__(self, root: str | Path):
+        self.dir = Path(root) / ".platformforge" / "ledger"
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.dir / "tokens.jsonl"
+
+    def record(self, entry: LedgerEntry) -> None:
+        with open(self.path, "a") as fh:
+            fh.write(json.dumps(entry.to_dict(), default=str) + "\n")
+
+    def entries(self) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        return [json.loads(l) for l in self.path.read_text().splitlines() if l.strip()]
+
+    def report(self) -> dict[str, Any]:
+        ents = self.entries()
+        tot = lambda k: sum(e.get(k) or 0 for e in ents)
+        hits, misses = tot("cache_hits"), tot("cache_misses")
+        return {
+            "operations": len(ents),
+            "context_requested": tot("context_requested"),
+            "context_delivered": tot("context_delivered"),
+            "context_reused": tot("context_reused"),
+            "context_skipped": tot("context_skipped"),
+            "context_compressed": tot("context_compressed"),
+            "cache_hit_ratio": (hits / (hits + misses)) if (hits + misses) else None,
+            "input_tokens_observed": tot("input_tokens"),
+            "output_tokens_observed": tot("output_tokens"),
+            "input_tokens_estimated": tot("input_tokens_est"),
+            "output_tokens_estimated": tot("output_tokens_est"),
+            "deterministic_input_bytes": tot("deterministic_input_bytes"),
+            "deterministic_fact_count": tot("deterministic_fact_count"),
+            "model_context_bytes": tot("model_context_bytes"),
+            "cache_tokens": tot("cache_tokens"),
+            "basis_counts": {
+                b: sum(1 for e in ents if e.get("token_basis") == b)
+                for b in ("observed", "estimated", "unknown")
+            },
+        }

platformforge/tokensave/packs.py

@@ -0,0 +1,285 @@
+"""Context packs v2 — graph-aware, explainable, budget-deciding (§22–§28).
+
+Pipeline (§23): task → intent terms → candidate files → changed artifacts →
+graph seeds/neighborhood → rules → facts → historical findings → risk
+modifiers → rank → dedup → budget → pack.
+
+Every item carries `score` + `reasons` (§25). Items are classified
+essential / high-value / optional / background (§27). If essential alone
+exceeds the budget the pack returns `budget_decision: refuse` — essential
+evidence is never dropped silently.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from platformforge.tokensave.budget import Budget
+from platformforge.tokensave.estimate import estimate_tokens
+from platformforge.tokensave.index import SearchIndex
+from platformforge.tokensave.ledger import LedgerEntry, TokenLedger
+
+WORD_RE = re.compile(r"[A-Za-z0-9_.\-/]{3,}")
+
+ESSENTIAL = "essential"        # findings, facts, rules, unresolved — never dropped
+HIGH_VALUE = "high-value"      # changed files, graph distance ≤ 1, risk-flagged
+OPTIONAL = "optional"
+BACKGROUND = "background"
+
+# §24 — explainable scoring weights. Each contributes a named reason.
+W_CHANGED = 10.0
+W_TASK_TERM = 2.0
+W_SYMBOL = 3.0
+W_PATH_TERM = 4.0
+W_GRAPH_DIST = {1: 6.0, 2: 3.0}
+W_RISK = {"critical": 8.0, "high": 5.0, "medium": 2.0}
+W_RULE = 4.0
+
+
+class ContextPackBuilder:
+    def __init__(self, index: SearchIndex, ledger: TokenLedger | None = None):
+        self.index = index
+        self.ledger = ledger
+
+    def _task_terms(self, task: str) -> list[str]:
+        return [t.lower() for t in WORD_RE.findall(task)]
+
+    def _rank_files(self, terms: list[str], changed: list[str],
+                    graph_nodes: list[str] | None,
+                    rule_ids: list[str] | None,
+                    risk: str | None,
+                    limit: int = 50) -> list[dict[str, Any]]:
+        """Ranked candidates with explainable reasons (§24–§25)."""
+        scores: dict[str, float] = {}
+        reasons: dict[str, list[str]] = {}
+
+        def bump(path: str, w: float, reason: str) -> None:
+            scores[path] = scores.get(path, 0.0) + w
+            reasons.setdefault(path, [])
+            if reason not in reasons[path]:
+                reasons[path].append(reason)
+
+        for path in changed:
+            bump(path, W_CHANGED, "changed-file")
+        for term in terms:
+            for hit in self.index.search(f'"{term}"', limit=20):
+                bump(hit["path"], W_TASK_TERM, f"task-term:{term}")
+            for hit in self.index.symbol(term):
+                bump(hit["path"], W_SYMBOL, f"symbol:{term}")
+            for path in self.index.by_path(f"*{term}*"):
+                bump(path, W_PATH_TERM, f"path:{term}")
+        for node in graph_nodes or []:
+            # graph seeds/neighbors: node label terms hit path ranking
+            depth = 1 if ":" not in node else int(node.split(":", 1)[1])
+            w = W_GRAPH_DIST.get(depth, 1.0)
+            label = node.split("/")[-1].split(":")[0]
+            for hit in self.index.search(f'"{label}"', limit=10):
+                bump(hit["path"], w, f"graph-distance:{depth}")
+            for path in self.index.by_path(f"*{label}*"):
+                bump(path, w, f"graph-distance:{depth}")
+        for rid in rule_ids or []:
+            for hit in self.index.search(f'"{rid}"', limit=5):
+                bump(hit["path"], W_RULE, f"rule:{rid}")
+        if risk:
+            for term in ("iam", "policy", "secret", "sg", "security"):
+                for hit in self.index.by_path(f"*{term}*"):
+                    bump(hit, W_RISK.get(risk, 0.0), f"risk:{risk}")
+        ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))
+        return [{"path": p, "score": round(s, 2), "reasons": reasons[p]}
+                for p, s in ranked[:limit]]
+
+    def build(self, task: str, budget: Budget | None = None,
+              changed_files: list[str] | None = None,
+              facts: list[dict] | None = None,
+              findings: list[dict] | None = None,
+              rules: list[str] | None = None,
+              graph_neighborhood: list[dict] | None = None,
+              risk: str | None = None,
+              previous_pack_hash: str | None = None,
+              previous_files: dict[str, str] | None = None,
+              sources: list[str] | None = None,
+              allow_escalate: bool = False,
+              max_file_bytes: int = 20_000,
+              retain_content: bool = False) -> dict[str, Any]:
+        budget = budget or Budget()
+        changed = changed_files or []
+        node_terms = [
+            f"{n.get('node', '')}:{n.get('depth', '')}" if isinstance(n, dict)
+            else str(n) for n in (graph_neighborhood or [])]
+        ranked = self._rank_files(self._task_terms(task), changed,
+                                  node_terms, rules, risk)
+        seen_hash: set[str] = set()
+
+        files_out: list[dict[str, Any]] = []
+        symbols_out: list[str] = []
+        used_tokens = 0
+        skipped = 0
+        reused = 0
+        for cand in ranked:
+            path, score, c_reasons = cand["path"], cand["score"], cand["reasons"]
+            body = self.index.read(path)
+            if body is None:
+                continue
+            sha = self.index.db.execute(
+                "SELECT sha256 FROM files WHERE path=?", (path,)).fetchone()[0]
+            if sha in seen_hash:
+                skipped += 1
+                continue  # dedup identical content
+            cls = HIGH_VALUE if ("changed-file" in c_reasons
+                                 or "graph-distance:1" in c_reasons) \
+                else OPTIONAL
+            truncated = body[:max_file_bytes]
+            tokens = estimate_tokens(truncated)
+            if budget.input_budget and used_tokens + tokens > budget.input_budget:
+                head = truncated[: len(truncated) // 4]
+                head_tokens = estimate_tokens(head)
+                if used_tokens + head_tokens <= budget.input_budget:
+                    truncated, tokens = head + "\n…[truncated by budget]", head_tokens
+                elif cls == HIGH_VALUE and previous_pack_hash is None:
+                    # high-value overflowing: degrade to optional head anyway
+                    skipped += 1
+                    continue
+                else:
+                    skipped += 1
+                    continue
+            seen_hash.add(sha)
+            # §26 — real delta accounting: identical sha as the previous
+            # pack means the file was reused, not re-read fresh.
+            if previous_files and previous_files.get(path) == sha:
+                reused += 1
+            used_tokens += tokens
+            entry = {"path": path, "score": score,
+                     "reasons": c_reasons, "class": cls,
+                     "tokens": tokens, "sha256": sha,
+                     "delivered_bytes": len(truncated.encode()),
+                     "delivered_chars": len(truncated)}
+            if retain_content:
+                # exact delivered payload — QPT measures what ships
+                entry["content"] = truncated
+            files_out.append(entry)
+            sym_row = self.index.db.execute(
+                "SELECT symbols FROM files WHERE path=?", (path,)).fetchone()
+            if sym_row and sym_row[0]:
+                symbols_out.extend(sym_row[0].split()[:8])
+
+        # §27–28 — essential evidence is facts/findings/rules/unresolved.
+        essential = {"facts": facts or [], "findings": findings or [],
+                     "rules": rules or []}
+        essential_tokens = estimate_tokens(json.dumps(essential, default=str))
+        over_essential = bool(budget.input_budget
+                              and essential_tokens > budget.input_budget)
+        if over_essential and allow_escalate:
+            decision = "escalate"
+            decision_reason = ("essential evidence exceeds input budget — "
+                               "escalating beyond budget (caller allowed)")
+        elif over_essential:
+            decision = "refuse"
+            decision_reason = ("essential evidence exceeds input budget "
+                               "— refusing rather than dropping evidence")
+        elif used_tokens > 0 and budget.input_budget \
+                and used_tokens + essential_tokens > budget.input_budget:
+            decision = "reduced_scope"
+            decision_reason = "optional items dropped to fit budget"
+        elif skipped:
+            decision = "reduced_scope"
+            decision_reason = "duplicates/overflow skipped"
+        else:
+            decision, decision_reason = "ok", "within budget"
+
+        pack = {
+            "task": {"description": task, "changed_files": changed},
+            "relevant_files": files_out,
+            "relevant_symbols": sorted(set(symbols_out))[:100],
+            "facts": facts or [],
+            "findings": findings or [],
+            "graph_neighborhood": graph_neighborhood or [],
+            "rules": rules or [],
+            "sources": sorted(set(sources or [])),
+            "security": {
+                # §21 contract field — redaction happens at index write
+                # (pre-FTS); packs never carry raw secrets downstream.
+                "redaction": "applied-at-index",
+                "secrets_in_pack": 0},
+            "budget": budget.to_dict(),
+            "budget_decision": decision,
+            "budget_reason": decision_reason,
+            "packed_files": len(files_out),
+            "packed_bytes": sum(f["delivered_bytes"] for f in files_out),
+            "est_input_tokens": used_tokens + essential_tokens,
+            "essential_tokens": essential_tokens,
+            "skipped_duplicates": skipped,
+            "delta_aware": previous_pack_hash is not None,
+            "reused_from_previous": reused,
+        }
+        if decision == "refuse":
+            pack["refusals"] = [{
+                "code": "PF-BUDGET-ESSENTIAL",
+                "reason": decision_reason,
+                "unlock": "raise --input-budget or narrow the task scope"}]
+            pack["relevant_files"] = []
+        else:
+            pack["refusals"] = []
+
+        if self.ledger:
+            self.ledger.record(LedgerEntry(
+                operation="context.pack",
+                context_requested=estimate_tokens(task) + sum(
+                    estimate_tokens(self.index.read(c["path"]) or "")
+                    for c in ranked),
+                context_candidate=sum(
+                    estimate_tokens(self.index.read(c["path"]) or "")
+                    for c in ranked),
+                context_selected=used_tokens,
+                context_delivered=used_tokens + essential_tokens,
+                context_skipped=skipped,
+                essential_tokens=essential_tokens,
+                optional_tokens=used_tokens,
+                input_tokens_est=used_tokens + essential_tokens,
+                token_basis="estimated",
+                extra={"budget_decision": decision},
+            ))
+        return pack
+
+    def delta_for_change(self, changed_files: list[str],
+                         budget: Budget | None = None,
+                         graph_neighborhood: list[dict] | None = None,
+                         previous_pack_hash: str | None = None,
+                         risk: str | None = None) -> dict[str, Any]:
+        """§26 — PR-style delta: diff → files → graph neighbors → rules →
+        pack. previous_pack_hash marks the delta (content-addressed dedup
+        already skips identical bodies)."""
+        return self.build(
+            task="review change", budget=budget, changed_files=changed_files,
+            graph_neighborhood=graph_neighborhood,
+            previous_pack_hash=previous_pack_hash, risk=risk)
+
+
+def pack_to_text(pack: dict[str, Any], index: SearchIndex) -> str:
+    """Render a pack for an agent prompt — file bodies bounded by what the
+    pack actually delivered (`delivered_bytes`), plus the essential
+    facts/findings/rules the pack carries. Never re-reads beyond the
+    pack's own truncation."""
+    out = [f"# task: {pack['task']['description']}"]
+    for f in pack["relevant_files"]:
+        path = f["path"] if isinstance(f, dict) else f
+        reasons = ""
+        content = None
+        if isinstance(f, dict):
+            reasons = f"  # {', '.join(f.get('reasons', []))}"
+            content = f.get("content")
+        out.append(f"\n## {path}{reasons}")
+        if content is None:
+            body = index.read(path) or ""
+            delivered = f.get("delivered_chars") if isinstance(f, dict) \
+                else None
+            content = body[:delivered] if delivered else body[:4000]
+        out.append(content)
+    essential = {"facts": pack.get("facts") or [],
+                 "findings": pack.get("findings") or [],
+                 "rules": pack.get("rules") or []}
+    if any(essential.values()):
+        out.append("\n## essential-evidence")
+        out.append(json.dumps(essential, default=str)[:8000])
+    return "\n".join(out)

platformforge/ui/__init__.py

@@ -0,0 +1,28 @@
+"""platform-forge vendored Forge UI Kit — stdlib-only interactive terminal layer.
+
+Zero dependencies, cross-platform (msvcrt on Windows, termios on
+POSIX). Every interaction has a headless equivalent so automation never
+blocks on a TTY that isn't there.
+"""
+
+from platformforge.ui.i18n import t
+from platformforge.ui.kit import (
+    UIContext,
+    confirm,
+    dashboard,
+    multi_select,
+    prompt,
+    select,
+    status_table,
+)
+
+__all__ = [
+    "UIContext",
+    "confirm",
+    "dashboard",
+    "multi_select",
+    "prompt",
+    "select",
+    "status_table",
+    "t",
+]