pushary 1.9.65 → 1.9.67

package/dist/chunk-VVIQWGS7.js

@@ -0,0 +1,2298 @@
+import {
+  needsShell
+} from "./chunk-XHKBHWLX.js";
+import {
+  hermesAppWiringRecord,
+  hermesConfigReceipt,
+  hermesSetupReceipt
+} from "./chunk-TI4JYPGQ.js";
+import {
+  readJsonSafe,
+  resolvePathBinary,
+  writeJsonAtomic
+} from "./chunk-WJLHZ6E6.js";
+import {
+  isNewerVersion,
+  isReleaseVersion
+} from "./chunk-QTOLNRET.js";
+import {
+  isRecord
+} from "./chunk-RQOT6QL3.js";
+
+// src/hermes/plugin-payload.ts
+import { createHash } from "crypto";
+
+// src/hermes/plugin-files.generated.ts
+var HERMES_PLUGIN_FILES = [
+  { path: "__init__.py", contents: `import json
+import logging
+import os
+import threading
+from pathlib import Path
+
+from . import api, approval, host, identity, installation, schemas, tools
+
+logger = logging.getLogger(__name__)
+
+MAX_ERROR_NOTIFICATIONS = 3
+SYSTEM_PROMPT_SECTION_ID = "pushary.reach-the-human"
+HERMES_QUESTION_TOOL = "clarify"
+QUESTION_ROUTING_PROMPT = (
+    " Ask the operator questions with pushary_ask, not clarify: clarify is routed to Pushary."
+)
+QUESTION_TOOL_REDIRECT = (
+    "Ask this with pushary_ask instead. Pushary routes Hermes questions to the "
+    "operator's phone and Mac, so they can answer when nobody is at this terminal."
+)
+
+SYSTEM_PROMPT_SECTION = (
+    "Pushary reaches the operator when they are away. Honor authorization already "
+    "granted in this session. Call pushary_ask only for an unresolved decision or "
+    "an action outside that authority; never bypass an enforced host gate. Use "
+    "pushary_propose_scope only for an unresolved or requested boundary; only file "
+    "paths are enforced, so a boundary that is not a path goes in promises, and an "
+    "empty enforces means nothing in it is checked automatically. "
+    "Follow answered, status and handoffAction (or nextAction); silence is not "
+    "consent, and choice/text answers do not authorize a separate action. "
+    "Call pushary_notify with context_type task_complete or error for meaningful "
+    "unattended results, not every step. Batch related questions. Delivery follows "
+    "the user's policy and presence; do not duplicate a live question in chat. "
+    "Confirm notifications can offer lock-screen actions; choices and text open "
+    "the app. Personal tools reach the operator; Partner tools use external_id "
+    "to reach an enrolled customer. For a personal reminder later, use pushary_remind; "
+    "it runs on Pushary after Hermes exits. Use Hermes cron for scheduled agent work."
+)
+
+TOOL_REGISTRATIONS = (
+    ("pushary_remind", schemas.PUSHARY_REMIND, "pushary_remind",
+     "Schedule, list or cancel personal reminders on Pushary"),
+    ("pushary_notify", schemas.PUSHARY_NOTIFY, "pushary_notify",
+     "Send push notification to user's phone"),
+    ("pushary_ask", schemas.PUSHARY_ASK, "pushary_ask",
+     "Ask user a question via push notification"),
+    ("pushary_wait", schemas.PUSHARY_WAIT, "pushary_wait",
+     "Wait for user's answer to a push question"),
+    ("pushary_cancel", schemas.PUSHARY_CANCEL, "pushary_cancel",
+     "Cancel a pending push question"),
+    ("pushary_propose_scope", schemas.PUSHARY_PROPOSE_SCOPE, "pushary_propose_scope",
+     "Agree what this run may touch before starting it"),
+    ("pushary_enroll", schemas.PUSHARY_ENROLL, "pushary_enroll",
+     "Connect one of your own end-users' phones for approvals (Partner plan)"),
+    ("pushary_ask_end_user", schemas.PUSHARY_ASK_END_USER, "pushary_ask_end_user",
+     "Ask one of your own end-users and block on a fail-closed answer (Partner plan)"),
+)
+
+_session_totals = {"tools": 0, "errors": 0, "notified": 0}
+_last_turn = {"completed": False, "interrupted": False}
+_plugin_activity = {"attempted": False}
+_plugin_activity_lock = threading.Lock()
+
+
+def register(ctx):
+    for name, schema, handler_name, description in TOOL_REGISTRATIONS:
+        ctx.register_tool(
+            name=name,
+            toolset="pushary",
+            schema=schema,
+            handler=getattr(tools, handler_name),
+            description=description,
+        )
+
+    hooks = {
+        "pre_llm_call": _on_pre_llm_call,
+        "pre_tool_call": _on_pre_tool_call,
+        "post_tool_call": _on_post_tool_call,
+        "on_session_start": _on_session_start,
+        "on_session_end": _on_session_end,
+        "on_session_finalize": _on_session_finalize,
+    }
+    for hook_name, callback in hooks.items():
+        ctx.register_hook(hook_name, callback)
+
+    transport = _register_approval_transport(ctx)
+    _register_system_prompt_section(ctx)
+
+    skills_dir = Path(__file__).parent / "skills"
+    if skills_dir.is_dir():
+        for child in sorted(skills_dir.iterdir()):
+            skill_md = child / "SKILL.md"
+            if child.is_dir() and skill_md.exists():
+                ctx.register_skill(child.name, skill_md)
+
+    installation.record_plugin_load(transport)
+
+    logger.info(
+        "[pushary] Plugin registered: %d tools, %d hooks, approval transport %s",
+        len(TOOL_REGISTRATIONS),
+        len(hooks),
+        "registered" if transport else "unavailable",
+    )
+
+
+def _register_approval_transport(ctx):
+    try:
+        ctx.register_approval_transport(host.TRANSPORT_NAME, approval.present)
+        return True
+    except Exception as exc:
+        logger.debug("[pushary] approval transport unavailable: %s", exc)
+        return False
+
+
+def system_prompt_section():
+    if installation.routes_questions():
+        return SYSTEM_PROMPT_SECTION + QUESTION_ROUTING_PROMPT
+    return SYSTEM_PROMPT_SECTION
+
+
+def _register_system_prompt_section(ctx):
+    try:
+        ctx.register_system_prompt_section(SYSTEM_PROMPT_SECTION_ID, system_prompt_section())
+    except Exception as exc:
+        logger.debug("[pushary] system prompt section unavailable: %s", exc)
+
+
+def _gated_tools():
+    raw = os.environ.get("PUSHARY_GATE_TOOLS", "")
+    return {name.strip().lower() for name in raw.split(",") if name.strip()}
+
+
+def _egress_redactor():
+    try:
+        from agent.redact import redact_for_egress
+    except ImportError:
+        return None
+    return redact_for_egress
+
+
+def _redact_outbound_text(text: str) -> str:
+    try:
+        from agent.redact import redact_sensitive_text
+
+        redacted = redact_sensitive_text(text, force=True, redact_url_credentials=True)
+        redact_for_egress = _egress_redactor()
+        return redact_for_egress(redacted) if redact_for_egress else redacted
+    except Exception:
+        logger.warning("[pushary] host redaction unavailable; omitting outbound detail")
+        return "[redaction unavailable]"
+
+
+def _summarize_args(args):
+    if not isinstance(args, dict) or not args:
+        return None
+    parts = []
+    for key, value in args.items():
+        rendered = _redact_outbound_text(f"{key}: {value}")
+        if len(rendered) > 200:
+            rendered = rendered[:200] + "\u2026"
+        parts.append(rendered)
+    return "\\n".join(parts)[:500]
+
+
+def _arg_target(args):
+    if not isinstance(args, dict):
+        return None
+    for key in ("command", "path", "file_path", "url", "query"):
+        value = args.get(key)
+        if value:
+            return " ".join(_redact_outbound_text(str(value)).split()[:2])[:80]
+    return None
+
+
+_APPROVE_VALUES = {"yes", "y", "true", "approve", "approved", "allow", "ok"}
+
+
+def _block_unapproved(tool_name):
+    return {
+        "action": "block",
+        "message": f"Approval for '{tool_name}' was not obtained. The tool was blocked.",
+    }
+
+
+def _escalate_to_host_gate(tool_name, args):
+    summary = _summarize_args(args)
+    detail = f"\\n{summary}" if summary else ""
+    return {
+        "action": "approve",
+        "message": f"Run {tool_name}?{detail}"[:500],
+        "rule_key": tool_name,
+    }
+
+
+def _requested_gate_seconds():
+    try:
+        return int(os.environ.get("PUSHARY_GATE_TIMEOUT_MS", "55000")) / 1000
+    except (TypeError, ValueError):
+        return host.GATE_MAX_SECONDS
+
+
+def _block_undeliverable(tool_name):
+    return {
+        "action": "block",
+        "message": (
+            f"'{tool_name}' is gated by Pushary but no phone, browser, or Slack "
+            "channel is connected to approve on, so nobody could be asked. Ask in "
+            "this session instead, or connect a device in the Pushary dashboard."
+        ),
+    }
+
+
+def _redirects_question_tool(tool_name):
+    return (
+        (tool_name or "").lower() == HERMES_QUESTION_TOOL
+        and installation.routes_questions()
+        and api.is_configured()
+    )
+
+
+def _on_pre_tool_call(tool_name=None, args=None, session_id=None, **kwargs):
+    identity.remember_session(session_id)
+
+    if _redirects_question_tool(tool_name):
+        return {"action": "block", "message": QUESTION_TOOL_REDIRECT}
+
+    gated = _gated_tools()
+    if not gated:
+        return None
+
+    name = (tool_name or "").lower()
+    if not name or name.startswith("pushary"):
+        return None
+    if name not in gated:
+        return None
+
+    if host.pushary_is_selected_transport():
+        return _escalate_to_host_gate(tool_name, args)
+
+    if not api.is_configured():
+        return _block_unapproved(tool_name)
+
+    try:
+        budget_ms = int(host.gate_budget_seconds(_requested_gate_seconds()) * 1000)
+        summary = _summarize_args(args)
+        result = json.loads(tools.pushary_ask({
+            "question": f"Allow Hermes to run \`{tool_name}\`?",
+            "type": "confirm",
+            "context": summary,
+            "agent_name": identity.agent_name(),
+            "tool_name": tool_name,
+            "tool_target": _arg_target(args),
+            "action_body": summary,
+            "wait": True,
+            "timeout_ms": budget_ms,
+        }))
+        if "error" in result:
+            return _block_unapproved(tool_name)
+
+        correlation_id = result.get("correlationId")
+        if not correlation_id:
+            return _block_unapproved(tool_name)
+
+        answer = result
+        if result.get("handoffAction") == "cancel_then_ask_in_current_client":
+            cancellation = api.cancel_question(correlation_id)
+            if cancellation.get("handoffAction") == "stop":
+                return _block_unapproved(tool_name)
+            if not cancellation.get("cancelled"):
+                answer = api.wait_for_answer(correlation_id, 1000)
+
+        if answer.get("answered"):
+            if str(answer.get("value", "")).strip().lower() in _APPROVE_VALUES:
+                return None
+            return {"action": "block", "message": f"Denied from Pushary: '{tool_name}' was not approved by the user."}
+
+        if answer.get("error"):
+            return _block_unapproved(tool_name)
+
+        if not result.get("handoffAction") and not result.get("nextAction"):
+            api.cancel_question(correlation_id)
+        if result.get("noDevices"):
+            return _block_undeliverable(tool_name)
+        return _block_unapproved(tool_name)
+    except Exception:
+        return _block_unapproved(tool_name)
+
+
+def _tool_failure(result, status, error_message):
+    if status is not None:
+        return (error_message or "tool returned an error") if status == "error" else None
+    try:
+        parsed = json.loads(result) if isinstance(result, str) else result
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if isinstance(parsed, dict) and parsed.get("error"):
+        return str(parsed["error"])
+    return None
+
+
+def _on_post_tool_call(tool_name, args, result, duration_ms=0, status=None,
+                       error_message=None, **kwargs):
+    _session_totals["tools"] += 1
+
+    failure = _tool_failure(result, status, error_message)
+    if failure is None:
+        return
+
+    _session_totals["errors"] += 1
+    if not api.is_configured():
+        return
+    if _session_totals["notified"] >= MAX_ERROR_NOTIFICATIONS:
+        return
+    _session_totals["notified"] += 1
+
+    try:
+        failure = _redact_outbound_text(str(failure))
+        api.send_notification(
+            title="Tool error in Hermes",
+            body=f"{tool_name} failed: {failure[:150]}",
+            agent_name=identity.agent_name(),
+            context={
+                "type": "error",
+                "errorMessage": failure[:500],
+                "summary": f"Tool '{tool_name}' returned an error after {duration_ms}ms",
+            },
+        )
+    except Exception:
+        pass
+
+
+def _on_session_start(session_id=None, **kwargs):
+    identity.remember_session(session_id)
+    _session_totals.update(tools=0, errors=0, notified=0)
+    _last_turn.update(completed=False, interrupted=False)
+    _report_session_event("session_start", session_id, can_drain=True)
+    _report_plugin_active_once(session_id)
+
+
+def _claim_plugin_active_report():
+    with _plugin_activity_lock:
+        if _plugin_activity["attempted"]:
+            return False
+        _plugin_activity["attempted"] = True
+        return True
+
+
+def _report_plugin_active_once(session_id):
+    if not session_id or installation.follows_catalog_rules() or not api.is_configured():
+        return None
+    if not _claim_plugin_active_report():
+        return None
+    report = threading.Thread(target=api.report_plugin_active, args=(session_id,), name="pushary-plugin-active", daemon=True)
+    report.start()
+    return report
+
+
+def _on_pre_llm_call(session_id=None, **kwargs):
+    identity.remember_session(session_id)
+    if not api.is_configured() or not identity.session_id():
+        return None
+    result = api.agent_event("user_prompt", identity.session_id(), can_drain=True)
+    command = result.get("pendingCommand") if isinstance(result, dict) else None
+    if not isinstance(command, str) or not command.strip():
+        return None
+    return {
+        "context": (
+            "The operator sent this instruction to the current Hermes session "
+            f"from Pushary:\\n\\n{command.strip()}"
+        )
+    }
+
+
+def _report_session_event(event, session_id, can_drain=False):
+    if not api.is_configured() or not session_id:
+        return
+    try:
+        api.agent_event(event, session_id, can_drain=can_drain)
+    except Exception:
+        pass
+
+
+def _on_session_end(session_id=None, completed=False, interrupted=False, **kwargs):
+    identity.remember_session(session_id)
+    _last_turn.update(completed=bool(completed), interrupted=bool(interrupted))
+    _report_session_event("session_end", session_id or identity.session_id())
+
+
+def _on_session_finalize(session_id=None, **kwargs):
+    _report_session_event("session_closed", session_id or identity.session_id())
+    tool_count = _session_totals["tools"]
+    error_count = _session_totals["errors"]
+    _session_totals.update(tools=0, errors=0, notified=0)
+
+    if not os.environ.get("PUSHARY_AUTO_NOTIFY_SESSION_END"):
+        identity.forget_session()
+        return
+    if not api.is_configured() or not tool_count:
+        identity.forget_session()
+        return
+
+    completed = _last_turn["completed"]
+    status = "completed" if completed else ("interrupted" if _last_turn["interrupted"] else "ended")
+    reference = str(session_id or identity.session_id() or "")
+
+    try:
+        api.send_notification(
+            title=f"Hermes session {status}",
+            body=f"Session used {tool_count} tool calls with {error_count} errors",
+            agent_name=identity.agent_name(),
+            context={
+                "type": "task_complete" if completed else "info",
+                "summary": f"Session {reference[:8]} {status}",
+                "details": [
+                    f"{tool_count} tool calls executed",
+                    f"{error_count} errors encountered",
+                ],
+            },
+        )
+    except Exception:
+        pass
+    finally:
+        identity.forget_session()
+` },
+  { path: "api.py", contents: `import json
+import hashlib
+import os
+import re
+import time
+from uuid import uuid4
+import urllib.request
+import urllib.error
+import urllib.parse
+from pathlib import Path
+
+from . import host, identity, installation
+
+BASE_URL = os.environ.get("PUSHARY_BASE_URL", "https://pushary.com")
+API_KEY_VARIABLE = "PUSHARY_API_KEY"
+PLUGIN_ACTIVE_EVENT = "agent_hook_active"
+PLUGIN_ACTIVE_TIMEOUT_SECONDS = 3
+SERVER_BASE = f"{BASE_URL}/api/v1/server"
+
+PENDING_DIR = Path.home() / ".pushary" / "run" / "hermes-commands"
+
+
+def _pending_path(session_id):
+    identity_value = f"{_get_api_key()}:{identity.machine_id()}:{session_id or '_no_session'}"
+    name = hashlib.sha256(identity_value.encode("utf-8")).hexdigest()
+    return PENDING_DIR / f"{name}.json"
+
+
+def _read_pending(session_id):
+    path = _pending_path(session_id)
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(value.get("id"), str) or not isinstance(value.get("text"), str):
+            return None
+        if value.get("expiresAtMs", 0) <= int(time.time() * 1000):
+            path.unlink(missing_ok=True)
+            return None
+        return value
+    except Exception:
+        return None
+
+
+def _write_pending(session_id, value, exclusive=False):
+    path = _pending_path(session_id)
+    try:
+        PENDING_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+        if exclusive:
+            with path.open("x", encoding="utf-8") as handle:
+                json.dump(value, handle)
+        else:
+            temporary = path.with_suffix(f".{os.getpid()}.tmp")
+            temporary.write_text(json.dumps(value), encoding="utf-8")
+            os.chmod(temporary, 0o600)
+            os.replace(temporary, path)
+        os.chmod(path, 0o600)
+        return True
+    except Exception:
+        if exclusive:
+            return False
+        pending = _read_pending(session_id)
+        return pending is not None \\
+            and pending.get("id") == value.get("id") \\
+            and pending.get("delivered") == value.get("delivered")
+
+
+def _remove_pending(session_id, command_id):
+    pending = _read_pending(session_id)
+    if pending and pending.get("id") == command_id:
+        try:
+            _pending_path(session_id).unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+def _ack_command(command_id, session_id):
+    ack = urllib.request.Request(
+        f"{BASE_URL}/api/agent/command/ack",
+        data=json.dumps(_with_identity({
+            "commandId": command_id,
+            "sessionId": session_id,
+            "state": "delivered",
+        })).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {_get_api_key()}",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(ack, timeout=10) as response:
+            return 200 <= response.status < 300
+    except Exception:
+        return False
+
+# Fail-closed affirmative set for a confirm decision. Anything not in here (a
+# decline, an empty answer, a timeout) is treated as "not approved".
+AFFIRMATIVE = {"yes", "y", "true", "approve", "approved", "allow", "ok", "okay", "confirm", "accept"}
+
+
+def is_affirmative(value):
+    return str(value or "").strip().lower() in AFFIRMATIVE
+
+
+def _parse_sse(body):
+    last = None
+    for event in re.split(r"\\r?\\n\\r?\\n", body):
+        data = "\\n".join(
+            line[5:].lstrip()
+            for line in re.split(r"\\r?\\n", event)
+            if line.startswith("data:")
+        ).strip()
+        if not data:
+            continue
+        try:
+            last = json.loads(data)
+        except json.JSONDecodeError:
+            continue
+    return last
+
+
+def is_configured():
+    return bool(_configured_key())
+
+
+def _configured_key():
+    key = host.profile_secret(API_KEY_VARIABLE)
+    if key or installation.follows_catalog_rules():
+        return key
+    return _key_in_pushary_config()
+
+
+def _key_in_pushary_config():
+    path = Path(os.environ.get("PUSHARY_CONFIG_FILE", "")).expanduser() \\
+        if os.environ.get("PUSHARY_CONFIG_FILE") else Path.home() / ".pushary" / "config.json"
+    try:
+        value = json.loads(path.read_text(encoding="utf-8")).get("apiKey")
+        return value if isinstance(value, str) and value else None
+    except Exception:
+        return None
+
+
+def _get_api_key():
+    key = _configured_key()
+    if not key:
+        raise ValueError(
+            f"{API_KEY_VARIABLE} is not set. Save it in Hermes with: hermes config set {API_KEY_VARIABLE} <your key>, "
+            "then restart Hermes. Get a key at https://pushary.com/sign-up?from=hermes"
+        )
+    return key
+
+
+def _with_versions(payload):
+    for field, value in (
+        ("adapterVersion", installation.LOADED_PLUGIN_VERSION),
+        ("agentVersion", installation.LOADED_HERMES_VERSION),
+    ):
+        if value:
+            payload[field] = value
+    return payload
+
+
+def _agent_event_request(payload):
+    return urllib.request.Request(
+        f"{BASE_URL}/api/agent/event",
+        data=json.dumps(_with_identity(payload)).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {_get_api_key()}",
+        },
+        method="POST",
+    )
+
+
+def report_plugin_active(session_id):
+    try:
+        request = _agent_event_request(_with_versions({
+            "event": PLUGIN_ACTIVE_EVENT,
+            "agentType": "hermes",
+            "agentName": identity.agent_name(),
+            "sessionId": session_id,
+        }))
+        with urllib.request.urlopen(request, timeout=PLUGIN_ACTIVE_TIMEOUT_SECONDS) as response:
+            return 200 <= response.status < 300
+    except Exception:
+        return False
+
+
+def agent_event(event, session_id, can_drain=False):
+    """Report a Hermes session and pick up a queued notch instruction."""
+    try:
+        pending = _read_pending(session_id) if can_drain else None
+        req = _agent_event_request({
+            "event": event,
+            "agentType": "hermes",
+            "agentName": identity.agent_name(),
+            "sessionId": session_id,
+            "canDrainCommand": can_drain and pending is None,
+            "ackMode": can_drain and pending is None,
+            "skipCommandDrain": pending is not None,
+        })
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            raw = resp.read().decode("utf-8")
+        result = json.loads(raw) if raw.strip() else {}
+        if not isinstance(result, dict):
+            return result
+        if pending:
+            result.pop("pendingCommand", None)
+            result.pop("pendingCommandId", None)
+            if not _ack_command(pending["id"], session_id):
+                return result
+            if pending.get("delivered") is True:
+                _remove_pending(session_id, pending["id"])
+                return result
+            delivered = {**pending, "delivered": True}
+            if not _write_pending(session_id, delivered):
+                return result
+            result["pendingCommand"] = pending["text"]
+            result["pendingCommandId"] = pending["id"]
+            return result
+        command_id = result.get("pendingCommandId")
+        command = result.get("pendingCommand")
+        if isinstance(command_id, str) and isinstance(command, str):
+            received = {
+                "id": command_id,
+                "text": command,
+                "expiresAtMs": result.get("pendingCommandExpiresAtMs", int(time.time() * 1000) + 3_600_000),
+                "delivered": False,
+            }
+            saved = _write_pending(session_id, received, exclusive=True)
+            if not saved or not _ack_command(command_id, session_id):
+                result.pop("pendingCommand", None)
+                result.pop("pendingCommandId", None)
+                return result
+            if not _write_pending(session_id, {**received, "delivered": True}):
+                result.pop("pendingCommand", None)
+                result.pop("pendingCommandId", None)
+        return result
+    except urllib.error.HTTPError as exc:
+        return {"error": f"HTTP {exc.code}: {exc.reason}"}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+def _mcp_call(tool_name, params):
+    api_key = _get_api_key()
+    url = f"{BASE_URL}/api/mcp/mcp"
+    payload = json.dumps({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": tool_name, "arguments": params},
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "Authorization": f"Bearer {api_key}",
+        },
+        method="POST",
+    )
+
+    blocking = tool_name in ("wait_for_answer", "propose_scope") or (tool_name == "ask_user" and params.get("wait", True))
+    timeout = min(max(params.get("timeoutMs", 30000), 1000), 55000) / 1000 + 2 if blocking else 4 if tool_name == "cancel_question" else 10
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+            content_type = resp.headers.get_content_type()
+    except urllib.error.HTTPError as e:
+        detail = ""
+        try:
+            detail = e.read().decode("utf-8").strip()[:200]
+        except Exception:
+            pass
+        return {"error": f"HTTP {e.code}: {e.reason}" + (f" \u2014 {detail}" if detail else "")}
+    except Exception as e:
+        return {"error": str(e)}
+
+    if "text/event-stream" in (content_type or ""):
+        body = _parse_sse(raw)
+    else:
+        try:
+            body = json.loads(raw) if raw.strip() else None
+        except json.JSONDecodeError:
+            body = None
+
+    if not body:
+        return {"error": "Empty response from Pushary"}
+
+    if "error" in body:
+        err = body["error"]
+        return {"error": err.get("message", str(err)) if isinstance(err, dict) else str(err)}
+
+    text = body.get("result", {}).get("content", [{}])[0].get("text", "{}")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return {"raw": text}
+
+
+IDENTITY_PARAM_NAMES = {
+    "session_id": "sessionId",
+    "machine_id": "machineId",
+}
+
+DECISION_PARAM_NAMES = {
+    **IDENTITY_PARAM_NAMES,
+    "tool_name": "toolName",
+    "tool_target": "toolTarget",
+    "repo_key": "repoKey",
+    "intent": "intent",
+    "action": "action",
+    "blocker": "blocker",
+    "action_body": "actionBody",
+    "scope_path": "scopePath",
+}
+
+
+def _with_decision_fields(params, values, accepted=DECISION_PARAM_NAMES):
+    unknown = set(values) - set(accepted)
+    if unknown:
+        raise TypeError("unexpected parameters: " + ", ".join(sorted(unknown)))
+    for key, camel in accepted.items():
+        value = values.get(key)
+        if value:
+            params[camel] = value
+    return _with_identity(params)
+
+
+def _with_identity(params):
+    for camel, value in (
+        ("sessionId", identity.session_id()),
+        ("machineId", identity.machine_id()),
+    ):
+        if value and not params.get(camel):
+            params[camel] = value
+    return params
+
+
+def send_notification(title, body, agent_name=None, context=None, **identity_fields):
+    params = {"title": title, "body": body}
+    if agent_name:
+        params["agentName"] = agent_name
+    if context:
+        params["context"] = context
+    return _mcp_call(
+        "send_notification",
+        _with_decision_fields(params, identity_fields, IDENTITY_PARAM_NAMES),
+    )
+
+
+def schedule_reminder(body=None, title=None, in_minutes=None, at=None,
+                      cancel_reminder_id=None, agent_name=None, env=None, request_id=None, reminder_id=None, **identity_fields):
+    if body is not None and request_id is None:
+        request_id = str(uuid4())
+    values = {"body": body, "title": title, "inMinutes": in_minutes, "at": at,
+              "cancelReminderId": cancel_reminder_id, "agentName": agent_name, "env": env,
+              "requestId": request_id, "reminderId": reminder_id}
+    params = {key: value for key, value in values.items() if value is not None}
+    return _mcp_call("schedule_reminder", _with_decision_fields(params, identity_fields, IDENTITY_PARAM_NAMES))
+
+
+def ask_user(question, question_type="confirm", options=None, placeholder=None,
+             context=None, agent_name=None, wait=True, timeout_ms=None, **decision):
+    params = {"question": question, "type": question_type, "wait": wait}
+    if options:
+        params["options"] = options
+    if placeholder:
+        params["placeholder"] = placeholder
+    if context:
+        params["context"] = context
+    if agent_name:
+        params["agentName"] = agent_name
+    if timeout_ms is not None:
+        params["timeoutMs"] = min(max(int(timeout_ms), 1000), 55000)
+    return _mcp_call("ask_user", _with_decision_fields(params, decision))
+
+
+def propose_scope(done_when, session_id, allowed_paths=None, off_limits_paths=None,
+                  agent_name=None, timeout_ms=None, promises=None):
+    # \`promises\` is appended LAST so the positional signature every released
+    # plugin calls keeps its meaning.
+    params = {"doneWhen": done_when, "sessionId": session_id}
+    if allowed_paths:
+        params["allowedPaths"] = allowed_paths
+    if off_limits_paths:
+        params["offLimitsPaths"] = off_limits_paths
+    if promises:
+        params["promises"] = promises
+    if agent_name:
+        params["agentName"] = agent_name
+    if timeout_ms is not None:
+        params["timeoutMs"] = min(max(int(timeout_ms), 1000), 55000)
+    return _mcp_call("propose_scope", _with_identity(params))
+
+
+def wait_for_answer(correlation_id, timeout_ms=30000):
+    return _mcp_call("wait_for_answer", {
+        "correlationId": correlation_id,
+        "timeoutMs": min(max(int(timeout_ms), 1000), 55000),
+    })
+
+
+def cancel_question(correlation_id):
+    return _mcp_call("cancel_question", {"correlationId": correlation_id})
+
+
+# --- Partner tools: reach your OWN product's end-users on their phones -----------
+#
+# The four tools above speak MCP (/api/mcp/mcp), which targets the phones connected
+# to the owner's workspace. Enrolling an end-user and the durable end-user decision
+# ledger are REST-only, so the partner tools bypass MCP and call the Server API
+# (/api/v1/server/*) directly with the same Bearer key. Both require the Partner plan.
+
+
+def _rest_call(method, path, body=None, params=None):
+    """Call the REST Server API directly and return the parsed JSON dict.
+
+    On a transport or HTTP error returns {"error": <message>}; a 403 carries the
+    "requires the Partner plan" message so the model can surface it rather than
+    retrying blindly.
+    """
+    api_key = _get_api_key()
+    url = f"{SERVER_BASE}{path}"
+    if params:
+        query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+        if query:
+            url = f"{url}?{query}"
+
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+        method=method,
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        detail = ""
+        try:
+            parsed = json.loads(e.read().decode("utf-8"))
+            detail = parsed.get("error") or parsed.get("message") or ""
+        except Exception:
+            detail = ""
+        return {"error": detail or f"HTTP {e.code}: {e.reason}"}
+    except Exception as e:
+        return {"error": str(e)}
+
+    try:
+        return json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        return {"error": "Invalid response from Pushary"}
+
+
+def enroll_end_user(external_id):
+    """Mint a keyless one-tap connect link for one of your end-users."""
+    return _rest_call("POST", "/enroll", body={"externalId": external_id})
+
+
+def create_end_user_decision(question, external_id, question_type="confirm",
+                             options=None, agent_name=None, context=None,
+                             idempotency_key=None):
+    """Open a durable decision addressed to a specific end-user (does not wait)."""
+    body = {
+        "question": question,
+        "type": question_type,
+        "externalId": external_id,
+        "wait": False,
+    }
+    if options:
+        body["options"] = options
+    if agent_name:
+        body["agentName"] = agent_name
+    if context:
+        body["context"] = context
+    if idempotency_key:
+        body["idempotencyKey"] = idempotency_key
+    return _rest_call("POST", "/decisions", body=body)
+
+
+def get_end_user_decision(decision_id, wait_seconds=45):
+    """Durably long-poll a decision (server caps wait at 55s)."""
+    seg = urllib.parse.quote(str(decision_id), safe="")
+    return _rest_call("GET", f"/decisions/{seg}", params={"wait": wait_seconds})
+` },
+  { path: "approval.py", contents: 'import time\n\nfrom . import api, identity\n\nHERMES_SHELL_TOOL = "terminal"\nDECISION_LINE_MAX = 500\nACTION_BODY_MAX = 4000\n\nPOLL_CEILING_SECONDS = 50.0\n\nCHOICE_LABELS = (\n    ("once", "Allow once"),\n    ("session", "Allow for this session"),\n    ("always", "Always allow"),\n    ("deny", "Deny"),\n)\n\n\nclass TransportUnavailable(Exception):\n    pass\n\n\nQUESTION_COMMAND_MAX = 160\n\nPLUGIN_RULE_MARKER = "(plugin approval rule)"\n\n\ndef _offered(allowed):\n    return [pair for pair in CHOICE_LABELS if pair[0] in set(allowed or ())]\n\n\ndef _command_head(command):\n    return " ".join(str(command or "").split()[:2])[:80]\n\n\ndef _command_summary(command):\n    collapsed = " ".join(str(command or "").split())\n    if len(collapsed) <= QUESTION_COMMAND_MAX:\n        return collapsed\n    return collapsed[:QUESTION_COMMAND_MAX - 1] + "\u2026"\n\n\ndef _choice_from_answer(value, offered, uses_select):\n    answer = str(value or "").strip()\n    if uses_select:\n        for choice, label in offered:\n            if answer.lower() == label.lower():\n                return choice\n        return "deny"\n    return "once" if api.is_affirmative(answer) else "deny"\n\n\ndef _subject(request):\n    """What to put in the question.\n\n    A dangerous-command approval carries the real command. A plugin rule\n    escalated from pre_tool_call carries a synthetic display label instead, and\n    the plugin\'s own message is the part worth reading, so use that.\n    """\n    command = str(request.command or "")\n    if PLUGIN_RULE_MARKER in command:\n        lines = str(request.description or "").strip().splitlines()\n        if lines and lines[0].strip():\n            return _command_summary(lines[0])\n    return _command_summary(command)\n\n\ndef _open_question(request, offered, uses_select):\n    command = str(request.command or "")\n    return api.ask_user(\n        question=f"Allow Hermes to run `{_subject(request)}`?",\n        question_type="select" if uses_select else "confirm",\n        options=[label for _, label in offered] if uses_select else None,\n        context=str(request.description or "")[:500] or None,\n        agent_name=identity.agent_name(),\n        session_id=identity.session_id(),\n        machine_id=identity.machine_id(),\n        tool_name=HERMES_SHELL_TOOL,\n        tool_target=_command_head(command),\n        action=command[:DECISION_LINE_MAX] or None,\n        action_body=command[:ACTION_BODY_MAX] or None,\n        blocker=(\n            f"Hermes flagged this command as {request.pattern_key}"[:DECISION_LINE_MAX]\n            if request.pattern_key\n            else None\n        ),\n        wait=False,\n    )\n\n\ndef _stopped(result):\n    return result.get("handoffAction") == "stop" or result.get("status") in ("cancelled", "unavailable", "stopped")\n\n\ndef _withdraw(correlation_id):\n    try:\n        cancelled = api.cancel_question(correlation_id)\n        if _stopped(cancelled) or cancelled.get("error"):\n            return {"handoffAction": "stop"}\n        if cancelled.get("cancelled") is True:\n            return {}\n        answer = api.wait_for_answer(correlation_id, 1000)\n        if answer.get("answered") or answer.get("status") in ("expired", "missing"):\n            return answer\n    except Exception:\n        pass\n    return {"handoffAction": "stop"}\n\n\ndef present(request):\n    offered = _offered(request.allowed_choices)\n    if not offered:\n        return request.respond("deny")\n    uses_select = [choice for choice, _ in offered] != ["once", "deny"]\n    # Reserve time for withdrawal before the host discards a late decision.\n    started_at = time.monotonic()\n    deadline = started_at + max(float(request.timeout_seconds or 0) - 10, 0.0)\n    created = _open_question(request, offered, uses_select)\n    if created.get("answered"):\n        return request.respond(_choice_from_answer(created.get("value"), offered, uses_select))\n    if _stopped(created):\n        return request.respond("deny")\n    correlation_id = created.get("correlationId")\n    if not correlation_id:\n        raise TransportUnavailable("Pushary did not create an approval")\n\n    policy_deadline = None\n    window_ms = created.get("policyTimeoutMs")\n    if created.get("deliveryMode") == "push_first" and isinstance(window_ms, (int, float)) and window_ms >= 0:\n        policy_deadline = started_at + window_ms / 1000\n        deadline = min(deadline, policy_deadline)\n    handoff = created.get("noDevices") or created.get("suppressed") or created.get("status") in ("terminal", "notified")\n    answer = created\n    try:\n        while not handoff and time.monotonic() < deadline:\n            remaining = deadline - time.monotonic()\n            answer = api.wait_for_answer(correlation_id, int(min(POLL_CEILING_SECONDS, max(1.0, remaining)) * 1000))\n            if answer.get("answered"):\n                return request.respond(_choice_from_answer(answer.get("value"), offered, uses_select))\n            if _stopped(answer) or answer.get("error") or answer.get("status") in ("expired", "missing"):\n                break\n            # Some hosts/proxies return pending immediately instead of long-polling.\n            time.sleep(min(0.1, max(0, deadline - time.monotonic())))\n    except Exception:\n        answer = {"handoffAction": "stop"}\n\n    late = _withdraw(correlation_id)\n    if _stopped(answer) or _stopped(late):\n        return request.respond("deny")\n    if late.get("answered"):\n        return request.respond(_choice_from_answer(late.get("value"), offered, uses_select))\n    if handoff or (policy_deadline is not None and time.monotonic() >= policy_deadline):\n        # Only a fenced question may reach Hermes\'s configured builtin fallback.\n        raise TransportUnavailable("Approval handed back to Hermes")\n    return request.respond("deny")\n' },
+  { path: "host.py", contents: 'import os\n\nTRANSPORT_NAME = "pushary"\n\nHOOK_TIMEOUT_DEFAULT_SECONDS = 30.0\nHOOK_TIMEOUT_MAX_SECONDS = 600.0\n\nGATE_HEADROOM_SECONDS = 5.0\nGATE_MIN_SECONDS = 5.0\nGATE_MAX_SECONDS = 55.0\n\n# The last Hermes that runs a pre_tool_call callback to completion. Anything\n# after this abandons one that outlives plugins.hook_callback_timeout.\nUNBOUNDED_THROUGH_VERSION = (0, 20, 5)\n\n\ndef _config():\n    try:\n        from hermes_cli.config import load_config_readonly\n\n        loaded = load_config_readonly()\n    except Exception:\n        return {}\n    return loaded if isinstance(loaded, dict) else {}\n\n\ndef _section(node, *path):\n    for key in path:\n        node = node.get(key) if isinstance(node, dict) else None\n        if node is None:\n            return {}\n    return node if isinstance(node, dict) else {}\n\n\ndef profile_secret(name):\n    try:\n        from agent.secret_scope import get_secret\n    except Exception:\n        return os.environ.get(name) or None\n    try:\n        return get_secret(name) or None\n    except Exception:\n        return None\n\n\ndef hermes_version_label():\n    try:\n        from importlib.metadata import version\n\n        return version("hermes-cli")\n    except Exception:\n        try:\n            import hermes_cli\n\n            label = getattr(hermes_cli, "__version__", None)\n        except Exception:\n            return None\n    return str(label) if label else None\n\n\ndef _hermes_version():\n    """This Hermes as a comparable tuple, or None when it will not say."""\n    raw = hermes_version_label()\n    if not raw:\n        return None\n    parts = []\n    for piece in str(raw).split(".")[:3]:\n        digits = ""\n        for char in piece:\n            if not char.isdigit():\n                break\n            digits += char\n        if not digits:\n            return None\n        parts.append(int(digits))\n    while len(parts) < 3:\n        parts.append(0)\n    return tuple(parts)\n\n\ndef bounds_pre_tool_call():\n    """Whether this Hermes abandons a slow pre_tool_call callback.\n\n    The timeout was added after 0.20.5, which runs plugin hooks to completion.\n    Clamping the wait on a host that would never have cut it off just shortens\n    the window the user has to answer, for nothing.\n\n    Unreadable means assume bounded. A wait that is shorter than it had to be\n    costs the user seconds; a wait longer than the host allows costs them the\n    answer they already gave.\n\n    That rule is why the private symbol is not asked on its own. `hasattr` on\n    `_HOOK_TIMEOUT_FAIL_CLOSED_HOOKS` cannot tell "this host runs hooks to\n    completion" apart from "the private name moved", and those two answers want\n    opposite behaviour: the first earns the full window, the second spends 55\n    seconds against a budget of 30 and loses an answer the user already gave.\n    A rename is the likelier of the two, because a private name is the one thing\n    a host is free to change. So the symbol is taken as proof of bounded, and\n    only a version this side of the timeout landing is taken as proof of the\n    other. Anything unreadable falls to bounded.\n    """\n    try:\n        from hermes_cli import plugins\n    except Exception:\n        return True\n    if hasattr(plugins, "_HOOK_TIMEOUT_FAIL_CLOSED_HOOKS"):\n        return True\n    version = _hermes_version()\n    if version is None:\n        return True\n    return version > UNBOUNDED_THROUGH_VERSION\n\n\ndef hook_callback_timeout_seconds():\n    raw = _section(_config(), "plugins").get("hook_callback_timeout")\n    if raw is None:\n        return HOOK_TIMEOUT_DEFAULT_SECONDS\n    try:\n        timeout = float(raw)\n    except (TypeError, ValueError):\n        return HOOK_TIMEOUT_DEFAULT_SECONDS\n    if timeout < 0:\n        return HOOK_TIMEOUT_DEFAULT_SECONDS\n    return min(timeout, HOOK_TIMEOUT_MAX_SECONDS)\n\n\ndef gate_budget_seconds(requested_seconds):\n    if not bounds_pre_tool_call():\n        return max(1.0, min(float(requested_seconds), GATE_MAX_SECONDS))\n    timeout = hook_callback_timeout_seconds()\n    ceiling = (\n        GATE_MAX_SECONDS\n        if timeout <= 0\n        else max(GATE_MIN_SECONDS, timeout - GATE_HEADROOM_SECONDS)\n    )\n    return max(1.0, min(float(requested_seconds), ceiling, GATE_MAX_SECONDS))\n\n\ndef pushary_is_selected_transport():\n    selected = _section(_config(), "security", "approval").get("transport")\n    return str(selected or "").strip().lower() == TRANSPORT_NAME\n' },
+  { path: "identity.py", contents: 'import hashlib\nimport os\nimport re\nimport socket\nfrom pathlib import Path\n\nDEFAULT_AGENT_NAME = "Hermes"\nMAX_ID_LENGTH = 128\nSHARED_MACHINE_ID_FILE = Path.home() / ".pushary" / "machine-id"\nSHARED_MACHINE_ID_PATTERN = re.compile(r"^[A-Za-z0-9-]{1,128}$")\n\n_session_id = None\n\n\ndef agent_name():\n    return os.environ.get("PUSHARY_AGENT_NAME", DEFAULT_AGENT_NAME)\n\n\ndef labelled_agent_name(requested):\n    project = str(requested or "").partition(" - ")[2].strip()\n    return f"{agent_name()} - {project}" if project else agent_name()\n\n\ndef shared_machine_id(path=None):\n    try:\n        value = (path or SHARED_MACHINE_ID_FILE).read_text(encoding="utf-8").strip()\n    except OSError:\n        return None\n    return value if SHARED_MACHINE_ID_PATTERN.match(value) else None\n\n\ndef hostname_machine_id():\n    try:\n        host = socket.gethostname()\n    except Exception:\n        return None\n    if not host:\n        return None\n    return hashlib.sha256(host.encode("utf-8")).hexdigest()[:8]\n\n\ndef machine_id():\n    return shared_machine_id() or hostname_machine_id()\n\n\ndef remember_session(value):\n    global _session_id\n    if value:\n        _session_id = str(value)[:MAX_ID_LENGTH]\n\n\ndef forget_session():\n    global _session_id\n    _session_id = None\n\n\ndef session_id():\n    return _session_id\n' },
+  { path: "installation.py", contents: `import json
+import logging
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import host
+
+logger = logging.getLogger(__name__)
+
+PLUGIN_DIRECTORY = Path(__file__).parent
+MANIFEST_FILE = "plugin.yaml"
+INSTALL_MARKER_FILE = ".pushary-install.json"
+INSTALL_MARKER_OWNER = "pushary"
+HERMES_PLUGINS_FOLDER = "plugins"
+PLUGIN_DATA_NAMESPACE = "pushary"
+LOAD_RECORDS_DIRECTORY = "loaded"
+LOAD_RECORD_RETENTION_SECONDS = 7 * 24 * 60 * 60
+
+
+def plugin_version(directory=None):
+    try:
+        manifest = ((directory or PLUGIN_DIRECTORY) / MANIFEST_FILE).read_text(encoding="utf-8")
+    except OSError:
+        return None
+    for line in manifest.splitlines():
+        key, separator, value = line.partition(":")
+        if separator and key.strip() == "version":
+            return value.strip().strip("'\\"") or None
+    return None
+
+
+LOADED_PLUGIN_VERSION = plugin_version()
+LOADED_HERMES_VERSION = host.hermes_version_label()
+
+
+def install_marker(directory=None):
+    try:
+        marker = json.loads(((directory or PLUGIN_DIRECTORY) / INSTALL_MARKER_FILE).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(marker, dict) or marker.get("owner") != INSTALL_MARKER_OWNER:
+        return None
+    return marker
+
+
+def follows_catalog_rules(directory=None):
+    folder = directory or PLUGIN_DIRECTORY
+    return folder.parent.name == HERMES_PLUGINS_FOLDER and install_marker(folder) is None
+
+
+def routes_questions(directory=None):
+    marker = install_marker(directory)
+    return bool(marker and marker.get("routeQuestions") is True)
+
+
+def hermes_home():
+    try:
+        from hermes_constants import get_hermes_home
+
+        return Path(get_hermes_home())
+    except Exception:
+        configured = os.environ.get("HERMES_HOME")
+        return Path(configured).expanduser() if configured else Path.home() / ".hermes"
+
+
+def load_records_directory(home=None):
+    return (home or hermes_home()) / "plugin-data" / PLUGIN_DATA_NAMESPACE / LOAD_RECORDS_DIRECTORY
+
+
+def load_record(approval_transport_registered, pid, loaded_at):
+    return {
+        "pluginVersion": LOADED_PLUGIN_VERSION,
+        "hermesVersion": LOADED_HERMES_VERSION,
+        "pid": pid,
+        "approvalTransport": bool(approval_transport_registered),
+        "loadedAt": loaded_at,
+    }
+
+
+def _process_is_running(pid):
+    if os.name == "nt":
+        return True
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except OSError:
+        return True
+    return True
+
+
+def _record_belongs_to_running_process(record):
+    return record.stem.isdigit() and _process_is_running(int(record.stem))
+
+
+def _prune_expired_load_records(directory, keep, now):
+    for record in directory.glob("*.json"):
+        if record.name == keep:
+            continue
+        try:
+            expired = now - record.stat().st_mtime > LOAD_RECORD_RETENTION_SECONDS
+            if expired and not _record_belongs_to_running_process(record):
+                record.unlink()
+        except OSError:
+            continue
+
+
+def record_plugin_load(approval_transport_registered, home=None, pid=None, now=None):
+    process_id = os.getpid() if pid is None else pid
+    moment = time.time() if now is None else now
+    directory = load_records_directory(home)
+    record_name = f"{process_id}.json"
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        loaded_at = datetime.fromtimestamp(moment, timezone.utc).isoformat()
+        staged = directory / f".{record_name}.tmp"
+        staged.write_text(
+            json.dumps(load_record(approval_transport_registered, process_id, loaded_at)),
+            encoding="utf-8",
+        )
+        os.replace(staged, directory / record_name)
+        _prune_expired_load_records(directory, record_name, moment)
+        return directory / record_name
+    except OSError as exc:
+        logger.debug("[pushary] could not record the plugin load: %s", exc)
+        return None
+` },
+  { path: "plugin.yaml", contents: "name: pushary\nversion: 0.8.0\ndescription: Push notifications and human-in-the-loop for Hermes Agent via Pushary\nauthor: RalphNex OU\nrequires_env:\n  - name: PUSHARY_API_KEY\n    description: Your Pushary API key\n    url: https://pushary.com/sign-up?from=hermes\n    secret: true\nprovides_tools:\n  - pushary_remind\n  - pushary_notify\n  - pushary_ask\n  - pushary_wait\n  - pushary_cancel\n  - pushary_propose_scope\n  - pushary_enroll\n  - pushary_ask_end_user\nprovides_hooks:\n  - pre_llm_call\n  - pre_tool_call\n  - post_tool_call\n  - on_session_start\n  - on_session_end\n  - on_session_finalize\nprovides_approval_transports:\n  - pushary\n" },
+  { path: "schemas.py", contents: `PUSHARY_REMIND = {
+    "name": "pushary_remind",
+    "description": "Schedule a one-time personal reminder on Pushary, even after Hermes exits. Use body plus in_minutes or at (ISO timestamp with explicit UTC offset, within 30 days). Never guess the user's timezone. Confirm the returned time. No arguments lists pending reminders; cancel_reminder_id cancels a scheduled one. Use Hermes cron for agent work; use this for reminding the operator.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "request_id": {"type": "string", "description": "Unique scheduling operation ID. Reuse unchanged when retrying."},
+            "reminder_id": {"type": "string", "description": "Look up your reminder outcome instead of scheduling or cancelling."},
+            "body": {"type": "string", "maxLength": 180, "description": "At most 180 UTF-16 units after secret redaction; emoji may use two."},
+            "title": {"type": "string", "maxLength": 100, "description": "At most 100 UTF-16 units after secret redaction; emoji may use two."},
+            "in_minutes": {"type": "integer", "minimum": 1, "maximum": 43200},
+            "at": {"type": "string", "description": "Future ISO 8601 time with Z or UTC offset."},
+            "cancel_reminder_id": {"type": "string"},
+            "agent_name": {"type": "string"},
+            "session_id": {"type": "string"},
+            "machine_id": {"type": "string"},
+            "env": {"type": "string", "enum": ["test"]},
+        },
+        "additionalProperties": False,
+    },
+}
+
+PUSHARY_NOTIFY = {
+    "name": "pushary_notify",
+    "description": (
+        "Send a push notification to the user's phone or desktop. Use when a task "
+        "completes, an error occurs, or a long-running process finishes. The user "
+        "sees this on their lock screen even if they're away from the computer. "
+        "Optionally include structured context with file changes, error details, "
+        "and next steps."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "title": {
+                "type": "string",
+                "description": "Notification title (max 100 chars, aim for under 60)",
+            },
+            "body": {
+                "type": "string",
+                "description": "Notification body (max 500 chars, aim for under 200)",
+            },
+            "agent_name": {
+                "type": "string",
+                "description": 'Identifies this Hermes instance (e.g., "Hermes - daily-briefing")',
+            },
+            "context_type": {
+                "type": "string",
+                "enum": ["task_complete", "error", "info"],
+                "description": (
+                    "Always pass this. It marks the notification a task update, and the "
+                    "user's setting for where task updates land can only route one that "
+                    "says so. Also drives the rich detail page."
+                ),
+            },
+            "summary": {
+                "type": "string",
+                "description": "Short summary shown on the detail page",
+            },
+            "details": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Bullet-point details",
+            },
+            "files_changed": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "List of files that were changed",
+            },
+            "error_message": {
+                "type": "string",
+                "description": "Error message if context_type is error",
+            },
+            "next_steps": {
+                "type": "string",
+                "description": "Suggested next steps for the user",
+            },
+            "session_id": {
+                "type": "string",
+                "description": "Per-session id, so parallel Hermes sessions are attributed separately. Filled in automatically when omitted.",
+            },
+        },
+        "required": ["title", "body"],
+    },
+}
+
+PUSHARY_ASK = {
+    "name": "pushary_ask",
+    "description": (
+        "Ask the user a question via push notification and wait for their answer. "
+        "By default it performs the initial wait and at most one server-directed poll. "
+        "Returns an answer or a structured unanswered result; follow handoffAction "
+        "when present, otherwise nextAction. "
+        "Supports three question types: confirm (yes/no), select (multiple choice "
+        "with 2-6 options), and input (free text). Set wait=false only when you want "
+        "an immediate correlationId and will continue pushary_wait while the question is pending."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "question": {
+                "type": "string",
+                "description": "The question to ask (max 8000 chars)",
+            },
+            "type": {
+                "type": "string",
+                "enum": ["confirm", "select", "input"],
+                "description": "Question type: confirm (yes/no), select (pick from options), input (free text)",
+                "default": "confirm",
+            },
+            "options": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Choices for select type (2-6 options)",
+            },
+            "placeholder": {
+                "type": "string",
+                "description": "Placeholder text for input type",
+            },
+            "context": {
+                "type": "string",
+                "description": "What you're working on, shown above the question",
+            },
+            "agent_name": {
+                "type": "string",
+                "description": 'Identifies this Hermes instance (e.g., "Hermes - server-maintenance")',
+            },
+            "wait": {
+                "type": "boolean",
+                "description": "Wait for the answer before returning (default true). Set false to get correlationId for manual polling.",
+                "default": True,
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "How long to wait per poll attempt in ms (default 30000, max 55000)",
+                "default": 30000,
+            },
+            "tool_name": {
+                "type": "string",
+                "description": "The tool this approval is for (e.g. \\"terminal\\"), so the user can choose to always-allow it.",
+            },
+            "tool_target": {
+                "type": "string",
+                "description": "Compact target of the tool call, e.g. the command head \\"git push\\" or a file extension. Used to mine policy suggestions.",
+            },
+            "repo_key": {
+                "type": "string",
+                "description": "Stable repository identity for the working directory, e.g. \\"github.com/acme/api\\", so a routing rule scoped to one repository does not govern another.",
+            },
+            "intent": {
+                "type": "string",
+                "description": "The user's stated task, one line. Shown as the Intent line so they can see why you stopped.",
+            },
+            "action": {
+                "type": "string",
+                "description": "The concrete operation about to happen, one line. Shown as the Action line.",
+            },
+            "blocker": {
+                "type": "string",
+                "description": "The single gating reason you stopped, one line. Shown as the Blocker line.",
+            },
+            "action_body": {
+                "type": "string",
+                "description": "The diff or full command, rendered as a collapsible detail block. Never used as the push body.",
+            },
+            "session_id": {
+                "type": "string",
+                "description": "Per-session id, so parallel Hermes sessions are attributed separately. Filled in automatically when omitted.",
+            },
+        },
+        "required": ["question"],
+    },
+}
+
+PUSHARY_WAIT = {
+    "name": "pushary_wait",
+    "description": (
+        "Poll once for a question created by pushary_ask with wait=false. Follow "
+        "handoffAction when present, otherwise nextAction. Do not loop."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "correlation_id": {
+                "type": "string",
+                "description": "The correlationId returned by pushary_ask",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "How long to wait in milliseconds (default 30000, max 55000)",
+                "default": 30000,
+            },
+        },
+        "required": ["correlation_id"],
+    },
+}
+
+PUSHARY_CANCEL = {
+    "name": "pushary_cancel",
+    "description": (
+        "Cancel a pending question so it can no longer be answered. Use when "
+        "the question is no longer relevant."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "correlation_id": {
+                "type": "string",
+                "description": "The correlationId of the question to cancel",
+            },
+        },
+        "required": ["correlation_id"],
+    },
+}
+
+PUSHARY_PROPOSE_SCOPE = {
+    "name": "pushary_propose_scope",
+    "description": (
+        "Propose what this run will touch and block until the user ratifies it on "
+        "their phone. Do not add a redundant approval to already authorized work. "
+        "The user approves the paths you intend to change, the areas you promise to "
+        "leave alone, and your definition of done in one tap. After that, editing a "
+        "file outside the agreed scope becomes a separate 'wants to widen scope' "
+        "question instead of a silent approval, so the user is asked once about the "
+        "boundary rather than repeatedly about each file. ONLY file paths are "
+        "enforced, and only on tool calls that carry one; shell commands, reads, web "
+        "requests and MCP tools carry no path, so the contract says nothing about "
+        "them. A boundary that is not a path (recipients, channels, spend, systems) "
+        "goes in promises, which is shown and recorded but never checked. Read the "
+        "returned enforces: an empty list means nothing here is checked "
+        "automatically, and you must say so rather than report that a scope is in "
+        "force. Returns ratified:true only on an explicit yes; "
+        "anything else means proceed as if no scope was agreed."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "done_when": {
+                "type": "string",
+                "description": "What \\"finished\\" means for this run, one or two lines.",
+            },
+            "allowed_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Globs you intend to change, e.g. [\\"src/**\\", \\"docs/*.md\\"].",
+            },
+            "off_limits_paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Globs you promise not to touch. These win wherever they overlap allowed_paths.",
+            },
+            "promises": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": (
+                    "Boundaries that are not file paths: recipients, channels, spend limits, "
+                    "systems you will not open. Up to 10 of 200 characters. Shown to the user "
+                    "as \\"Promised, not checked\\" and recorded, but NEVER enforced, because the "
+                    "gate judges a file path and these have none. Do not put these in allowed_paths."
+                ),
+            },
+            "agent_name": {
+                "type": "string",
+                "description": 'Identifies this Hermes instance (e.g., "Hermes - migration").',
+            },
+            "session_id": {
+                "type": "string",
+                "description": "Per-session id. Filled in from the running Hermes session when omitted.",
+            },
+            "timeout_ms": {
+                "type": "integer",
+                "description": "How long to block waiting for ratification (max 55000).",
+            },
+        },
+        "required": ["done_when"],
+    },
+}
+
+# --- Partner tools (require the Partner plan) -----------------------------------
+# Reach your OWN product's end-users, not the operator's own devices. Use these when
+# Hermes runs as a product that serves many people (gateway mode), so each person
+# approves their own action on their own phone.
+
+PUSHARY_ENROLL = {
+    "name": "pushary_enroll",
+    "description": (
+        "Connect one of your OWN end-users' phones so they can approve actions "
+        "(Partner plan). Returns a single-use link to show that person; one tap "
+        "connects them through the Pushary app or supported browser fallback, without an operator account. Call once per "
+        "end-user and reuse the enrollment, not the link, which expires. Use before "
+        "pushary_ask_end_user for a user who has not connected a phone yet."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "external_id": {
+                "type": "string",
+                "description": "Your own stable id for the end-user (a user id, tenant key, email hash).",
+            },
+        },
+        "required": ["external_id"],
+    },
+}
+
+PUSHARY_ASK_END_USER = {
+    "name": "pushary_ask_end_user",
+    "description": (
+        "Ask one of your OWN end-users a question and block until they answer on "
+        "their phone (Partner plan). Durable and fail-closed: a decline, a timeout, "
+        "or no answer comes back as approved=false, so silence never turns into "
+        "consent. Connect the person first with pushary_enroll. In gateway "
+        "(multi-user) mode, pass each user's external_id from your own user model, "
+        "not the Hermes session id."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "question": {
+                "type": "string",
+                "description": "The question to ask (max 8000 chars).",
+            },
+            "external_id": {
+                "type": "string",
+                "description": "Your own id for the end-user who should answer.",
+            },
+            "type": {
+                "type": "string",
+                "enum": ["confirm", "select", "input"],
+                "description": "confirm (yes/no), select (pick from options), input (free text).",
+                "default": "confirm",
+            },
+            "options": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Choices for a select question (2-6 options).",
+            },
+            "context": {
+                "type": "string",
+                "description": "What you are working on, shown above the question.",
+            },
+            "agent_name": {
+                "type": "string",
+                "description": 'Identifies this Hermes instance (e.g., "Hermes - support").',
+            },
+            "timeout_seconds": {
+                "type": "integer",
+                "description": "How long to block waiting for the answer (default 50, the decision stays open longer).",
+                "default": 50,
+            },
+        },
+        "required": ["question", "external_id"],
+    },
+}
+` },
+  { path: "skills/pushary/SKILL.md", contents: '---\nname: pushary-hermes\nversion: 0.9.0\ndescription: Push notifications and human-in-the-loop for Hermes Agent. Use this whenever a running agent needs a human and no chat session is active, such as before an irreversible or destructive action, before spending money, deploying, force-pushing or deleting, when blocked on a decision outside your authority, when running unattended and you hit a genuine ambiguity, when another skill\'s workflow says to confirm with the user, and when a long task finishes or fails with nobody watching. Send alerts when tasks finish, ask questions (yes/no, multiple choice, or free text) via web push, and get answers from their connected devices. Use these tools proactively when the user is not actively in a chat session. Works alongside Hermes\'s built-in messaging platforms (Telegram, Discord, etc.) as a universal fallback channel.\nmetadata:\n  hermes:\n    tags: [notifications, push, human-in-the-loop, alerts, permissions]\n    category: productivity\n    requires_toolsets: []\n    config:\n      - key: PUSHARY_API_KEY\n        description: "Your Pushary API key for push notifications"\n        default: ""\n  tags: notifications, push, mcp, human-in-the-loop, hermes, alerts, permissions\n---\n\n# Pushary - Push Notifications for Hermes Agent\n\nPushary adds mobile, Mac and browser delivery for Hermes. Use it when the user is not actively monitoring a chat platform, or when you need to reach them on their phone\'s lock screen for a time-sensitive decision.\n\n## Ask in as Few Interruptions as Possible\n\nHonor authorization already granted in this session. Ask only for a missing decision or an action outside that authorization, or when an enforced host policy requires it. A multi-step task alone does not require plan approval. Never ask again merely because the next authorized step deletes, deploys or publishes something. These skills guide the agent; supported hooks and runtime approval gates enforce policy. Do not bypass an enforced gate.\n\nEvery question costs the user their attention wherever they are. Before a run of more than a step or two, work out where you will need a human and fold those points together: one `select` carrying the real options beats three `confirm`s in a row, ask once at a boundary rather than once per instance, and never ask what you can determine yourself from the task or from a tool call you can make.\n\n## When to Use Pushary vs Hermes Platforms\n\n**Use Pushary when:**\n- The user has no active chat session (Telegram, Discord, etc.)\n- You need to reach the user\'s phone lock screen for a quick decision\n- A background task finishes and the user may have walked away\n- Permission escalation - a dangerous command needs approval\n- Another skill\'s workflow says to confirm with the user, and no chat session is active to confirm in\n- The user explicitly asked for push notifications\n\n**Use the active Hermes platform when:**\n- The user is currently in a Telegram/Discord/Slack conversation with you\n- The question is part of an ongoing dialog\n- The user prefers responses in their current platform\n\nUse an extra push only when the user requested it or a meaningful unattended result needs attention. Do not assume you can detect whether a Telegram or Discord message was read.\n\n## Setup\n\nOn a Mac, the Pushary app connects Hermes: it puts this plugin in `~/.hermes/plugins/pushary` and selects Pushary as the approval transport. On any computer, `npx pushary@latest setup --agents hermes` does the same. The plugin can also come from the Hermes catalog with `hermes plugins install pushary`. Never install a second copy over one that is already there. No MCP server configuration is needed. Keep credentials out of chat and verify the paired account and device.\n\nIf the `pushary_*` tools are missing from a Hermes session, the plugin did not load. Do not pip-install it into Hermes\'s Python: current Hermes does not load packages added that way. Ask the user to open the Pushary app and repair Hermes, or to run `npx pushary@latest setup --agents hermes`. Then they restart Hermes with `hermes gateway restart`.\n\n## Approvals Go to the Phone\n\nThe plugin registers `pushary` as a Hermes **approval transport**, so the dangerous-command approvals Hermes already asks for open in the app with the same four choices the terminal offers: allow once, allow for this session, always allow, deny. Hermes owns the timeout (300 seconds by default) and remembers session and always decisions exactly as it would have.\n\n```yaml\nsecurity:\n  approval:\n    transport: pushary\n    transport_fallback: builtin\n```\n\nHermes denies by default when Pushary is unreachable. Only an operator who sets `transport_fallback: builtin` enables its built-in prompt after a safe local handoff; cancellation or an unverifiable withdrawal still stops the action. You do not call this yourself; it fires when Hermes decides a command needs a human.\n\n## Answer surfaces and account boundaries\n\n| Surface | What the user can do |\n| --- | --- |\n| Mobile app | Answer confirm, select and input questions. Supported confirm notifications offer approve/deny actions on the lock screen; arbitrary choices and text open the app. |\n| Mac notch | Answer personal account questions with confirm, select, input and question-set controls, including keyboard controls. Presence and delivery policy determine when the phone is also reached. |\n| Slack | Answer through buttons, menus or text modals when the integration and intended recipient are configured. |\n| Browser | Open the decision page as a fallback; browser notification delivery requires permission. |\n\nPersonal setup connects the operator\'s devices. For a Mac, the operator installs from https://pushary.com/download, signs in to the same personal account and connects their agents in the app. Request one harmless test question and verify it reaches the intended surface. Test phone fallback while away from the Mac; do not infer delivery from a successful API call alone.\n\nPartner customers use scoped enrollment links issued by their application. Do not enroll them into the operator\'s account or send their decisions through personal tools. The Mac notch currently uses the personal account/session API; do not promise a Partner customer inbox on Mac. See https://pushary.com/docs/agents/embed for Partner setup.\n\n## Tools\n\nTool names below are the native plugin names. An MCP client without the plugin sees the same capabilities as `send_notification`, `schedule_reminder`, `ask_user`, `wait_for_answer`, `cancel_question`, and `propose_scope`.\n\n### pushary_remind\n\nFor personal reminders later, use `pushary_remind` with `body` and `in_minutes`, or `at` with an explicit UTC offset. Never guess the timezone; confirm the returned time. Pushary saves it and delivers after Hermes exits. Use Hermes cron for future agent work. No arguments lists pending reminders; `cancel_reminder_id` cancels a scheduled one. One-time only, up to 30 days ahead, and delivery can be about a minute late. A connected phone is required. Do not use `pushary_ask` for reminders.\n\n### pushary_notify\n\n\nSend a one-way push notification. Optionally include structured context for a rich detail page.\n\n**Parameters:**\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| title | string | Yes | Notification title (max 100 chars, aim for under 60) |\n| body | string | Yes | Notification body (max 500 chars, aim for under 200) |\n| agent_name | string | No | Identifies this Hermes instance (e.g., "Hermes - daily-briefing") |\n| context_type | "task_complete" / "error" / "info" | Yes for task updates | Marks the notification for task-update routing. |\n| summary | string | No | Short summary of the result. |\n| details / files_changed | string[] | No | Result details or changed paths. |\n| error_message / next_steps | string | No | Error or suggested follow-up. |\n\n**Example - cron task completed:**\n\n```json\n{\n  "title": "Daily briefing ready",\n  "body": "Compiled 12 news items and 3 calendar events",\n  "agent_name": "Hermes - daily-briefing",\n  "context_type": "task_complete",\n  "summary": "Morning briefing compiled from RSS feeds and Google Calendar",\n  "details": ["12 tech news items", "3 meetings today", "2 PRs awaiting review"],\n  "next_steps": "Say \'read briefing\' in Telegram to hear the full summary"\n}\n```\n\n### pushary_ask\n\nAsk a question via push notification and **wait for the answer** (blocks by default). Three question types: confirm (yes/no), select (multiple choice), input (free text).\n\n**Parameters:**\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| question | string | Yes | The complete question (max 8000 chars; notifications show a short preview) |\n| type | "confirm" / "select" / "input" | No | Question type (default: confirm) |\n| options | string[] | No | Choices for select type (2-6 options) |\n| placeholder | string | No | Placeholder text for input type |\n| context | string | No | What you\'re working on, shown above the question |\n| agent_name | string | No | Identifies this Hermes instance |\n| wait | boolean | No | Wait for answer before returning (default: true) |\n| timeout_ms | integer | No | Max wait in ms (max 55000). Defaults to 30000 per poll attempt; server policy may hand off earlier. |\n\n**Returns:**\n- `{ "answered": true, "value": "yes" }` - user responded\n- `{ "answered": false, "timedOut": true }` - no response within timeout\n\n**Example - dangerous command approval:**\n\n```json\n{\n  "question": "Allow: rm -rf /tmp/build-artifacts/*",\n  "type": "confirm",\n  "context": "Cleaning up 2.3GB of stale build artifacts from last week",\n  "agent_name": "Hermes - server-maintenance",\n  "timeout_ms": 12000\n}\n```\n\n### pushary_wait\n\nPoll once for a response when `pushary_ask` was called with `wait: false`. Not needed with default blocking mode.\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| correlation_id | string | Yes | The correlationId from pushary_ask |\n| timeout_ms | integer | No | How long to wait (default 30000, max 55000) |\n\n### pushary_cancel\n\nCancel a pending question that\'s no longer relevant.\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| correlation_id | string | Yes | The correlationId to cancel |\n\n### pushary_propose_scope\n\nAgree the boundary of a multi-step run in one tap, before doing the work, instead of asking file by file. Use it once when a boundary needs agreement or the user requests an enforced scope. Skip a redundant proposal for already authorized work.\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n| done_when | string | Yes | What "finished" means for this run |\n| allowed_paths | string[] | No | Globs you intend to change, e.g. `["src/**"]` |\n| off_limits_paths | string[] | No | Globs you promise not to touch; these win on overlap |\n| promises | string[] | No | Boundaries that are not file paths: recipients, channels, spend, systems you will not open |\n| agent_name | string | No | Identifies this Hermes instance |\n\nOnly file paths are enforced, and only on tool calls that carry one. Shell commands, reads, web requests and MCP tools carry no path, so the contract says nothing about them. A run that changes no files belongs in `promises`, which is shown to the user and recorded but never checked. A word that is not a path in `allowed_paths` matches no file and makes every change ask instead.\n\nRead `enforces` in the result. An empty list means nothing here is checked automatically, and you must say so rather than report that a scope is in force.\n\nReturns `ratified: true` only on an explicit yes. Anything else means proceed as if no scope was agreed; do not describe it as ratified.\n\n## Human-in-the-Loop Flow\n\n`pushary_ask` performs its initial wait and at most one server-directed poll within that tool call. If the returned status is still pending, continue with `pushary_wait` and the same correlationId. With `wait: false`, start that polling yourself. Follow an explicit handoff instead when one is returned.\n\nRead `answered`, `status` and `handoffAction` (falling back to `nextAction`) on every response. Only `pending` is live; expired, cancelled, missing and unavailable are not new timeouts. Keep waiting with the same correlationId while pending. A poll ending does not expire the question; never cancel just because a poll returned without an answer. Before moving a live question to the current chat, cancel it. If cancellation says `stop`, stop; if it loses a race, poll once for one second and honor the winning answer. Silence is never consent. A select or input value containing \u201Cyes\u201D is answer data, not approval of a separate action.\n\nDelivery is controlled by the user\'s policy: `push_first` uses presence, `push_only` requests push every time, `notify_only` leaves the decision in the current client, and `terminal_only` avoids push. Do not override the mode or duplicate a question on every surface. The runtime owns delivery, expiry and settlement; do not claim that a reply can restart an ended agent turn.\n\nEach call returns an answer, a pending wait, or an explicit handoff:\n\n```\nresult = pushary_ask({\n  question: "Deploy the updated config to production?",\n  type: "confirm",\n  context: "nginx config updated with new rate limits",\n  tool_name: "terminal",\n  tool_target: "systemctl reload",\n  agent_name: "Hermes - devops"\n})\n\nif result.answered:\n    if result.value == "yes":\n        // proceed with deployment\n    else:\n        // abort and notify via active platform\nelse:\n    // follow handoffAction when present, otherwise nextAction\n```\n\nPass `tool_name` and `tool_target` whenever the question is about a specific operation. They are what let the user turn a repeated approval into a standing rule, and what group the decision in their ledger.\n\n## Identifying Your Instance\n\nAlways pass `agent_name` so the user knows which Hermes profile or task is asking.\n\n**Format:** `"Hermes - {profile or task}"`\n\n**Examples:**\n- `"Hermes - daily-briefing"`\n- `"Hermes - server-maintenance"`\n- `"Hermes - code-review"`\n- `"Hermes - personal-assistant"`\n\n## Notification Etiquette\n\n- **Titles under 60 characters.** Phone lock screens truncate aggressively.\n- **Bodies under 200 characters.** Use the flat `summary`, `details` and `next_steps` fields.\n- **Max 3 push notifications per task.** If the user is in an active chat, prefer that channel.\n- **Don\'t duplicate.** If you already sent the message via Telegram/Discord, send another push only if requested or needed for an unattended result.\n' },
+  { path: "tools.py", contents: `import json
+import time
+import uuid
+from . import api, identity
+
+CONTEXT_FIELDS = {
+    "summary": "summary",
+    "details": "details",
+    "files_changed": "filesChanged",
+    "error_message": "errorMessage",
+    "next_steps": "nextSteps",
+}
+
+
+def _accepted_fields(params, accepted):
+    return {key: params[key] for key in accepted if params.get(key) is not None}
+
+
+def pushary_notify(params, **kwargs):
+    title = params.get("title", "")
+    body = params.get("body", "")
+    agent_name = identity.labelled_agent_name(params.get("agent_name"))
+
+    context = None
+    context_type = params.get("context_type")
+    if context_type:
+        context = {"type": context_type}
+        for field, camel in CONTEXT_FIELDS.items():
+            value = params.get(field)
+            if value is not None:
+                context[camel] = value
+
+    try:
+        result = api.send_notification(
+            title,
+            body,
+            agent_name=agent_name,
+            context=context,
+            **_accepted_fields(params, api.IDENTITY_PARAM_NAMES),
+        )
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_remind(params, **kwargs):
+    try:
+        result = api.schedule_reminder(
+            agent_name=identity.labelled_agent_name(params.get("agent_name")),
+            **_accepted_fields(params, ("body", "title", "in_minutes", "at", "cancel_reminder_id", "request_id", "reminder_id", "env", *api.IDENTITY_PARAM_NAMES)),
+        )
+        return json.dumps(result)
+    except Exception as exc:
+        return json.dumps({"error": str(exc)})
+
+
+def pushary_ask(params, **kwargs):
+    question = params.get("question", "")
+    question_type = params.get("type", "confirm")
+    options = params.get("options")
+    placeholder = params.get("placeholder")
+    context = params.get("context")
+    agent_name = identity.labelled_agent_name(params.get("agent_name"))
+    wait = params.get("wait", True)
+    timeout_ms = params.get("timeout_ms", 30000)
+
+    try:
+        result = api.ask_user(
+            question,
+            question_type=question_type,
+            options=options,
+            placeholder=placeholder,
+            context=context,
+            agent_name=agent_name,
+            wait=wait,
+            timeout_ms=timeout_ms,
+            **_accepted_fields(params, api.DECISION_PARAM_NAMES),
+        )
+
+        next_action = result.get("handoffAction") or result.get("nextAction")
+        if (
+            not wait
+            or "error" in result
+            or result.get("answered")
+            or (next_action and next_action != "wait_for_answer")
+        ):
+            return json.dumps(result)
+
+        correlation_id = result.get("correlationId")
+        if not correlation_id:
+            return json.dumps(result)
+
+        answer = api.wait_for_answer(correlation_id, timeout_ms)
+        return json.dumps({
+            "correlationId": correlation_id,
+            "question": question,
+            "type": question_type,
+            **answer,
+        })
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_wait(params, **kwargs):
+    correlation_id = params.get("correlation_id", "")
+    timeout_ms = params.get("timeout_ms", 30000)
+
+    try:
+        result = api.wait_for_answer(correlation_id, timeout_ms)
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_cancel(params, **kwargs):
+    correlation_id = params.get("correlation_id", "")
+
+    try:
+        result = api.cancel_question(correlation_id)
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_propose_scope(params, **kwargs):
+    done_when = params.get("done_when", "")
+    if not done_when:
+        return json.dumps({"error": "done_when is required"})
+
+    session = params.get("session_id") or identity.session_id()
+    if not session:
+        return json.dumps({
+            "error": "No session id is available yet, so a scope contract could not be "
+                     "enforced. Proceed without one and ask before each risky step.",
+        })
+
+    try:
+        result = api.propose_scope(
+            done_when,
+            session,
+            allowed_paths=params.get("allowed_paths"),
+            off_limits_paths=params.get("off_limits_paths"),
+            promises=params.get("promises"),
+            agent_name=identity.labelled_agent_name(params.get("agent_name")),
+            timeout_ms=params.get("timeout_ms"),
+        )
+        return json.dumps(result)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_enroll(params, **kwargs):
+    """Partner tool: connect one of your OWN end-users' phones (keyless, one tap)."""
+    external_id = params.get("external_id", "")
+    if not external_id:
+        return json.dumps({"error": "external_id is required"})
+
+    try:
+        result = api.enroll_end_user(external_id)
+        if "error" in result:
+            return json.dumps(result)
+        return json.dumps({
+            "externalId": result.get("externalId", external_id),
+            "connectLink": result.get("universalLink"),
+            "expiresInSeconds": result.get("expiresInSeconds"),
+            "hint": (
+                "Show connectLink to this end-user. One tap connects their phone for "
+                "approvals. The link is single-use and expires, so cache the enrollment, "
+                "not the link."
+            ),
+        })
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def pushary_ask_end_user(params, **kwargs):
+    """Partner tool: ask one of your OWN end-users and block on a fail-closed answer.
+
+    Opens a durable decision addressed to external_id, then long-polls the ledger
+    until it resolves or the timeout passes. Fail-closed: only an answered,
+    affirmative confirm returns approved=True.
+    """
+    question = params.get("question", "")
+    external_id = params.get("external_id", "")
+    question_type = params.get("type", "confirm")
+    options = params.get("options")
+    context = params.get("context")
+    agent_name = params.get("agent_name")
+    try:
+        timeout_seconds = max(1, int(params.get("timeout_seconds", 50)))
+    except (TypeError, ValueError):
+        timeout_seconds = 50
+
+    if not question or not external_id:
+        return json.dumps({"error": "question and external_id are required"})
+
+    try:
+        created = api.create_end_user_decision(
+            question,
+            external_id,
+            question_type=question_type,
+            options=options,
+            agent_name=agent_name,
+            context=context,
+            # One tool call = one intended ask. A fresh key per invocation means two
+            # identical-text asks never collapse into one silent auto-approval.
+            idempotency_key=uuid.uuid4().hex,
+        )
+        if "error" in created:
+            return json.dumps(created)
+
+        decision_id = created.get("decisionId")
+        if not decision_id:
+            return json.dumps({"error": "Pushary did not return a decisionId", "raw": created})
+
+        status = created.get("status", "pending")
+        value = created.get("value")
+
+        deadline = time.monotonic() + timeout_seconds
+        while status == "pending" and time.monotonic() < deadline:
+            remaining = deadline - time.monotonic()
+            wait = max(1, min(45, int(remaining) + 1))
+            polled = api.get_end_user_decision(decision_id, wait_seconds=wait)
+            if "error" in polled:
+                break
+            status = polled.get("status", status)
+            value = polled.get("value")
+
+        answered = status == "answered"
+        approved = answered and question_type == "confirm" and api.is_affirmative(value)
+        return json.dumps({
+            "decisionId": decision_id,
+            "externalId": external_id,
+            "status": status,
+            "answered": answered,
+            "approved": approved,
+            "value": value,
+        })
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+` }
+];
+
+// src/hermes/plugin-payload.ts
+var HERMES_PLUGIN_KEY = "pushary";
+var HERMES_MANIFEST_FILE = "plugin.yaml";
+var HERMES_INSTALL_MARKER_FILE = ".pushary-install.json";
+var HERMES_INSTALL_MARKER_OWNER = "pushary";
+var HERMES_LOAD_RECORDS_PATH = "plugin-data/pushary/loaded";
+var HERMES_LEGACY_PIP_PACKAGE = "hermes-plugin-pushary";
+var HERMES_QUESTION_TOOLSET = "clarify";
+var HERMES_APPROVAL_TRANSPORT_KEY = "security.approval.transport";
+var HERMES_APPROVAL_FALLBACK_KEY = "security.approval.transport_fallback";
+var HERMES_PLUGINS_ENABLED_KEY = "plugins.enabled";
+var HERMES_DISABLED_TOOLSETS_KEY = "agent.disabled_toolsets";
+var HERMES_PUSHARY_TRANSPORT = "pushary";
+var HERMES_PUSHARY_FALLBACK = "builtin";
+var HERMES_PUSHARY_SETTINGS = [
+  { key: HERMES_APPROVAL_TRANSPORT_KEY, value: HERMES_PUSHARY_TRANSPORT },
+  { key: HERMES_APPROVAL_FALLBACK_KEY, value: HERMES_PUSHARY_FALLBACK }
+];
+var unquoted = (value) => value.trim().replace(/^['"]|['"]$/g, "");
+var manifestVersion = (manifest) => {
+  for (const line of manifest.split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator < 0 || line.slice(0, separator).trim() !== "version") continue;
+    return unquoted(line.slice(separator + 1)) || null;
+  }
+  return null;
+};
+var hermesPluginVersion = (files) => {
+  const manifest = files.find((file) => file.path === HERMES_MANIFEST_FILE);
+  return manifest ? manifestVersion(manifest.contents) : null;
+};
+var hermesPluginDigest = (files) => {
+  const hash = createHash("sha256");
+  for (const file of [...files].sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(file.path).update("\0").update(file.contents).update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+};
+var shippedHermesPlugin = (files = HERMES_PLUGIN_FILES) => {
+  const version = hermesPluginVersion(files);
+  if (!version) throw new Error(`The bundled Hermes plugin has no version in ${HERMES_MANIFEST_FILE}`);
+  return { files, version, digest: hermesPluginDigest(files) };
+};
+
+// src/hermes/runtime.ts
+import { execFileSync } from "child_process";
+import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { basename, dirname, isAbsolute, join } from "path";
+var HERMES_COMMAND_TIMEOUT_MS = 2e4;
+var LEGACY_PIP_TIMEOUT_MS = 6e4;
+var HERMES_SETTING_NOT_SET = "Config key not set";
+var HERMES_PLUGINS_SECTION = "plugins";
+var HERMES_APPROVAL_SECTION = "security.approval";
+var INSTALL_METADATA_FILE = ".install-metadata.json";
+var GATEWAY_STATE_FILE = "gateway_state.json";
+var GATEWAY_PID_FILE = "gateway.pid";
+var GATEWAY_RUNNING = "running";
+var HERMES_LAUNCHER_NAME = "hermes";
+var HERMES_LAUNCHER_DIRECTORIES = ["/opt/homebrew/bin", "/usr/local/bin"];
+var isExecutableFile = (path) => {
+  try {
+    accessSync(path, constants.X_OK);
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+var hermesLauncherCandidates = (userHome) => [join(userHome, ".local", "bin"), ...HERMES_LAUNCHER_DIRECTORIES].map((directory) => join(directory, HERMES_LAUNCHER_NAME));
+var findHermesLauncher = () => {
+  const onPath = resolvePathBinary(HERMES_LAUNCHER_NAME);
+  if (onPath) return { path: onPath };
+  if (process.platform === "win32") return null;
+  const installed = hermesLauncherCandidates(homedir()).find(isExecutableFile);
+  return installed ? { path: installed } : null;
+};
+var quotedForWindowsShell = (argument) => `"${argument.replace(/"/g, '\\"')}"`;
+var commandOutput = (error) => {
+  if (!isRecord(error)) return String(error);
+  return [error.stdout, error.stderr].map((part) => part === void 0 || part === null ? "" : String(part)).join("\n");
+};
+var runHermesCommand = (launcher, args) => {
+  const shell = needsShell(launcher.path);
+  try {
+    const stdout = execFileSync(
+      shell ? quotedForWindowsShell(launcher.path) : launcher.path,
+      shell ? args.map(quotedForWindowsShell) : [...args],
+      { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], timeout: HERMES_COMMAND_TIMEOUT_MS, shell }
+    );
+    return { kind: "ok", stdout };
+  } catch (error) {
+    return { kind: "failed", output: commandOutput(error) };
+  }
+};
+var lastLine = (output) => output.trim().split(/\r?\n/).filter((line) => line.trim().length > 0).at(-1)?.trim() ?? "";
+var readHermesHome = (launcher) => {
+  const result = runHermesCommand(launcher, ["config", "path"]);
+  if (result.kind !== "ok") return null;
+  const configPath = lastLine(result.stdout);
+  return isAbsolute(configPath) ? dirname(configPath) : null;
+};
+var parsedJson = (text) => {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+};
+var readHermesSetting = (launcher, key) => {
+  const result = runHermesCommand(launcher, ["config", "get", key, "--json"]);
+  if (result.kind === "failed") return result.output.includes(HERMES_SETTING_NOT_SET) ? { kind: "unset" } : null;
+  const parsed = parsedJson(lastLine(result.stdout));
+  return parsed.ok ? { kind: "set", value: parsed.value } : null;
+};
+var settingArgument = (value) => typeof value === "string" ? value : JSON.stringify(value);
+var writeHermesSetting = (launcher, key, value) => runHermesCommand(launcher, ["config", "set", key, settingArgument(value)]).kind === "ok";
+var unsetHermesSetting = (launcher, key) => {
+  const result = runHermesCommand(launcher, ["config", "unset", key]);
+  return result.kind === "ok" || result.output.includes(HERMES_SETTING_NOT_SET);
+};
+var enableHermesPlugin = (launcher) => runHermesCommand(launcher, ["plugins", "enable", HERMES_PLUGIN_KEY]).kind === "ok";
+var disableHermesPlugin = (launcher) => runHermesCommand(launcher, ["plugins", "disable", HERMES_PLUGIN_KEY]).kind === "ok";
+var removeHermesPlugin = (launcher) => runHermesCommand(launcher, ["plugins", "remove", HERMES_PLUGIN_KEY]).kind === "ok";
+var stringList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+var readingValue = (reading) => reading.kind === "set" ? reading.value : void 0;
+var stringOrNull = (value) => typeof value === "string" ? value : null;
+var readHermesSettings = (launcher) => {
+  const plugins = readHermesSetting(launcher, HERMES_PLUGINS_SECTION);
+  const approval = readHermesSetting(launcher, HERMES_APPROVAL_SECTION);
+  const toolsets = readHermesSetting(launcher, HERMES_DISABLED_TOOLSETS_KEY);
+  if (!plugins || !approval || !toolsets) return null;
+  const pluginSection = readingValue(plugins);
+  const approvalSection = readingValue(approval);
+  const enabled = isRecord(pluginSection) ? stringList(pluginSection.enabled) : [];
+  const disabled = isRecord(pluginSection) ? stringList(pluginSection.disabled) : [];
+  return {
+    pluginEnabled: enabled.includes(HERMES_PLUGIN_KEY),
+    pluginDisabled: disabled.includes(HERMES_PLUGIN_KEY),
+    approvalTransport: isRecord(approvalSection) ? stringOrNull(approvalSection.transport) : null,
+    approvalFallback: isRecord(approvalSection) ? stringOrNull(approvalSection.transport_fallback) : null,
+    disabledToolsets: stringList(readingValue(toolsets))
+  };
+};
+var HERMES_SNAPSHOT_KEYS = [HERMES_APPROVAL_TRANSPORT_KEY, HERMES_APPROVAL_FALLBACK_KEY];
+var hermesPluginDirectory = (home) => join(home, "plugins", HERMES_PLUGIN_KEY);
+var HERMES_ROOT_DIRECTORY = ".hermes";
+var HERMES_CONFIG_FILE = "config.yaml";
+var HERMES_ACTIVE_PROFILE_FILE = "active_profile";
+var HERMES_PROFILES_DIRECTORY = "profiles";
+var HERMES_DEFAULT_PROFILE = "default";
+var HERMES_PROFILE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var BYTE_ORDER_MARK = /^\uFEFF/;
+var expandUserHome = (path, userHome) => path === "~" || path.startsWith("~/") ? join(userHome, path.slice(1)) : path;
+var activeProfileName = (raw) => {
+  const name = raw?.replace(BYTE_ORDER_MARK, "").trim() ?? "";
+  return HERMES_PROFILE_NAME.test(name) && name !== HERMES_DEFAULT_PROFILE ? name : null;
+};
+var resolveHermesHome = (facts) => {
+  const configured = facts.configuredHome?.trim() ? expandUserHome(facts.configuredHome.trim(), facts.userHome) : null;
+  if (configured && basename(dirname(configured)) === HERMES_PROFILES_DIRECTORY) return configured;
+  const root = configured ?? join(facts.userHome, HERMES_ROOT_DIRECTORY);
+  const profile = activeProfileName(facts.readActiveProfile(root));
+  const profileHome = profile === null ? null : join(root, HERMES_PROFILES_DIRECTORY, profile);
+  return profileHome !== null && facts.isDirectory(profileHome) ? profileHome : root;
+};
+var isDirectoryOnDisk = (path) => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+var defaultHermesHome = () => resolveHermesHome({
+  configuredHome: process.env.HERMES_HOME ?? null,
+  userHome: homedir(),
+  readActiveProfile: (root) => readTextFile(join(root, HERMES_ACTIVE_PROFILE_FILE)),
+  isDirectory: isDirectoryOnDisk
+});
+var readJsonFile = (path) => {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+};
+var readTextFile = (path) => {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+};
+var readHermesPluginFolderFacts = (home) => {
+  const directory = hermesPluginDirectory(home);
+  const metadata = readJsonFile(join(home, "plugins", INSTALL_METADATA_FILE));
+  const manifest = readTextFile(join(directory, HERMES_MANIFEST_FILE));
+  return {
+    exists: existsSync(directory),
+    marker: readJsonFile(join(directory, HERMES_INSTALL_MARKER_FILE)),
+    hasGitDirectory: existsSync(join(directory, ".git")),
+    listedByHermesInstaller: isRecord(metadata) && isRecord(metadata[HERMES_PLUGIN_KEY]),
+    manifestVersion: manifest === null ? null : manifestVersion(manifest)
+  };
+};
+var writeStagedFiles = (staging, files, marker) => {
+  rmSync(staging, { recursive: true, force: true });
+  for (const file of files) {
+    const path = join(staging, ...file.path.split("/"));
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, file.contents);
+  }
+  writeFileSync(join(staging, HERMES_INSTALL_MARKER_FILE), `${JSON.stringify(marker, null, 2)}
+`);
+};
+var writeHermesPluginFolder = (home, files, marker) => {
+  const target = hermesPluginDirectory(home);
+  const staging = join(home, `.pushary-plugin-staging-${process.pid}`);
+  const previous = join(home, `.pushary-plugin-previous-${process.pid}`);
+  writeStagedFiles(staging, files, marker);
+  mkdirSync(dirname(target), { recursive: true });
+  rmSync(previous, { recursive: true, force: true });
+  const hadTarget = existsSync(target);
+  if (hadTarget) renameSync(target, previous);
+  try {
+    renameSync(staging, target);
+  } catch (error) {
+    if (hadTarget) renameSync(previous, target);
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+  rmSync(previous, { recursive: true, force: true });
+};
+var isLiveProcess = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isRecord(error) && error.code === "EPERM";
+  }
+};
+var positivePid = (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+var readHermesGateway = (home) => {
+  const state = readJsonFile(join(home, GATEWAY_STATE_FILE));
+  const pidFile = readJsonFile(join(home, GATEWAY_PID_FILE));
+  const statePid = isRecord(state) && state.gateway_state === GATEWAY_RUNNING ? positivePid(state.pid) : null;
+  const pid = statePid ?? (isRecord(state) ? null : isRecord(pidFile) ? positivePid(pidFile.pid) : null);
+  return pid !== null && isLiveProcess(pid) ? { kind: "running", pid } : { kind: "not_running" };
+};
+var readHermesLoadRecord = (home, pid) => {
+  const record = readJsonFile(join(home, ...HERMES_LOAD_RECORDS_PATH.split("/"), `${pid}.json`));
+  if (!isRecord(record)) return null;
+  return {
+    pluginVersion: stringOrNull(record.pluginVersion),
+    approvalTransport: record.approvalTransport === true
+  };
+};
+var PYTHON_INTERPRETER = /python/i;
+var SHEBANG_READ_BYTES = 1024;
+var readFirstLine = (path) => {
+  let descriptor = null;
+  try {
+    descriptor = openSync(path, "r");
+    const buffer = Buffer.alloc(SHEBANG_READ_BYTES);
+    const length = readSync(descriptor, buffer, 0, SHEBANG_READ_BYTES, 0);
+    return buffer.subarray(0, length).toString("utf-8").split("\n", 1)[0] ?? "";
+  } catch {
+    return "";
+  } finally {
+    if (descriptor !== null) closeSync(descriptor);
+  }
+};
+var legacyHermesPython = (launcher) => {
+  const firstLine = readFirstLine(launcher.path);
+  if (!firstLine.startsWith("#!")) return null;
+  const interpreter = firstLine.slice(2).trim().split(/\s+/)[0] ?? "";
+  if (!PYTHON_INTERPRETER.test(interpreter)) return null;
+  try {
+    accessSync(interpreter, constants.X_OK);
+    return interpreter;
+  } catch {
+    return null;
+  }
+};
+var removeLegacyPipCopy = (python, distribution) => {
+  try {
+    execFileSync(python, ["-m", "pip", "uninstall", "-y", distribution], { stdio: "ignore", timeout: LEGACY_PIP_TIMEOUT_MS });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// src/hermes/wiring-state.ts
+var HERMES_INSTALLERS = ["cli", "mac_app"];
+var isHermesInstaller = (value) => HERMES_INSTALLERS.some((installer) => installer === value);
+var parseHermesInstallMarker = (value) => {
+  if (!isRecord(value) || value.owner !== HERMES_INSTALL_MARKER_OWNER) return null;
+  if (!isHermesInstaller(value.installedBy)) return null;
+  if (typeof value.version !== "string" || typeof value.digest !== "string") return null;
+  return {
+    owner: HERMES_INSTALL_MARKER_OWNER,
+    installedBy: value.installedBy,
+    version: value.version,
+    digest: value.digest,
+    routeQuestions: value.routeQuestions === true
+  };
+};
+var hermesInstallMarker = (installedBy, plugin) => ({
+  owner: HERMES_INSTALL_MARKER_OWNER,
+  installedBy,
+  version: plugin.version,
+  digest: plugin.digest,
+  routeQuestions: true
+});
+var classifyHermesPluginFolder = (facts) => {
+  if (!facts.exists) return { kind: "absent" };
+  if (facts.hasGitDirectory || facts.listedByHermesInstaller) {
+    return { kind: "hermes_installer", version: facts.manifestVersion };
+  }
+  const marker = parseHermesInstallMarker(facts.marker);
+  if (marker) return { kind: "pushary", marker, version: facts.manifestVersion };
+  return { kind: "unknown", version: facts.manifestVersion };
+};
+var replacesInstalledRelease = (bundled, installed) => {
+  if (!isReleaseVersion(bundled.version) || !isReleaseVersion(installed.version)) return false;
+  if (isNewerVersion(bundled.version, installed.version)) return true;
+  return bundled.version === installed.version && bundled.digest !== installed.digest;
+};
+var bundledPluginReplaces = (folder, bundled) => {
+  if (folder.kind === "absent") return true;
+  return folder.kind === "pushary" && replacesInstalledRelease(bundled, folder.marker);
+};
+var hermesWiringOwner = (folder, macAppRecordExists) => {
+  if (folder.kind === "pushary") return folder.marker.installedBy;
+  return macAppRecordExists ? "mac_app" : null;
+};
+var routesHermesApprovals = (settings) => settings.approvalTransport === HERMES_PUSHARY_TRANSPORT;
+var routesHermesQuestions = (folder) => folder.kind === "pushary" && folder.marker.routeQuestions;
+var folderVersion = (folder) => folder.kind === "absent" ? null : folder.version;
+var wiringProblems = (facts) => [
+  ...facts.folder.kind === "absent" ? ["plugin_missing"] : [],
+  ...facts.settings.pluginEnabled ? [] : ["plugin_not_enabled"],
+  ...facts.settings.pluginDisabled ? ["plugin_disabled"] : []
+];
+var isUnwired = (facts) => facts.folder.kind === "absent" && !facts.settings.pluginEnabled && !routesHermesApprovals(facts.settings);
+var hermesWiringState = (facts) => {
+  if (isUnwired(facts)) return { kind: "not_wired" };
+  const problems = wiringProblems(facts);
+  if (problems.length > 0) return { kind: "needs_repair", problems };
+  const installedVersion = folderVersion(facts.folder);
+  const recordsItsLoad = facts.folder.kind === "pushary";
+  if (facts.gateway.kind === "not_running" || !recordsItsLoad) {
+    return { kind: "connected", live: false, gatewayRunning: facts.gateway.kind === "running", version: installedVersion, runningVersion: null };
+  }
+  if (!facts.gatewayLoad) return { kind: "restart_needed", installedVersion };
+  return { kind: "connected", live: true, gatewayRunning: true, version: installedVersion, runningVersion: facts.gatewayLoad.pluginVersion };
+};
+var runsAnOlderPlugin = (state) => state.kind === "connected" && state.live && state.runningVersion !== state.version;
+var isHermesWired = (state) => state.kind === "connected" || state.kind === "restart_needed";
+var hasUpdateFrom = (folder, installer, bundled) => folder.kind === "pushary" && folder.marker.installedBy === installer && bundledPluginReplaces(folder, bundled);
+var toolsetsWithoutPusharyQuestionRouting = (disabledToolsets, questionRoutingAdded) => {
+  if (!questionRoutingAdded || !disabledToolsets.includes(HERMES_QUESTION_TOOLSET)) return null;
+  return disabledToolsets.filter((toolset) => toolset !== HERMES_QUESTION_TOOLSET);
+};
+
+// src/hermes/install.ts
+import { existsSync as existsSync2, rmSync as rmSync2 } from "fs";
+
+// src/hermes/setup-receipt.ts
+var HERMES_SETUP_RECEIPT_VERSION = 2;
+var settingSnapshot = (key, reading) => reading.kind === "set" ? { key, wasSet: true, before: reading.value } : { key, wasSet: false, before: null };
+var isSettingSnapshot = (value) => isRecord(value) && typeof value.key === "string" && typeof value.wasSet === "boolean" && Object.hasOwn(value, "before");
+var parseCurrentReceipt = (value) => {
+  const { settings, pluginWasEnabled, questionRoutingAdded } = value;
+  if (!Array.isArray(settings) || !settings.every(isSettingSnapshot)) return null;
+  if (typeof pluginWasEnabled !== "boolean" || typeof questionRoutingAdded !== "boolean") return null;
+  return { settings, pluginWasEnabled, questionRoutingAdded };
+};
+var LEGACY_SNAPSHOT_KEYS = ["security", "approval", "transport", "fallback", "plugins", "enabled", "agent", "disabled"];
+var isLegacySnapshot = (value) => isRecord(value) && typeof value.present === "boolean" && Object.hasOwn(value, "value");
+var legacySetting = (key, snapshot) => ({ key, wasSet: snapshot.present, before: snapshot.present ? snapshot.value : null });
+var parseLegacyReceipt = (value) => {
+  if (!LEGACY_SNAPSHOT_KEYS.every((key) => isLegacySnapshot(value[key]))) return null;
+  if (typeof value.pushary_enabled !== "boolean" || typeof value.clarify_disabled !== "boolean") return null;
+  const transport = value.transport;
+  const fallback = value.fallback;
+  if (!isLegacySnapshot(transport) || !isLegacySnapshot(fallback)) return null;
+  return {
+    settings: [legacySetting(HERMES_APPROVAL_TRANSPORT_KEY, transport), legacySetting(HERMES_APPROVAL_FALLBACK_KEY, fallback)],
+    pluginWasEnabled: value.pushary_enabled,
+    questionRoutingAdded: !value.clarify_disabled
+  };
+};
+var parseHermesSetupReceipt = (value) => {
+  if (!isRecord(value)) return null;
+  return value.version === HERMES_SETUP_RECEIPT_VERSION ? parseCurrentReceipt(value) : parseLegacyReceipt(value);
+};
+var serializeHermesSetupReceipt = (receipt) => ({ version: HERMES_SETUP_RECEIPT_VERSION, ...receipt });
+var receiptWithoutSnapshots = () => ({
+  settings: [
+    { key: HERMES_APPROVAL_TRANSPORT_KEY, wasSet: false, before: null },
+    { key: HERMES_APPROVAL_FALLBACK_KEY, wasSet: false, before: null }
+  ],
+  pluginWasEnabled: false,
+  questionRoutingAdded: false
+});
+var receiptAfterQuestionRoutingReturned = (receipt) => ({ ...receipt, questionRoutingAdded: false });
+var PUSHARY_VALUES = {
+  [HERMES_APPROVAL_TRANSPORT_KEY]: HERMES_PUSHARY_TRANSPORT,
+  [HERMES_APPROVAL_FALLBACK_KEY]: HERMES_PUSHARY_FALLBACK
+};
+var hermesSettingRestore = (snapshot, current) => {
+  const ours = PUSHARY_VALUES[snapshot.key];
+  const stillOurs = current.kind === "set" && current.value === ours;
+  const oursBeforeSetup = snapshot.wasSet && snapshot.before === ours;
+  return stillOurs && !oursBeforeSetup ? { kind: "restore", key: snapshot.key, snapshot } : { kind: "leave", key: snapshot.key };
+};
+var sameSettingValue = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+// src/hermes/install.ts
+var RECEIPT_MODE = 384;
+var inspectWithLauncher = (launcher) => {
+  const home = readHermesHome(launcher);
+  const settings = home ? readHermesSettings(launcher) : null;
+  if (!home || !settings) return { kind: "unreadable", home };
+  const folder = classifyHermesPluginFolder(readHermesPluginFolderFacts(home));
+  const gateway = readHermesGateway(home);
+  const gatewayLoad = gateway.kind === "running" ? readHermesLoadRecord(home, gateway.pid) : null;
+  const state = hermesWiringState({ folder, settings, gateway, gatewayLoad });
+  return { kind: "inspected", launcher, home, folder, settings, gateway, state };
+};
+var findLauncherWhereHermesLives = () => existsSync2(defaultHermesHome()) ? findHermesLauncher() : null;
+var inspectHermesWiring = (launcher) => {
+  const resolved = launcher === void 0 ? findLauncherWhereHermesLives() : launcher;
+  return resolved ? inspectWithLauncher(resolved) : { kind: "no_launcher" };
+};
+var hermesReceiptPaths = () => ({
+  receiptPath: hermesSetupReceipt(),
+  legacyReceiptPath: hermesConfigReceipt()
+});
+var hermesSetupWasRecorded = (receipts = hermesReceiptPaths()) => existsSync2(receipts.receiptPath) || existsSync2(receipts.legacyReceiptPath);
+var pipSetupFacts = () => ({
+  receipts: hermesReceiptPaths(),
+  macAppWiringRecord: hermesAppWiringRecord(),
+  home: defaultHermesHome()
+});
+var hermesSetupPredatesThePluginFolder = (facts = pipSetupFacts()) => existsSync2(facts.receipts.legacyReceiptPath) && !existsSync2(facts.receipts.receiptPath) && !existsSync2(facts.macAppWiringRecord) && !existsSync2(hermesPluginDirectory(facts.home));
+var readReceiptFile = (path) => {
+  const read = readJsonSafe(path);
+  if (read.kind === "missing") return { kind: "missing" };
+  const receipt = read.kind === "ok" ? parseHermesSetupReceipt(read.value) : null;
+  return receipt ? { kind: "ok", receipt } : { kind: "invalid" };
+};
+var readSetupReceipt = (receipts) => {
+  const current = readReceiptFile(receipts.receiptPath);
+  return current.kind === "missing" ? readReceiptFile(receipts.legacyReceiptPath) : current;
+};
+var writeSetupReceipt = (receipts, receipt) => writeJsonAtomic(receipts.receiptPath, serializeHermesSetupReceipt(receipt), RECEIPT_MODE);
+var removeSetupReceipts = (receipts) => {
+  rmSync2(receipts.receiptPath, { force: true });
+  rmSync2(receipts.legacyReceiptPath, { force: true });
+};
+var snapshotSettings = (launcher) => {
+  const settings = readHermesSettings(launcher);
+  if (!settings) return null;
+  const snapshots = [];
+  for (const key of HERMES_SNAPSHOT_KEYS) {
+    const reading = readHermesSetting(launcher, key);
+    if (!reading) return null;
+    snapshots.push(settingSnapshot(key, reading));
+  }
+  return {
+    settings: snapshots,
+    pluginWasEnabled: settings.pluginEnabled,
+    questionRoutingAdded: false
+  };
+};
+var ensureSetupReceipt = (launcher, receipts) => {
+  const existing = readSetupReceipt(receipts);
+  if (existing.kind === "invalid") return { kind: "failed", reason: "receipt_invalid" };
+  const receipt = existing.kind === "ok" ? existing.receipt : snapshotSettings(launcher);
+  if (!receipt) return { kind: "failed", reason: "settings_unreadable" };
+  if (!existsSync2(receipts.receiptPath)) writeSetupReceipt(receipts, receipt);
+  return { kind: "ok", receipt };
+};
+var settingNeedsWrite = (launcher, key, value) => {
+  const current = readHermesSetting(launcher, key);
+  return !(current?.kind === "set" && current.value === value);
+};
+var applyPusharySettings = (launcher) => {
+  if (!enableHermesPlugin(launcher)) return false;
+  return HERMES_PUSHARY_SETTINGS.every((setting) => !settingNeedsWrite(launcher, setting.key, setting.value) || writeHermesSetting(launcher, setting.key, setting.value));
+};
+var writeListSetting = (launcher, key, list) => {
+  if (list.length > 0) return writeHermesSetting(launcher, key, list);
+  if (!unsetHermesSetting(launcher, key)) return false;
+  const after = readHermesSetting(launcher, key);
+  return after?.kind !== "set" || sameSettingValue(after.value, []) || writeHermesSetting(launcher, key, []);
+};
+var returnQuestionsToHermes = (launcher, receipt) => {
+  const toolsets = readHermesSetting(launcher, HERMES_DISABLED_TOOLSETS_KEY);
+  if (!toolsets) return false;
+  const current = toolsets.kind === "set" && Array.isArray(toolsets.value) ? toolsets.value.filter((item) => typeof item === "string") : [];
+  const next = toolsetsWithoutPusharyQuestionRouting(current, receipt.questionRoutingAdded);
+  return next === null || writeListSetting(launcher, HERMES_DISABLED_TOOLSETS_KEY, next);
+};
+var removeLegacyCopy = (launcher) => {
+  const python = legacyHermesPython(launcher);
+  return python !== null && removeLegacyPipCopy(python, HERMES_LEGACY_PIP_PACKAGE);
+};
+var returnQuestionsIfThePluginRoutesThem = (launcher, home, receipts, receipt) => {
+  const folder = classifyHermesPluginFolder(readHermesPluginFolderFacts(home));
+  if (!receipt.questionRoutingAdded || !routesHermesQuestions(folder)) return true;
+  if (!returnQuestionsToHermes(launcher, receipt)) return false;
+  writeSetupReceipt(receipts, receiptAfterQuestionRoutingReturned(receipt));
+  return true;
+};
+var installHermesPlugin = (request) => {
+  const launcher = request.launcher === void 0 ? findHermesLauncher() : request.launcher;
+  if (!launcher) return { kind: "no_launcher" };
+  const home = readHermesHome(launcher);
+  if (!home) return { kind: "failed", reason: "home_unknown" };
+  const ensured = ensureSetupReceipt(launcher, request.receipts);
+  if (ensured.kind === "failed") return ensured;
+  const folder = classifyHermesPluginFolder(readHermesPluginFolderFacts(home));
+  if (folder.kind === "unknown") return { kind: "failed", reason: "plugin_folder_not_ours" };
+  const folderWritten = bundledPluginReplaces(folder, request.plugin);
+  if (folderWritten) {
+    try {
+      writeHermesPluginFolder(home, request.plugin.files, hermesInstallMarker(request.installedBy, request.plugin));
+    } catch {
+      return { kind: "failed", reason: "plugin_write_failed" };
+    }
+  }
+  if (!applyPusharySettings(launcher)) return { kind: "failed", reason: "settings_failed" };
+  if (!returnQuestionsIfThePluginRoutesThem(launcher, home, request.receipts, ensured.receipt)) {
+    return { kind: "failed", reason: "settings_failed" };
+  }
+  const legacyCopyRemoved = removeLegacyCopy(launcher);
+  return { kind: "installed", folderWritten, legacyCopyRemoved, inspection: inspectWithLauncher(launcher) };
+};
+var refreshHermesPluginFiles = (installedBy, plugin, home = defaultHermesHome()) => {
+  const folder = classifyHermesPluginFolder(readHermesPluginFolderFacts(home));
+  if (folder.kind !== "pushary" || folder.marker.installedBy !== installedBy) return "not_ours";
+  if (!hasUpdateFrom(folder, installedBy, plugin)) return "current";
+  try {
+    writeHermesPluginFolder(home, plugin.files, hermesInstallMarker(installedBy, plugin));
+    return "refreshed";
+  } catch {
+    return "failed";
+  }
+};
+var macAppOwnsHermes = (folder, request) => hermesWiringOwner(folder, existsSync2(request.macAppWiringRecord)) === "mac_app";
+var removePluginEntry = (launcher, settings) => {
+  if (!settings.pluginEnabled || disableHermesPlugin(launcher)) return true;
+  const enabled = readHermesSetting(launcher, HERMES_PLUGINS_ENABLED_KEY);
+  const list = enabled?.kind === "set" && Array.isArray(enabled.value) ? enabled.value : [];
+  return writeListSetting(
+    launcher,
+    HERMES_PLUGINS_ENABLED_KEY,
+    list.filter((item) => typeof item === "string" && item !== HERMES_PLUGIN_KEY)
+  );
+};
+var removePushPlugin = (launcher, home, folder, settings, receipt) => {
+  removeLegacyCopy(launcher);
+  if (folder.kind === "pushary") {
+    if (removeHermesPlugin(launcher)) return true;
+    rmSync2(hermesPluginDirectory(home), { recursive: true, force: true });
+    return removePluginEntry(launcher, settings);
+  }
+  return receipt.pluginWasEnabled || removePluginEntry(launcher, settings);
+};
+var restoreSetting = (launcher, snapshot) => {
+  const current = readHermesSetting(launcher, snapshot.key);
+  if (!current) return false;
+  if (hermesSettingRestore(snapshot, current).kind === "leave") return true;
+  if (!unsetHermesSetting(launcher, snapshot.key)) return false;
+  if (!snapshot.wasSet) return true;
+  const after = readHermesSetting(launcher, snapshot.key);
+  return after?.kind === "set" && sameSettingValue(after.value, snapshot.before) ? true : writeHermesSetting(launcher, snapshot.key, snapshot.before);
+};
+var macAppOwnsTheFolderOnDisk = (request) => macAppOwnsHermes(classifyHermesPluginFolder(readHermesPluginFolderFacts(request.home ?? defaultHermesHome())), request);
+var removeHermesWiring = (request) => {
+  if (request.keepMacAppWiring && macAppOwnsTheFolderOnDisk(request)) return { kind: "kept_for_mac_app" };
+  const receiptRead = readSetupReceipt(request.receipts);
+  const launcher = request.launcher === void 0 ? receiptRead.kind === "missing" ? findLauncherWhereHermesLives() : findHermesLauncher() : request.launcher;
+  if (!launcher) return receiptRead.kind === "missing" ? { kind: "not_found" } : { kind: "runtime_missing" };
+  if (receiptRead.kind === "invalid") return { kind: "failed", step: "receipt_invalid" };
+  const inspection = inspectWithLauncher(launcher);
+  if (inspection.kind !== "inspected") {
+    return receiptRead.kind === "missing" ? { kind: "not_found" } : { kind: "failed", step: "home_unknown" };
+  }
+  const { home, folder, settings, state } = inspection;
+  if (request.keepMacAppWiring && macAppOwnsHermes(folder, request)) return { kind: "kept_for_mac_app" };
+  if (state.kind === "not_wired" && receiptRead.kind === "missing") return { kind: "not_found" };
+  const receipt = receiptRead.kind === "ok" ? receiptRead.receipt : receiptWithoutSnapshots();
+  if (request.dryRun) return { kind: "removed", pluginRemoved: folder.kind === "pushary", settingsRestored: true, dryRun: true };
+  if (!removePushPlugin(launcher, home, folder, settings, receipt)) return { kind: "failed", step: "plugin" };
+  const settingsRestored = receipt.settings.every((snapshot) => restoreSetting(launcher, snapshot)) && returnQuestionsToHermes(launcher, receipt);
+  if (!settingsRestored) return { kind: "failed", step: "settings" };
+  removeSetupReceipts(request.receipts);
+  return { kind: "removed", pluginRemoved: folder.kind === "pushary", settingsRestored, dryRun: false };
+};
+
+export {
+  shippedHermesPlugin,
+  findHermesLauncher,
+  hermesPluginDirectory,
+  HERMES_CONFIG_FILE,
+  defaultHermesHome,
+  hermesWiringOwner,
+  routesHermesApprovals,
+  routesHermesQuestions,
+  runsAnOlderPlugin,
+  isHermesWired,
+  hasUpdateFrom,
+  inspectHermesWiring,
+  hermesReceiptPaths,
+  hermesSetupWasRecorded,
+  hermesSetupPredatesThePluginFolder,
+  installHermesPlugin,
+  refreshHermesPluginFiles,
+  removeHermesWiring
+};