agentproc 0.3.0__tar.gz → 0.4.0__tar.gz

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

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

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

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

@@ -227,6 +227,27 @@ def build_parser() -> argparse.ArgumentParser:
 def show_help() -> None:
     sys.stdout.write(f"""agentproc v{PKG_VERSION} (protocol {PROTOCOL_VERSION})
 
+The fastest way in:
+  agentproc hub list                          # see what's available
+  agentproc hub run echo-agent -p "hello"     # smoke test (no API key)
+  cd ~/projects/my-app && agentproc hub run claude-code -p "explain this"
+
+The CLI fetches the profile from the GitHub hub on first use, caches it at
+~/.agentproc/cache/hub/<name>/ (24h TTL), and uses your current directory as
+the agent's cwd. Set GITHUB_TOKEN to raise the rate limit (see `agentproc hub --help`).
+
+Hub subcommands:
+  hub list                          List all profiles in the hub
+  hub show <name>                   Show a profile's README
+  hub run <name> [run-options]      Fetch (if needed) and run a profile
+  hub install <name>                Copy a profile to the current directory
+
+Run `agentproc hub --help` for the full hub reference.
+
+───────────────────────────────────────────────────────────────────────────────
+
+Advanced: run a local profile YAML directly (no hub fetch)
+
 Usage:
   agentproc --profile <path.yaml> --prompt "hello" [options]
 
@@ -240,7 +261,8 @@ Session:
   --from <user>             Sender identifier
 
 Execution:
-  --cwd <path>              Override profile.cwd
+  --cwd <path>              Override profile.cwd (relative paths resolve
+                            against the profile.yaml's directory)
   --env KEY=VALUE           Extra env var (repeatable)
   --timeout <secs>          Override profile.timeout_secs
   --no-stream               Set AGENT_STREAMING=0
@@ -263,9 +285,16 @@ Output semantics:
 The final session id is printed on stderr as: agentproc:session:<id>
 
 Examples:
-  agentproc --profile hub/echo-agent/profile.yaml --prompt "hi"
-  agentproc -p hub/claude-code/profile.yaml --prompt "hello" --verbose
-  cat prompt.txt | agentproc -p prof.yaml --stdin
+  # Local profile (relative cwd resolves next to profile.yaml):
+  agentproc --profile ./hub/echo-agent/profile.yaml --prompt "hi"
+
+  # Local claude-code profile, claude runs against your project:
+  agentproc --profile ./hub/claude-code/profile.yaml \\
+            --prompt "explain this codebase" \\
+            --cwd /path/to/your/project
+
+  # Prompt from stdin:
+  cat prompt.txt | agentproc --profile prof.yaml --stdin
 """)
 
 
@@ -288,9 +317,46 @@ def _run_hub_subcommand(args: List[str]) -> int:
     sub = args[0]
     rest = args[1:]
 
+    # Any subcommand with --help/-h shows the hub help uniformly.
+    if "--help" in rest or "-h" in rest:
+        _show_hub_help()
+        return 0
+
     # Common flag
     refresh = "--refresh" in rest
-    positional = [a for a in rest if not a.startswith("--")]
+
+    # Separate hub-level flags from runner-level flags and positional args.
+    # In the `hub run` context, `-p` means `--prompt` (the profile name is
+    # positional, not a path), so normalize it before handing off to argparse.
+    positional: List[str] = []
+    runner_args: List[str] = []
+    takes_value = {"--prompt", "-p", "--session", "--session-name", "--from",
+                   "--cwd", "--env", "--timeout"}
+    boolean_flags = {"--no-stream", "--verbose", "--quiet", "--raw", "--stdin"}
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a in ("--refresh", "-h", "--help"):
+            i += 1
+            continue
+        if a in takes_value:
+            runner_args.append("--prompt" if a == "-p" else a)
+            if i + 1 < len(rest):
+                runner_args.append(rest[i + 1])
+                i += 2
+            else:
+                i += 1
+            continue
+        if a in boolean_flags:
+            runner_args.append(a)
+            i += 1
+            continue
+        if a.startswith("-"):
+            sys.stderr.write(f"error: unknown option: {a}\n\n")
+            _show_hub_help()
+            return 2
+        positional.append(a)
+        i += 1
 
     def _log(msg: str) -> None:
         sys.stderr.write(msg + "\n")
@@ -319,7 +385,14 @@ def _run_hub_subcommand(args: List[str]) -> int:
         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)
+        dest = hub_mod.install_profile(positional[0], Path.cwd(), refresh=refresh, on_log=_log)
+        # Tell the user exactly what they got and how to run it next.
+        rel_profile = os.path.relpath(str(dest / "profile.yaml"), str(Path.cwd()))
+        sys.stderr.write("\n")
+        sys.stderr.write(f"Next: edit {rel_profile} if you want, then run:\n")
+        sys.stderr.write(
+            f'  agentproc --profile {rel_profile} --prompt "hi" --cwd <your-project>\n'
+        )
         return 0
 
     if sub == "run":
@@ -330,18 +403,20 @@ def _run_hub_subcommand(args: List[str]) -> int:
         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.
+        # Parse the runner-level flags we separated out above.
         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
 
+        # hub run uses the user's current directory as the agent's cwd when
+        # --cwd is not given. Matches the hub docs and the right default for
+        # AI-CLI profiles where the agent should operate on the user's project.
+        if not opts.cwd:
+            opts.cwd = str(Path.cwd())
+
         return _run_agent_with_profile(profile_path, opts)
 
     sys.stderr.write(f"error: unknown hub subcommand: {sub}\n\n")
@@ -385,6 +460,7 @@ 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."""
+    profile_dir = str(Path(profile_path).resolve().parent)
     try:
         yaml_text = Path(profile_path).resolve().read_text(encoding="utf-8")
         profile_raw = parse_yaml(yaml_text)
@@ -426,6 +502,7 @@ def _run_agent_with_profile(profile_path: str, opts) -> int:
                 from_user=opts.from_user,
                 streaming=streaming,
                 cwd=opts.cwd,
+                profile_dir=profile_dir,
                 extra_env=extra_env,
                 timeout_secs=opts.timeout,
             ),
@@ -446,6 +523,7 @@ def _run_agent_with_profile(profile_path: str, opts) -> int:
             from_user=opts.from_user,
             streaming=streaming,
             cwd=opts.cwd,
+            profile_dir=profile_dir,
             extra_env=extra_env,
             timeout_secs=opts.timeout,
             on_partial=lambda t: verbose and sys.stderr.write(
@@ -478,26 +556,48 @@ 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
+    try:
+        # `agentproc hub <subcommand>` — defer to hub dispatcher.
+        if argv and argv[0] == "hub":
+            return _run_hub_subcommand(argv[1:])
 
-    if not opts.profile:
-        sys.stderr.write("error: --profile is required\n\n")
-        show_help()
-        return 2
+        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)
+        return _run_agent_with_profile(opts.profile, opts)
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        # Friendly handling for known hub errors: print the message + hint,
+        # never a raw stack trace.
+        from .hub import HubError
+        if isinstance(e, HubError):
+            sys.stderr.write(f"error: {e}\n")
+            if e.hint:
+                sys.stderr.write(f"\n{e.hint}\n")
+            return 1
+        # Network errors that slipped through unwrapped.
+        msg = str(e)
+        if any(s in msg for s in ("fetch failed", "ENOTFOUND", "ECONNREFUSED", "ECONNRESET", "urlopen error")):
+            sys.stderr.write(f"error: network error talking to GitHub: {msg}\n")
+            sys.stderr.write("\nThis is usually transient. Re-run the command, or run against a local checkout:\n")
+            sys.stderr.write('  agentproc --profile ./hub/<name>/profile.yaml --prompt "hi"\n')
+            return 1
+        # Everything else: surface the message without dumping a traceback.
+        sys.stderr.write(f"error: {msg}\n")
+        return 1
 
 
 if __name__ == "__main__":

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

@@ -27,7 +27,7 @@ import time
 import urllib.error
 import urllib.request
 from pathlib import Path
-from typing import Callable, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 HUB_REPO = "jeffkit/agentproc"
 HUB_REF = "main"
@@ -38,6 +38,38 @@ GITHUB_TREES = "https://api.github.com/repos/{repo}/git/trees/{ref}?recursive=1"
 GITHUB_RAW = "https://raw.githubusercontent.com/{repo}/{ref}/{path}"
 
 
+class HubError(RuntimeError):
+    """Hub fetch failure with a human-readable remediation hint.
+
+    The CLI prints `message` + `hint` to stderr instead of dumping a stack
+    trace. `status` is the HTTP status (0 for network errors).
+
+    Inherits from RuntimeError so existing `except RuntimeError` callers
+    continue to work.
+    """
+
+    def __init__(self, message: str, *, hint: str = "", status: int = 0) -> None:
+        super().__init__(message)
+        self.hint = hint
+        self.status = status
+
+
+def _auth_headers(*, json: bool = False) -> Dict[str, str]:
+    """Build HTTP headers, adding Authorization if a token is in env.
+
+    GITHUB_TOKEN (the env var GitHub Actions injects) or GH_TOKEN (what
+    the `gh` CLI sets) raises GitHub's anonymous rate limit from ~60/hr
+    to ~5000/hr.
+    """
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN") or ""
+    h: Dict[str, str] = {"User-Agent": "agentproc-cli"}
+    if json:
+        h["Accept"] = "application/vnd.github+json"
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    return h
+
+
 def _cache_root() -> Path:
     """Root cache directory: ~/.agentproc/cache/hub/"""
     return Path.home() / ".agentproc" / "cache" / "hub"
@@ -73,19 +105,95 @@ def _write_cache_meta(name: str) -> None:
 
 
 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"))
+    """GET a URL, return parsed JSON. Raises HubError on failure."""
+    req = urllib.request.Request(url, headers=_auth_headers(json=True))
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = ""
+        try:
+            body = e.read().decode("utf-8", errors="replace")
+        except Exception:
+            pass
+        raise _http_error_to_hub(e.code, body[:200], url, is_json=True) from e
+    except urllib.error.URLError as e:
+        # Network/DNS/connection-level errors (no HTTP status).
+        raise HubError(
+            "could not reach GitHub while fetching hub profile",
+            status=0,
+            hint=(
+                "This is usually a transient network issue. Try:\n"
+                "  1. Re-run the command (often succeeds on retry).\n"
+                "  2. If your network requires a proxy, set HTTPS_PROXY.\n"
+                "  3. To avoid the network entirely, run against a local checkout:\n"
+                "       agentproc --profile ./hub/<name>/profile.yaml --prompt \"hi\""
+            ),
+        ) from e
 
 
 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")
+    req = urllib.request.Request(url, headers=_auth_headers(json=False))
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return r.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        body = ""
+        try:
+            body = e.read().decode("utf-8", errors="replace")
+        except Exception:
+            pass
+        raise _http_error_to_hub(e.code, body[:200], url, is_json=False) from e
+    except urllib.error.URLError as e:
+        raise HubError(
+            "could not reach GitHub while fetching hub profile",
+            status=0,
+            hint=(
+                "This is usually a transient network issue. Try:\n"
+                "  1. Re-run the command (often succeeds on retry).\n"
+                "  2. If your network requires a proxy, set HTTPS_PROXY.\n"
+                "  3. To avoid the network entirely, run against a local checkout:\n"
+                "       agentproc --profile ./hub/<name>/profile.yaml --prompt \"hi\""
+            ),
+        ) from e
+
+
+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"))
+    if status in (403, 429):
+        if authed:
+            hint = (
+                "Your GITHUB_TOKEN is set but still rate-limited. Wait a few minutes and retry,\n"
+                "or run against a local checkout instead:\n"
+                "  agentproc --profile ./hub/<name>/profile.yaml --prompt \"hi\"\n"
+                "\n"
+                "Not sure the profile name is right? Check with: agentproc hub list"
+            )
+        else:
+            hint = (
+                "GitHub limits anonymous hub fetches to ~60/hour. To raise this to 5,000/hour:\n"
+                "  export GITHUB_TOKEN=$(gh auth token)   # if you have the GitHub CLI\n"
+                "  # or set GITHUB_TOKEN to any personal access token\n"
+                "\n"
+                "To skip the network entirely, run against a local checkout:\n"
+                "  git clone https://github.com/jeffkit/agentproc && cd agentproc\n"
+                "  agentproc --profile ./hub/<name>/profile.yaml --prompt \"hi\"\n"
+                "\n"
+                "Not sure the profile name is right? Check with: agentproc hub list"
+            )
+        return HubError(f"GitHub rate-limited the hub fetch (HTTP {status})", status=status, hint=hint)
+    if status == 404:
+        return HubError(
+            "profile not found on GitHub (HTTP 404)",
+            status=404,
+            hint="Check the profile name with `agentproc hub list`. (Typos are case-sensitive.)",
+        )
+    return HubError(
+        f"GitHub returned HTTP {status} for hub fetch",
+        status=status,
+        hint=body or "No additional detail from GitHub.",
+    )
 
 
 def _list_remote_files(subpath: str) -> List[Dict[str, str]]:
@@ -157,6 +265,85 @@ def _list_remote_profile_files(name: str) -> List[Dict[str, str]]:
     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).
+    """
+    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 []
+    names: List[str] = []
+    seen = set()
+    for entry in data["tree"]:
+        if not isinstance(entry, dict):
+            continue
+        p = str(entry.get("path", ""))
+        if not p.startswith("hub/"):
+            continue
+        seg = p[len("hub/"):].split("/")[0]
+        # Directories prefixed with `_` (e.g. `_shared`) hold bridge
+        # utilities, not profiles — exclude from listings and suggestions.
+        if seg and not seg.startswith("_") and seg not in seen:
+            seen.add(seg)
+            names.append(seg)
+    return sorted(names)
+
+
+def _suggest_close_name(input_name: str, candidates: List[str]) -> str:
+    """Lightweight "did you mean" hint.
+
+    Two paths to a match:
+      1. Prefix match — `claude` matches `claude-code`, `echo` matches
+         `echo-agent`. Common typo pattern (user forgot a suffix).
+         Only accepts an unambiguous prefix.
+      2. Edit distance with length-scaled threshold (≤6 → 1 edit,
+         7-12 → 2, >12 → 3). Catches transpositions and small typos.
+    """
+    if not input_name or not candidates:
+        return ""
+    n = input_name.lower()
+    # Path 1: unique prefix match.
+    prefix_matches = [c for c in candidates if c.lower().startswith(n)]
+    if len(prefix_matches) == 1:
+        return prefix_matches[0]
+    # Path 2: edit distance.
+    threshold = 1 if len(input_name) <= 6 else (2 if len(input_name) <= 12 else 3)
+    best = ""
+    best_dist = float("inf")
+    for c in candidates:
+        d = _edit_distance(n, c.lower())
+        if d < best_dist:
+            best_dist = d
+            best = c
+    if best and best_dist <= threshold:
+        return best
+    return ""
+
+
+def _edit_distance(a: str, b: str) -> int:
+    m, n = len(a), len(b)
+    if m == 0:
+        return n
+    if n == 0:
+        return m
+    prev = list(range(n + 1))
+    curr = [0] * (n + 1)
+    for i in range(1, m + 1):
+        curr[0] = i
+        for j in range(1, n + 1):
+            cost = 0 if a[i - 1] == b[j - 1] else 1
+            curr[j] = min(
+                prev[j] + 1,        # deletion
+                curr[j - 1] + 1,    # insertion
+                prev[j - 1] + cost  # substitution
+            )
+        prev, curr = curr, prev
+    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)
@@ -196,7 +383,27 @@ def fetch_profile(
 
     entries = _list_remote_profile_files(name)
     if not entries:
-        raise RuntimeError(f"profile '{name}' not found in hub")
+        # 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.
+        known: List[str] = []
+        try:
+            known = _list_profile_names()
+        except Exception:
+            pass
+        suggestion = _suggest_close_name(name, known)
+        lines = []
+        if suggestion:
+            lines.append(f"Did you mean `{suggestion}`?")
+            lines.append("")
+        lines.append("Available profiles:")
+        for k in known:
+            lines.append(f"  - {k}")
+        raise HubError(
+            f"profile '{name}' not found in hub",
+            status=404,
+            hint="\n".join(lines),
+        )
 
     # Clear cache, then re-download every file in the profile directory.
     if cached.exists():
@@ -227,6 +434,10 @@ def list_profiles(
         if entry["type"] != "dir":
             continue
         name = entry["name"]
+        # Skip utility directories like `_shared/` — they hold shared bridge
+        # helpers, not a runnable profile (no profile.yaml).
+        if name.startswith("_"):
+            continue
         # Read profile.yaml from raw URL to get metadata.
         try:
             yaml_url = GITHUB_RAW.format(

{agentproc-0.3.0 → agentproc-0.4.0}/src/agentproc/runner.py

@@ -1,7 +1,8 @@
 """AgentProc runner — the canonical bridge-side engine.
 
 This module is the canonical implementation of the AgentProc bridge-side
-contract (spec/protocol.md). The CLI (cli.py) is a thin wrapper around it.
+contract (spec/protocol.md, wire protocol 0.1). The CLI (cli.py) is a thin
+wrapper around it.
 
 Responsibilities:
   - Parse and validate a profile dict
@@ -91,12 +92,14 @@ class RunOptions:
     streaming: Optional[bool] = None
     extra_env: Dict[str, str] = field(default_factory=dict)
     cwd: Optional[str] = None
+    profile_dir: Optional[str] = None
     timeout_secs: Optional[int] = None
     on_partial: Optional[Callable[[str], None]] = None
     on_session: Optional[Callable[[str], None]] = None
     on_error: Optional[Callable[[str], None]] = None
     on_protocol_line: Optional[Callable[[str], None]] = None
     on_stderr: Optional[Callable[[str], None]] = None
+    forward_stdin: Optional[bool] = None
 
 
 # ---------------------------------------------------------------------------
@@ -114,24 +117,52 @@ def normalize_profile(raw: Dict[str, Any]) -> Dict[str, Any]:
     if not isinstance(command, str) or not command.strip():
         raise ValueError("profile.command must be a non-empty string")
 
-    argv = command.strip().split()
-    if not argv:
-        raise ValueError("profile.command produced empty argv")
-
-    args_value = src.get("args", [])
+    has_args_field = "args" in src and src["args"] is not None
+    args_value = src.get("args") or []
     if not isinstance(args_value, list):
         raise ValueError("profile.args must be a list")
 
+    # Per spec: `command` is argv[0]; `args` is argv[1..]. Two mutually
+    # exclusive forms:
+    #   (a) `args` absent + command has whitespace → split command into argv
+    #       (the legacy shorthand: `command: python3 ./bridge.py`)
+    #   (b) `args` present (even empty `[]`) → command is a single token,
+    #       never split. This is the escape hatch for paths with whitespace:
+    #         command: "/path with spaces/my agent"
+    #         args: []
+    # `args: []` (explicit empty list) is DISTINCT from "args absent": the
+    # explicit form means "do not split command"; the absent form falls back
+    # to the whitespace-splitting shorthand.
+    if has_args_field:
+        argv = [command.strip()]
+    else:
+        argv = command.strip().split()
+    if not argv or not argv[0]:
+        raise ValueError("profile.command produced empty argv")
+
     cwd_value = src.get("cwd")
     env_value = src.get("env") or {}
     if not isinstance(env_value, dict):
         raise ValueError("profile.env must be a dict")
 
+    # env_allowlist (optional): when present, ${VAR} references in the env
+    # block whose name is NOT in the list expand to empty + a stderr warning.
+    # Absent ⇒ current behaviour (expand against the full bridge environment).
+    # Opt-in: existing profiles keep working unchanged.
+    allowlist_raw = src.get("env_allowlist")
+    if allowlist_raw is None:
+        env_allowlist: Optional[set] = None
+    elif isinstance(allowlist_raw, list):
+        env_allowlist = {str(x) for x in allowlist_raw}
+    else:
+        raise ValueError("profile.env_allowlist must be a list")
+
     return {
         "argv": argv,
         "args": [str(a) for a in args_value],
         "cwd": expand_path(str(cwd_value)) if cwd_value else None,
         "env": env_value,
+        "env_allowlist": env_allowlist,
         "stdin": "message" if src.get("stdin") == "message" else "none",
         "timeout_secs": (
             int(src["timeout_secs"]) if _is_int_like(src.get("timeout_secs"))
@@ -173,15 +204,127 @@ def substitute(value: str, ctx: Dict[str, str]) -> str:
         .replace("{{MESSAGE}}", ctx.get("message", ""))
         .replace("{{SESSION_ID}}", ctx.get("session_id", ""))
         .replace("{{SESSION_NAME}}", ctx.get("session_name", ""))
+        .replace("{{PROFILE_DIR}}", ctx.get("profile_dir", ""))
     )
 
 
-def expand_env_ref(value: str, env: Dict[str, str]) -> str:
-    return re.sub(
-        r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}",
-        lambda m: env.get(m.group(1), ""),
-        str(value),
-    )
+def expand_env_ref(
+    value: str,
+    env: Dict[str, str],
+    allowlist: Optional[set] = None,
+    on_blocked: Optional[Callable[[str], None]] = None,
+) -> str:
+    """Expand ${VAR} references against ``env``.
+
+    When ``allowlist`` is a set of variable names, references to names NOT in
+    the set expand to empty string and ``on_blocked`` (if given) is called
+    with each blocked name. When ``allowlist`` is None, all references expand
+    normally (the default, pre-allowlist behaviour).
+    """
+    def repl(m: "re.Match[str]") -> str:
+        name = m.group(1)
+        if allowlist is not None and name not in allowlist:
+            if on_blocked:
+                on_blocked(name)
+            return ""
+        return env.get(name, "")
+    return re.sub(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}", repl, str(value))
+
+
+def _diagnose_spawn_error(
+    err: BaseException,
+    *,
+    argv: List[str],
+    cwd: Optional[str],
+    env: Dict[str, str],
+) -> str:
+    """Produce a human-friendly hint for a spawn FileNotFoundError / ENOENT.
+
+    Subprocess raises FileNotFoundError when either the command isn't on
+    PATH or the cwd doesn't exist — Python folds both into the same
+    exception attributed to argv[0], which is misleading. Disambiguate.
+    """
+    # (a) cwd doesn't exist or isn't a directory
+    if cwd:
+        p = Path(cwd)
+        try:
+            if not p.is_dir():
+                return f"profile.cwd is not a directory: {cwd}"
+        except PermissionError:
+            return f"profile.cwd is not accessible (permission denied): {cwd}"
+        except OSError:
+            return f"profile.cwd does not exist: {cwd}. Pass --cwd <path> to point at a real directory."
+
+    # (b) the command (argv[0]) is not on PATH (bare name, no slash)
+    cmd = argv[0] if argv else ""
+    is_pathed = "/" in cmd or "\\" in cmd
+    if not is_pathed and cmd:
+        from shutil import which
+        if not which(cmd):
+            return (
+                f"'{cmd}' not found on PATH. Install it, or if it's installed, "
+                "make sure PATH is set correctly when the bridge spawns the agent."
+            )
+
+    # (c) argv[0] looks like a path — check whether the file itself exists
+    if is_pathed and cmd:
+        if not Path(cmd).exists():
+            return f"command path does not exist or is not executable: {cmd}"
+
+    # (d) Command exists; suspect an argv file argument (e.g. python3 ./bridge.py)
+    for a in argv[1:]:
+        if a.startswith("-"):
+            continue
+        if "/" in a or "\\" in a:
+            resolved = a if Path(a).is_absolute() else (
+                str(Path(cwd) / a) if cwd else str(Path(a).resolve())
+            )
+            if not Path(resolved).exists():
+                return (
+                    f"argument file not found: {a} (resolved to {resolved}). "
+                    "The profile likely needs --cwd or the bundled script path is wrong."
+                )
+
+    return ""
+
+
+def _diagnose_stderr_failure(stderr_text: str) -> str:
+    """Best-effort pattern check against the agent's accumulated stderr.
+
+    Catches "bridge file not found" failures that the wrapped interpreter
+    writes to its own stderr before exiting non-zero. Returns a friendly
+    hint, or '' if nothing recognizable.
+    """
+    if not stderr_text:
+        return ""
+    lower = stderr_text.lower()
+
+    # python3: "can't open file '/path/x.py': [Errno 2] No such file or directory"
+    m = re.search(r"(?:can'?t|cannot) open file '([^']+)': \[Errno 2\] No such file or directory", stderr_text)
+    if m:
+        return (
+            f"agent script not found: {m.group(1)}. Check the profile's command "
+            "path (likely a {{PROFILE_DIR}} issue or a typo)."
+        )
+
+    # node: "Error: Cannot find module '/path/x.js'"
+    m = re.search(r"Cannot find module '([^']+)'", stderr_text)
+    if m:
+        return (
+            f"agent script not found: {m.group(1)}. Check the profile's command "
+            "path (likely a {{PROFILE_DIR}} issue or a typo)."
+        )
+
+    # bash: "bash: line N: ./x.sh: No such file or directory"
+    m = re.search(r"(?:^|\n)[^:]+: line \d+: ([^:]+): No such file or directory", stderr_text)
+    if m:
+        return f"agent script not found: {m.group(1)}. Check the profile's command path."
+
+    # Generic errno 2 / ENOENT sentinel.
+    if re.search(r"errno 2|enoent|no such file or directory", lower):
+        return "agent reported a missing file. Check the profile's command and cwd."
+
+    return ""
 
 
 # ---------------------------------------------------------------------------
@@ -194,9 +337,13 @@ def decode_json_value(raw: str) -> str:
         return ""
     try:
         v = json.loads(text)
-        return v if isinstance(v, str) else str(v)
     except json.JSONDecodeError:
         return text
+    # Only JSON strings are meaningful payloads — a sentinel's value is text
+    # for the user. Non-string JSON (number/bool/null/array/object) means the
+    # agent misused the API; fall back to the raw text so the result is
+    # language-independent (str(True) != String(true) across runtimes).
+    return v if isinstance(v, str) else text
 
 
 def classify_line(line: str) -> Dict[str, str]:
@@ -224,20 +371,39 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
         options.timeout_secs if options.timeout_secs is not None else profile["timeout_secs"]
     )
     cwd = options.cwd or profile["cwd"]
+    # Resolve relative cwd against the profile's own directory (if known),
+    # so profiles written as `cwd: .` work no matter where the user invokes
+    # from. Absolute paths and ~-prefixed paths are already absolute.
+    if cwd and not Path(cwd).is_absolute() and options.profile_dir:
+        cwd = str(Path(options.profile_dir) / cwd)
 
     subst_ctx = {
         "message": options.message,
         "session_id": options.session_id,
         "session_name": options.session_name,
+        "profile_dir": options.profile_dir or "",
     }
 
-    argv = list(profile["argv"])
+    # Substitute placeholders in argv (command) too, not just args — so
+    # `command: python3 {{PROFILE_DIR}}/bridge.py` resolves correctly.
+    argv = [substitute(a, subst_ctx) for a in profile["argv"]]
     for a in profile["args"]:
         argv.append(substitute(a, subst_ctx))
 
     env = dict(os.environ)
+    allowlist = profile["env_allowlist"]
     for k, v in profile["env"].items():
-        env[k] = expand_env_ref(substitute(str(v), subst_ctx), os.environ)
+        env[k] = expand_env_ref(
+            substitute(str(v), subst_ctx),
+            os.environ,
+            allowlist=allowlist,
+            on_blocked=(
+                lambda name: options.on_stderr(
+                    f"[agentproc runner] env_allowlist blocked ${{{name}}} "
+                    f"(not in allowlist); expanded to empty"
+                ) if options.on_stderr else None
+            ),
+        )
     for k, v in options.extra_env.items():
         env[k] = str(v)
 
@@ -248,10 +414,30 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
     env["AGENT_STREAMING"] = "1" if streaming else "0"
     env["AGENT_PROTOCOL_VERSION"] = PROTOCOL_VERSION
 
-    stdin_payload = options.message if profile["stdin"] == "message" else None
+    # forward_stdin overrides profile.stdin: when True, always write the
+    # message to stdin (used by the CLI's --stdin flag). When None/False,
+    # fall back to the profile's stdin setting.
+    use_stdin = profile["stdin"] == "message" or bool(options.forward_stdin)
+    stdin_payload = options.message if use_stdin else None
 
     result = RunResult()
     body_lines: List[str] = []
+    # Two views on stderr:
+    #   - stderr_window: bounded sliding window (8 KB) for the on_stderr UI
+    #     callback, so a noisy agent cannot exhaust memory.
+    #   - stderr_full:   unbounded capture used only for post-mortem pattern
+    #     diagnosis. Without the full text, a chatty agent can push the real
+    #     error out of the window and the friendly hint goes missing.
+    stderr_window: List[str] = []
+    stderr_full: List[str] = []
+    STDERR_CAP = 8192
+
+    def _append_stderr(text: str) -> None:
+        stderr_full.append(text)
+        stderr_window.append(text)
+        total = sum(len(s) for s in stderr_window)
+        while total > STDERR_CAP and len(stderr_window) > 1:
+            total -= len(stderr_window.pop(0))
 
     try:
         proc = subprocess.Popen(
@@ -265,13 +451,24 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
             bufsize=1,
         )
     except FileNotFoundError as e:
+        tip = _diagnose_spawn_error(e, argv=argv, cwd=cwd, env=env)
         if options.on_stderr:
             options.on_stderr(f"[agentproc runner] spawn error: {e}")
+            if tip:
+                options.on_stderr(f"[agentproc runner] hint: {tip}")
+        if options.on_error:
+            options.on_error(f"failed to start agent: {tip or str(e)}")
+        if not result.error:
+            result.error = tip or str(e)
         result.exit_code = EXIT_ERROR
         return result
     except PermissionError as e:
         if options.on_stderr:
             options.on_stderr(f"[agentproc runner] spawn error: {e}")
+        if options.on_error:
+            options.on_error(f"failed to start agent: {e}")
+        if not result.error:
+            result.error = str(e)
         result.exit_code = EXIT_ERROR
         return result
 
@@ -285,6 +482,7 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
     def _drain_stderr() -> None:
         assert proc.stderr is not None
         for line in proc.stderr:
+            _append_stderr(line)
             line = line.rstrip("\r\n")
             if options.on_stderr:
                 options.on_stderr(line)
@@ -337,15 +535,18 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
                 except subprocess.TimeoutExpired:
                     if time.monotonic() >= deadline:
                         timed_out = True
+                        # terminate() is SIGTERM on POSIX, TerminateProcess on
+                        # Windows — both are the "polite shutdown" the spec's
+                        # SIGTERM→SIGKILL contract refers to.
                         try:
-                            proc.send_signal(signal.SIGTERM)
+                            proc.terminate()
                         except (ProcessLookupError, PermissionError):
                             pass
                         try:
                             proc.wait(timeout=profile["kill_grace_secs"])
                         except subprocess.TimeoutExpired:
                             try:
-                                proc.send_signal(signal.SIGKILL)
+                                proc.kill()
                             except (ProcessLookupError, PermissionError):
                                 pass
                         try:
@@ -356,20 +557,48 @@ def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
         else:
             exit_code = proc.wait()
     except KeyboardInterrupt:
-        try:
-            proc.send_signal(signal.SIGINT)
-        except (ProcessLookupError, PermissionError):
-            pass
+        # SIGINT only exists on POSIX. On Windows we fall back to terminate().
+        if hasattr(signal, "SIGINT"):
+            try:
+                proc.send_signal(signal.SIGINT)
+            except (ProcessLookupError, PermissionError):
+                pass
+        else:
+            try:
+                proc.terminate()
+            except (ProcessLookupError, PermissionError):
+                pass
         exit_code = proc.wait()
 
     stdout_thread.join(timeout=5)
-    stderr_thread.join(timeout=2)
+    # Drain stderr fully before running post-mortem diagnosis. The diagnosis
+    # reads the full capture, so we need the drain thread to have caught up.
+    # Generous timeout since the process has already exited — at most we wait
+    # for the pipe buffer to flush.
+    stderr_thread.join(timeout=10)
+    if stderr_thread.is_alive():
+        # Very rare; indicates a pathological agent that keeps stderr open.
+        # The diagnosis may be incomplete, but we don't want to hang forever.
+        if options.on_stderr:
+            options.on_stderr("[agentproc runner] warning: stderr drain timed out; diagnosis may be incomplete")
 
     result.reply = "\n".join(body_lines)
     if len(result.reply) > profile["max_reply_chars"]:
         suffix = "\n\n…(truncated)" if profile["max_reply_chars"] == DEFAULT_MAX_REPLY_CHARS else ""
         result.reply = result.reply[: profile["max_reply_chars"]] + suffix
 
+    # If the agent exited non-zero with no AGENT_ERROR, peek at its stderr for
+    # common "command/file not found" patterns and surface a friendly hint.
+    # Uses the FULL stderr — a noisy agent can fill the 8 KB window with
+    # progress junk before the real error lands at the end.
+    if not timed_out and not result.error and exit_code != 0:
+        stderr_text = "".join(stderr_full)
+        hint = _diagnose_stderr_failure(stderr_text)
+        if hint:
+            result.error = hint
+            if options.on_error:
+                options.on_error(hint)
+
     if timed_out:
         result.timed_out = True
         result.exit_code = EXIT_TIMEOUT

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

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

@@ -9,5 +9,6 @@ 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_conformance.py
 tests/test_hub.py
 tests/test_runner.py

agentproc-0.4.0/tests/test_conformance.py

@@ -0,0 +1,33 @@
+"""Cross-implementation conformance tests.
+
+Drives the shared `spec/conformance/cases.json` fixture through the Python
+runner's `classify_line` and asserts the result matches the expected
+{kind, value}. The Node SDK runs the same fixture through its `classifyLine`
+in `sdk/node/src/conformance.test.js` — together they guarantee the two
+reference implementations classify stdout identically.
+
+When you change the spec's line-recognition rules, add a case here first;
+both SDKs will fail until they agree.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from agentproc.runner import classify_line
+
+CASES_PATH = Path(__file__).resolve().parents[3] / "spec" / "conformance" / "cases.json"
+
+
+def _load_cases():
+    data = json.loads(CASES_PATH.read_text(encoding="utf-8"))
+    return [pytest.param(c["line"], c["expect"], id=c["line"][:60]) for c in data["cases"]]
+
+
+@pytest.mark.parametrize("line,expect", _load_cases())
+def test_classify_line_conformance(line: str, expect: dict) -> None:
+    got = classify_line(line)
+    assert got == expect, f"line={line!r}: got {got}, expected {expect}"

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

@@ -32,6 +32,10 @@ from agentproc.hub import (
 
 FAKE_TREE = [
     {"path": "hub", "type": "tree"},
+    {"path": "hub/_shared", "type": "tree"},
+    {"path": "hub/_shared/stream_utils.py", "type": "blob"},
+    {"path": "hub/_shared/stream_utils.js", "type": "blob"},
+    {"path": "hub/_shared/README.md", "type": "blob"},
     {"path": "hub/echo-agent", "type": "tree"},
     {"path": "hub/echo-agent/profile.yaml", "type": "blob"},
     {"path": "hub/echo-agent/bridge.py", "type": "blob"},
@@ -237,6 +241,15 @@ class TestListProfiles:
             assert p["name"].startswith("")  # just a sanity check
             assert "/" not in p["name"]
 
+    def test_list_skips_underscore_utility_dirs(self, isolated_cache):
+        """`_shared/` holds bridge helpers, not a profile — must be excluded."""
+        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 = [p["name"] for p in profiles]
+        assert not any(n.startswith("_") for n in names), names
+        assert "_shared" not in names
+
 
 # ---------------------------------------------------------------------------
 # show_readme