agentproc 0.4.0__tar.gz → 0.4.1__tar.gz

{agentproc-0.4.0 → agentproc-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.4.0
+Version: 0.4.1
 Summary: AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform
 License: MIT
 Project-URL: Homepage, https://github.com/jeffkit/agentproc

{agentproc-0.4.0 → agentproc-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentproc"
-version = "0.4.0"
+version = "0.4.1"
 description = "AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform"
 readme = "README.md"
 license = { text = "MIT" }

{agentproc-0.4.0 → agentproc-0.4.1}/src/agentproc/hub.py

@@ -158,6 +158,22 @@ def _http_get_text(url: str, timeout: int = 30) -> str:
         ) from e
 
 
+def _http_get_text_optional(url: str, timeout: int = 30) -> Optional[str]:
+    """Like _http_get_text, but returns None on 404 instead of raising.
+
+    Used for probing optional profile files (e.g. bridge.sh only exists for
+    echo-agent) and for detecting "profile does not exist" without burning
+    a rate-limited Trees API call. Delegates to _http_get_text so callers
+    that patch _http_get_text in tests automatically cover this path.
+    """
+    try:
+        return _http_get_text(url, timeout=timeout)
+    except HubError as e:
+        if e.status == 404:
+            return None
+        raise
+
+
 def _http_error_to_hub(status: int, body: str, url: str, *, is_json: bool) -> HubError:
     """Translate a GitHub HTTP error into a HubError with a remediation hint."""
     authed = bool(os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN"))
@@ -196,91 +212,123 @@ def _http_error_to_hub(status: int, body: str, url: str, *, is_json: bool) -> Hu
     )
 
 
-def _list_remote_files(subpath: str) -> List[Dict[str, str]]:
-    """List files in a hub subpath via the git tree API (1 API call for all).
+# ---------------------------------------------------------------------------
+# Repo tree — cached in-memory and on disk (24h TTL)
+# ---------------------------------------------------------------------------
+#
+# The GitHub Trees API is the one call that rate-limits anonymous users to
+# ~60/hr. Every CLI invocation is a fresh process, so an in-memory cache
+# alone doesn't help across calls. The disk cache (~/.agentproc/cache/hub/
+# tree.json) is what gives rate-limit relief: a normal user makes at most
+# ~1 Trees API call per day, regardless of how many `hub list` / `hub run`
+# invocations they run.
+
+_tree_cache: Optional[List[Dict[str, str]]] = None
+
+
+def _tree_cache_path() -> Path:
+    return _cache_root() / "tree.json"
+
+
+def _clear_tree_cache() -> None:
+    """Drop the in-memory tree cache and delete the disk cache file."""
+    global _tree_cache
+    _tree_cache = None
+    p = _tree_cache_path()
+    if p.exists():
+        try:
+            p.unlink()
+        except OSError:
+            pass
 
-    Returns list of {name, path, type, download_url}. We avoid the Contents
-    API because its rate limit is 60/hr unauthenticated; the tree API gives
-    us the entire hub/ tree in one call.
+
+def _get_tree() -> List[Dict[str, str]]:
+    """Return the full repo tree as a list of {path, type('blob'|'tree')}.
+
+    Serves from in-memory cache → disk cache (24h TTL) → GitHub API, writing
+    each layer as it misses. The API is the only rate-limited step.
     """
-    if not subpath.endswith("/"):
-        subpath = subpath + "/"
+    global _tree_cache
+    if _tree_cache is not None:
+        return _tree_cache
+
+    tp = _tree_cache_path()
+    if tp.exists():
+        try:
+            meta = json.loads(tp.read_text(encoding="utf-8"))
+            age = max(0.0, time.time() - float(meta.get("fetched_at", 0)))
+            if age < HUB_CACHE_TTL_SECS and isinstance(meta.get("tree"), list):
+                _tree_cache = [
+                    {"path": str(e.get("path", "")), "type": str(e.get("type", ""))}
+                    for e in meta["tree"] if isinstance(e, dict)
+                ]
+                return _tree_cache
+        except (ValueError, OSError):
+            pass  # corrupt cache file — refetch
+
     url = GITHUB_TREES.format(repo=HUB_REPO, ref=HUB_REF)
     data = _http_get_json(url)
-    if not isinstance(data, dict) or "tree" not in data:
+    if not isinstance(data, dict) or not isinstance(data.get("tree"), list):
         raise RuntimeError(f"unexpected tree API response: {type(data).__name__}")
+    _tree_cache = [
+        {"path": str(e.get("path", "")), "type": str(e.get("type", ""))}
+        for e in data["tree"] if isinstance(e, dict)
+    ]
+
+    try:
+        _cache_root().mkdir(parents=True, exist_ok=True)
+        tp.write_text(
+            json.dumps(
+                {"fetched_at": time.time(), "ref": HUB_REF, "tree": _tree_cache},
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass  # disk cache is best-effort
+
+    return _tree_cache
+
+
+def _list_remote_files(subpath: str) -> List[Dict[str, str]]:
+    """List top-level entries in a hub subpath (e.g. 'hub' → all profile dirs).
+
+    Uses _get_tree(), which is cached in-memory and on disk (24h TTL) so
+    repeated calls don't re-hit the rate-limited Trees API.
+    """
+    if not subpath.endswith("/"):
+        subpath = subpath + "/"
+    tree = _get_tree()
     out: List[Dict[str, str]] = []
-    for entry in data["tree"]:
-        if not isinstance(entry, dict):
-            continue
-        p = str(entry.get("path", ""))
+    seen = set()
+    for entry in tree:
+        p = entry["path"]
         if not p.startswith(subpath):
             continue
-        # type is "blob" (file) or "tree" (directory)
-        etype = "file" if entry.get("type") == "blob" else (
-            "dir" if entry.get("type") == "tree" else ""
-        )
-        # Name is the part after subpath.
         name = p[len(subpath):].split("/")[0]
+        if not name or name in seen:
+            continue
+        seen.add(name)
+        is_dir = any(t["path"] == subpath + name and t["type"] == "tree" for t in tree)
         out.append({
             "name": name,
             "path": p,
-            "type": etype,
-            # We don't use download_url from the API; we use raw URLs.
+            "type": "dir" if is_dir else "file",
             "download_url": "",
         })
-    # Deduplicate: for directory listing we only want the top-level entries.
-    seen = set()
-    unique: List[Dict[str, str]] = []
-    for e in out:
-        if e["name"] in seen:
-            continue
-        seen.add(e["name"])
-        unique.append(e)
-    return unique
-
-
-def _list_remote_profile_files(name: str) -> List[Dict[str, str]]:
-    """List the actual files inside hub/<name>/ (not just top-level entries).
-
-    Returns only file entries (type=file), with their full remote paths.
-    """
-    prefix = f"hub/{name}/"
-    url = GITHUB_TREES.format(repo=HUB_REPO, ref=HUB_REF)
-    data = _http_get_json(url)
-    if not isinstance(data, dict) or "tree" not in data:
-        raise RuntimeError(f"unexpected tree API response: {type(data).__name__}")
-    out: List[Dict[str, str]] = []
-    for entry in data["tree"]:
-        if not isinstance(entry, dict):
-            continue
-        p = str(entry.get("path", ""))
-        if not p.startswith(prefix):
-            continue
-        if entry.get("type") != "blob":
-            continue
-        # Filename is the last segment.
-        fname = p[len(prefix):].split("/")[-1]
-        out.append({"name": fname, "path": p})
     return out
 
 
 def _list_profile_names() -> List[str]:
     """List top-level profile names (directories directly under hub/).
 
-    Cheap: uses the same tree fetch as everything else, so this is one
-    network call at most (cached in-memory by urllib).
+    Cheap: uses the disk-cached tree, so this is at most ~1 Trees API call
+    per day regardless of how many times it's called.
     """
-    url = GITHUB_TREES.format(repo=HUB_REPO, ref=HUB_REF)
-    data = _http_get_json(url)
-    if not isinstance(data, dict) or "tree" not in data:
-        return []
+    tree = _get_tree()
     names: List[str] = []
     seen = set()
-    for entry in data["tree"]:
-        if not isinstance(entry, dict):
-            continue
-        p = str(entry.get("path", ""))
+    for entry in tree:
+        p = entry["path"]
         if not p.startswith("hub/"):
             continue
         seg = p[len("hub/"):].split("/")[0]
@@ -344,12 +392,19 @@ def _edit_distance(a: str, b: str) -> int:
     return prev[n]
 
 
-def _download_file(remote_path: str, local_path: Path) -> None:
-    """Download a single file from raw.githubusercontent.com."""
-    url = GITHUB_RAW.format(repo=HUB_REPO, ref=HUB_REF, path=remote_path)
-    text = _http_get_text(url)
-    local_path.parent.mkdir(parents=True, exist_ok=True)
-    local_path.write_text(text, encoding="utf-8")
+# Every hub profile is this fixed set of files (see hub/README.md):
+#   profile.yaml (required) + bridge.py + bridge.js + README.md,
+# with echo-agent additionally shipping bridge.sh. We fetch them directly
+# via raw.githubusercontent.com (CDN, not rate-limited) so `hub run` never
+# calls the GitHub Trees API in the happy path. If a future profile adds a
+# new file type, extend this list.
+_PROFILE_FILE_CANDIDATES = (
+    "profile.yaml",
+    "bridge.py",
+    "bridge.js",
+    "bridge.sh",
+    "README.md",
+)
 
 
 # ---------------------------------------------------------------------------
@@ -363,9 +418,17 @@ def fetch_profile(
 ) -> Path:
     """Fetch a profile directory to local cache. Returns the cache path.
 
+    Fetches files directly via raw.githubusercontent.com (CDN, not
+    rate-limited) — no GitHub Trees API call in the happy path. Only an
+    unknown profile name (profile.yaml 404) falls back to the disk-cached
+    tree to produce a "did you mean" suggestion.
+
     If a fresh cache exists (younger than HUB_CACHE_TTL_SECS) and refresh
     is False, returns immediately without network access.
     """
+    if refresh:
+        _clear_tree_cache()
+
     age = _cache_age_secs(name)
     cached = cache_dir(name)
     profile_yaml = cached / "profile.yaml"
@@ -381,11 +444,15 @@ def fetch_profile(
         else:
             on_log(f"fetching profile '{name}' from {HUB_REPO}:{HUB_REF}...")
 
-    entries = _list_remote_profile_files(name)
-    if not entries:
-        # getTree succeeded (otherwise _list_remote_profile_files would have
-        # raised HubError already). So the name is genuinely wrong — surface
-        # the list of available names so the user can correct the typo.
+    # Probe profile.yaml via raw URL. raw.githubusercontent.com is CDN-backed
+    # and not subject to the 60/hr anonymous API limit, so this does not burn
+    # rate-limit budget.
+    probe_url = GITHUB_RAW.format(repo=HUB_REPO, ref=HUB_REF, path=f"hub/{name}/profile.yaml")
+    probe = _http_get_text_optional(probe_url)
+    if probe is None:
+        # profile.yaml 404 → the name is wrong. Fall back to the (disk-cached)
+        # tree to produce a "did you mean" suggestion. This is the only path
+        # that may call the Trees API for `hub run`, and it's cached for 24h.
         known: List[str] = []
         try:
             known = _list_profile_names()
@@ -405,16 +472,26 @@ def fetch_profile(
             hint="\n".join(lines),
         )
 
-    # Clear cache, then re-download every file in the profile directory.
+    # Clear cache, then download the candidate file set via raw URLs.
     if cached.exists():
         shutil.rmtree(cached)
     cached.mkdir(parents=True, exist_ok=True)
 
-    for entry in entries:
-        local = cached / entry["name"]
-        _download_file(entry["path"], local)
+    # profile.yaml already fetched via the probe.
+    (cached / "profile.yaml").write_text(probe, encoding="utf-8")
+    if on_log:
+        on_log("  - profile.yaml")
+
+    for fname in _PROFILE_FILE_CANDIDATES:
+        if fname == "profile.yaml":
+            continue
+        url = GITHUB_RAW.format(repo=HUB_REPO, ref=HUB_REF, path=f"hub/{name}/{fname}")
+        text = _http_get_text_optional(url)
+        if text is None:
+            continue  # optional file not present for this profile
+        (cached / fname).write_text(text, encoding="utf-8")
         if on_log:
-            on_log(f"  - {entry['name']}")
+            on_log(f"  - {fname}")
 
     _write_cache_meta(name)
     return cached

{agentproc-0.4.0 → agentproc-0.4.1}/src/agentproc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.4.0
+Version: 0.4.1
 Summary: AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform
 License: MIT
 Project-URL: Homepage, https://github.com/jeffkit/agentproc

{agentproc-0.4.0 → agentproc-0.4.1}/tests/test_hub.py

@@ -19,6 +19,7 @@ import pytest
 from agentproc import hub as hub_mod
 from agentproc.hub import (
     HUB_CACHE_TTL_SECS,
+    HubError,
     cache_dir,
     _cache_root,
     _cache_age_secs,
@@ -92,23 +93,33 @@ def _make_fake_http_get_json(tree=None):
 
 
 def _make_fake_http_get_text(contents=None):
-    """Return a callable that emulates _http_get_text for raw file fetches."""
+    """Return a callable that emulates _http_get_text for raw file fetches.
+
+    Unmatched URLs raise a HubError(404) so that _http_get_text_optional
+    (which wraps _http_get_text and swallows 404) returns None — modelling
+    an optional profile file that doesn't exist (e.g. bridge.sh on a
+    non-echo profile) or a wrong profile name.
+    """
     contents = contents or FAKE_FILE_CONTENTS
     def fake(url, timeout=30):
         # Extract path from raw URL: .../agentproc/main/hub/echo-agent/profile.yaml
         for path, content in contents.items():
             if url.endswith(path):
                 return content
-        raise AssertionError(f"unexpected text URL: {url}")
+        raise HubError(f"fetch failed (HTTP 404) for {url}", status=404)
     return fake
 
 
 @pytest.fixture
 def isolated_cache(monkeypatch, tmp_path):
-    """Redirect cache to a tmp dir."""
+    """Redirect cache to a tmp dir and reset the module-level tree cache."""
     cache_root = tmp_path / "cache" / "hub"
     monkeypatch.setattr(hub_mod, "_cache_root", lambda: cache_root)
     monkeypatch.setattr(hub_mod, "cache_dir", lambda name: cache_root / name)
+    # _tree_cache is module-global and would otherwise leak across tests
+    # (each test uses a different fake tree). Reset it so every test starts
+    # cold and _get_tree re-reads from the (fresh) fake _http_get_json.
+    hub_mod._clear_tree_cache()
     return tmp_path
 
 
@@ -159,9 +170,38 @@ class TestFetchProfile:
         assert "README.md" in names
         assert ".cache-meta.json" in names
 
+    def test_fetch_happy_path_does_not_call_trees_api(self, isolated_cache):
+        # `hub run` fetches profile files via raw.githubusercontent.com (CDN,
+        # not rate-limited). A known profile must not trigger any
+        # api.github.com call — that's the whole point of the rate-limit fix.
+        json_calls = {"n": 0}
+
+        def assert_no_json(url, timeout=30):
+            json_calls["n"] += 1
+            raise AssertionError(f"unexpected Trees API call: {url}")
+
+        with patch("agentproc.hub._http_get_json", side_effect=assert_no_json), \
+             patch("agentproc.hub._http_get_text", side_effect=_make_fake_http_get_text()):
+            hub_mod.fetch_profile("echo-agent")
+        assert json_calls["n"] == 0
+
+    def test_fetch_skips_optional_files_that_404(self, isolated_cache):
+        # claude-code has no bridge.sh in the fixtures → the 404 is swallowed
+        # and bridge.sh is not stored, while the four standard files are.
+        with patch("agentproc.hub._http_get_json", side_effect=_make_fake_http_get_json()), \
+             patch("agentproc.hub._http_get_text", side_effect=_make_fake_http_get_text()):
+            p = hub_mod.fetch_profile("claude-code")
+        names = [x.name for x in p.iterdir()]
+        assert "profile.yaml" in names
+        assert "bridge.py" in names
+        assert "bridge.js" in names
+        assert "README.md" in names
+        assert "bridge.sh" not in names
+
     def test_fetch_unknown_profile_raises(self, isolated_cache):
         empty_tree = [{"path": "hub", "type": "tree"}]
-        with patch("agentproc.hub._http_get_json", side_effect=_make_fake_http_get_json(empty_tree)):
+        with patch("agentproc.hub._http_get_json", side_effect=_make_fake_http_get_json(empty_tree)), \
+             patch("agentproc.hub._http_get_text", side_effect=_make_fake_http_get_text()):
             with pytest.raises(RuntimeError, match="not found in hub"):
                 hub_mod.fetch_profile("nope")
 
@@ -186,18 +226,20 @@ class TestFetchProfile:
             assert call_count["text"] == first_text  # no new file downloads
 
     def test_refresh_forces_refetch(self, isolated_cache):
-        call_count = {"json": 0}
+        call_count = {"text": 0}
 
-        def counting_json(url, timeout=30):
-            call_count["json"] += 1
-            return _make_fake_http_get_json()(url, timeout)
+        def counting_text(url, timeout=30):
+            call_count["text"] += 1
+            return _make_fake_http_get_text()(url, timeout)
 
-        with patch("agentproc.hub._http_get_json", side_effect=counting_json), \
-             patch("agentproc.hub._http_get_text", side_effect=_make_fake_http_get_text()):
+        with patch("agentproc.hub._http_get_json", side_effect=_make_fake_http_get_json()), \
+             patch("agentproc.hub._http_get_text", side_effect=counting_text):
             hub_mod.fetch_profile("echo-agent")
-            first = call_count["json"]
+            first_text = call_count["text"]
             hub_mod.fetch_profile("echo-agent", refresh=True)
-            assert call_count["json"] > first
+            # hub run fetches files via raw URLs (CDN), not the rate-limited
+            # Trees API — so a refresh re-fetches the file set, not the tree.
+            assert call_count["text"] > first_text
 
     def test_fetch_overwrites_old_files(self, isolated_cache):
         # First fetch.
@@ -250,6 +292,24 @@ class TestListProfiles:
         assert not any(n.startswith("_") for n in names), names
         assert "_shared" not in names
 
+    def test_tree_disk_cached_across_calls(self, isolated_cache):
+        # First list_profiles hits the Trees API (json 0→1) and writes
+        # ~/.agentproc/cache/hub/tree.json. A second call reuses the cached
+        # tree and must not make another API call.
+        json_calls = {"n": 0}
+
+        def counting_json(url, timeout=30):
+            json_calls["n"] += 1
+            return _make_fake_http_get_json()(url, timeout)
+
+        with patch("agentproc.hub._http_get_json", side_effect=counting_json), \
+             patch("agentproc.hub._http_get_text", side_effect=_make_fake_http_get_text()):
+            hub_mod.list_profiles()
+            assert json_calls["n"] == 1
+            assert (hub_mod._cache_root() / "tree.json").exists()
+            hub_mod.list_profiles()
+            assert json_calls["n"] == 1, "second call hit the Trees API again"
+
 
 # ---------------------------------------------------------------------------
 # show_readme