agentpack-cli 0.3.31__tar.gz → 0.3.33__tar.gz

{agentpack_cli-0.3.31 → agentpack_cli-0.3.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.31
+Version: 0.3.33
 Summary: Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows.
 Project-URL: Homepage, https://github.com/vishal2612200/agentpack
 Project-URL: Documentation, https://vishal2612200.github.io/agentpack/
@@ -164,7 +164,7 @@ agentpack task set "fix billing webhook retry handling"
 agentpack pack --task auto
 ```
 
-AgentPack writes local context under `.agentpack/`, including selected files, omitted-file receipts, freshness checks, and token stats.
+AgentPack writes local context under `.agentpack/`, including selected files, omitted-file receipts, freshness checks, token stats, and `.agentpack/citations.json` source provenance for the packed claims.
 It reuses cached file summaries and snapshot metadata so repeated packs do not start from zero.
 
 ## What AgentPack Gives Your Agent
@@ -174,28 +174,41 @@ It reuses cached file summaries and snapshot metadata so repeated packs do not s
 - likely tests and commands
 - repo rules and agent instructions
 - compact context pack under budget
+- curated broad repo context for review/share/audit tasks without a separate bundle command
+- citation-backed provenance for packed claims and review artifacts
+- review preflight and staged review prompts for file-grounded PR review
+- local memory, evaluation, and runtime/performance diagnostics for repeat workflows
 - cached summaries for faster repeated orientation
 - omitted-file receipts for review
 - freshness warnings when task or git state changes
 - local benchmark data when selected context misses real changed files
 
+## What's Current In 0.3.33
+
+- Grounded broad context now supports review, sharing, audit, and repo-overview tasks with citation checks and scoped safety gates.
+- Review workflows now push agents through preflight, understanding, and findings stages instead of letting review prompts answer inline.
+- Pack and route fallbacks are stricter about stale context, missing MCP surfaces, and source provenance.
+- The npm wrapper preserves the selected Python descriptor when creating the versioned CLI environment.
+- Packaged Codex plugin metadata, docs URLs, and scanner automation now score cleanly in local HOL scans.
+- Light fixture recall improved by keeping correlated source/deploy summaries and using concrete owner terms in fixture tasks.
+
 ## Proof So Far
 
-AgentPack's current public benchmark checks one narrow thing: whether selected context overlaps with files actually changed in historical commits.
+AgentPack's current public benchmark checks one narrow thing: whether selected context overlaps with files actually changed in historical commits. Treat it as evidence for a ranked starting map, not proof that any agent will finish every task faster or better.
 
 Current scoped result:
 
 | Signal | Result | Developer meaning |
 |---|---:|---|
-| Public commit cases | 108 | real historical file-selection checks |
-| Average recall | 66.0% | did AgentPack include files that mattered? |
-| Token precision | 51.1% | how much of pack was useful instead of noise? |
+| Public commit cases | 107 | real historical file-selection checks |
+| Average recall | 65.7% | did AgentPack include files that mattered? |
+| Token precision | 51.4% | how much of pack was useful instead of noise? |
 | Pack p50 | 315 tokens | typical compact starting context |
 | Pack p95 | 1,137 tokens | larger but still bounded starting context |
 
-Source: [`benchmarks/results/2026-06-14-public.md`](benchmarks/results/2026-06-14-public.md). Benchmark guide: [`docs/benchmarking.md`](docs/benchmarking.md).
+Source: [`benchmarks/results/2026-06-25-public.md`](benchmarks/results/2026-06-25-public.md). Benchmark guide: [`docs/benchmarking.md`](docs/benchmarking.md).
 
-This is useful but not magic. It says AgentPack often gets meaningful files into a small pack. It does not claim every agent finishes faster or writes better code. Agent success A/B benchmarks should report task success, tool calls, token cost, and time-to-first-correct-file.
+This is useful but not magic. It says AgentPack often gets meaningful files into a small pack. It does not replace source inspection, tests, runtime evidence, or review. Agent success A/B benchmarks should report task success, tool calls, token cost, validation quality, and time-to-first-correct-file.
 
 ## What We Want To Prove Next
 
@@ -278,7 +291,7 @@ Do not use AgentPack when:
 
 ## How It Works
 
-AgentPack scans repo locally, builds and reuses file summaries, indexes local skills and rules, combines filename, git, config, dependency, summary, and benchmark signals, ranks likely files for task, then renders a compact context pack.
+AgentPack scans repo locally, builds and reuses file summaries, indexes local skills and rules, combines filename, git, config, dependency, summary, memory, and benchmark signals, ranks likely files for task, then renders a compact context pack. Review/share/audit tasks also get broad module summaries and inventory receipts in the same artifact.
 
 It can expose the same workflow through CLI, markdown files, MCP tools, hooks, plugins, and CI.
 
@@ -333,7 +346,7 @@ pipx ensurepath
 
 ## Status
 
-Alpha: `0.3.25`.
+Alpha: `0.3.33`.
 
 Works, tested, and used in real sessions. Python and JavaScript/TypeScript have strongest support. APIs may change before 1.0.
 

{agentpack_cli-0.3.31 → agentpack_cli-0.3.33}/README.md

@@ -117,7 +117,7 @@ agentpack task set "fix billing webhook retry handling"
 agentpack pack --task auto
 ```
 
-AgentPack writes local context under `.agentpack/`, including selected files, omitted-file receipts, freshness checks, and token stats.
+AgentPack writes local context under `.agentpack/`, including selected files, omitted-file receipts, freshness checks, token stats, and `.agentpack/citations.json` source provenance for the packed claims.
 It reuses cached file summaries and snapshot metadata so repeated packs do not start from zero.
 
 ## What AgentPack Gives Your Agent
@@ -127,28 +127,41 @@ It reuses cached file summaries and snapshot metadata so repeated packs do not s
 - likely tests and commands
 - repo rules and agent instructions
 - compact context pack under budget
+- curated broad repo context for review/share/audit tasks without a separate bundle command
+- citation-backed provenance for packed claims and review artifacts
+- review preflight and staged review prompts for file-grounded PR review
+- local memory, evaluation, and runtime/performance diagnostics for repeat workflows
 - cached summaries for faster repeated orientation
 - omitted-file receipts for review
 - freshness warnings when task or git state changes
 - local benchmark data when selected context misses real changed files
 
+## What's Current In 0.3.33
+
+- Grounded broad context now supports review, sharing, audit, and repo-overview tasks with citation checks and scoped safety gates.
+- Review workflows now push agents through preflight, understanding, and findings stages instead of letting review prompts answer inline.
+- Pack and route fallbacks are stricter about stale context, missing MCP surfaces, and source provenance.
+- The npm wrapper preserves the selected Python descriptor when creating the versioned CLI environment.
+- Packaged Codex plugin metadata, docs URLs, and scanner automation now score cleanly in local HOL scans.
+- Light fixture recall improved by keeping correlated source/deploy summaries and using concrete owner terms in fixture tasks.
+
 ## Proof So Far
 
-AgentPack's current public benchmark checks one narrow thing: whether selected context overlaps with files actually changed in historical commits.
+AgentPack's current public benchmark checks one narrow thing: whether selected context overlaps with files actually changed in historical commits. Treat it as evidence for a ranked starting map, not proof that any agent will finish every task faster or better.
 
 Current scoped result:
 
 | Signal | Result | Developer meaning |
 |---|---:|---|
-| Public commit cases | 108 | real historical file-selection checks |
-| Average recall | 66.0% | did AgentPack include files that mattered? |
-| Token precision | 51.1% | how much of pack was useful instead of noise? |
+| Public commit cases | 107 | real historical file-selection checks |
+| Average recall | 65.7% | did AgentPack include files that mattered? |
+| Token precision | 51.4% | how much of pack was useful instead of noise? |
 | Pack p50 | 315 tokens | typical compact starting context |
 | Pack p95 | 1,137 tokens | larger but still bounded starting context |
 
-Source: [`benchmarks/results/2026-06-14-public.md`](benchmarks/results/2026-06-14-public.md). Benchmark guide: [`docs/benchmarking.md`](docs/benchmarking.md).
+Source: [`benchmarks/results/2026-06-25-public.md`](benchmarks/results/2026-06-25-public.md). Benchmark guide: [`docs/benchmarking.md`](docs/benchmarking.md).
 
-This is useful but not magic. It says AgentPack often gets meaningful files into a small pack. It does not claim every agent finishes faster or writes better code. Agent success A/B benchmarks should report task success, tool calls, token cost, and time-to-first-correct-file.
+This is useful but not magic. It says AgentPack often gets meaningful files into a small pack. It does not replace source inspection, tests, runtime evidence, or review. Agent success A/B benchmarks should report task success, tool calls, token cost, validation quality, and time-to-first-correct-file.
 
 ## What We Want To Prove Next
 
@@ -231,7 +244,7 @@ Do not use AgentPack when:
 
 ## How It Works
 
-AgentPack scans repo locally, builds and reuses file summaries, indexes local skills and rules, combines filename, git, config, dependency, summary, and benchmark signals, ranks likely files for task, then renders a compact context pack.
+AgentPack scans repo locally, builds and reuses file summaries, indexes local skills and rules, combines filename, git, config, dependency, summary, memory, and benchmark signals, ranks likely files for task, then renders a compact context pack. Review/share/audit tasks also get broad module summaries and inventory receipts in the same artifact.
 
 It can expose the same workflow through CLI, markdown files, MCP tools, hooks, plugins, and CI.
 
@@ -286,7 +299,7 @@ pipx ensurepath
 
 ## Status
 
-Alpha: `0.3.25`.
+Alpha: `0.3.33`.
 
 Works, tested, and used in real sessions. Python and JavaScript/TypeScript have strongest support. APIs may change before 1.0.
 

{agentpack_cli-0.3.31 → agentpack_cli-0.3.33}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.31"
+version = "0.3.33"
 description = "Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows."
 readme = "README.md"
 requires-python = ">=3.10"

{agentpack_cli-0.3.31 → agentpack_cli-0.3.33}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.3.31"
+__version__ = "0.3.33"

agentpack_cli-0.3.33/src/agentpack/analysis/broad_context.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import PurePosixPath
+from typing import Any
+
+from agentpack.core.citations import file_citation
+from agentpack.core.models import BroadContext, Citation, FileInfo, ModuleSummary
+from agentpack.core.token_estimator import estimate_tokens
+
+_CONFIG_NAMES = {
+    "pyproject.toml", "package.json", "pnpm-workspace.yaml", "yarn.lock", "package-lock.json",
+    "requirements.txt", "poetry.lock", "setup.py", "setup.cfg", "tox.ini", "ruff.toml",
+    "tsconfig.json", "vite.config.ts", "next.config.js", "dockerfile", "docker-compose.yml",
+}
+_ENTRYPOINT_PARTS = ("main", "app", "cli", "server", "index", "routes", "router", "api")
+_TEST_PARTS = ("test", "tests", "spec", "specs")
+_DOC_EXTS = {".md", ".rst", ".txt"}
+
+
+def build_broad_context(
+    *,
+    files: list[FileInfo],
+    summaries: dict[str, Any],
+    scored: list[tuple[Any, float, list[str]]],
+    intent: str,
+    max_module_summaries: int,
+    max_inventory_files: int,
+    budget_tokens: int,
+) -> BroadContext:
+    """Build curated broad repo context without extra file reads."""
+    if budget_tokens <= 0:
+        budget_tokens = 1_000
+    score_map = {fi.path: score for fi, score, _reasons in scored}
+    packable = sorted(
+        (fi for fi in files if not fi.ignored and not fi.binary),
+        key=lambda fi: (-score_map.get(fi.path, 0.0), fi.path),
+    )
+    entrypoints: list[str] = []
+    configs: list[str] = []
+    docs: list[str] = []
+    tests: list[str] = []
+    inventory: list[str] = []
+    omitted: list[str] = []
+
+    modules: dict[str, list[FileInfo]] = defaultdict(list)
+    for fi in packable:
+        module = _module_for(fi.path)
+        modules[module].append(fi)
+        category = _category(fi.path)
+        if category == "entrypoint" and len(entrypoints) < 25:
+            entrypoints.append(fi.path)
+        elif category == "config" and len(configs) < 25:
+            configs.append(fi.path)
+        elif category == "doc" and len(docs) < 25:
+            docs.append(fi.path)
+        elif category == "test" and len(tests) < 25:
+            tests.append(fi.path)
+        if len(inventory) < max_inventory_files:
+            inventory.append(fi.path)
+        else:
+            omitted.append(fi.path)
+
+    ranked_modules = sorted(
+        modules.items(),
+        key=lambda item: (-_module_score(item[1], score_map), item[0]),
+    )
+    module_summaries: list[ModuleSummary] = []
+    for module, module_files in ranked_modules[:max_module_summaries]:
+        module_summaries.append(_summarize_module(module, module_files, summaries, score_map))
+    for module, module_files in ranked_modules[max_module_summaries:]:
+        omitted.extend(fi.path for fi in module_files[:3])
+
+    context = BroadContext(
+        intent=intent,
+        inventory_files=len(packable),
+        module_summaries=module_summaries,
+        entrypoints=_dedupe(entrypoints),
+        configs=_dedupe(configs),
+        docs=_dedupe(docs),
+        tests=_dedupe(tests),
+        inventory=_dedupe(inventory),
+        semantic_clusters=_semantic_clusters(packable, summaries, score_map),
+        omitted_by_budget=_dedupe(omitted),
+        citations=_inventory_citations(packable, inventory),
+    )
+    return _trim_to_budget(context, budget_tokens)
+
+
+def _module_for(path: str) -> str:
+    parts = PurePosixPath(path).parts
+    if not parts:
+        return "."
+    if parts[0] in {"src", "tests", "docs"} and len(parts) > 1:
+        return "/".join(parts[:2])
+    if parts[0] in {"apps", "packages", "services", "libs"} and len(parts) > 1:
+        return "/".join(parts[:2])
+    return parts[0]
+
+
+def _category(path: str) -> str:
+    lower = path.lower()
+    name = lower.rsplit("/", 1)[-1]
+    suffix = PurePosixPath(lower).suffix
+    parts = set(PurePosixPath(lower).parts)
+    stem = PurePosixPath(lower).stem
+    if name in _CONFIG_NAMES or "config" in stem:
+        return "config"
+    if suffix in _DOC_EXTS:
+        return "doc"
+    if parts & set(_TEST_PARTS) or stem.startswith("test_") or stem.endswith("_test") or stem.endswith(".test"):
+        return "test"
+    if any(part in stem for part in _ENTRYPOINT_PARTS):
+        return "entrypoint"
+    return "file"
+
+
+def _module_score(files: list[FileInfo], score_map: dict[str, float]) -> float:
+    return sum(score_map.get(fi.path, 0.0) for fi in files[:20]) + min(len(files), 20)
+
+
+def _summarize_module(
+    module: str,
+    files: list[FileInfo],
+    summaries: dict[str, Any],
+    score_map: dict[str, float],
+) -> ModuleSummary:
+    ordered = sorted(files, key=lambda fi: (-score_map.get(fi.path, 0.0), fi.path))
+    languages = sorted({fi.language for fi in files if fi.language})[:6]
+    key_files = [fi.path for fi in ordered[:8]]
+    roles: list[str] = []
+    for fi in ordered[:12]:
+        summary = summaries.get(fi.path) or {}
+        role = summary.get("role") or summary.get("domain") or summary.get("summary")
+        if isinstance(role, str) and role.strip():
+            roles.append(role.strip().splitlines()[0][:120])
+    text = "; ".join(_dedupe(roles)[:3])
+    return ModuleSummary(
+        path=module,
+        files=len(files),
+        tokens=sum(fi.estimated_tokens for fi in files),
+        languages=languages,
+        key_files=key_files,
+        summary=text or "Repository area with no cached semantic summary yet.",
+        citations=[
+            file_citation(
+                fi,
+                kind="summary",
+                claim_id=f"module:{module}:{fi.path}",
+                note=f"module summary source for {module}",
+            )
+            for fi in ordered[:5]
+        ],
+    )
+
+
+def _semantic_clusters(
+    files: list[FileInfo],
+    summaries: dict[str, Any],
+    score_map: dict[str, float],
+    limit: int = 12,
+) -> list[str]:
+    buckets: dict[str, list[str]] = defaultdict(list)
+    for fi in sorted(files, key=lambda item: (-score_map.get(item.path, 0.0), item.path)):
+        summary = summaries.get(fi.path) or {}
+        label = summary.get("role") or summary.get("domain")
+        if not isinstance(label, str) or not label.strip():
+            continue
+        key = label.strip().splitlines()[0][:60]
+        if len(buckets[key]) < 6:
+            buckets[key].append(fi.path)
+    ranked = sorted(buckets.items(), key=lambda item: (-len(item[1]), item[0]))[:limit]
+    return [f"{label}: " + ", ".join(paths) for label, paths in ranked]
+
+
+def _trim_to_budget(context: BroadContext, budget_tokens: int) -> BroadContext:
+    while estimate_tokens(context.model_dump_json()) > budget_tokens and context.module_summaries:
+        context.omitted_by_budget.extend(context.module_summaries.pop().key_files[:3])
+    while estimate_tokens(context.model_dump_json()) > budget_tokens and context.inventory:
+        context.omitted_by_budget.append(context.inventory.pop())
+    while estimate_tokens(context.model_dump_json()) > budget_tokens and context.semantic_clusters:
+        context.semantic_clusters.pop()
+    if len(context.omitted_by_budget) > 100:
+        context.omitted_by_budget = context.omitted_by_budget[:100]
+    return context
+
+
+def _dedupe(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for value in values:
+        if value not in seen:
+            seen.add(value)
+            out.append(value)
+    return out
+
+
+def _inventory_citations(files: list[FileInfo], inventory: list[str]) -> list[Citation]:
+    by_path = {fi.path: fi for fi in files}
+    citations: list[Citation] = []
+    for path in inventory[:25]:
+        fi = by_path.get(path)
+        if fi is None:
+            continue
+        citations.append(
+            file_citation(
+                fi,
+                kind="summary",
+                claim_id=f"broad-context:{path}",
+                note="broad context inventory source",
+            )
+        )
+    return citations

agentpack_cli-0.3.33/src/agentpack/analysis/context_intent.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+
+ContextIntent = Literal["coding_task", "review", "share", "repo_overview", "audit"]
+
+_AUDIT_TERMS = ("audit", "security review", "risk review", "architecture review")
+_REVIEW_TERMS = ("review", "pr", "pull request", "code review")
+_SHARE_TERMS = ("share", "handoff", "promptable artifact", "broad context")
+_OVERVIEW_TERMS = ("repo overview", "repository overview", "explain repo", "understand repo", "map repo")
+
+
+def infer_context_intent(task: str, *, task_mode: str | None = None) -> ContextIntent:
+    text = " ".join((task or "").lower().replace("_", " ").replace("-", " ").split())
+    mode = (task_mode or "").lower()
+    if mode == "pr_review" or _has_any(text, _REVIEW_TERMS):
+        if _has_any(text, _AUDIT_TERMS):
+            return "audit"
+        return "review"
+    if _has_any(text, _AUDIT_TERMS):
+        return "audit"
+    if _has_any(text, _SHARE_TERMS):
+        return "share"
+    if _has_any(text, _OVERVIEW_TERMS):
+        return "repo_overview"
+    return "coding_task"
+
+
+def broad_context_enabled(config_value: str, intent: ContextIntent) -> bool:
+    value = (config_value or "auto").strip().lower()
+    if value == "off":
+        return False
+    if value == "on":
+        return True
+    return intent in {"review", "share", "repo_overview", "audit"}
+
+
+def _has_any(text: str, terms: tuple[str, ...]) -> bool:
+    return any(re.search(rf"(?<![a-z0-9_]){re.escape(term)}(?![a-z0-9_])", text) for term in terms)

{agentpack_cli-0.3.31 → agentpack_cli-0.3.33}/src/agentpack/analysis/ranking.py

@@ -283,6 +283,11 @@ _FILENAME_CORROBORATION_PREFIXES = (
     "workspace match",
 )
 
+_GENERATED_AGENT_ARTIFACT_PREFIXES = (
+    ".agentpack/",
+    ".agent/",
+)
+
 
 def _add_keyword_weight(weights: dict[str, float], keyword: str, weight: float) -> None:
     weights[keyword] = max(weights.get(keyword, 0.0), weight)
@@ -1277,6 +1282,16 @@ def _has_strong_structural_reason(reasons: list[str]) -> bool:
     )
 
 
+def _is_generated_agent_artifact(path: str) -> bool:
+    return path.startswith(_GENERATED_AGENT_ARTIFACT_PREFIXES)
+
+
+def _generated_agent_artifact_score(score: float, *, changed: bool) -> float:
+    if changed:
+        return min(score, 160.0)
+    return min(score * 0.25, 80.0)
+
+
 def _keyword_only_false_positive(path: str, reasons: list[str], content_hits: int) -> bool:
     if _is_test_file(path):
         return False
@@ -1617,6 +1632,10 @@ def score_files(
             score = max(0.0, score * 0.72)
             reasons.append("likely false positive: keyword-only match")
 
+        if _is_generated_agent_artifact(fi.path):
+            score = _generated_agent_artifact_score(score, changed=fi.path in changed_paths)
+            reasons.append("generated agent artifact dampening")
+
         results.append((fi, score, reasons))
 
     return results