agentmint-hermes-runner 0.4.0__py3-none-any.whl

agentmint_hermes_runner/__init__.py

@@ -0,0 +1,40 @@
+from .auth.bearer import BearerAuth
+from .auth.tempo import TempoAuth
+from .dispatcher import AgentMintDispatcher
+from .exceptions import (
+    AgentMintError,
+    DispatchInterrupted,
+    DispatchTimeout,
+    UnsupportedToolset,
+)
+from .hermes_patch import install_delegate_task_wrapper
+from .models import AgentRecord, DispatchResult, Task
+from .translation import (
+    DEFAULT_TOOLSETS,
+    ROLE_HINTS,
+    TOOLSET_RESTRICTION_HINTS,
+    UNSUPPORTED_TOOLSETS,
+    compose_prompt,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "AgentMintDispatcher",
+    "BearerAuth",
+    "TempoAuth",
+    "AgentRecord",
+    "DispatchResult",
+    "Task",
+    "AgentMintError",
+    "DispatchTimeout",
+    "DispatchInterrupted",
+    "UnsupportedToolset",
+    "compose_prompt",
+    "DEFAULT_TOOLSETS",
+    "ROLE_HINTS",
+    "TOOLSET_RESTRICTION_HINTS",
+    "UNSUPPORTED_TOOLSETS",
+    "install_delegate_task_wrapper",
+    "__version__",
+]

agentmint_hermes_runner/auth/__init__.py

@@ -0,0 +1,5 @@
+from .base import Auth
+from .bearer import BearerAuth
+from .tempo import TempoAuth
+
+__all__ = ["Auth", "BearerAuth", "TempoAuth"]

agentmint_hermes_runner/auth/base.py

@@ -0,0 +1,18 @@
+from typing import Protocol
+
+
+class Auth(Protocol):
+    """Transport strategy for AgentMint /a2a calls.
+
+    Implementations own the full HTTP exchange so we can support both
+    header-based auth (Bearer JWT) and external-CLI auth (Tempo's
+    `tempo request` subprocess that handles the 402 dance end-to-end).
+    """
+
+    def call(self, endpoint: str, method: str, body: bytes) -> bytes:
+        """POST `body` to `endpoint` and return the response body bytes.
+
+        `method` is the JSON-RPC method name (for logging only — the actual
+        envelope is already serialized into `body`).
+        """
+        ...

agentmint_hermes_runner/auth/bearer.py

@@ -0,0 +1,29 @@
+import httpx
+
+
+class BearerAuth:
+    """Stripe-Link credit-wallet authentication via cached JWT.
+
+    Bootstrap the JWT once via `link-cli` calling `credits.topup`; every
+    subsequent /a2a call uses `Authorization: Bearer <jwt>` and debits the
+    caller-wide credit wallet keyed by `link_stripe:cus_...`.
+    """
+
+    def __init__(self, jwt: str, timeout: float = 30.0):
+        if not jwt:
+            raise ValueError("jwt is required")
+        self.jwt = jwt
+        self.timeout = timeout
+
+    def call(self, endpoint: str, method: str, body: bytes) -> bytes:
+        with httpx.Client(timeout=self.timeout) as http:
+            resp = http.post(
+                endpoint,
+                content=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.jwt}",
+                },
+            )
+            resp.raise_for_status()
+            return resp.content

agentmint_hermes_runner/auth/tempo.py

@@ -0,0 +1,37 @@
+import subprocess
+
+
+class TempoAuth:
+    """Per-call MPP payment via the `tempo request` CLI.
+
+    The Tempo CLI handles the 402 challenge / USDC.e transfer / signature
+    end-to-end as a single subprocess, then prints the merchant response on
+    stdout. We just shell out and return the stdout bytes.
+
+    Note: `tempo-request` plugin must be at version 0.5.2. Newer versions
+    (0.6.0+) hit "Invalid base64 JSON header" against AgentMint's challenge.
+    Downgrade via: `tempo cli 0.0.0 downgrade tempo request cli to 0.5.2`
+    """
+
+    def __init__(
+        self,
+        executable: str = "tempo",
+        account: str | None = None,
+        timeout: float = 120.0,
+    ):
+        self.executable = executable
+        self.account = account
+        self.timeout = timeout
+
+    def call(self, endpoint: str, method: str, body: bytes) -> bytes:
+        cmd: list[str] = [self.executable, "request", "-X", "POST", "--json", body.decode("utf-8")]
+        if self.account:
+            cmd.extend(["-n", self.account])
+        cmd.append(endpoint)
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            timeout=self.timeout,
+            check=True,
+        )
+        return proc.stdout

agentmint_hermes_runner/client.py

@@ -0,0 +1,40 @@
+import json
+import uuid
+from typing import Any
+
+from .auth.base import Auth
+from .exceptions import AgentMintError
+
+
+class Client:
+    """Minimal JSON-RPC 2.0 client for AgentMint /a2a.
+
+    Auth strategy owns the HTTP transport; this class only handles envelope
+    serialization and error mapping.
+    """
+
+    def __init__(self, endpoint: str, auth: Auth):
+        self.endpoint = endpoint
+        self.auth = auth
+
+    def call(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        body = json.dumps(
+            {
+                "jsonrpc": "2.0",
+                "id": str(uuid.uuid4()),
+                "method": method,
+                "params": params or {},
+            }
+        ).encode("utf-8")
+        resp_bytes = self.auth.call(self.endpoint, method, body)
+        try:
+            data = json.loads(resp_bytes)
+        except json.JSONDecodeError as e:
+            raise AgentMintError(f"non-JSON response from {self.endpoint}: {e}") from e
+        if "error" in data:
+            err = data["error"]
+            raise AgentMintError(
+                f"{err.get('code', 'unknown')}: {err.get('message', '')}",
+                data=err.get("data"),
+            )
+        return data.get("result")

agentmint_hermes_runner/dispatcher.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import threading
+from concurrent.futures import CancelledError, ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FutureTimeoutError
+from typing import Any
+
+from .auth.base import Auth
+from .client import Client
+from .exceptions import DispatchInterrupted, DispatchTimeout
+from .models import AgentRecord, DispatchResult, Task
+from .translation import compose_prompt
+
+CHILD_TIMEOUT_FLOOR = 30.0  # Hermes parity: floor 30s when timeout is enabled
+
+
+class AgentMintDispatcher:
+    """High-level wrapper around AgentMint's /a2a JSON-RPC surface.
+
+    Translates Hermes' `delegate_task` ergonomics (goal + context + toolsets
+    + role) into AgentMint's single-`prompt` agent.run model. The
+    persistent-sandbox semantics are NOT abstracted — that's the value: a
+    Hermes operator calls `dispatch()` and the work lands in a sandbox
+    whose /workspace survives across calls.
+    """
+
+    def __init__(
+        self,
+        auth: Auth,
+        endpoint: str = "https://api.agentmint.store/a2a",
+    ):
+        self.client = Client(endpoint, auth)
+
+    # ----- direct method passthroughs ------------------------------------
+
+    def create(self, name: str, **kwargs: Any) -> AgentRecord:
+        params = {"name": name, **kwargs}
+        result = self.client.call("agent.create", params)
+        return AgentRecord.from_dict(result or {})
+
+    def get(self, agent_name: str) -> AgentRecord:
+        result = self.client.call("agent.get", {"name": agent_name})
+        return AgentRecord.from_dict(result or {})
+
+    def list(self, limit: int = 50, offset: int = 0) -> list[AgentRecord]:
+        result = self.client.call("agent.list", {"limit": limit, "offset": offset})
+        agents = (result or {}).get("agents", [])
+        return [AgentRecord.from_dict(a) for a in agents]
+
+    def delete(self, agent_name: str) -> None:
+        self.client.call("agent.delete", {"name": agent_name})
+
+    def cancel(self, agent_name: str) -> None:
+        self.client.call("agent.cancel", {"name": agent_name})
+
+    def run_status(self, run_id: str) -> dict[str, Any]:
+        """Read the status of an async dispatch by `run_id` (returned from
+        `dispatch(async_=True)`).
+
+        Bearer-only / Stripe-Link-only on the server side (v0.7.0+). Free.
+        Used by the polling delivery mode in `hermes_patch`.
+        """
+        return self.client.call("agent.run.status", {"run_id": run_id})
+
+    # ----- single dispatch -----------------------------------------------
+
+    def dispatch(
+        self,
+        agent_name: str,
+        goal: str,
+        context: str | None = None,
+        toolsets: list[str] | None = None,
+        role: str = "leaf",
+        max_iterations: int | None = None,
+        files: list[dict] | None = None,
+        cleanup_paths: list[str] | None = None,
+        async_: bool = False,
+        hermes_context: dict | None = None,
+        child_timeout_seconds: float | None = None,
+    ) -> DispatchResult:
+        """Dispatch one task to a named subagent.
+
+        `goal` and `context` are concatenated client-side (Hermes' rule:
+        the parent passes everything). `toolsets` / `role` / `max_iterations`
+        become soft system-prompt hints — AgentMint sandboxes can't
+        structurally enforce them.
+
+        Async dispatches return immediately with a `run_id`; poll
+        completion via `run_status(run_id)`.
+
+        If `child_timeout_seconds` is set, the call is wrapped with a hard
+        cap (floor 30s); on expiry, `agent.cancel` is fired and
+        `DispatchTimeout` is raised.
+        """
+        prompt = compose_prompt(goal, context, toolsets, role, max_iterations)
+        params: dict[str, Any] = {"name": agent_name, "prompt": prompt}
+        if files:
+            params["files"] = files
+        if cleanup_paths:
+            params["cleanup_paths"] = cleanup_paths
+        if async_:
+            params["async"] = True
+        if hermes_context:
+            params["metadata"] = {"hermes": hermes_context}
+
+        if child_timeout_seconds is None:
+            result = self.client.call("agent.run", params)
+            return DispatchResult.from_dict(result or {})
+
+        cap = max(float(child_timeout_seconds), CHILD_TIMEOUT_FLOOR)
+        with ThreadPoolExecutor(max_workers=1) as ex:
+            future = ex.submit(self.client.call, "agent.run", params)
+            try:
+                result = future.result(timeout=cap)
+            except FutureTimeoutError as e:
+                try:
+                    self.client.call("agent.cancel", {"name": agent_name})
+                except Exception:
+                    pass
+                raise DispatchTimeout(
+                    f"dispatch of {agent_name!r} exceeded {cap}s; agent.cancel issued"
+                ) from e
+        return DispatchResult.from_dict(result or {})
+
+    # ----- batch dispatch ------------------------------------------------
+
+    def dispatch_batch(
+        self,
+        tasks: list[Task],
+        max_concurrent_children: int = 3,
+        child_timeout_seconds: float | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> list[DispatchResult]:
+        """Fan out N tasks in parallel against named subagents.
+
+        - Results are returned in **input order** (matches Hermes' contract
+          "Results are sorted by task index to match input order regardless
+          of completion order").
+        - Up to `max_concurrent_children` run simultaneously
+          (`ThreadPoolExecutor`).
+        - On exception per task, a `DispatchResult` with `status="failed"`
+          (or `"timeout"` / `"interrupted"`) is inserted at that index — the
+          batch never aborts partial.
+        - `cancel_event` (a `threading.Event`) — when set, in-flight tasks
+          receive a best-effort `agent.cancel` and remaining tasks raise
+          `DispatchInterrupted`.
+        """
+        if max_concurrent_children < 1:
+            raise ValueError("max_concurrent_children must be >= 1")
+        if not tasks:
+            return []
+
+        results: list[DispatchResult | None] = [None] * len(tasks)
+
+        def run_one(idx: int, task: Task) -> None:
+            if cancel_event is not None and cancel_event.is_set():
+                results[idx] = DispatchResult(
+                    status="interrupted",
+                    extra={"error": "cancel_event set before task started"},
+                )
+                return
+            try:
+                results[idx] = self.dispatch(
+                    agent_name=task.agent_name,
+                    goal=task.goal,
+                    context=task.context,
+                    toolsets=task.toolsets,
+                    role=task.role,
+                    max_iterations=task.max_iterations,
+                    files=task.files,
+                    cleanup_paths=task.cleanup_paths,
+                    hermes_context=task.hermes_context,
+                    child_timeout_seconds=child_timeout_seconds,
+                )
+            except DispatchTimeout as e:
+                results[idx] = DispatchResult(status="timeout", extra={"error": str(e)})
+            except DispatchInterrupted as e:
+                results[idx] = DispatchResult(status="interrupted", extra={"error": str(e)})
+            except Exception as e:
+                results[idx] = DispatchResult(
+                    status="failed",
+                    extra={"error": str(e), "type": type(e).__name__},
+                )
+
+        watcher: threading.Thread | None = None
+        with ThreadPoolExecutor(max_workers=max_concurrent_children) as ex:
+            futures = [ex.submit(run_one, i, t) for i, t in enumerate(tasks)]
+
+            if cancel_event is not None:
+                def watch() -> None:
+                    cancel_event.wait()
+                    for f in futures:
+                        f.cancel()
+                    seen: set[str] = set()
+                    for t in tasks:
+                        if t.agent_name in seen:
+                            continue
+                        seen.add(t.agent_name)
+                        try:
+                            self.client.call("agent.cancel", {"name": t.agent_name})
+                        except Exception:
+                            pass
+
+                watcher = threading.Thread(target=watch, daemon=True)
+                watcher.start()
+
+            for f in futures:
+                try:
+                    f.result()
+                except CancelledError:
+                    # The cancel_event watcher cancelled this pending future
+                    # before run_one had a chance to set results[idx]. Leave
+                    # the slot as None; the synthesizer below fills it.
+                    pass
+
+        # Fill any None slots — either because the watcher cancelled a
+        # pending future, or (defensively) some other untracked path.
+        cancelled = cancel_event is not None and cancel_event.is_set()
+        fallback_status = "interrupted" if cancelled else "failed"
+        return [
+            r if r is not None else DispatchResult(
+                status=fallback_status,
+                extra={"error": f"task did not start ({fallback_status})"},
+            )
+            for r in results
+        ]

agentmint_hermes_runner/exceptions.py

@@ -0,0 +1,28 @@
+from typing import Any
+
+
+class AgentMintError(Exception):
+    def __init__(self, message: str, data: Any = None):
+        super().__init__(message)
+        self.data = data
+
+
+class DispatchTimeout(AgentMintError):
+    """Raised when a child_timeout_seconds limit fires for a single dispatch.
+
+    The adapter has already issued `agent.cancel` to the AgentMint server
+    by the time this is raised; the cancellation is best-effort (the
+    underlying run may still complete depending on timing).
+    """
+
+
+class DispatchInterrupted(AgentMintError):
+    """Raised inside a batch dispatch when the caller's cancel_event was set."""
+
+
+class UnsupportedToolset(AgentMintError):
+    """Raised when the caller requests a Hermes toolset that AgentMint does
+    not yet support (e.g. `"web"` in v0.2 — there is no canonical AgentMint
+    web-fetch skill yet; the three supported harnesses have built-in web
+    capability but we don't expose it as a structured toolset).
+    """

agentmint_hermes_runner/hermes_patch.py

@@ -0,0 +1,213 @@
+"""Monkey-patch Hermes' `tools.async_delegation.dispatch_async_delegation` so
+every `delegate_task(background=True, single-task)` routes to a named,
+persistent AgentMint subagent.
+
+Sync `delegate_task` is untouched (Hermes-native fan-out / batch behaviour
+preserved). Multi-task `background=True` is rejected upstream in Hermes
+itself, so we never see it.
+
+Completion is delivered exclusively via **polling** against AgentMint's
+`agent.run.status` endpoint (Bearer-only, free). No public HTTPS endpoint,
+no webhook secret, no HTTP route to register.
+"""
+import logging
+import threading
+import time
+from collections.abc import Callable
+from typing import Any
+
+from .dispatcher import AgentMintDispatcher
+
+logger = logging.getLogger(__name__)
+
+_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled", "timeout"})
+
+
+def install_delegate_task_wrapper(
+    dispatcher: AgentMintDispatcher,
+    default_agent_name: str,
+    poll_interval: float = 5.0,
+) -> Callable[[], None]:
+    """Patch Hermes' async-delegation rail to route through AgentMint.
+
+    Must be called ONCE at gateway startup, BEFORE any
+    `delegate_task(background=True)` call. Returns a callable that
+    reverses the patch (useful in tests / shutdown).
+
+    Parameters
+    ----------
+    dispatcher : AgentMintDispatcher
+        Pre-built dispatcher with auth attached.
+    default_agent_name : str
+        Name of the pre-minted AgentMint subagent every background
+        delegation routes to. The subagent's persistent `/workspace`
+        accumulates context across all delegations.
+    poll_interval : float
+        Seconds between `agent.run.status` polls (default 5.0). The
+        polling thread uses exponential backoff on errors up to 60s.
+    """
+    try:
+        import tools.async_delegation as _ad
+    except ImportError as e:
+        raise RuntimeError(
+            "Hermes module 'tools.async_delegation' not importable. "
+            "Run install_delegate_task_wrapper() inside the same Python "
+            "environment + process as Hermes' gateway."
+        ) from e
+
+    original = _ad.dispatch_async_delegation
+
+    def patched(**kwargs: Any) -> dict:
+        goal = kwargs.get("goal", "")
+        context = kwargs.get("context")
+        toolsets = kwargs.get("toolsets")
+        role = kwargs.get("role")
+        model = kwargs.get("model")
+        session_key = kwargs.get("session_key", "")
+
+        try:
+            result = dispatcher.dispatch(
+                agent_name=default_agent_name,
+                goal=goal,
+                context=context,
+                toolsets=toolsets,
+                role=role or "leaf",
+                async_=True,
+                hermes_context={"session_key": session_key, "model": model},
+            )
+            run_id = result.run_id or result.delegation_id
+            if not run_id:
+                raise RuntimeError("AgentMint async dispatch returned no run_id")
+
+            _spawn_poller(
+                dispatcher=dispatcher,
+                run_id=run_id,
+                goal=goal,
+                context=context,
+                session_key=session_key,
+                poll_interval=poll_interval,
+            )
+
+            return {
+                "status": "dispatched",
+                "delegation_id": run_id,
+                "goal": goal,
+                "mode": "background",
+                "source": "agentmint",
+            }
+        except Exception:
+            logger.exception(
+                "agentmint patched dispatch failed — falling back to Hermes-native"
+            )
+            return original(**kwargs)
+
+    _ad.dispatch_async_delegation = patched
+    logger.info(
+        "agentmint-hermes: installed delegate_task wrapper "
+        "(default_agent=%s, poll_interval=%.1fs)",
+        default_agent_name, poll_interval,
+    )
+
+    def uninstall() -> None:
+        _ad.dispatch_async_delegation = original
+
+    return uninstall
+
+
+def _spawn_poller(
+    *,
+    dispatcher: AgentMintDispatcher,
+    run_id: str,
+    goal: str,
+    context: str | None,
+    session_key: str,
+    poll_interval: float,
+) -> threading.Thread:
+    """Background daemon thread: polls `agent.run.status` until terminal,
+    then pushes a Hermes async_delegation completion event onto Hermes'
+    completion_queue.
+
+    Returns the thread (mostly for tests). Exits on terminal status or
+    after a hard cap of 30 minutes — the AgentMint run's own 30-minute
+    server-side TTL means the record disappears anyway past that point.
+    """
+    HARD_CAP_SECONDS = 30 * 60
+
+    def push_completion(status: str, payload: dict) -> None:
+        try:
+            from tools.async_delegation import _push_completion_event
+            _push_completion_event(
+                delegation_id=run_id,
+                status=status,
+                result=payload,
+            )
+            return
+        except Exception:
+            logger.warning(
+                "agentmint-hermes: _push_completion_event unavailable; "
+                "falling back to direct queue.put"
+            )
+        try:
+            from hermes.gateway.process_registry import completion_queue
+            completion_queue.put({
+                "type": "async_delegation",
+                "delegation_id": run_id,
+                "status": status,
+                "result": payload,
+                "task_source": {
+                    "goal": goal,
+                    "context": context,
+                    "session_key": session_key,
+                    "source": "agentmint",
+                },
+            })
+        except Exception:
+            logger.exception(
+                "agentmint-hermes: completion_queue push failed; "
+                "completion will not re-inject"
+            )
+
+    def loop() -> None:
+        backoff = poll_interval
+        started = time.monotonic()
+        while True:
+            time.sleep(backoff)
+            if time.monotonic() - started > HARD_CAP_SECONDS:
+                logger.warning(
+                    "agentmint-hermes: poller for %s exceeded 30-minute cap; "
+                    "emitting timeout completion", run_id,
+                )
+                push_completion("timeout", {"task_source": {
+                    "goal": goal, "context": context, "session_key": session_key,
+                }})
+                return
+            try:
+                resp = dispatcher.run_status(run_id)
+                status = (resp or {}).get("status", "pending")
+                if status in _TERMINAL_STATUSES:
+                    push_completion(status, {
+                        "billed_usdc": (resp or {}).get("billed_usdc"),
+                        "completed_at": (resp or {}).get("completed_at"),
+                        "task_source": {
+                            "goal": goal,
+                            "context": context,
+                            "session_key": session_key,
+                        },
+                    })
+                    return
+                # Reset backoff on a successful poll (status still pending).
+                backoff = poll_interval
+            except Exception:
+                logger.exception(
+                    "agentmint-hermes: poller iteration failed for %s; "
+                    "backing off", run_id,
+                )
+                backoff = min(backoff * 1.5, 60.0)
+
+    t = threading.Thread(
+        target=loop,
+        daemon=True,
+        name=f"agentmint-poll-{run_id[:12]}",
+    )
+    t.start()
+    return t

agentmint_hermes_runner/models.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass, field, fields
+from typing import Any
+
+
+@dataclass
+class AgentRecord:
+    agent_id: str
+    name: str | None = None
+    mode: str | None = None
+    harness: str | None = None
+    model: str | None = None
+    runtime: str | None = None
+    size: str | None = None
+    created_at: int | None = None
+    last_used: int | None = None
+    lifetime_runs: int | None = None
+    lifetime_billed_usdc: float | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentRecord":
+        known = {f.name for f in fields(cls)} - {"extra"}
+        kwargs = {k: v for k, v in d.items() if k in known}
+        extra = {k: v for k, v in d.items() if k not in known}
+        return cls(**kwargs, extra=extra)
+
+
+@dataclass
+class DispatchResult:
+    status: str | None = None
+    delegation_id: str | None = None
+    run_id: str | None = None
+    result: Any = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DispatchResult":
+        known = {f.name for f in fields(cls)} - {"extra"}
+        kwargs = {k: v for k, v in d.items() if k in known}
+        extra = {k: v for k, v in d.items() if k not in known}
+        return cls(**kwargs, extra=extra)
+
+
+@dataclass
+class Task:
+    """One task in a `dispatch_batch` call.
+
+    Mirrors Hermes' batch-task shape (`{goal, context, toolsets}`) plus an
+    explicit `agent_name` — each AgentMint task targets a named, persistent
+    subagent (which is the inversion of Hermes' "fresh AIAgent per task").
+    """
+
+    goal: str
+    agent_name: str
+    context: str | None = None
+    toolsets: list[str] | None = None
+    max_iterations: int | None = None
+    role: str = "leaf"
+    files: list[dict] | None = None
+    cleanup_paths: list[str] | None = None
+    hermes_context: dict | None = None

agentmint_hermes_runner/translation.py

@@ -0,0 +1,93 @@
+"""Translate Hermes `delegate_task` semantics into AgentMint /a2a calls.
+
+The translation is deliberately client-side and prompt-based:
+
+  - AgentMint's `agent.run` has a single `prompt` field. Hermes' `goal`
+    + `context` are concatenated into that prompt under labelled sections.
+  - AgentMint sandboxes always have terminal + filesystem. Restrictions
+    can't be enforced structurally — they become soft system-prompt hints
+    ("Do not run shell commands.").
+  - Role (leaf vs orchestrator) and max_iterations are similarly soft —
+    the harness reads them out of the prompt if it knows to.
+
+The `"web"` toolset is **unsupported in v0.2**. AgentMint's three
+harnesses (claude-code / codex / opencode) all have a built-in WebFetch
+tool, but we don't yet ship a Hermes-symmetric web-fetch skill that the
+adapter can advertise or restrict — passing `"web"` in toolsets raises
+`UnsupportedToolset`. Track: GitHub issues on agentmint-hermes.
+
+This mirrors Hermes' load-bearing rule: "The parent agent must pass
+everything the subagent needs in the call" — but where Hermes spawns a
+fresh AIAgent, AgentMint dispatches to a persistent sandbox whose
+`/workspace/MEMORY.md` accumulates context across calls.
+"""
+
+from .exceptions import UnsupportedToolset
+
+# Web is intentionally excluded — see module docstring + UnsupportedToolset.
+DEFAULT_TOOLSETS: tuple[str, ...] = ("terminal", "file")
+
+TOOLSET_RESTRICTION_HINTS: dict[str, str] = {
+    "terminal": "Do not run shell commands.",
+    "file": "Do not read or write files outside /workspace.",
+}
+
+UNSUPPORTED_TOOLSETS: frozenset[str] = frozenset({"web"})
+
+ROLE_HINTS: dict[str, str] = {
+    "leaf": (
+        "You are a leaf subagent. Focus on completing this task end-to-end. "
+        "Do not delegate further."
+    ),
+    "orchestrator": (
+        "You are an orchestrator subagent. You may break complex subtasks "
+        "into further delegations if your installed skills allow it."
+    ),
+}
+
+
+def compose_prompt(
+    goal: str,
+    context: str | None = None,
+    toolsets: list[str] | None = None,
+    role: str | None = None,
+    max_iterations: int | None = None,
+) -> str:
+    """Concat goal + context + soft-enforcement hints into one prompt string.
+
+    `toolsets` is interpreted as "the only allowed toolsets" — any default
+    toolset NOT listed becomes a restriction hint. Pass `None` to mean
+    "no restrictions" (Hermes default). Listing `"web"` raises
+    `UnsupportedToolset`.
+    """
+    if not goal or not goal.strip():
+        raise ValueError("goal is required")
+
+    if toolsets is not None:
+        unsupported = sorted(t for t in toolsets if t in UNSUPPORTED_TOOLSETS)
+        if unsupported:
+            raise UnsupportedToolset(
+                f"toolset(s) {unsupported!r} not supported in this version — "
+                f"AgentMint does not yet ship a Hermes-symmetric skill for them. "
+                f"Drop them from the toolsets list to proceed."
+            )
+
+    sections: list[str] = [f"## Goal\n{goal.strip()}"]
+    if context and context.strip():
+        sections.append(f"## Context\n{context.strip()}")
+
+    hints: list[str] = []
+    if toolsets is not None:
+        restricted = [t for t in DEFAULT_TOOLSETS if t not in toolsets]
+        hints.extend(TOOLSET_RESTRICTION_HINTS[t] for t in restricted)
+    if role:
+        if role not in ROLE_HINTS:
+            raise ValueError(f"unknown role: {role!r} (expected 'leaf' or 'orchestrator')")
+        hints.append(ROLE_HINTS[role])
+    if max_iterations:
+        hints.append(f"Soft iteration budget: ~{max_iterations} actions.")
+
+    if hints:
+        sections.append("## Constraints\n" + "\n".join(f"- {h}" for h in hints))
+
+    return "\n\n".join(sections)

agentmint_hermes_runner-0.4.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: agentmint-hermes-runner
+Version: 0.4.0
+Summary: Route Hermes delegate_task(background=True) to named, persistent AgentMint subagents.
+Project-URL: Homepage, https://github.com/mesutcelik/agentmint-hermes
+Project-URL: Repository, https://github.com/mesutcelik/agentmint-hermes
+Project-URL: Issues, https://github.com/mesutcelik/agentmint-hermes/issues
+Author: AgentMint
+License: MIT
+License-File: LICENSE
+Keywords: agentmint,ai-agents,delegation,hermes,mpp,stripe-link,subagents,tempo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentmint-hermes-runner
+
+Route Hermes `delegate_task(background=True)` to named, persistent AgentMint subagents.
+
+> Positioning + full quickstart in [`agentmint-hermes/SKILL.md`](agentmint-hermes/SKILL.md).
+
+## Status
+
+**v0.4.0** — alpha. Auth backends: `BearerAuth` (Stripe-Link), `TempoAuth` (Tempo USDC.e). Polling-only delivery. Hermes feature coverage matrix in [`agentmint-hermes/SKILL.md`](agentmint-hermes/SKILL.md).
+
+## Install in Hermes
+
+```bash
+hermes skills install mesutcelik/agentmint-hermes/agentmint-hermes
+```
+
+(The third segment is the skill subfolder inside the repo, per Hermes' `GitHubSource` convention.)
+
+## Three-line Hermes wiring (Strategy B)
+
+```python
+import os
+from agentmint_hermes_runner import (
+    AgentMintDispatcher, BearerAuth, install_delegate_task_wrapper,
+)
+
+dispatcher = AgentMintDispatcher(auth=BearerAuth(jwt=os.environ["AGENTMINT_JWT"]))
+install_delegate_task_wrapper(dispatcher, default_agent_name="default-worker")
+```
+
+Every `delegate_task(background=True)` inside Hermes now routes to AgentMint's `default-worker` subagent. Its `/workspace/MEMORY.md` accumulates across every delegation. No HTTPS, no ngrok, no webhook secret — a daemon thread polls `agent.run.status` (free, Bearer-only) every 5 s and pushes completions onto Hermes' `completion_queue` directly. Server-side requires AgentMint API ≥ 0.7.0 for the polling endpoint.
+
+## Install
+
+```bash
+pip install agentmint-hermes-runner
+```
+
+## Surface
+
+```python
+from agentmint_hermes_runner import (
+    AgentMintDispatcher,
+    AgentMintWebhookReceiver,
+    BearerAuth, TempoAuth,
+    Task,
+)
+
+dispatcher = AgentMintDispatcher(
+    auth=BearerAuth(jwt=os.environ["AGENTMINT_JWT"]),
+    webhook_url="https://my-gateway.example.com/agentmint-webhook",  # optional
+)
+
+# Single dispatch (Hermes delegate_task analog):
+result = dispatcher.dispatch(
+    agent_name="reviewer-myrepo",
+    goal="Review the diff in /workspace/pr-42 and flag risks.",
+    context="Project at /workspace, Python 3.11, uses Flask + PyJWT.",
+    toolsets=["terminal", "file"],   # "web" raises UnsupportedToolset in v0.2
+    role="leaf",                      # or "orchestrator"
+    max_iterations=50,
+    child_timeout_seconds=600,        # floor 30s; fires agent.cancel on expiry
+)
+
+# Batch dispatch (Hermes tasks=[…] analog):
+results = dispatcher.dispatch_batch(
+    tasks=[
+        Task(agent_name="researcher-wasm", goal="WASM 2026 survey", context="…"),
+        Task(agent_name="researcher-riscv", goal="RISC-V 2026 survey", context="…"),
+    ],
+    max_concurrent_children=3,
+    child_timeout_seconds=900,
+)
+# results in input order; failed/timeout/interrupted statuses returned in-band
+```
+
+## Test
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## Known unsupported (v0.2)
+
+- **`toolsets=["web"]`** — no canonical AgentMint web-fetch skill yet. The supported harnesses (claude-code / codex / opencode) all have built-in web access via the harness itself, but we don't expose a Hermes-symmetric toolset for it. Raises `UnsupportedToolset` at compose time so the gap is loud, not silent.
+- **`max_spawn_depth`** — AgentMint sandboxes aren't structurally bounded by depth.
+
+## License
+
+MIT

agentmint_hermes_runner-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agentmint_hermes_runner/__init__.py,sha256=CBpLrbDWN_J63Z42JkEMh65YRkyWIjMUH3bkYu5W5n8,918
+agentmint_hermes_runner/client.py,sha256=P1rKGTic5UwyRHxF8jR7lj1s_oGKlOa6fumXis85FMA,1232
+agentmint_hermes_runner/dispatcher.py,sha256=UWunqBBjAz1xHF9MXA10yGBS_o1zUksVcpYqWyk5KI4,9272
+agentmint_hermes_runner/exceptions.py,sha256=vw6elB4i52NYffsF7v1gETV7qJU0MmLvgqPPlBNiO0k,973
+agentmint_hermes_runner/hermes_patch.py,sha256=yOXWRj4IB2O7asutm9v7sT2D6TT5LPTu9132EYaYyPk,7462
+agentmint_hermes_runner/models.py,sha256=H5xwrlbY3zFDsveSAls95YSY4K_DfE4ER6z7HhOXvgU,1888
+agentmint_hermes_runner/translation.py,sha256=XBOZnlErWi_HXU6YBWhnwz7tCqk58tEd7h5ye5t6X_o,3721
+agentmint_hermes_runner/auth/__init__.py,sha256=LpafSzNF3sKekADwwvXGUHqn24ayKIlETsAehP33gdE,130
+agentmint_hermes_runner/auth/base.py,sha256=4Xn88CqujJhWTbOGuf7n42SX8gEgx-htlPH_WdSb4UE,620
+agentmint_hermes_runner/auth/bearer.py,sha256=gsVvU696T2bgS5uzSAPbnHRyq21E9Je8WOqnV0XIUrE,952
+agentmint_hermes_runner/auth/tempo.py,sha256=66kZkpVwgLEh9D2HE15IJwc_p20mRTS_XbsD2WvvmfA,1226
+agentmint_hermes_runner-0.4.0.dist-info/METADATA,sha256=MWtrc7-gFzbz2Y6JULBDdO49nVPAZqT0tY302Syi7QY,4257
+agentmint_hermes_runner-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentmint_hermes_runner-0.4.0.dist-info/licenses/LICENSE,sha256=I6Rrtz19ACJO9Vv8pJa8UpRIB2OCqkiswyGqm0qomXA,1066
+agentmint_hermes_runner-0.4.0.dist-info/RECORD,,

agentmint_hermes_runner-0.4.0.dist-info/WHEEL

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

agentmint_hermes_runner-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentMint
+
+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.