agentproc 0.1.1__tar.gz → 0.2.1__tar.gz

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.1.1
-Summary: AgentProc SDK — connect any Agent CLI to a messaging platform with a single function
+Version: 0.2.1
+Summary: AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform
 License: MIT
 Project-URL: Homepage, https://github.com/jeffkit/agentproc
-Project-URL: Documentation, https://jeffkit.github.io/agentproc/
+Project-URL: Documentation, https://agentproc.dev/
 Project-URL: Repository, https://github.com/jeffkit/agentproc
 Project-URL: Issues, https://github.com/jeffkit/agentproc/issues
 Requires-Python: >=3.9

{agentproc-0.1.1 → agentproc-0.2.1}/pyproject.toml

@@ -4,16 +4,19 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentproc"
-version = "0.1.1"
-description = "AgentProc SDK — connect any Agent CLI to a messaging platform with a single function"
+version = "0.2.1"
+description = "AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.9"
 dependencies = []
 
+[project.scripts]
+agentproc = "agentproc.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/jeffkit/agentproc"
-Documentation = "https://jeffkit.github.io/agentproc/"
+Documentation = "https://agentproc.dev/"
 Repository = "https://github.com/jeffkit/agentproc"
 Issues = "https://github.com/jeffkit/agentproc/issues"
 

agentproc-0.2.1/src/agentproc/cli.py

@@ -0,0 +1,373 @@
+"""agentproc CLI — run any AgentProc profile against a message.
+
+Usage:
+    agentproc --profile <path.yaml> --prompt "hello" [options]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .runner import (
+    PROTOCOL_VERSION,
+    EXIT_ERROR,
+    EXIT_SUCCESS,
+    EXIT_TIMEOUT,
+    RunOptions,
+    run,
+)
+
+
+def _read_pkg_version() -> str:
+    """Read version from pyproject.toml at runtime (zero-dep)."""
+    try:
+        toml_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        if toml_path.exists():
+            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"
+
+
+PKG_VERSION = _read_pkg_version()
+
+
+# ---------------------------------------------------------------------------
+# Minimal YAML parser (zero-dep; covers hub profile subset)
+# ---------------------------------------------------------------------------
+
+def parse_yaml(text: str) -> Dict[str, Any]:
+    """Parse a YAML subset into a Python dict.
+
+    Supports: nested maps, block scalars (|), inline flow sequences ([a, b]),
+    block sequences (- item), quoted strings, booleans, null, ints, floats.
+    """
+    text_stripped = text.strip()
+    if text_stripped.startswith("{") or text_stripped.startswith("["):
+        try:
+            return json.loads(text)
+        except Exception:
+            pass
+
+    lines = text.splitlines()
+    root: Dict[str, Any] = {}
+    stack: List[Tuple[int, Any]] = [(-1, root)]
+
+    def current(min_indent: int) -> Tuple[int, Any]:
+        while len(stack) > 1 and stack[-1][0] >= min_indent:
+            stack.pop()
+        return stack[-1]
+
+    i = 0
+    while i < len(lines):
+        raw = lines[i]
+        if raw.strip() == "" or raw.strip().startswith("#"):
+            i += 1
+            continue
+        indent = _leading_spaces(raw)
+        content = raw[indent:].rstrip("\r")
+        _, container = current(indent)
+
+        if content == "-" or content.startswith("- "):
+            if isinstance(container, list):
+                rest = "" if content == "-" else content[2:]
+                if rest.strip():
+                    container.append(_strip_scalar(rest))
+            i += 1
+            continue
+
+        m = re.match(r"^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$", content)
+        if not m:
+            i += 1
+            continue
+        key, val = m.group(1), m.group(2)
+
+        if val == "":
+            j = i + 1
+            while j < len(lines) and (lines[j].strip() == "" or lines[j].strip().startswith("#")):
+                j += 1
+            if j < len(lines):
+                next_indent = _leading_spaces(lines[j])
+                next_content = lines[j][next_indent:]
+                if next_indent > indent and (next_content == "-" or next_content.startswith("- ")):
+                    arr: List[Any] = []
+                    if isinstance(container, dict):
+                        container[key] = arr
+                    stack.append((indent, arr))
+                    i += 1
+                    continue
+                elif next_indent > indent:
+                    child: Dict[str, Any] = {}
+                    if isinstance(container, dict):
+                        container[key] = child
+                    stack.append((indent, child))
+                    i += 1
+                    continue
+            if isinstance(container, dict):
+                container[key] = ""
+            i += 1
+            continue
+
+        if val in ("|", "|-", ">"):
+            block_lines: List[str] = []
+            j = i + 1
+            while j < len(lines):
+                nr = lines[j]
+                if nr.strip() == "":
+                    block_lines.append("")
+                    j += 1
+                    continue
+                ni = _leading_spaces(nr)
+                if ni <= indent:
+                    break
+                block_lines.append(nr[min(indent + 2, len(nr)):])
+                j += 1
+            joined = "\n".join(block_lines)
+            if val == "|":
+                value = re.sub(r"\n*$", "\n", joined)
+            else:
+                value = re.sub(r"\n*$", "", joined)
+            if isinstance(container, dict):
+                container[key] = value
+            i = j
+            continue
+
+        if isinstance(container, dict):
+            container[key] = _strip_scalar(val)
+        i += 1
+
+    return root
+
+
+def _leading_spaces(s: str) -> int:
+    n = 0
+    for ch in s:
+        if ch == " ":
+            n += 1
+        elif ch == "\t":
+            n += 2
+        else:
+            break
+    return n
+
+
+def _strip_scalar(v: str) -> Any:
+    v = v.strip()
+    if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
+        return v[1:-1]
+    if v.startswith("[") and v.endswith("]"):
+        inner = v[1:-1].strip()
+        if not inner:
+            return []
+        return [_strip_scalar(s.strip()) for s in inner.split(",")]
+    lv = v.lower()
+    if lv == "true":
+        return True
+    if lv == "false":
+        return False
+    if lv in ("null", "~", ""):
+        return None
+    if re.match(r"^[+-]?\d+$", v):
+        return int(v)
+    if re.match(r"^[+-]?\d+\.\d+$", v):
+        return float(v)
+    return v
+
+
+# ---------------------------------------------------------------------------
+# Argparse setup
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="agentproc",
+        description="Run an AgentProc profile against a message.",
+        add_help=False,
+    )
+    p.add_argument("-h", "--help", action="store_true")
+    p.add_argument("--version", action="store_true")
+    p.add_argument("-p", "--profile")
+    p.add_argument("--prompt")
+    p.add_argument("--session", default="")
+    p.add_argument("--session-name", default="default")
+    p.add_argument("--from", dest="from_user", default="")
+    p.add_argument("--cwd")
+    p.add_argument("--env", action="append", default=[])
+    p.add_argument("--timeout", type=int)
+    p.add_argument("--no-stream", action="store_true")
+    p.add_argument("--verbose", action="store_true")
+    p.add_argument("--quiet", action="store_true")
+    p.add_argument("--raw", action="store_true")
+    p.add_argument("--stdin", action="store_true")
+    return p
+
+
+def show_help() -> None:
+    sys.stdout.write(f"""agentproc v{PKG_VERSION} (protocol {PROTOCOL_VERSION})
+
+Usage:
+  agentproc --profile <path.yaml> --prompt "hello" [options]
+
+Required:
+  --profile, -p <path>      Profile YAML path
+  --prompt <text>           User message (or use --stdin)
+
+Session:
+  --session <id>            Previous session id (multi-turn)
+  --session-name <name>     Human-readable session name (default: "default")
+  --from <user>             Sender identifier
+
+Execution:
+  --cwd <path>              Override profile.cwd
+  --env KEY=VALUE           Extra env var (repeatable)
+  --timeout <secs>          Override profile.timeout_secs
+  --no-stream               Set AGENT_STREAMING=0
+
+Output:
+  --verbose                 Forward protocol lines to stderr (default)
+  --quiet                   Suppress protocol lines on stderr
+  --raw                     Don't parse stdout; forward agent output verbatim
+  --stdin                   Read prompt from stdin instead of --prompt
+
+Other:
+  --version                 Print version and exit
+  --help, -h                Show this help
+
+Output semantics:
+  stderr  → protocol lines (AGENT_PARTIAL:, AGENT_SESSION:, AGENT_ERROR:)
+  stdout  → final reply body (non-protocol lines)
+  exit    → 0 success · 1 error · 124 timeout (per spec)
+
+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
+""")
+
+
+def show_version() -> None:
+    sys.stdout.write(f"agentproc {PKG_VERSION} (protocol {PROTOCOL_VERSION})\n")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main(argv: Optional[List[str]] = None) -> int:
+    if argv is None:
+        argv = sys.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
+
+    prompt = opts.prompt
+    if opts.stdin:
+        try:
+            prompt = sys.stdin.read().rstrip("\n")
+        except KeyboardInterrupt:
+            return EXIT_ERROR
+    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:
+        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:
+        r = run(
+            profile_raw,
+            RunOptions(
+                message=prompt,
+                session_id=opts.session,
+                session_name=opts.session_name,
+                from_user=opts.from_user,
+                streaming=streaming,
+                cwd=opts.cwd,
+                extra_env=extra_env,
+                timeout_secs=opts.timeout,
+            ),
+        )
+        sys.stdout.write(r.reply)
+        if r.reply and not r.reply.endswith("\n"):
+            sys.stdout.write("\n")
+        return 0 if r.exit_code == 0 else 1
+
+    verbose = opts.verbose or not opts.quiet
+
+    r = run(
+        profile_raw,
+        RunOptions(
+            message=prompt,
+            session_id=opts.session,
+            session_name=opts.session_name,
+            from_user=opts.from_user,
+            streaming=streaming,
+            cwd=opts.cwd,
+            extra_env=extra_env,
+            timeout_secs=opts.timeout,
+            on_partial=lambda t: verbose and sys.stderr.write(
+                f"AGENT_PARTIAL:{json.dumps(t, ensure_ascii=False)}\n"
+            ),
+            on_session=lambda sid: verbose and sys.stderr.write(f"AGENT_SESSION:{sid}\n"),
+            on_error=lambda msg: verbose and sys.stderr.write(
+                f"AGENT_ERROR:{json.dumps(msg, ensure_ascii=False)}\n"
+            ),
+            on_stderr=lambda line: verbose and sys.stderr.write(f"[agent stderr] {line}\n"),
+        ),
+    )
+
+    if r.reply:
+        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
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentproc-0.2.1/src/agentproc/runner.py

@@ -0,0 +1,381 @@
+"""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.
+
+Responsibilities:
+  - Parse and validate a profile dict
+  - Substitute {{MESSAGE}}, {{SESSION_ID}}, {{SESSION_NAME}} placeholders
+  - Inject AGENT_* env vars + profile env block
+  - Spawn the agent command (no shell)
+  - Read stdout line by line, classify protocol lines vs reply body
+  - Forward AGENT_PARTIAL: in real time (via on_partial callback)
+  - Capture the last AGENT_SESSION: line (last-wins rule)
+  - Honor AGENT_ERROR: lines
+  - Enforce timeout_secs with SIGTERM → kill_grace_secs → SIGKILL
+  - Write message to stdin and close (when profile.stdin == 'message')
+  - Return RunResult(reply, session_id, error, exit_code, timed_out)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "DEFAULT_TIMEOUT_SECS",
+    "DEFAULT_KILL_GRACE_SECS",
+    "DEFAULT_MAX_REPLY_CHARS",
+    "EXIT_SUCCESS",
+    "EXIT_ERROR",
+    "EXIT_TIMEOUT",
+    "EXIT_SIGINT",
+    "EXIT_SIGTERM",
+    "RunResult",
+    "RunOptions",
+    "run",
+    "normalize_profile",
+    "classify_line",
+    "decode_json_value",
+    "substitute",
+    "expand_env_ref",
+    "expand_path",
+]
+
+PROTOCOL_VERSION = "0.1"
+
+DEFAULT_TIMEOUT_SECS = 1800
+DEFAULT_KILL_GRACE_SECS = 5
+DEFAULT_MAX_REPLY_CHARS = 8000
+
+PREFIX_SESSION = "AGENT_SESSION:"
+PREFIX_PARTIAL = "AGENT_PARTIAL:"
+PREFIX_ERROR = "AGENT_ERROR:"
+
+EXIT_SUCCESS = 0
+EXIT_ERROR = 1
+EXIT_TIMEOUT = 124
+EXIT_SIGINT = 130
+EXIT_SIGTERM = 143
+
+
+@dataclass
+class RunResult:
+    """Result of running an agent process."""
+
+    reply: str = ""
+    session_id: str = ""
+    error: str = ""
+    exit_code: int = 0
+    timed_out: bool = False
+
+
+@dataclass
+class RunOptions:
+    """Options passed to run()."""
+
+    message: str
+    session_id: str = ""
+    session_name: str = "default"
+    from_user: str = ""
+    streaming: Optional[bool] = None
+    extra_env: Dict[str, str] = field(default_factory=dict)
+    cwd: 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
+
+
+# ---------------------------------------------------------------------------
+# Profile parsing & validation
+# ---------------------------------------------------------------------------
+
+def normalize_profile(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """Validate and normalize a profile dict."""
+    if not isinstance(raw, dict):
+        raise ValueError("profile must be a dict")
+
+    src = raw.get("agentproc") if isinstance(raw.get("agentproc"), dict) else raw
+
+    command = src.get("command")
+    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", [])
+    if not isinstance(args_value, list):
+        raise ValueError("profile.args must be a list")
+
+    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")
+
+    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,
+        "stdin": "message" if src.get("stdin") == "message" else "none",
+        "timeout_secs": (
+            int(src["timeout_secs"]) if _is_int_like(src.get("timeout_secs"))
+            else DEFAULT_TIMEOUT_SECS
+        ),
+        "kill_grace_secs": (
+            int(src["kill_grace_secs"]) if _is_int_like(src.get("kill_grace_secs"))
+            else DEFAULT_KILL_GRACE_SECS
+        ),
+        "max_reply_chars": (
+            int(src["max_reply_chars"]) if _is_int_like(src.get("max_reply_chars"))
+            else DEFAULT_MAX_REPLY_CHARS
+        ),
+        "streaming": src.get("streaming", True) is not False,
+    }
+
+
+def _is_int_like(v: Any) -> bool:
+    if isinstance(v, bool):
+        return False
+    if isinstance(v, int):
+        return True
+    if isinstance(v, str) and v.strip().lstrip("-").isdigit():
+        return True
+    return False
+
+
+def expand_path(p: str) -> str:
+    if p == "~":
+        return str(Path.home())
+    if p.startswith("~/"):
+        return str(Path.home() / p[2:])
+    return p
+
+
+def substitute(value: str, ctx: Dict[str, str]) -> str:
+    return (
+        str(value)
+        .replace("{{MESSAGE}}", ctx.get("message", ""))
+        .replace("{{SESSION_ID}}", ctx.get("session_id", ""))
+        .replace("{{SESSION_NAME}}", ctx.get("session_name", ""))
+    )
+
+
+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),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Line classification (per spec)
+# ---------------------------------------------------------------------------
+
+def decode_json_value(raw: str) -> str:
+    text = raw.strip()
+    if not text:
+        return ""
+    try:
+        v = json.loads(text)
+        return v if isinstance(v, str) else str(v)
+    except json.JSONDecodeError:
+        return text
+
+
+def classify_line(line: str) -> Dict[str, str]:
+    if line.startswith(PREFIX_SESSION):
+        return {"kind": "session", "value": line[len(PREFIX_SESSION):].strip()}
+    if line.startswith(PREFIX_PARTIAL):
+        return {"kind": "partial", "value": decode_json_value(line[len(PREFIX_PARTIAL):])}
+    if line.startswith(PREFIX_ERROR):
+        return {"kind": "error", "value": decode_json_value(line[len(PREFIX_ERROR):])}
+    return {"kind": "body", "value": line}
+
+
+# ---------------------------------------------------------------------------
+# run() — the main entry point
+# ---------------------------------------------------------------------------
+
+def run(profile_raw: Dict[str, Any], options: RunOptions) -> RunResult:
+    """Run an agent process per the AgentProc spec."""
+    profile = normalize_profile(profile_raw)
+
+    streaming = (
+        options.streaming if options.streaming is not None else profile["streaming"]
+    )
+    timeout_secs = (
+        options.timeout_secs if options.timeout_secs is not None else profile["timeout_secs"]
+    )
+    cwd = options.cwd or profile["cwd"]
+
+    subst_ctx = {
+        "message": options.message,
+        "session_id": options.session_id,
+        "session_name": options.session_name,
+    }
+
+    argv = list(profile["argv"])
+    for a in profile["args"]:
+        argv.append(substitute(a, subst_ctx))
+
+    env = dict(os.environ)
+    for k, v in profile["env"].items():
+        env[k] = expand_env_ref(substitute(str(v), subst_ctx), os.environ)
+    for k, v in options.extra_env.items():
+        env[k] = str(v)
+
+    env["AGENT_MESSAGE"] = options.message
+    env["AGENT_SESSION_ID"] = options.session_id
+    env["AGENT_SESSION_NAME"] = options.session_name
+    env["AGENT_FROM_USER"] = options.from_user
+    env["AGENT_STREAMING"] = "1" if streaming else "0"
+    env["AGENT_PROTOCOL_VERSION"] = PROTOCOL_VERSION
+
+    stdin_payload = options.message if profile["stdin"] == "message" else None
+
+    result = RunResult()
+    body_lines: List[str] = []
+
+    try:
+        proc = subprocess.Popen(
+            argv,
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.PIPE if stdin_payload is not None else subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+    except FileNotFoundError as e:
+        if options.on_stderr:
+            options.on_stderr(f"[agentproc runner] spawn error: {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}")
+        result.exit_code = EXIT_ERROR
+        return result
+
+    if stdin_payload is not None:
+        try:
+            proc.stdin.write(stdin_payload)
+            proc.stdin.close()
+        except BrokenPipeError:
+            pass
+
+    def _drain_stderr() -> None:
+        assert proc.stderr is not None
+        for line in proc.stderr:
+            line = line.rstrip("\r\n")
+            if options.on_stderr:
+                options.on_stderr(line)
+
+    stderr_thread = threading.Thread(target=_drain_stderr, daemon=True)
+    stderr_thread.start()
+
+    assert proc.stdout is not None
+
+    def _handle_line(raw_line: str) -> None:
+        line = raw_line.rstrip("\r")
+        c = classify_line(line)
+        if c["kind"] == "session":
+            result.session_id = c["value"]
+            if options.on_session:
+                options.on_session(c["value"])
+            if options.on_protocol_line:
+                options.on_protocol_line(line)
+        elif c["kind"] == "partial":
+            if streaming and options.on_partial:
+                options.on_partial(c["value"])
+            if options.on_protocol_line:
+                options.on_protocol_line(line)
+        elif c["kind"] == "error":
+            result.error = c["value"]
+            if options.on_error:
+                options.on_error(c["value"])
+            if options.on_protocol_line:
+                options.on_protocol_line(line)
+        else:
+            body_lines.append(line)
+
+    def _drain_stdout() -> None:
+        assert proc.stdout is not None
+        for raw_line in proc.stdout:
+            _handle_line(raw_line.rstrip("\n"))
+
+    stdout_thread = threading.Thread(target=_drain_stdout, daemon=True)
+    stdout_thread.start()
+
+    exit_code: int
+    timed_out = False
+    try:
+        if timeout_secs and timeout_secs > 0:
+            deadline = time.monotonic() + timeout_secs
+            while True:
+                try:
+                    exit_code = proc.wait(timeout=0.5)
+                    break
+                except subprocess.TimeoutExpired:
+                    if time.monotonic() >= deadline:
+                        timed_out = True
+                        try:
+                            proc.send_signal(signal.SIGTERM)
+                        except (ProcessLookupError, PermissionError):
+                            pass
+                        try:
+                            proc.wait(timeout=profile["kill_grace_secs"])
+                        except subprocess.TimeoutExpired:
+                            try:
+                                proc.send_signal(signal.SIGKILL)
+                            except (ProcessLookupError, PermissionError):
+                                pass
+                        try:
+                            exit_code = proc.wait(timeout=2)
+                        except subprocess.TimeoutExpired:
+                            exit_code = EXIT_TIMEOUT
+                        break
+        else:
+            exit_code = proc.wait()
+    except KeyboardInterrupt:
+        try:
+            proc.send_signal(signal.SIGINT)
+        except (ProcessLookupError, PermissionError):
+            pass
+        exit_code = proc.wait()
+
+    stdout_thread.join(timeout=5)
+    stderr_thread.join(timeout=2)
+
+    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 timed_out:
+        result.timed_out = True
+        result.exit_code = EXIT_TIMEOUT
+    elif result.error:
+        result.exit_code = EXIT_ERROR if exit_code == 0 else exit_code
+    else:
+        result.exit_code = exit_code
+
+    return result

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: agentproc
-Version: 0.1.1
-Summary: AgentProc SDK — connect any Agent CLI to a messaging platform with a single function
+Version: 0.2.1
+Summary: AgentProc Protocol SDK + CLI — connect any Agent CLI to a messaging platform
 License: MIT
 Project-URL: Homepage, https://github.com/jeffkit/agentproc
-Project-URL: Documentation, https://jeffkit.github.io/agentproc/
+Project-URL: Documentation, https://agentproc.dev/
 Project-URL: Repository, https://github.com/jeffkit/agentproc
 Project-URL: Issues, https://github.com/jeffkit/agentproc/issues
 Requires-Python: >=3.9

{agentproc-0.1.1 → agentproc-0.2.1}/src/agentproc.egg-info/SOURCES.txt

@@ -1,7 +1,11 @@
 pyproject.toml
 src/agentproc/__init__.py
+src/agentproc/cli.py
+src/agentproc/runner.py
 src/agentproc.egg-info/PKG-INFO
 src/agentproc.egg-info/SOURCES.txt
 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_agentproc.py
+tests/test_runner.py

agentproc-0.2.1/src/agentproc.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentproc = agentproc.cli:main

agentproc-0.2.1/tests/test_runner.py

@@ -0,0 +1,374 @@
+"""Tests for agentproc.runner — the canonical bridge-side implementation."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import textwrap
+from pathlib import Path
+from typing import List
+
+import pytest
+
+from agentproc.runner import (
+    PROTOCOL_VERSION,
+    RunOptions,
+    classify_line,
+    decode_json_value,
+    expand_env_ref,
+    expand_path,
+    normalize_profile,
+    run,
+    substitute,
+)
+
+
+# ---------------------------------------------------------------------------
+# 1. Pure-function tests
+# ---------------------------------------------------------------------------
+
+class TestClassifyLine:
+    def test_session_line(self):
+        assert classify_line("AGENT_SESSION:abc-123") == {"kind": "session", "value": "abc-123"}
+
+    def test_session_strips_whitespace(self):
+        assert classify_line("AGENT_SESSION:  abc-123  ") == {"kind": "session", "value": "abc-123"}
+
+    def test_partial_json_string(self):
+        assert classify_line('AGENT_PARTIAL:"hello"') == {"kind": "partial", "value": "hello"}
+
+    def test_partial_with_newline_in_json(self):
+        assert classify_line('AGENT_PARTIAL:"line1\\nline2"') == {"kind": "partial", "value": "line1\nline2"}
+
+    def test_partial_lenient_on_bad_json(self):
+        assert classify_line("AGENT_PARTIAL:not json") == {"kind": "partial", "value": "not json"}
+
+    def test_partial_empty_value(self):
+        assert classify_line("AGENT_PARTIAL:") == {"kind": "partial", "value": ""}
+
+    def test_error_line(self):
+        assert classify_line('AGENT_ERROR:"rate limited"') == {"kind": "error", "value": "rate limited"}
+
+    def test_error_lenient_on_bad_json(self):
+        assert classify_line("AGENT_ERROR:boom") == {"kind": "error", "value": "boom"}
+
+    def test_body_line(self):
+        assert classify_line("hello world") == {"kind": "body", "value": "hello world"}
+
+    def test_line_starting_with_space_is_not_protocol(self):
+        assert classify_line(" AGENT_SESSION:foo") == {"kind": "body", "value": " AGENT_SESSION:foo"}
+
+    def test_prefix_like_but_not_exact(self):
+        assert classify_line("AGENT_SESSION") == {"kind": "body", "value": "AGENT_SESSION"}
+
+
+class TestDecodeJsonValue:
+    def test_json_string(self):
+        assert decode_json_value('"hi"') == "hi"
+
+    def test_json_string_with_newline(self):
+        assert decode_json_value('"a\\nb"') == "a\nb"
+
+    def test_empty(self):
+        assert decode_json_value("") == ""
+
+    def test_non_json_returns_trimmed_raw(self):
+        assert decode_json_value("  not json  ") == "not json"
+
+    def test_json_number(self):
+        assert decode_json_value("42") == "42"
+
+
+class TestSubstitute:
+    def test_message(self):
+        assert substitute("You said: {{MESSAGE}}", {"message": "hi"}) == "You said: hi"
+
+    def test_session_id(self):
+        assert substitute("s={{SESSION_ID}}", {"session_id": "abc"}) == "s=abc"
+
+    def test_session_name(self):
+        assert substitute("n={{SESSION_NAME}}", {"session_name": "work"}) == "n=work"
+
+    def test_empty_session_id(self):
+        assert substitute("s={{SESSION_ID}}", {"session_id": ""}) == "s="
+
+    def test_multiple_placeholders(self):
+        out = substitute(
+            "{{MESSAGE}} [{{SESSION_ID}}] ({{SESSION_NAME}})",
+            {"message": "hi", "session_id": "s1", "session_name": "work"},
+        )
+        assert out == "hi [s1] (work)"
+
+
+class TestExpandEnvRef:
+    def test_known_var(self):
+        assert expand_env_ref("${HOME}", {"HOME": "/u/x"}) == "/u/x"
+
+    def test_unknown_var_becomes_empty(self):
+        assert expand_env_ref("${NOPE}", {}) == ""
+
+    def test_no_refs(self):
+        assert expand_env_ref("plain value", {}) == "plain value"
+
+    def test_mixed(self):
+        assert expand_env_ref("key=${HOME} and ${missing}", {"HOME": "/h"}) == "key=/h and "
+
+
+class TestExpandPath:
+    def test_tilde_alone(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        assert expand_path("~") == str(tmp_path)
+
+    def test_tilde_slash(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        assert expand_path("~/foo") == str(tmp_path / "foo")
+
+    def test_absolute_unchanged(self):
+        assert expand_path("/usr/bin") == "/usr/bin"
+
+    def test_relative_unchanged(self):
+        assert expand_path("./foo") == "./foo"
+
+
+class TestNormalizeProfile:
+    def test_minimal_valid(self):
+        p = normalize_profile({"command": "bash ./x.sh"})
+        assert p["argv"] == ["bash", "./x.sh"]
+        assert p["stdin"] == "none"
+        assert p["streaming"] is True
+
+    def test_hub_form(self):
+        p = normalize_profile({"agentproc": {"command": "node ./x.js"}})
+        assert p["argv"] == ["node", "./x.js"]
+
+    def test_rejects_missing_command(self):
+        with pytest.raises(ValueError, match="command must be a non-empty string"):
+            normalize_profile({})
+
+    def test_rejects_empty_command(self):
+        with pytest.raises(ValueError, match="command must be a non-empty string"):
+            normalize_profile({"command": "   "})
+
+    def test_rejects_non_dict(self):
+        with pytest.raises(ValueError, match="must be a dict"):
+            normalize_profile(None)  # type: ignore
+
+    def test_argv_splits_on_whitespace(self):
+        p = normalize_profile({"command": "bash    ./spaced.sh"})
+        assert p["argv"] == ["bash", "./spaced.sh"]
+
+    def test_args_default_empty(self):
+        p = normalize_profile({"command": "x"})
+        assert p["args"] == []
+
+    def test_args_cast_to_str(self):
+        p = normalize_profile({"command": "x", "args": ["--foo", 42]})
+        assert p["args"] == ["--foo", "42"]
+
+    def test_cwd_tilde_expanded(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        p = normalize_profile({"command": "x", "cwd": "~/proj"})
+        assert p["cwd"] == str(tmp_path / "proj")
+
+    def test_stdin_message_vs_other(self):
+        assert normalize_profile({"command": "x", "stdin": "message"})["stdin"] == "message"
+        assert normalize_profile({"command": "x", "stdin": "none"})["stdin"] == "none"
+        assert normalize_profile({"command": "x", "stdin": "bogus"})["stdin"] == "none"
+        assert normalize_profile({"command": "x"})["stdin"] == "none"
+
+    def test_streaming_false_honored(self):
+        assert normalize_profile({"command": "x", "streaming": False})["streaming"] is False
+        assert normalize_profile({"command": "x", "streaming": True})["streaming"] is True
+        assert normalize_profile({"command": "x"})["streaming"] is True
+
+
+def test_protocol_version_is_0_1():
+    assert PROTOCOL_VERSION == "0.1"
+
+
+# ---------------------------------------------------------------------------
+# 2. run() end-to-end tests with tiny agent scripts
+# ---------------------------------------------------------------------------
+
+def write_script(content: str, tmp_path: Path) -> Path:
+    f = tmp_path / "agent.sh"
+    f.write_text(content)
+    f.chmod(f.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    return f
+
+
+@pytest.fixture
+def agent_script(tmp_path):
+    def _make(content: str) -> Path:
+        return write_script(content, tmp_path)
+    return _make
+
+
+class TestRunEndToEnd:
+    def test_simple_reply_body(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho 'hello'\n")
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.reply.strip() == "hello"
+        assert r.session_id == ""
+        assert r.error == ""
+        assert r.exit_code == 0
+
+    def test_session_last_wins(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo "AGENT_SESSION:first"
+            echo "AGENT_SESSION:second"
+            echo "done"
+        """))
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.session_id == "second"
+        assert r.reply.strip() == "done"
+
+    def test_partial_triggers_callback(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo 'AGENT_PARTIAL:"chunk1"'
+            echo 'AGENT_PARTIAL:"chunk2"'
+            echo "final"
+        """))
+        partials: List[str] = []
+        r = run(
+            {"command": str(agent)},
+            RunOptions(message="hi", on_partial=partials.append),
+        )
+        assert partials == ["chunk1", "chunk2"]
+        assert r.reply.strip() == "final"
+
+    def test_partial_skipped_when_streaming_false(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo 'AGENT_PARTIAL:"chunk1"'
+            echo "final"
+        """))
+        partials: List[str] = []
+        r = run(
+            {"command": str(agent)},
+            RunOptions(message="hi", streaming=False, on_partial=partials.append),
+        )
+        assert partials == []
+        assert r.reply.strip() == "final"
+
+    def test_error_surfaces(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo 'AGENT_PARTIAL:"thinking..."'
+            echo 'AGENT_ERROR:"rate limited"'
+            exit 1
+        """))
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.error == "rate limited"
+        assert r.exit_code == 1
+
+    def test_error_marks_exit_1_even_if_process_exits_0(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo 'AGENT_ERROR:"soft fail"'
+            exit 0
+        """))
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.error == "soft fail"
+        assert r.exit_code == 1
+
+    def test_body_lines_with_leading_space_not_treated_as_protocol(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo " AGENT_SESSION:foo"
+            echo "real reply"
+        """))
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.session_id == ""
+        assert "\n" in r.reply
+
+    def test_exit_code_propagates(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\nexit 3\n")
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.exit_code == 3
+
+    def test_message_injected_as_env(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho \"got: $AGENT_MESSAGE\"\n")
+        r = run({"command": str(agent)}, RunOptions(message="payload"))
+        assert r.reply.strip() == "got: payload"
+
+    def test_session_id_injected_from_options(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho \"prev: $AGENT_SESSION_ID\"\n")
+        r = run({"command": str(agent)}, RunOptions(message="hi", session_id="prev-123"))
+        assert r.reply.strip() == "prev: prev-123"
+
+    def test_protocol_version_injected(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho \"pv=$AGENT_PROTOCOL_VERSION\"\n")
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.reply.strip() == f"pv={PROTOCOL_VERSION}"
+
+    def test_streaming_reflects_option(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho \"stream=$AGENT_STREAMING\"\n")
+        r1 = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r1.reply.strip() == "stream=1"
+        r2 = run({"command": str(agent)}, RunOptions(message="hi", streaming=False))
+        assert r2.reply.strip() == "stream=0"
+
+    def test_profile_env_with_var_ref(self, agent_script, monkeypatch):
+        monkeypatch.setenv("MY_TEST_VAR", "/some/path")
+        agent = agent_script("#!/usr/bin/env bash\necho \"v=$MY_KEY\"\n")
+        r = run(
+            {"command": str(agent), "env": {"MY_KEY": "${MY_TEST_VAR}"}},
+            RunOptions(message="hi"),
+        )
+        assert r.reply.strip() == "v=/some/path"
+
+    def test_message_placeholder_in_args(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho \"args: $1\"\n")
+        r = run(
+            {"command": str(agent), "args": ["{{MESSAGE}}"]},
+            RunOptions(message="hello"),
+        )
+        assert r.reply.strip() == "args: hello"
+
+    def test_extra_env_applied(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\necho \"x=$X\"\n")
+        r = run(
+            {"command": str(agent)},
+            RunOptions(message="hi", extra_env={"X": "extra"}),
+        )
+        assert r.reply.strip() == "x=extra"
+
+    def test_stdin_message_written_and_eof(self, tmp_path):
+        agent = tmp_path / "agent.sh"
+        agent.write_text("#!/usr/bin/env bash\nread line\necho \"stdin: $line\"\n")
+        agent.chmod(agent.stat().st_mode | 0o111)
+        r = run(
+            {"command": str(agent), "stdin": "message"},
+            RunOptions(message="via-stdin"),
+        )
+        assert r.reply.strip() == "stdin: via-stdin"
+
+    def test_timeout_kills_long_agent(self, agent_script):
+        agent = agent_script("#!/usr/bin/env bash\nsleep 30\necho 'should not reach'\n")
+        r = run(
+            {"command": str(agent), "kill_grace_secs": 1},
+            RunOptions(message="hi", timeout_secs=1),
+        )
+        assert r.timed_out is True
+        assert r.exit_code == 124
+
+    def test_multiline_reply_preserves_newlines(self, agent_script):
+        agent = agent_script(textwrap.dedent("""\
+            #!/usr/bin/env bash
+            echo "line 1"
+            echo "line 2"
+            echo "line 3"
+        """))
+        r = run({"command": str(agent)}, RunOptions(message="hi"))
+        assert r.reply == "line 1\nline 2\nline 3"
+
+    def test_spawn_error_command_not_found(self):
+        r = run(
+            {"command": "/nonexistent/command/xyz"},
+            RunOptions(message="hi"),
+        )
+        assert r.exit_code == 1