agentpm 0.1.0__py3-none-any.whl

agentpm/__init__.py

@@ -0,0 +1,30 @@
+"""AgentPM Python SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+__all__ = ["load", "to_langchain_tool", "__version__"]
+
+# Real exports
+from importlib.metadata import PackageNotFoundError, version
+
+from .core import load
+
+try:
+    __version__ = version("agentpm")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+# Tell type checkers that this symbol exists (no runtime import cost)
+if TYPE_CHECKING:
+    from .adapters.langchain import to_langchain_tool as to_langchain_tool  # re-exported type
+
+
+# Lazy attribute for optional adapter (runtime)
+def __getattr__(name: str) -> Any:
+    if name == "to_langchain_tool":
+        from .adapters.langchain import to_langchain_tool
+
+        return to_langchain_tool
+    raise AttributeError(name)

agentpm/adapters/langchain.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import TypedDict, TypeGuard
+
+from ..types import JsonValue, LoadedWithMeta, ToolFunc, ToolMeta
+
+# ---------- JSON Schema typing & guards ----------
+
+
+class JsonSchemaProperty(TypedDict, total=False):
+    type: str
+
+
+class JsonSchemaObject(TypedDict, total=False):
+    type: str
+    properties: dict[str, JsonSchemaProperty]
+    required: list[str]
+
+
+def _is_json_schema_object(x: object) -> TypeGuard[JsonSchemaObject]:
+    if not isinstance(x, dict):
+        return False
+    if x.get("type") != "object":
+        return False
+    props = x.get("properties")
+    # ok if missing or a dict
+    return props is None or isinstance(props, dict)
+
+
+def _is_record_json(x: object) -> TypeGuard[dict[str, JsonValue]]:
+    return isinstance(x, dict)
+
+
+# ---------- Result mapping ----------
+
+
+def _default_result_to_string(result: JsonValue, meta: ToolMeta | None) -> str:
+    outputs = meta.get("outputs") if meta else None
+    if _is_json_schema_object(outputs):
+        o = outputs
+        req = o.get("required")
+        key = req[0] if isinstance(req, list) and req else None
+        if isinstance(key, str):
+            props = o.get("properties") or {}
+            prop = props.get(key)
+            if isinstance(prop, dict) and prop.get("type") == "string" and _is_record_json(result):
+                val = result.get(key)
+                if isinstance(val, str):
+                    return val
+    return result if isinstance(result, str) else json.dumps(result)
+
+
+# ---------- Minimal adapter tool we return ----------
+
+
+@dataclass
+class _AdapterTool:
+    name: str
+    description: str
+    _call_structured: Callable[[Mapping[str, JsonValue]], str]
+
+    def invoke(self, args: Mapping[str, JsonValue]) -> str:
+        return self._call_structured(args)
+
+    def func(self, args: Mapping[str, JsonValue]) -> str:
+        return self._call_structured(args)
+
+    def __call__(self, args: Mapping[str, JsonValue]) -> str:
+        return self._call_structured(args)
+
+
+# ---------- Public API ----------
+
+
+def to_langchain_tool(
+    loaded: LoadedWithMeta,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    result_to_string: Callable[[JsonValue], str] | None = None,
+    force_simple: bool = False,
+) -> _AdapterTool:
+    # Enforce optional dependency presence
+    try:
+        import langchain_core.tools as _  # noqa: F401
+    except Exception as e:  # pragma: no cover
+        raise ImportError(
+            "to_langchain_tool() requires langchain-core. Install with: pip install 'agentpm[langchain]'"
+        ) from e
+
+    tool_func: ToolFunc = loaded["func"]
+    meta: ToolMeta = loaded["meta"]
+
+    if not callable(tool_func):
+        raise TypeError("loaded['func'] must be callable")
+
+    tool_name: str = name or (meta.get("name") or "agentpm_tool")
+    desc_base: str = description or (meta.get("description") or "")
+
+    rich_desc = desc_base
+    if "inputs" in meta:
+        rich_desc += f" Inputs: {json.dumps(meta['inputs'])}."
+    if "outputs" in meta:
+        rich_desc += f" Outputs: {json.dumps(meta['outputs'])}."
+
+    r2s: Callable[[JsonValue], str] = result_to_string or (
+        lambda r: _default_result_to_string(r, meta)
+    )
+
+    inputs_schema = meta.get("inputs")
+    structured = _is_json_schema_object(inputs_schema) and not force_simple
+
+    if structured:
+
+        def call_structured(args: Mapping[str, JsonValue]) -> str:
+            res = tool_func(dict(args))  # plain dict[str, JsonValue]
+            return r2s(res)
+
+        return _AdapterTool(name=tool_name, description=rich_desc, _call_structured=call_structured)
+
+    # Simple path: coerce to object if schema hints at properties
+    def call_simple(input_like: Mapping[str, JsonValue]) -> str:
+        payload: JsonValue
+        if _is_json_schema_object(inputs_schema):
+            props = list((inputs_schema.get("properties") or {}).keys())
+            if "text" in props and isinstance(input_like.get("text"), str):
+                payload = {"text": input_like["text"]}
+            elif len(props) == 1:
+                key = props[0]
+                val = input_like.get(key)
+                # accept JSON-compatible values; else stringify
+                if val is None or isinstance(val, str | int | float | bool | dict | list):
+                    payload = {key: val}
+                else:
+                    payload = {key: str(val)}
+            else:
+                # Try common keys
+                for k in ("input", "value", "text"):
+                    v = input_like.get(k)
+                    if isinstance(v, str | int | float | bool):
+                        payload = {"text": str(v)}
+                        break
+                else:
+                    payload = dict(input_like)
+        else:
+            if isinstance(input_like.get("text"), str):
+                payload = {"text": input_like["text"]}
+            else:
+                payload = dict(input_like)
+
+        res = tool_func(payload)
+        return r2s(res)
+
+    return _AdapterTool(name=tool_name, description=rich_desc, _call_structured=call_simple)

agentpm/core.py

@@ -0,0 +1,600 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import resource
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Callable
+from contextlib import suppress
+from pathlib import Path
+from typing import Literal, cast, overload
+
+from semver import VersionInfo
+from semver import match as semver_match
+
+from .types import Entrypoint, JsonValue, LoadedWithMeta, Manifest, Runtime, ToolFunc, ToolMeta
+
+DEFAULT_TIMEOUT = 120.0
+_ALLOWED = {"node", "nodejs", "python", "python3"}
+
+
+def _debug_enabled() -> bool:
+    val = os.getenv("AGENTPM_DEBUG", "")
+    return val not in ("", "0", "false", "False", "no")
+
+
+def _dprint(msg: str) -> None:
+    if _debug_enabled():
+        sys.stderr.write(f"[agentpm-debug] {msg}\n")
+
+
+def _abbrev(s: str, n: int = 240) -> str:
+    return s if len(s) <= n else (s[:n] + "…")
+
+
+def _merge_env(
+    entry_env: dict[str, str] | None,
+    caller_env: dict[str, str] | None,
+) -> dict[str, str]:
+    merged = os.environ.copy()
+    if entry_env:
+        merged.update(entry_env)
+    if caller_env:
+        merged.update(caller_env)
+    return merged
+
+
+def _canonical(cmd: str) -> str:
+    # handle absolute paths and Windows extensions
+    base = os.path.basename(cmd).lower()
+    for ext in (".exe", ".cmd", ".bat"):
+        if base.endswith(ext):
+            return base[: -len(ext)]
+    return base
+
+
+def _interpreter_family(cmd: str) -> str | None:
+    base = os.path.basename(cmd).lower()
+    if base in ("node", "nodejs"):
+        return "node"
+    if base.startswith("python"):
+        return "python"
+    return None  # absolute paths still get matched by basename
+
+
+def _resolve_interpreter_command(
+    cmd: str,
+    entry_env: dict[str, str] | None,
+    caller_env: dict[str, str] | None,
+    runtime_type: str | None,
+) -> str:
+    merged = _merge_env(entry_env, caller_env)
+
+    # Prefer inferring from the command; fall back to runtime hint if needed
+    inferred = _interpreter_family(cmd)
+    hint = runtime_type if runtime_type == "node" or runtime_type == "python" else None
+    family = inferred or hint or None
+
+    if family == "node" and merged.get("AGENTPM_NODE"):
+        _dprint(f'override interpreter (node): "{cmd}" -> "{merged["AGENTPM_NODE"]}"')
+        return merged["AGENTPM_NODE"]
+    if family == "python" and merged.get("AGENTPM_PYTHON"):
+        _dprint(f'override interpreter (python): "{cmd}" -> "{merged["AGENTPM_PYTHON"]}"')
+        return merged["AGENTPM_PYTHON"]
+    return cmd
+
+
+def _assert_allowed_interpreter(cmd: str) -> None:
+    canon = _canonical(cmd)
+    if canon not in _ALLOWED and not canon.startswith("pyhton3"):
+        raise ValueError(
+            f'Unsupported agent.json.entrypoint.command "{cmd}". Allowed: node|nodejs|python|python3'
+        )
+
+
+# verify the interpreter exists on PATH
+def _assert_interpreter_available(
+    cmd: str, entry_env: dict[str, str] | None, caller_env: dict[str, str] | None
+) -> None:
+    merged = _merge_env(entry_env, caller_env)
+
+    which = shutil.which(cmd, path=merged.get("PATH", ""))
+    _dprint(f'interpreter="{cmd}" which={which or "<not found>"}')
+    _dprint(f'MERGED PATH={_abbrev(merged.get("PATH",""))}')
+
+    if which is None:
+        raise FileNotFoundError(
+            f'Interpreter "{cmd}" not found on PATH.\nChecked PATH={merged.get("PATH","")}'
+        )
+
+
+def _assert_interpreter_matches_runtime(cmd: str, runtime: Runtime) -> None:
+    canon = _canonical(cmd)
+    runtime_interpreter = _canonical(runtime["type"])
+
+    if not is_interpreter_match(runtime_interpreter, canon):
+        raise ValueError(
+            f'Misconfigured tool - agent.json.entrypoint.command "{cmd}" does not match tool runtime {runtime_interpreter}'
+        )
+
+
+def is_interpreter_match(runtime: str, command: str) -> bool:
+    if runtime == command:
+        return True
+
+    # runtime -> acceptable command aliases
+    aliases = {"python": ["python3"], "node": ["nodejs"]}
+
+    return command in aliases.get(runtime, [])
+
+
+def _list_installed_versions(base: Path, name: str) -> list[str]:
+    """Return all installed x.y.z versions for a tool name, searching all name dir variants."""
+    seen: set[str] = set()
+
+    for name_dir in candidate_name_dirs(str(base), name):
+        root = Path(name_dir)
+        if not root.is_dir():
+            continue
+
+        for child in root.iterdir():
+            if not child.is_dir():
+                continue
+
+            v = child.name
+            try:
+                # validate semver
+                VersionInfo.parse(v)
+            except ValueError:
+                continue
+
+            if (child / "agent.json").exists():
+                seen.add(v)
+
+    # highest first
+    return sorted(seen, key=VersionInfo.parse, reverse=True)
+
+
+def candidate_name_dirs(base: str, name: str) -> list[str]:
+    """
+    Supports names like "@scope/name" or "scope/name".
+    Tries:
+      base/@scope/name, base/scope/name, base/scope__name, base/scope-name
+    Falls back to base/name for unscoped.
+    """
+    parts = name.split("/")
+
+    if len(parts) == 2:
+        raw_scope, pkg = parts
+        scope = raw_scope[1:] if raw_scope.startswith("@") else raw_scope
+        return [
+            os.path.join(base, f"@{scope}", pkg),  # with '@'
+            os.path.join(base, scope, pkg),  # without '@'
+            os.path.join(base, f"{scope}__{pkg}"),
+            os.path.join(base, f"{scope}-{pkg}"),
+        ]
+
+    # Unscoped package
+    return [os.path.join(base, name)]
+
+
+def _find_installed(base: Path, name: str, version: str) -> tuple[Path, Path] | None:
+    """Return (root, manifest_path) if this exact version exists, searching all name dir variants."""
+    for name_dir in candidate_name_dirs(str(base), name):
+        root = Path(name_dir) / version
+        manifest = root / "agent.json"
+        if manifest.exists():
+            return root, manifest
+    return None
+
+
+def find_project_root(start_dir: str | Path) -> Path:
+    """
+    Walk up from start_dir looking for project markers.
+    Priority: agent.json, package.json, pnpm-workspace.yaml, turbo.json, lerna.json, .git
+    Returns the resolved start_dir if nothing is found.
+    """
+    dir_path = Path(start_dir).resolve()
+    while True:
+        if (dir_path / "agent.json").exists():
+            return dir_path
+        if (dir_path / "package.json").exists():
+            return dir_path
+        if (dir_path / "pnpm-workspace.yaml").exists():
+            return dir_path
+        if (dir_path / "turbo.json").exists():
+            return dir_path
+        if (dir_path / "lerna.json").exists():
+            return dir_path
+        if (dir_path / ".git").exists():
+            return dir_path
+
+        parent = dir_path.parent
+        if parent == dir_path:  # reached filesystem root
+            break
+        dir_path = parent
+
+    return Path(start_dir).resolve()
+
+
+def _normalize_selector(selector: str) -> str:
+    s = selector.strip()
+    if not s or s.lower() == "latest":
+        return ""
+
+    def parts(ver: str) -> tuple[int, int, int, int]:
+        xs = [p for p in ver.strip().split(".") if p != ""]
+        n = len(xs)
+        maj = int(xs[0]) if n >= 1 else 0
+        min_ = int(xs[1]) if n >= 2 else 0
+        pat = int(xs[2]) if n >= 3 else 0
+        return maj, min_, pat, n
+
+    if s[0] in ("^", "~"):
+        op, base = s[0], s[1:].strip()
+        maj, min_, pat, n = parts(base)
+        lower = f">={maj}.{min_}.{pat}"
+        if op == "^":
+            if maj > 0:
+                upper = f"<{maj+1}.0.0"
+            elif n == 1:
+                upper = "<1.0.0"  # ^0
+            elif min_ > 0:
+                upper = f"<0.{min_+1}.0"  # ^0.y
+            else:
+                upper = f"<0.0.{pat+1}"  # ^0.0.z
+        else:  # '~'
+            upper = f"<{maj + 1}.0.0" if n == 1 else f"<{maj}.{min_ + 1}.0"
+        # return space-separated; we'll split on spaces/commas later
+        return f"{lower} {upper}"
+
+    # Comparator set like ">=0.1.1 <0.2.0" (or commas) → normalize whitespace
+    tokens = [t for t in s.replace(",", " ").split() if t]
+    return " ".join(tokens)
+
+
+def _version_satisfies(ver: str, selector: str) -> bool:
+    expr = _normalize_selector(selector)
+    if not expr:  # empty / "latest"
+        return True
+    # Split on spaces or commas
+    tokens = [t for t in re.split(r"[,\s]+", expr) if t]
+    try:
+        return all(semver_match(ver, tok) for tok in tokens)
+    except ValueError:
+        return False
+
+
+def _resolve_tool_root(spec: str, tool_dir_override: str | None) -> tuple[Path, Path]:
+    # spec form: @scope/name@<version or range or 'latest'>
+    at = spec.rfind("@")
+    if at <= 0 or at == len(spec) - 1:
+        raise ValueError(f'Invalid tool spec "{spec}". Expected "@scope/name@version".')
+
+    selector = spec[at + 1 :].strip()
+
+    raw_name = spec[:at]
+    name = raw_name[1:] if raw_name.startswith("@") else raw_name  # drop leading '@' if present
+
+    project_root = find_project_root(Path.cwd())
+    _dprint(f"project_root={project_root}")
+
+    # candidate search roots (project first)
+    candidates: list[Path] = []
+    if tool_dir_override:
+        candidates.append(Path(tool_dir_override))
+
+    env_dir = os.getenv("AGENTPM_TOOL_DIR")
+    if env_dir:
+        candidates.append(Path(env_dir))
+
+    candidates.append(project_root / ".agentpm" / "tools")
+    candidates.append(Path.home() / ".agentpm" / "tools")
+
+    _dprint("candidates:\n  " + "\n  ".join(str(c) for c in candidates))
+
+    # 1) Exact version fast path
+    try:
+        if selector and selector.lower() != "latest":
+            VersionInfo.parse(selector)  # raises if not exact x.y.z
+            for base in candidates:
+                hit = _find_installed(base, name, selector)
+                if hit:
+                    return hit
+            raise FileNotFoundError(f'Tool "{spec}" not found in .agentpm/tools (or overrides).')
+    except ValueError:
+        # not an exact version → fall through to range/latest
+        pass
+
+    # 2) Range or "latest" (or empty after "@")
+    want_latest = (not selector) or (selector.lower() == "latest")
+
+    for base in candidates:
+        installed = _list_installed_versions(base, name)
+        if not installed:
+            continue
+
+        if want_latest:
+            picked = installed[0]
+            hit = _find_installed(base, name, picked)
+            if hit:
+                return hit
+            continue
+
+        # Filter by range using semver.match, then pick highest
+        satisfying: list[str] = []
+        for v in installed:
+            if _version_satisfies(v, selector):
+                satisfying.append(v)
+
+        if satisfying:
+            picked = sorted(satisfying, key=VersionInfo.parse, reverse=True)[0]
+            hit = _find_installed(base, name, picked)
+            if hit:
+                return hit
+
+    searched = ", ".join(str(c) for c in candidates)
+    raise FileNotFoundError(
+        f'No installed version of "{name}" matches "{selector or "latest"}". Searched: {searched}'
+    )
+
+
+def _read_manifest(p: Path) -> Manifest:
+    m = json.loads(p.read_text(encoding="utf-8"))
+    ep = m.get("entrypoint", {})
+    if not ep or not ep.get("command"):
+        raise ValueError(f"agent.json missing entrypoint.command at: {p}")
+    return m  # type: ignore[no-any-return]
+
+
+def _build_env(
+    entry_env: dict[str, str], caller_env: dict[str, str], home: str, tmpdir: str
+) -> dict[str, str]:
+    base = {
+        "PATH": os.environ.get("PATH", ""),
+        "HOME": home,
+        "TMPDIR": tmpdir,
+    }
+    # Optional: preserve locale if present
+    for k in ("LANG", "LC_ALL"):
+        if k in os.environ:
+            base[k] = os.environ[k]
+    # Agent-provided env wins, then caller overrides
+    return {**base, **entry_env, **caller_env}
+
+
+def _preexec_rlimits_for(
+    cmd: str,
+    *,
+    max_cpu_s: int | None = 10,
+    max_files: int | None = 512,
+    max_addr_mb: int | None = 512,
+) -> Callable[[], None]:
+    """
+    Apply rlimits safely per interpreter.
+
+    - Node (node/nodejs): SKIP RLIMIT_AS by default (V8 JIT/WASM need large VA space).
+      You can force a value with env AGENTPM_RLIMIT_AS_MB.
+    - Python: keep modest RLIMIT_AS if you want.
+    """
+    import os
+    import resource  # type: ignore
+
+    IS_DARWIN = os.uname().sysname == "Darwin"
+    fam = _canonical(cmd)
+    is_node = fam in ("node", "nodejs")
+
+    # Optional global override
+    env_override = os.getenv("AGENTPM_RLIMIT_AS_MB")
+    addr_mb = max_addr_mb
+    if env_override:
+        with suppress(ValueError):
+            parsed = int(env_override)
+            if parsed > 0:
+                addr_mb = parsed
+
+    # Default: do NOT cap address space for Node
+    if is_node and env_override is None:
+        addr_mb = None
+
+    _dprint(
+        f"rlimits: cmd={cmd} RLIMIT_AS={'off' if is_node and env_override is None else addr_mb}MB"
+    )
+
+    def _fn() -> None:
+        if max_cpu_s is not None and hasattr(resource, "RLIMIT_CPU"):
+            resource.setrlimit(resource.RLIMIT_CPU, (max_cpu_s, max_cpu_s))
+        if max_files is not None and hasattr(resource, "RLIMIT_NOFILE"):
+            resource.setrlimit(resource.RLIMIT_NOFILE, (max_files, max_files))
+        if addr_mb is not None and not IS_DARWIN and hasattr(resource, "RLIMIT_AS"):
+            limit = addr_mb * 1024 * 1024
+            resource.setrlimit(resource.RLIMIT_AS, (limit, limit))
+
+    return _fn
+
+
+def _spawn_once(
+    root: Path, entry: Entrypoint, payload: JsonValue, timeout_s: float, env: dict[str, str]
+) -> JsonValue:
+    # 1) Tool working dir (what the tool expects for relative paths)
+    tool_cwd = (root / entry.get("cwd", ".")).resolve()
+
+    # 2) Isolated run dirs for HOME/TMPDIR
+    run_root: Path = tool_cwd / "run"
+    run_root.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(prefix="run-", dir=str(run_root)))
+    home = str(work / "home")
+    Path(home).mkdir(parents=True, exist_ok=True)
+    tmpd = str(work / "tmp")
+    Path(tmpd).mkdir(parents=True, exist_ok=True)
+
+    # 3) Clean env
+    env = _build_env(entry.get("env", {}), env, home, tmpd)
+
+    # 4) Command + hardening flags
+    cmd = [entry["command"], *entry.get("args", [])]
+    if _canonical(entry["command"]).startswith("python"):
+        if "-I" not in cmd:
+            cmd.insert(1, "-I")
+        if "-B" not in cmd:
+            cmd.insert(1, "-B")
+    elif _canonical(entry["command"]).startswith("node"):
+        old_space = int(env.get("AGENTPM_NODE_OLD_SPACE_MB", "256"))
+
+        if not any(a.startswith("--max-old-space-size") for a in cmd[1:]):
+            cmd.insert(1, f"--max-old-space-size={old_space}")
+
+        want_jitless = (
+            any(a == "--jitless" for a in cmd[1:])
+            or "--jitless" in (env or {}).get("NODE_OPTIONS", "")
+            or env.get("AGENTPM_NODE_JITLESS", "").lower() in ("1", "true", "yes")
+        )
+        if want_jitless and "--jitless" not in cmd[1:]:
+            cmd.insert(1, "--jitless")
+
+    _dprint(f"launch: argv={cmd}")
+    _dprint(f"cwd={tool_cwd}")
+    # _dprint(f"env={env}")
+    # 5) Spawn (cwd = tool_cwd)
+    proc = subprocess.Popen(
+        cmd,
+        cwd=str(tool_cwd),
+        env=env,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        start_new_session=True,
+        preexec_fn=(
+            _preexec_rlimits_for(entry["command"]) if hasattr(resource, "setrlimit") else None
+        ),
+    )
+    try:
+        stdout, stderr = proc.communicate(input=json.dumps(payload), timeout=timeout_s)
+    except subprocess.TimeoutExpired as e:
+        proc.kill()
+        raise TimeoutError(f"Tool timed out after {timeout_s:.1f}s") from e
+
+    # Cap outputs (10MB)
+    max_bytes = 10 * 1024 * 1024
+    if len(stdout.encode("utf-8")) + len(stderr.encode("utf-8")) > max_bytes:
+        raise RuntimeError("Tool produced too much output; limit is 10MB")
+
+    if proc.returncode != 0:
+        # Save full streams for inspection and KEEP the run dir on error
+        try:
+            (work / "child.stdout").write_text(stdout or "", encoding="utf-8")
+            (work / "child.stderr").write_text(stderr or "", encoding="utf-8")
+        except Exception:
+            pass
+        _dprint(f"[agentpm] child logs saved in: {work}")
+
+        tail = stderr[-4000:] if stderr else ""
+        raise RuntimeError(f"Tool exited with code {proc.returncode}. Stderr (tail):\n{tail}")
+
+    try:
+        return _extract_last_json(stdout)
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to parse tool JSON output.\nStderr:\n{stderr}\nStdout:\n{stdout}\nReason: {e}"
+        ) from e
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+def _extract_last_json(text: str) -> JsonValue:
+    # naive but effective: scan for last '{' and try parse json from there.
+    idx = text.rfind("{")
+    if idx < 0:
+        raise RuntimeError("No JSON object found on stdout.")
+    return json.loads(text[idx:])  # type: ignore[no-any-return]
+
+
+# --- Overloads (type-only) ---
+@overload
+def load(
+    spec: str,
+    with_meta: Literal[True],
+    timeout: float | None = ...,
+    tool_dir_override: str | None = ...,
+    env: dict[str, str] | None = ...,
+) -> LoadedWithMeta: ...
+@overload
+def load(
+    spec: str,
+    with_meta: Literal[False] = ...,
+    timeout: float | None = ...,
+    tool_dir_override: str | None = ...,
+    env: dict[str, str] | None = ...,
+) -> ToolFunc: ...
+
+
+def load(
+    spec: str,
+    with_meta: bool = False,
+    timeout: float | None = None,
+    tool_dir_override: str | None = None,
+    env: dict[str, str] | None = None,
+) -> ToolFunc | LoadedWithMeta:
+    _dprint(f"spec={spec}")
+
+    root, manifest_path = _resolve_tool_root(spec, tool_dir_override)
+    m = _read_manifest(manifest_path)
+
+    env = env or {}
+
+    # enforce interpreter whitelist and available
+    ep = m["entrypoint"]
+
+    _dprint(f"resolved root={root}")
+    _dprint(f"manifest={manifest_path}")
+    _dprint(f'entry.command="{ep["command"]}" args={ep.get("args", [])}')
+
+    runtime = m.get("runtime") or {}
+    rt = runtime.get("type")
+    runtime_type: str | None = rt if rt in ("node", "python") else None
+    resolved_cmd = _resolve_interpreter_command(ep["command"], ep.get("env", {}), env, runtime_type)
+
+    # enforce interpreter whitelist and available
+    _assert_allowed_interpreter(resolved_cmd)
+    _assert_interpreter_available(resolved_cmd, ep.get("env", {}), env)
+
+    # enforce interpreter and runtime compatability
+    if "runtime" in m and "type" in m["runtime"]:
+        _assert_interpreter_matches_runtime(resolved_cmd, m["runtime"])
+
+    t_s = (
+        timeout
+        if timeout is not None
+        else float(ep.get("timeout_ms") or (DEFAULT_TIMEOUT * 1000)) / 1000.0
+    )
+
+    entry_for_spawn = ep | {"command": resolved_cmd}
+
+    def func(input: JsonValue) -> JsonValue:
+        return _spawn_once(root, entry_for_spawn, input, t_s, env)
+
+    if with_meta:
+        name = m["name"]
+        version = m["version"]
+
+        meta: ToolMeta = {
+            "name": name,
+            "version": version,
+        }
+
+        desc = m.get("description")
+        if isinstance(desc, str):
+            meta["description"] = desc
+        if "inputs" in m:
+            meta["inputs"] = cast(JsonValue, m["inputs"])
+        if "outputs" in m:
+            meta["outputs"] = cast(JsonValue, m["outputs"])
+
+        return {"func": func, "meta": meta}
+
+    return func

agentpm/types.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NotRequired, Required, TypedDict
+
+JsonPrimitive = str | int | float | bool | None
+JsonValue = JsonPrimitive | dict[str, "JsonValue"] | list["JsonValue"]
+
+
+class ToolMeta(TypedDict, total=False):
+    name: Required[str]
+    version: Required[str]
+    description: NotRequired[str]
+    inputs: NotRequired[JsonValue]
+    outputs: NotRequired[JsonValue]
+    runtime: NotRequired[Runtime]
+
+
+class Runtime(TypedDict, total=False):
+    type: str
+    version: str
+
+
+class Entrypoint(TypedDict, total=False):
+    command: str
+    args: list[str]
+    cwd: str
+    timeout_ms: int
+    env: dict[str, str]
+
+
+class Manifest(ToolMeta, total=False):
+    entrypoint: Entrypoint
+
+
+ToolFunc = Callable[[JsonValue], JsonValue]
+
+
+class LoadedWithMeta(TypedDict):
+    func: ToolFunc
+    meta: ToolMeta

agentpm-0.1.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: agentpm
+Version: 0.1.0
+Summary: AgentPM Python SDK
+Project-URL: Homepage, https://github.com/agentpm-dev/sdk-python
+Project-URL: Repository, https://github.com/agentpm-dev/sdk-python
+Project-URL: Issues, https://github.com/agentpm-dev/sdk-python/issues
+Project-URL: Changelog, https://github.com/agentpm-dev/sdk-python/releases
+Author-email: AgentPM <dev@agentpm.dev>
+License: MIT License
+        
+        Copyright (c) 2025 Zack Hine
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the “Software”), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+License-File: LICENSE
+Keywords: agentpm,agents,ai,tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: semver>=3.0.0
+Provides-Extra: dev
+Requires-Dist: black>=24.8.0; extra == 'dev'
+Requires-Dist: build>=1.2.1; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.8; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# AgentPM Python SDK
+
+A lean, typed Python SDK for **AgentPM** tools. It discovers tools installed by `agentpm install`, executes their entrypoints in a subprocess, and returns JSON results you can pass to your agents.
+
+- 🔎 **Discovers** tools in `.agentpm/tools` (project) and `~/.agentpm/tools` (user), with `AGENTPM_TOOL_DIR` override.
+- 🚀 **Runs entrypoints** via `node` or `python` (whitelisted) and exchanges JSON over stdin/stdout.
+- 🧩 **Metadata-aware**: `with_meta=True` returns `func + meta` (name, version, description, inputs, outputs).
+- 🧪 **Framework adapters (optional)**: e.g., a LangChain adapter you can use if installed.
+
+> Requires Python **3.10+**.
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+Using **uv**:
+```bash
+uv pip install agentpm
+```
+
+Or with standard pip:
+```bash
+python -m pip install agentpm
+```
+
+If you'll use the optional LangChain adapter:
+```bash
+uv pip install 'agentpm[langchain]'
+# or
+python -m pip install 'agentpm[langchain]'
+```
+---
+
+## Quick Start (with `uv`)
+
+```bash
+# create and activate a venv
+uv venv
+source .venv/bin/activate
+
+# install SDK in editable dev mode (ruff/black/mypy/pytest, etc.)
+uv pip install -e ".[dev]"
+
+# sanity checks
+uv run ruff check .
+uv run black --check .
+uv run mypy
+uv run pytest -q
+```
+
+> If you're not using `uv`, standard `python -m venv` + `pip install -e ".[dev]"` works too.
+
+---
+
+## Using the SDK
+
+```python
+from agentpm import load
+
+# Spec format: "@scope/name@version"
+summarize = load("@zack/summarize@0.1.0")
+
+result = summarize({"text": "Long document content..."})
+print(result["summary"])
+```
+
+### With metadata (build richer tool descriptions)
+```python
+from agentpm import load
+
+tool = load("@zack/summarize@0.1.0", with_meta=True)
+summarize, meta = tool["func"], tool["meta"]
+
+rich_description = (
+    f"{meta.get('description','')} "
+    f"Inputs: {meta.get('inputs')}. "
+    f"Outputs: {meta.get('outputs')}."
+)
+
+print(rich_description)
+print(summarize({"text": "hello"})["summary"])
+```
+
+### Optional: LangChain adapter
+The adapter is lazy-imported and only needed if you call it.
+
+```python
+from agentpm import load, to_langchain_tool  # to_langchain_tool is loaded on first access
+
+loaded = load("@zack/summarize@0.1.0", with_meta=True)
+tool = to_langchain_tool(loaded)  # requires `langchain-core` installed
+```
+
+If you use the adapter, install LangChain core:
+
+```bash
+uv pip install langchain-core
+```
+
+---
+
+## Where tools are discovered
+
+Resolution order:
+
+1. `AGENTPM_TOOL_DIR` (environment variable)
+2. `./.agentpm/tools` (project-local)
+3. `~/.agentpm/tools` (user-local)
+
+Each tool lives in a directory like:
+
+```
+.agentpm/
+  tools/
+    @zack/summarize/
+      0.1.0/
+        agent.json
+        (tool files…)
+```
+
+---
+
+## Manifest & Runtime Contract
+
+**`agent.json` (minimal fields used by the SDK):**
+```json
+{
+  "name": "@zack/summarize",
+  "version": "0.1.0",
+  "description": "Summarize long text.",
+  "inputs": {
+    "type": "object",
+    "properties": { "text": { "type": "string", "description": "Text to summarize" } },
+    "required": ["text"]
+  },
+  "outputs": {
+    "type": "object",
+    "properties": { "summary": { "type": "string", "description": "Summarized text" } },
+    "required": ["summary"]
+  },
+  "entrypoint": {
+    "command": "python",
+    "args": ["main.py"],
+    "cwd": ".",
+    "timeout_ms": 60000,
+    "env": {}
+  }
+}
+```
+
+**Execution contract:**
+- SDK writes **inputs JSON** to the process **stdin**.
+- Tool writes a single **outputs JSON** object to **stdout**.
+- Non-JSON logs should go to **stderr**.
+- Process must exit with **code 0** on success.
+
+**Interpreter whitelist:** `node`, `nodejs`, `python`, `python3`.
+The SDK validates the interpreter and checks it’s present on `PATH`.
+
+---
+
+## Development
+
+### Project layout
+```
+src/
+  agentpm/
+    __init__.py           # re-exports: load, to_langchain_tool (lazy)
+    core.py               # resolver/spawn/JSON plumbing
+    types.py              # JsonValue, TypedDicts
+    adapters/
+      __init__.py
+      langchain.py        # optional adapter
+    py.typed              # marks package as typed
+tests/
+  test_basic.py
+```
+
+### Common tasks (via `uv`)
+```bash
+uv run ruff check .
+uv run black --check .
+uv run mypy
+uv run pytest -q
+
+# run hooks locally on all files
+uv run pre-commit run --all-files
+```
+
+---
+
+## Building & Publishing
+
+```bash
+# build wheel & sdist
+uv run python -m build
+
+# verify metadata
+uv run twine check dist/*
+
+# upload (PyPI)
+uv run twine upload dist/*
+
+# or TestPyPI first
+uv run twine upload -r testpypi dist/*
+```
+
+---
+
+## Running mixed-runtime Agent apps with Docker
+
+Some AgentPM tools run on Node, some on Python—and your agent may need to spawn both. Using Docker gives you a single, reproducible environment where both interpreters are installed and on PATH, which avoids the common “interpreter not found” issues that pop up on PaaS/CI or IDEs.
+
+Why Docker?
+
+✅ Hermetic: Python + Node versions are pinned inside the image.
+
+✅ No PATH drama: node/python are present and discoverable.
+
+✅ Prod/CI parity: the same image runs on your laptop, CI, and servers.
+
+✅ Easy secrets: pass API keys via env at docker run/Compose time.
+
+✅ Fewer surprises: consistent OS libs for LLM clients, SSL, etc.
+
+### When to use it
+
+- You deploy to platforms that don’t let you apt-get both runtimes.
+- Your agent uses tools with different interpreters (Node + Python).
+- Your local dev/IDE PATH differs from production and causes failures.
+- You want reproducible builds and easy rollback.
+
+### How to use it
+
+1. Copy the provided [Dockerfile](https://github.com/agentpm-dev/sdk-python/tree/main/examples/python-agent) into your repo.
+2. (Optional) Pre-install tools locally with agentpm install ... and commit or copy .agentpm/tools/ into the image, or run agentpm install at build time if your CLI is available in the image.
+3. Build & run:
+
+```bash
+docker build -t agent-app .
+docker run --rm -e OPENAI_API_KEY=$OPENAI_API_KEY agent-app
+```
+
+4. For development, use the docker-compose.yml snippet to mount your source and pass env vars conveniently.
+
+### Troubleshooting
+
+- Set `AGENTPM_DEBUG=1` to print the SDK’s project root, search paths, merged PATH, and resolved interpreters.
+- You can force interpreters via:
+```ini
+AGENTPM_NODE=/usr/bin/node
+AGENTPM_PYTHON=/usr/local/bin/python3.11
+```
+
+- Prefer absolute interpreters in agent.json.entrypoint.command for production (e.g., /usr/bin/node). The SDKs still enforce the Node/Python family.
+
+---
+
+## Troubleshooting
+
+- **`No JSON object found on stdout.`**
+  Ensure your tool prints a single JSON object as the last thing on stdout, and writes logs to stderr.
+
+- **`Unsupported agent.json.entrypoint.command`**
+  Only `node` / `python` are allowed (including `nodejs` / `python3`). Update `entrypoint.command`.
+
+- **`Interpreter "... " not found on PATH`**
+  Install the interpreter or adjust `entrypoint.command`. The SDK runs `<command> --version` to verify availability.
+
+- **PEP 668 / “externally managed”**
+  Use a venv (we recommend `uv venv`) and install with `uv pip install -e ".[dev]"`.
+
+- **IDE can’t import `agentpm`**
+  Ensure your interpreter is the project’s `.venv/bin/python`, and that you ran the editable install.
+
+---
+
+## License
+
+MIT — see `LICENSE`.

agentpm-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+agentpm/__init__.py,sha256=kmS34PbRFkkgXCrV7o8YQ8EvFg-wAPk8-q8ouOsRdek,784
+agentpm/core.py,sha256=PaF-KEeUYmg4-m_4zshZP7Zxp7-mLObjO6BQKJf10nA,19411
+agentpm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentpm/types.py,sha256=8kKv6MD-cfVEMRUeU-tEEftx-ggFQMGATgvgXkJAu0c,874
+agentpm/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentpm/adapters/langchain.py,sha256=k812eo325LdE76TjPiFPkuPfpcZSMEOS1QSHnKswo8g,5204
+agentpm-0.1.0.dist-info/METADATA,sha256=mdxwdrDoD_iv-a8ruBWRLxIRt17skMPQmBkeIrB0QHs,9880
+agentpm-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agentpm-0.1.0.dist-info/licenses/LICENSE,sha256=8uYxF1GbxKhtQUFq4nHvYXzglvMsqlF-ZpMQjKkCxTI,1074
+agentpm-0.1.0.dist-info/RECORD,,

agentpm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentpm-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zack Hine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.