agentproc 0.2.1__tar.gz → 0.3.0__tar.gz

{agentproc-0.2.1 → agentproc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.2.1
+Version: 0.3.0
 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.2.1 → agentproc-0.3.0}/pyproject.toml

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

{agentproc-0.2.1 → agentproc-0.3.0}/src/agentproc/__init__.py

@@ -47,8 +47,35 @@ __all__ = [
     "load_history",
     "append_history",
     "session_file_path",
+    "__version__",
 ]
 
+
+def _read_version() -> str:
+    try:
+        from importlib.metadata import version, PackageNotFoundError
+        try:
+            return version("agentproc")
+        except PackageNotFoundError:
+            pass
+    except ImportError:
+        pass
+    try:
+        from pathlib import Path
+        toml_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        if toml_path.exists():
+            import re
+            text = toml_path.read_text(encoding="utf-8")
+            m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
+            if m:
+                return m.group(1)
+    except Exception:
+        pass
+    return "0.0.0+unknown"
+
+
+__version__ = _read_version()
+
 PROTOCOL_VERSION = "0.1"
 
 

{agentproc-0.2.1 → agentproc-0.3.0}/src/agentproc/cli.py

@@ -25,7 +25,20 @@ from .runner import (
 
 
 def _read_pkg_version() -> str:
-    """Read version from pyproject.toml at runtime (zero-dep)."""
+    """Read installed package version.
+
+    Primary: importlib.metadata (works after pip/pipx install).
+    Fallback: parse pyproject.toml (works in source checkout, dev mode).
+    """
+    try:
+        from importlib.metadata import version, PackageNotFoundError
+        try:
+            return version("agentproc")
+        except PackageNotFoundError:
+            pass
+    except ImportError:
+        pass
+    # Fallback for source checkout (development, not installed).
     try:
         toml_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
         if toml_path.exists():
@@ -261,56 +274,146 @@ def show_version() -> None:
 
 
 # ---------------------------------------------------------------------------
-# Main
+# Hub subcommand dispatcher
 # ---------------------------------------------------------------------------
 
-def main(argv: Optional[List[str]] = None) -> int:
-    if argv is None:
-        argv = sys.argv[1:]
+def _run_hub_subcommand(args: List[str]) -> int:
+    """Handle `agentproc hub <list|show|install|run> [args]`."""
+    from . import hub as hub_mod
 
-    parser = build_parser()
-    opts = parser.parse_args(argv)
+    if not args or args[0] in ("-h", "--help"):
+        _show_hub_help()
+        return 0
 
-    if opts.help:
-        show_help()
+    sub = args[0]
+    rest = args[1:]
+
+    # Common flag
+    refresh = "--refresh" in rest
+    positional = [a for a in rest if not a.startswith("--")]
+
+    def _log(msg: str) -> None:
+        sys.stderr.write(msg + "\n")
+
+    if sub == "list":
+        profiles = hub_mod.list_profiles(on_log=_log)
+        sys.stdout.write("Available profiles in the official hub:\n\n")
+        for p in profiles:
+            sys.stdout.write(
+                f"  {p['name']:<15} {p['tested']:<12} {p['description'][:60]}\n"
+            )
+        sys.stdout.write('\nRun `agentproc hub run <name> -p "hi"` to use one.\n')
         return 0
-    if opts.version:
-        show_version()
+
+    if sub == "show":
+        if not positional:
+            sys.stderr.write("error: hub show requires a profile name\n")
+            return 2
+        readme = hub_mod.show_readme(positional[0], refresh=refresh, on_log=_log)
+        sys.stdout.write(readme)
+        if not readme.endswith("\n"):
+            sys.stdout.write("\n")
         return 0
 
-    if not opts.profile:
-        sys.stderr.write("error: --profile is required\n\n")
-        show_help()
+    if sub == "install":
+        if not positional:
+            sys.stderr.write("error: hub install requires a profile name\n")
+            return 2
+        hub_mod.install_profile(positional[0], Path.cwd(), refresh=refresh, on_log=_log)
+        return 0
+
+    if sub == "run":
+        if not positional:
+            sys.stderr.write("error: hub run requires a profile name\n")
+            return 2
+        profile_name = positional[0]
+        cache_dir = hub_mod.fetch_profile(profile_name, refresh=refresh, on_log=_log)
+        profile_path = str(cache_dir / "profile.yaml")
+
+        # Re-parse remaining args (excluding the profile name) as runner options.
+        parser = build_parser()
+        # Drop the first positional (profile name) and --refresh from rest.
+        runner_args = [a for i, a in enumerate(rest) if not (
+            (not a.startswith("--") and i == 0) or a == "--refresh"
+        )]
+        opts = parser.parse_args(runner_args)
+
+        if not opts.prompt and not opts.stdin:
+            sys.stderr.write("error: hub run requires --prompt <text> or --stdin\n")
+            return 2
+
+        return _run_agent_with_profile(profile_path, opts)
+
+    sys.stderr.write(f"error: unknown hub subcommand: {sub}\n\n")
+    _show_hub_help()
+    return 2
+
+
+def _show_hub_help() -> None:
+    sys.stdout.write("""agentproc hub — manage profiles from the official Hub
+
+Usage:
+  agentproc hub list                       List all profiles in the hub
+  agentproc hub show <name>                Show a profile's README
+  agentproc hub install <name>             Copy a profile to the current directory
+  agentproc hub run <name> [run-options]   Fetch (if needed) and run a profile
+
+Hub run options (same as the regular --profile runner):
+  -p, --prompt <text>          User message (or use --stdin)
+  --cwd <path>                 Override profile.cwd (default: current dir)
+  --env KEY=VALUE              Extra env var (repeatable)
+  --session <id>               Previous session id for multi-turn
+  --timeout <secs>             Override profile.timeout_secs
+  --no-stream                  Disable streaming
+  --verbose / --quiet          Protocol line visibility (default: verbose)
+  --stdin                      Read prompt from stdin
+
+Common options:
+  --refresh                    Force re-fetch from GitHub (ignore cache)
+  -h, --help                   Show this help
+
+Examples:
+  agentproc hub list
+  agentproc hub run echo-agent -p "hello"
+  cd ~/projects/my-app && agentproc hub run claude-code -p "explain this" --env ANTHROPIC_API_KEY=$KEY
+  agentproc hub show codex
+  agentproc hub install agy
+
+Profiles are cached at ~/.agentproc/cache/hub/<name>/ (24h TTL).
+""")
+
+
+def _run_agent_with_profile(profile_path: str, opts) -> int:
+    """Shared runner logic for both --profile path and hub run path."""
+    try:
+        yaml_text = Path(profile_path).resolve().read_text(encoding="utf-8")
+        profile_raw = parse_yaml(yaml_text)
+    except FileNotFoundError:
+        sys.stderr.write(f"error: profile not found: {profile_path}\n")
+        return 2
+    except Exception as e:
+        sys.stderr.write(f"error: failed to parse profile {profile_path}: {e}\n")
         return 2
 
+    # Read prompt.
     prompt = opts.prompt
     if opts.stdin:
         try:
             prompt = sys.stdin.read().rstrip("\n")
         except KeyboardInterrupt:
-            return EXIT_ERROR
+            return 1
     if prompt is None:
         sys.stderr.write("error: --prompt (or --stdin) is required\n")
         return 2
 
     extra_env: Dict[str, str] = {}
-    for kv in opts.env:
+    for kv in opts.env or []:
         eq = kv.find("=")
         if eq < 0:
             sys.stderr.write(f"error: --env expects KEY=VALUE, got: {kv}\n")
             return 2
         extra_env[kv[:eq]] = kv[eq + 1:]
 
-    try:
-        yaml_text = Path(opts.profile).resolve().read_text(encoding="utf-8")
-        profile_raw = parse_yaml(yaml_text)
-    except FileNotFoundError:
-        sys.stderr.write(f"error: profile not found: {opts.profile}\n")
-        return 2
-    except Exception as e:
-        sys.stderr.write(f"error: failed to parse profile {opts.profile}: {e}\n")
-        return 2
-
     streaming = False if opts.no_stream else None
 
     if opts.raw:
@@ -360,14 +463,42 @@ def main(argv: Optional[List[str]] = None) -> int:
         sys.stdout.write(r.reply)
         if not r.reply.endswith("\n"):
             sys.stdout.write("\n")
-
     if r.session_id:
         sys.stderr.write(f"agentproc:session:{r.session_id}\n")
     if r.error:
         sys.stderr.write(f"agentproc:error:{r.error}\n")
-
     return 0 if r.exit_code == 0 else 1
 
 
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main(argv: Optional[List[str]] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # `agentproc hub <subcommand>` — defer to hub dispatcher.
+    if argv and argv[0] == "hub":
+        return _run_hub_subcommand(argv[1:])
+
+    parser = build_parser()
+    opts = parser.parse_args(argv)
+
+    if opts.help:
+        show_help()
+        return 0
+    if opts.version:
+        show_version()
+        return 0
+
+    if not opts.profile:
+        sys.stderr.write("error: --profile is required\n\n")
+        show_help()
+        return 2
+
+    return _run_agent_with_profile(opts.profile, opts)
+
+
 if __name__ == "__main__":
     sys.exit(main())

agentproc-0.3.0/src/agentproc/hub.py

@@ -0,0 +1,294 @@
+"""Hub client — fetch and manage profile directories from the official Hub.
+
+The Hub lives at https://github.com/jeffkit/agentproc/tree/main/hub/
+Profiles are cached locally at ~/.agentproc/cache/hub/<name>/ with a
+24-hour TTL. Pass refresh=True to force re-fetch.
+
+Public API:
+    HUB_REPO            — the github repo id ("jeffkit/agentproc")
+    HUB_REF             — the git ref to fetch from ("main")
+    HUB_CACHE_TTL_SECS  — default 24 hours
+    cache_dir(name)     — Path to the local cache directory for a profile
+    fetch_profile(name, refresh=False, on_log=None) -> Path
+    list_profiles(refresh=False, on_log=None) -> List[Dict[str,str]]
+    show_readme(name, refresh=False, on_log=None) -> str
+    install_profile(name, target_dir, refresh=False, on_log=None) -> Path
+
+All network access is via urllib (stdlib). Zero dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+HUB_REPO = "jeffkit/agentproc"
+HUB_REF = "main"
+HUB_CACHE_TTL_SECS = 24 * 60 * 60  # 24 hours
+
+GITHUB_API = "https://api.github.com/repos/{repo}/contents/{path}?ref={ref}"
+GITHUB_TREES = "https://api.github.com/repos/{repo}/git/trees/{ref}?recursive=1"
+GITHUB_RAW = "https://raw.githubusercontent.com/{repo}/{ref}/{path}"
+
+
+def _cache_root() -> Path:
+    """Root cache directory: ~/.agentproc/cache/hub/"""
+    return Path.home() / ".agentproc" / "cache" / "hub"
+
+
+def cache_dir(name: str) -> Path:
+    """Local cache path for a profile."""
+    return _cache_root() / name
+
+
+def _cache_age_secs(name: str) -> Optional[float]:
+    """Seconds since the cache was last written. None if not cached."""
+    p = cache_dir(name)
+    marker = p / ".cache-meta.json"
+    if not marker.exists():
+        return None
+    try:
+        meta = json.loads(marker.read_text(encoding="utf-8"))
+        ts = meta.get("fetched_at", 0)
+        return max(0, time.time() - ts)
+    except Exception:
+        return None
+
+
+def _write_cache_meta(name: str) -> None:
+    """Write a small metadata file recording when we fetched."""
+    p = cache_dir(name)
+    p.mkdir(parents=True, exist_ok=True)
+    (p / ".cache-meta.json").write_text(
+        json.dumps({"fetched_at": time.time(), "ref": HUB_REF}),
+        encoding="utf-8",
+    )
+
+
+def _http_get_json(url: str, timeout: int = 30) -> Any:
+    """GET a URL, return parsed JSON. Raises urllib.error.HTTPError on failure."""
+    req = urllib.request.Request(url, headers={
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "agentproc-cli",
+    })
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode("utf-8"))
+
+
+def _http_get_text(url: str, timeout: int = 30) -> str:
+    req = urllib.request.Request(url, headers={"User-Agent": "agentproc-cli"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return r.read().decode("utf-8")
+
+
+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).
+
+    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.
+    """
+    if not subpath.endswith("/"):
+        subpath = subpath + "/"
+    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(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]
+        out.append({
+            "name": name,
+            "path": p,
+            "type": etype,
+            # We don't use download_url from the API; we use raw URLs.
+            "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 _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")
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def fetch_profile(
+    name: str,
+    refresh: bool = False,
+    on_log: Optional[Callable[[str], None]] = None,
+) -> Path:
+    """Fetch a profile directory to local cache. Returns the cache path.
+
+    If a fresh cache exists (younger than HUB_CACHE_TTL_SECS) and refresh
+    is False, returns immediately without network access.
+    """
+    age = _cache_age_secs(name)
+    cached = cache_dir(name)
+    profile_yaml = cached / "profile.yaml"
+
+    if not refresh and age is not None and age < HUB_CACHE_TTL_SECS and profile_yaml.exists():
+        if on_log:
+            on_log(f"using cached profile: {cached} (age {int(age)}s)")
+        return cached
+
+    if on_log:
+        if refresh:
+            on_log(f"refreshing profile '{name}' from {HUB_REPO}:{HUB_REF}...")
+        else:
+            on_log(f"fetching profile '{name}' from {HUB_REPO}:{HUB_REF}...")
+
+    entries = _list_remote_profile_files(name)
+    if not entries:
+        raise RuntimeError(f"profile '{name}' not found in hub")
+
+    # Clear cache, then re-download every file in the profile directory.
+    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)
+        if on_log:
+            on_log(f"  - {entry['name']}")
+
+    _write_cache_meta(name)
+    return cached
+
+
+def list_profiles(
+    refresh: bool = False,
+    on_log: Optional[Callable[[str], None]] = None,
+) -> List[Dict[str, str]]:
+    """List profiles in the official hub.
+
+    Returns list of dicts: {name, description, cli, tested}.
+    """
+    entries = _list_remote_files("hub")
+    profiles: List[Dict[str, str]] = []
+    for entry in entries:
+        if entry["type"] != "dir":
+            continue
+        name = entry["name"]
+        # Read profile.yaml from raw URL to get metadata.
+        try:
+            yaml_url = GITHUB_RAW.format(
+                repo=HUB_REPO, ref=HUB_REF, path=f"hub/{name}/profile.yaml"
+            )
+            yaml_text = _http_get_text(yaml_url)
+            from .cli import parse_yaml  # local import to avoid cycle
+            data = parse_yaml(yaml_text)
+            profiles.append({
+                "name": str(data.get("name", name)),
+                "description": str(data.get("description", "")),
+                "cli": str(data.get("cli", "")),
+                "tested": str(data.get("tested", "unverified")),
+            })
+        except Exception as e:
+            if on_log:
+                on_log(f"warning: could not read metadata for {name}: {e}")
+            profiles.append({
+                "name": name,
+                "description": "(failed to read metadata)",
+                "cli": "",
+                "tested": "unverified",
+            })
+    return profiles
+
+
+def show_readme(
+    name: str,
+    refresh: bool = False,
+    on_log: Optional[Callable[[str], None]] = None,
+) -> str:
+    """Return the README.md content for a profile (fetches if needed)."""
+    cached = fetch_profile(name, refresh=refresh, on_log=on_log)
+    readme = cached / "README.md"
+    if not readme.exists():
+        return f"(no README.md for profile '{name}')"
+    return readme.read_text(encoding="utf-8")
+
+
+def install_profile(
+    name: str,
+    target_dir: Path,
+    refresh: bool = False,
+    on_log: Optional[Callable[[str], None]] = None,
+) -> Path:
+    """Copy a cached profile into target_dir/<name>/.
+
+    Useful when the user wants to own and edit the profile locally.
+    """
+    cached = fetch_profile(name, refresh=refresh, on_log=on_log)
+    dest = Path(target_dir) / name
+    if dest.exists():
+        raise RuntimeError(f"target already exists: {dest}")
+    shutil.copytree(cached, dest)
+    # Don't copy our cache meta file.
+    meta = dest / ".cache-meta.json"
+    if meta.exists():
+        meta.unlink()
+    if on_log:
+        on_log(f"installed to: {dest}")
+    return dest
+
+
+# Re-export for type checker
+from typing import Any  # noqa: E402

{agentproc-0.2.1 → agentproc-0.3.0}/src/agentproc.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.2.1
+Version: 0.3.0
 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.2.1 → agentproc-0.3.0}/src/agentproc.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 pyproject.toml
 src/agentproc/__init__.py
 src/agentproc/cli.py
+src/agentproc/hub.py
 src/agentproc/runner.py
 src/agentproc.egg-info/PKG-INFO
 src/agentproc.egg-info/SOURCES.txt
@@ -8,4 +9,5 @@ src/agentproc.egg-info/dependency_links.txt
 src/agentproc.egg-info/entry_points.txt
 src/agentproc.egg-info/top_level.txt
 tests/test_agentproc.py
+tests/test_hub.py
 tests/test_runner.py

agentproc-0.3.0/tests/test_hub.py

@@ -0,0 +1,299 @@
+"""Tests for agentproc.hub.
+
+Mock-based — no real network access. Covers:
+  - Tree API response parsing
+  - Local cache TTL logic
+  - list/show/install/run operations
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any, Dict, List
+from unittest.mock import patch
+
+import pytest
+
+from agentproc import hub as hub_mod
+from agentproc.hub import (
+    HUB_CACHE_TTL_SECS,
+    cache_dir,
+    _cache_root,
+    _cache_age_secs,
+    _write_cache_meta,
+)
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures: synthetic GitHub tree + file contents
+# ---------------------------------------------------------------------------
+
+FAKE_TREE = [
+    {"path": "hub", "type": "tree"},
+    {"path": "hub/echo-agent", "type": "tree"},
+    {"path": "hub/echo-agent/profile.yaml", "type": "blob"},
+    {"path": "hub/echo-agent/bridge.py", "type": "blob"},
+    {"path": "hub/echo-agent/bridge.js", "type": "blob"},
+    {"path": "hub/echo-agent/bridge.sh", "type": "blob"},
+    {"path": "hub/echo-agent/README.md", "type": "blob"},
+    {"path": "hub/claude-code", "type": "tree"},
+    {"path": "hub/claude-code/profile.yaml", "type": "blob"},
+    {"path": "hub/claude-code/bridge.py", "type": "blob"},
+    {"path": "hub/claude-code/bridge.js", "type": "blob"},
+    {"path": "hub/claude-code/README.md", "type": "blob"},
+    {"path": "README.md", "type": "blob"},
+    {"path": "spec/protocol.md", "type": "blob"},
+]
+
+FAKE_FILE_CONTENTS = {
+    "hub/echo-agent/profile.yaml": (
+        "name: echo-agent\n"
+        "description: Minimal hello-world agent\n"
+        "cli: none\n"
+        "agentproc:\n"
+        "  command: python3 ./bridge.py\n"
+        "  cwd: .\n"
+        "tested: official\n"
+        "maintainer: jeffkit\n"
+    ),
+    "hub/echo-agent/bridge.py": "#!/usr/bin/env python3\nprint('echo')\n",
+    "hub/echo-agent/bridge.js": "'use strict';\nconsole.log('echo');\n",
+    "hub/echo-agent/bridge.sh": "#!/usr/bin/env bash\necho echo\n",
+    "hub/echo-agent/README.md": "# echo-agent\n\nHello world.\n",
+    "hub/claude-code/profile.yaml": (
+        "name: claude-code\n"
+        "description: Claude Code wrapper\n"
+        "cli: claude\n"
+        "agentproc:\n"
+        "  command: python3 ./bridge.py\n"
+        "tested: official\n"
+        "maintainer: jeffkit\n"
+    ),
+    "hub/claude-code/bridge.py": "#!/usr/bin/env python3\nprint('claude')\n",
+    "hub/claude-code/bridge.js": "'use strict';\nconsole.log('claude');\n",
+    "hub/claude-code/README.md": "# claude-code\n\nReal wrapper.\n",
+}
+
+
+def _make_fake_http_get_json(tree=None):
+    """Return a callable that emulates _http_get_json for the tree API."""
+    tree = tree if tree is not None else FAKE_TREE
+    def fake(url, timeout=30):
+        if "git/trees" in url:
+            return {"tree": tree}
+        raise AssertionError(f"unexpected JSON URL: {url}")
+    return fake
+
+
+def _make_fake_http_get_text(contents=None):
+    """Return a callable that emulates _http_get_text for raw file fetches."""
+    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}")
+    return fake
+
+
+@pytest.fixture
+def isolated_cache(monkeypatch, tmp_path):
+    """Redirect cache to a tmp dir."""
+    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)
+    return tmp_path
+
+
+# ---------------------------------------------------------------------------
+# Cache helpers
+# ---------------------------------------------------------------------------
+
+class TestCacheHelpers:
+    def test_cache_age_none_when_not_cached(self, isolated_cache):
+        assert _cache_age_secs("never-cached") is None
+
+    def test_cache_age_after_write(self, isolated_cache):
+        _write_cache_meta("foo")
+        age = _cache_age_secs("foo")
+        assert age is not None
+        assert age < 5  # just written
+
+    def test_cache_age_old(self, isolated_cache, tmp_path):
+        # Manually write an old marker.
+        marker = isolated_cache / "cache" / "hub" / "old" / ".cache-meta.json"
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text(json.dumps({"fetched_at": time.time() - 100000, "ref": "main"}))
+        age = _cache_age_secs("old")
+        assert age is not None
+        assert age > 100000
+
+    def test_cache_age_invalid_meta(self, isolated_cache):
+        marker = isolated_cache / "cache" / "hub" / "bad" / ".cache-meta.json"
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text("not json at all")
+        assert _cache_age_secs("bad") is None
+
+
+# ---------------------------------------------------------------------------
+# fetch_profile
+# ---------------------------------------------------------------------------
+
+class TestFetchProfile:
+    def test_fetch_downloads_all_files(self, isolated_cache):
+        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("echo-agent", on_log=lambda m: None)
+        assert p.exists()
+        names = sorted(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 ".cache-meta.json" 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 pytest.raises(RuntimeError, match="not found in hub"):
+                hub_mod.fetch_profile("nope")
+
+    def test_fetch_uses_cache_on_second_call(self, isolated_cache):
+        call_count = {"json": 0, "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=counting_text):
+            hub_mod.fetch_profile("echo-agent")
+            first_json = call_count["json"]
+            first_text = call_count["text"]
+            hub_mod.fetch_profile("echo-agent")  # should hit cache
+            assert call_count["json"] == first_json  # no new API calls
+            assert call_count["text"] == first_text  # no new file downloads
+
+    def test_refresh_forces_refetch(self, isolated_cache):
+        call_count = {"json": 0}
+
+        def counting_json(url, timeout=30):
+            call_count["json"] += 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.fetch_profile("echo-agent")
+            first = call_count["json"]
+            hub_mod.fetch_profile("echo-agent", refresh=True)
+            assert call_count["json"] > first
+
+    def test_fetch_overwrites_old_files(self, isolated_cache):
+        # First fetch.
+        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()):
+            hub_mod.fetch_profile("echo-agent")
+        # Modify cache.
+        cached_file = cache_dir("echo-agent") / "bridge.py"
+        original = cached_file.read_text()
+        cached_file.write_text("# tampered\n")
+        # Refresh — should restore original.
+        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()):
+            hub_mod.fetch_profile("echo-agent", refresh=True)
+        assert cached_file.read_text() == original
+
+
+# ---------------------------------------------------------------------------
+# list_profiles
+# ---------------------------------------------------------------------------
+
+class TestListProfiles:
+    def test_list_returns_all_dirs(self, isolated_cache):
+        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()):
+            profiles = hub_mod.list_profiles()
+        names = sorted(p["name"] for p in profiles)
+        assert names == ["claude-code", "echo-agent"]
+        ec = next(p for p in profiles if p["name"] == "echo-agent")
+        assert ec["tested"] == "official"
+        assert ec["description"] == "Minimal hello-world agent"
+        assert ec["cli"] == "none"
+
+    def test_list_skips_non_hub_paths(self, isolated_cache):
+        """The repo root README.md and spec/ should not appear in hub listing."""
+        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()):
+            profiles = hub_mod.list_profiles()
+        # No root-level files leaked.
+        for p in profiles:
+            assert p["name"].startswith("")  # just a sanity check
+            assert "/" not in p["name"]
+
+
+# ---------------------------------------------------------------------------
+# show_readme
+# ---------------------------------------------------------------------------
+
+class TestShowReadme:
+    def test_returns_readme_content(self, isolated_cache):
+        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()):
+            text = hub_mod.show_readme("echo-agent")
+        assert "echo-agent" in text
+        assert "Hello world" in text
+
+    def test_missing_readme_returns_placeholder(self, isolated_cache):
+        # Fetch a profile with no README.
+        tree = [
+            {"path": "hub/noreadme", "type": "tree"},
+            {"path": "hub/noreadme/profile.yaml", "type": "blob"},
+        ]
+        contents = {"hub/noreadme/profile.yaml": "name: noreadme\ndescription: x\ntested: unverified\n"}
+        with patch("agentproc.hub._http_get_json", side_effect=_make_fake_http_get_json(tree)), \
+             patch("agentproc.hub._http_get_text", side_effect=_make_fake_http_get_text(contents)):
+            text = hub_mod.show_readme("noreadme")
+        assert "no README.md" in text
+
+
+# ---------------------------------------------------------------------------
+# install_profile
+# ---------------------------------------------------------------------------
+
+class TestInstallProfile:
+    def test_install_copies_to_target(self, isolated_cache, tmp_path):
+        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()):
+            dest = hub_mod.install_profile("echo-agent", tmp_path)
+        assert dest.exists()
+        assert (dest / "profile.yaml").exists()
+        assert (dest / "bridge.py").exists()
+        # Cache meta should NOT be copied to the installed copy.
+        assert not (dest / ".cache-meta.json").exists()
+
+    def test_install_refuses_existing_target(self, isolated_cache, tmp_path):
+        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()):
+            hub_mod.install_profile("echo-agent", tmp_path)
+            with pytest.raises(RuntimeError, match="target already exists"):
+                hub_mod.install_profile("echo-agent", tmp_path)
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+def test_hub_cache_ttl_is_24h():
+    assert HUB_CACHE_TTL_SECS == 24 * 60 * 60
+
+
+def test_hub_repo_constants():
+    assert hub_mod.HUB_REPO == "jeffkit/agentproc"
+    assert hub_mod.HUB_REF == "main"