muad-skill-http 0.1.0__py3-none-any.whl

muad_skill_http/__init__.py

@@ -0,0 +1,47 @@
+"""muad_skill_http: trace-aware requests helper and platform request client.
+
+Usage in skills::
+
+    import muad_skill_http
+
+    response = muad_skill_http.get("http://service/api")
+    response = muad_skill_http.platform_request("mssw", "GET", "/api/v1/targets")
+
+Without importing this module, existing skills keep their original behavior:
+``requests`` is never patched and no trace spool is written.
+"""
+
+from __future__ import annotations
+
+from . import _platform, _trace
+from ._http import delete, get, head, options, patch, post, put, request, session
+from ._platform import PlatformClient, PlatformSessionError, platform, platform_request
+from ._trace import EXIT_REQUEST_LIMIT
+
+__all__ = [
+    "EXIT_REQUEST_LIMIT",
+    "PlatformClient",
+    "PlatformSessionError",
+    "delete",
+    "get",
+    "head",
+    "options",
+    "patch",
+    "platform",
+    "platform_request",
+    "post",
+    "put",
+    "request",
+    "session",
+]
+
+
+def _reset_for_tests():
+    """Drop the process-wide recorder and session cache (tests only)."""
+    _trace.reset()
+    _platform.reset_cache()
+
+
+def _flush_summary():
+    """Write the trace summary early (tests and one-shot scripts)."""
+    _trace.flush_summary()

muad_skill_http/_http.py

@@ -0,0 +1,109 @@
+"""Thin requests pass-through that records every helper request."""
+
+from __future__ import annotations
+
+import time
+
+import requests
+
+from . import _trace
+from ._normalize import split_target
+
+
+def _duration_ms(started):
+    return int((time.monotonic() - started) * 1000)
+
+
+def _send(call, method, url, **kwargs):
+    method = str(method).upper()
+    extra = kwargs.pop("_trace_extra", None)
+    recorder = _trace.get_recorder()
+    host, path = split_target(url)
+    recorder.admit(host, method, path)
+    started = time.monotonic()
+    try:
+        response = call(method, url, **kwargs)
+    except requests.RequestException as exc:
+        recorder.complete(host, method, path, None, _duration_ms(started), type(exc).__name__, extra)
+        raise
+    status = response.status_code
+    error_class = "http_%d" % status if status >= 400 else ""
+    recorder.complete(host, method, path, status, _duration_ms(started), error_class, extra)
+    return response
+
+
+def request(method, url, **kwargs):
+    """requests.request with trace + per-interface limit accounting."""
+    return _send(requests.request, method, url, **kwargs)
+
+
+def get(url, **kwargs):
+    return request("GET", url, **kwargs)
+
+
+def head(url, **kwargs):
+    return request("HEAD", url, **kwargs)
+
+
+def options(url, **kwargs):
+    return request("OPTIONS", url, **kwargs)
+
+
+def post(url, **kwargs):
+    return request("POST", url, **kwargs)
+
+
+def put(url, **kwargs):
+    return request("PUT", url, **kwargs)
+
+
+def patch(url, **kwargs):
+    return request("PATCH", url, **kwargs)
+
+
+def delete(url, **kwargs):
+    return request("DELETE", url, **kwargs)
+
+
+class _TrackedSession:
+    def __init__(self):
+        self._session = requests.Session()
+
+    def request(self, method, url, **kwargs):
+        return _send(self._session.request, method, url, **kwargs)
+
+    def get(self, url, **kwargs):
+        return self.request("GET", url, **kwargs)
+
+    def head(self, url, **kwargs):
+        return self.request("HEAD", url, **kwargs)
+
+    def options(self, url, **kwargs):
+        return self.request("OPTIONS", url, **kwargs)
+
+    def post(self, url, **kwargs):
+        return self.request("POST", url, **kwargs)
+
+    def put(self, url, **kwargs):
+        return self.request("PUT", url, **kwargs)
+
+    def patch(self, url, **kwargs):
+        return self.request("PATCH", url, **kwargs)
+
+    def delete(self, url, **kwargs):
+        return self.request("DELETE", url, **kwargs)
+
+    def close(self):
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False
+
+
+def session():
+    """A requests.Session wrapper (supports ``with``) that traces each call."""
+    return _TrackedSession()

muad_skill_http/_normalize.py

@@ -0,0 +1,49 @@
+"""Path and target normalization for interface counting."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlsplit
+
+_UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+_HEX_RE = re.compile(r"^[0-9a-fA-F]{8,}$")
+_DIGITS_RE = re.compile(r"^\d+$")
+
+
+def normalize_path(path):
+    """Collapse volatile path segments and drop query/fragment.
+
+    Numeric, UUID and long hex segments become ``{id}`` so one business
+    interface is counted once regardless of object ids.
+    """
+    if not isinstance(path, str):
+        path = str(path or "")
+    if path.startswith(("http://", "https://")):
+        raw = urlsplit(path).path or "/"
+    else:
+        raw = path.split("?", 1)[0].split("#", 1)[0]
+    if not raw:
+        return "/"
+    segments = ["{id}" if _is_volatile(segment) else segment for segment in raw.split("/")]
+    return "/".join(segments) or "/"
+
+
+def split_target(url):
+    """Return (host:port, normalized path) for a request URL."""
+    parts = urlsplit(str(url))
+    host = (parts.hostname or "").lower()
+    try:
+        port = parts.port
+    except ValueError:
+        port = None
+    if port:
+        host = "%s:%d" % (host, port)
+    return host, normalize_path(parts.path or "/")
+
+
+def _is_volatile(segment):
+    if not segment:
+        return False
+    return bool(_DIGITS_RE.match(segment) or _UUID_RE.match(segment) or _HEX_RE.match(segment))

muad_skill_http/_platform.py

@@ -0,0 +1,404 @@
+"""Platform request client: session state, headers, refresh and retry.
+
+Header order follows the backend design:
+browser defaults -> hostHeader -> staticHeaders -> caller/extra headers ->
+Cookie -> CSRF -> Traceid -> re-assert mandatory headers. Header values never
+reach the trace spool or diagnostics.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import threading
+import uuid
+from datetime import datetime, timezone
+
+import requests
+
+from . import _http
+from ._normalize import normalize_path
+
+__all__ = [
+    "PlatformSessionError",
+    "normalize_path",
+    "build_platform_headers",
+    "platform_request",
+    "platform",
+]
+
+SESSION_MANAGER_BIN = "session-manager"
+GET_STATE_TIMEOUT_SECONDS = 30
+DEFAULT_TRACE_HEADER = "Traceid"
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD"})
+USER_AGENT = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+)
+
+_platform_session = requests.Session()
+_cache = {}
+_cache_lock = threading.Lock()
+_load_lock = threading.Lock()
+
+
+class PlatformSessionError(RuntimeError):
+    """Platform credentials/state unavailable; skills should fail loud."""
+
+
+# --------------------------------------------------------------------------- #
+# public API
+# --------------------------------------------------------------------------- #
+
+def platform_request(platform, method, path, **kwargs):
+    """Send a business request with platform headers and trace accounting."""
+    method = str(method).upper()
+    for attempt in (0, 1):
+        call_kwargs = dict(kwargs)
+        extra_headers = call_kwargs.pop("extra_headers", None)
+        caller_headers = call_kwargs.pop("headers", None)
+        context = _get_context(platform)
+        url = _resolve_url(platform, context["profile"], path)
+        headers, trace_id = build_platform_headers(
+            context["profile"], context["cookies"], caller_headers, extra_headers, call_kwargs
+        )
+        call_kwargs["headers"] = headers
+        extra = {"platform": platform}
+        if trace_id:
+            extra["traceId"] = trace_id
+        response = _http._send(
+            _platform_session.request, method, url, _trace_extra=extra, **call_kwargs
+        )
+        if attempt == 0 and method in IDEMPOTENT_METHODS and response.status_code in (401, 403):
+            _invalidate(platform)
+            continue
+        return response
+
+
+def platform(name):
+    """Return a reusable client bound to one platform profile."""
+    return PlatformClient(name)
+
+
+class PlatformClient:
+    def __init__(self, name):
+        self.platform = name
+
+    def request(self, method, path, **kwargs):
+        return platform_request(self.platform, method, path, **kwargs)
+
+    def get(self, path, **kwargs):
+        return self.request("GET", path, **kwargs)
+
+    def head(self, path, **kwargs):
+        return self.request("HEAD", path, **kwargs)
+
+    def post(self, path, **kwargs):
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path, **kwargs):
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path, **kwargs):
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path, **kwargs):
+        return self.request("DELETE", path, **kwargs)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# headers
+# --------------------------------------------------------------------------- #
+
+def build_platform_headers(profile, cookies, caller_headers=None, extra_headers=None, request_kwargs=None):
+    """Build the header dict in the design's mandated order.
+
+    Returns ``(headers, trace_id)``; ``trace_id`` is ``None`` when the profile
+    disables the trace header.
+    """
+    headers = {}
+    _set_header(headers, "Accept", "application/json, text/plain, */*")
+    _set_header(headers, "Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
+    content_type = _content_type(request_kwargs or {})
+    if content_type:
+        _set_header(headers, "Content-Type", content_type)
+    _set_header(headers, "User-Agent", USER_AGENT)
+    _set_header(headers, "X-Requested-With", "XMLHttpRequest")
+    if profile.get("referer"):
+        _set_header(headers, "Referer", profile["referer"])
+
+    for name, value in profile.get("hostHeader", {}).items():
+        _set_header(headers, name, value)
+    for name, value in profile.get("staticHeaders", {}).items():
+        _set_header(headers, name, value)
+
+    if profile.get("extraAllowed", True):
+        for name, value in _header_items(caller_headers):
+            _set_header(headers, name, value)
+        for name, value in _header_items(extra_headers):
+            _set_header(headers, name, value)
+
+    cookie_values = _cookie_values(cookies)
+    cookie_header = "; ".join("%s=%s" % (name, value) for name, value in cookie_values.items())
+    if cookie_header:
+        _set_header(headers, "Cookie", cookie_header)
+
+    csrf_headers = []
+    for mapping in profile.get("csrf", []):
+        value = cookie_values.get(mapping["cookie"])
+        if value:
+            _set_header(headers, mapping["header"], value)
+            csrf_headers.append((mapping["header"], value))
+
+    trace_header = profile.get("traceHeader")
+    trace_id = None
+    if trace_header:
+        trace_id = str(uuid.uuid4())
+        _set_header(headers, trace_header, trace_id)
+
+    # Mandatory headers are written last so caller/extra headers cannot win.
+    if cookie_header:
+        _set_header(headers, "Cookie", cookie_header)
+    for name, value in csrf_headers:
+        _set_header(headers, name, value)
+    if trace_header and trace_id:
+        _set_header(headers, trace_header, trace_id)
+    return headers, trace_id
+
+
+def _set_header(headers, name, value):
+    for existing in [key for key in headers if key.lower() == name.lower()]:
+        del headers[existing]
+    headers[name] = str(value)
+
+
+def _header_items(raw):
+    if not isinstance(raw, dict):
+        return []
+    items = []
+    for name, value in raw.items():
+        if isinstance(name, str) and name.strip() and value is not None:
+            items.append((name.strip(), value))
+    return items
+
+
+def _content_type(kwargs):
+    if kwargs.get("json") is not None:
+        return "application/json;charset=UTF-8"
+    if kwargs.get("data") is not None:
+        return "application/x-www-form-urlencoded;charset=UTF-8"
+    return ""
+
+
+def _cookie_values(cookies):
+    result = {}
+    if not isinstance(cookies, list):
+        return result
+    for item in cookies:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name")
+        value = item.get("value")
+        if isinstance(name, str) and name and isinstance(value, str):
+            result[name] = value
+    return result
+
+
+# --------------------------------------------------------------------------- #
+# session state
+# --------------------------------------------------------------------------- #
+
+def _get_context(name):
+    with _cache_lock:
+        context = _cache.get(name)
+    if context is not None and not _expired(context["expires_at"]):
+        return context
+    with _load_lock:
+        with _cache_lock:
+            context = _cache.get(name)
+            if context is not None and not _expired(context["expires_at"]):
+                return context
+        context = _load_state(name)
+        with _cache_lock:
+            _cache[name] = context
+        return context
+
+
+def _invalidate(name):
+    with _cache_lock:
+        _cache.pop(name, None)
+
+
+def reset_cache():
+    with _cache_lock:
+        _cache.clear()
+    with _diagnosed_lock:
+        _diagnosed.clear()
+
+
+def _load_state(name):
+    skill_name = (os.environ.get("MUAD_SKILL_NAME") or "").strip()
+    if not skill_name:
+        raise PlatformSessionError(
+            "platform session unavailable for %s: MUAD_SKILL_NAME is not set" % name
+        )
+    try:
+        completed = subprocess.run(
+            [SESSION_MANAGER_BIN, "get-state", "--skill-name", skill_name],
+            capture_output=True,
+            text=True,
+            timeout=GET_STATE_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise PlatformSessionError(
+            "platform session unavailable for %s: session-manager could not run" % name
+        ) from exc
+    if completed.returncode != 0:
+        detail = _first_line(completed.stderr)
+        message = "platform session unavailable for %s: session-manager get-state exited %d" % (
+            name,
+            completed.returncode,
+        )
+        if detail:
+            message += " (%s)" % detail
+        raise PlatformSessionError(message)
+
+    try:
+        payload = json.loads(completed.stdout)
+        state_file = payload["sessionStateFile"]
+        with open(state_file, "r", encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (ValueError, KeyError, TypeError, OSError) as exc:
+        raise PlatformSessionError(
+            "platform session unavailable for %s: session state file is unreadable" % name
+        ) from exc
+
+    section = (state.get("platforms") or {}).get(name)
+    if not isinstance(section, dict):
+        raise PlatformSessionError(
+            "platform session unavailable for %s: no credentials in session state" % name
+        )
+    expires_at = _parse_expiry(section.get("expiresAt"))
+    if _expired(expires_at):
+        raise PlatformSessionError(
+            "platform session unavailable for %s: session state expired after refresh" % name
+        )
+    return {
+        "platform": name,
+        "profile": _profile(section, name),
+        "cookies": section.get("cookies") or [],
+        "expires_at": expires_at,
+    }
+
+
+def _profile(section, name):
+    raw = section.get("requestProfile")
+    if not isinstance(raw, dict):
+        _diagnostic(name, "request profile fallback missing=requestProfile")
+        raw = {}
+    return {
+        "baseUrl": _string(raw.get("baseUrl")),
+        "hostHeader": _string_map(raw.get("hostHeader")),
+        "referer": _string(raw.get("referer")),
+        "csrf": _csrf_mappings(raw.get("csrf")),
+        "staticHeaders": _string_map(raw.get("staticHeaders")),
+        "traceHeader": _trace_header(raw),
+        "extraAllowed": raw.get("extraAllowed") is not False,
+    }
+
+
+def _trace_header(raw):
+    if "traceHeader" not in raw:
+        return DEFAULT_TRACE_HEADER
+    value = raw.get("traceHeader")
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def _csrf_mappings(raw):
+    mappings = []
+    if not isinstance(raw, list):
+        return mappings
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        cookie_name = _string(item.get("cookie"))
+        header_name = _string(item.get("header"))
+        if cookie_name and header_name:
+            mappings.append({"cookie": cookie_name, "header": header_name})
+    return mappings
+
+
+def _string(value):
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _string_map(raw):
+    result = {}
+    if not isinstance(raw, dict):
+        return result
+    for name, value in raw.items():
+        if isinstance(name, str) and name.strip() and isinstance(value, str) and value.strip():
+            result[name.strip()] = value.strip()
+    return result
+
+
+def _resolve_url(name, profile, path):
+    path = str(path)
+    if path.startswith(("http://", "https://")):
+        return path
+    base_url = profile.get("baseUrl") or ""
+    if not base_url:
+        raise PlatformSessionError(
+            "platform request unavailable for %s: request profile has no baseUrl "
+            "and path is not absolute" % name
+        )
+    return base_url.rstrip("/") + "/" + path.lstrip("/")
+
+
+def _parse_expiry(value):
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _expired(expires_at):
+    if expires_at is None:
+        return False
+    return expires_at <= datetime.now(timezone.utc)
+
+
+def _first_line(text):
+    if not isinstance(text, str):
+        return ""
+    for line in text.splitlines():
+        line = line.strip()
+        if line:
+            return line[:200]
+    return ""
+
+
+_diagnosed = set()
+_diagnosed_lock = threading.Lock()
+
+
+def _diagnostic(name, message):
+    key = (name, message)
+    with _diagnosed_lock:
+        if key in _diagnosed:
+            return
+        _diagnosed.add(key)
+    try:
+        sys.stderr.write("[muad-skill-sdk][platform] platform=%s %s\n" % (name, message))
+    except Exception:
+        return

muad_skill_http/_trace.py

@@ -0,0 +1,216 @@
+"""Per-execution trace spool and interface request limit.
+
+The recorder is process-wide. Counting and limit enforcement stay in memory
+under a lock; the spool file is the only observable side effect and every
+I/O failure is swallowed so auditing never breaks a skill request.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import threading
+import time
+from collections import deque
+from datetime import datetime, timezone
+
+EXIT_REQUEST_LIMIT = 86
+DETAIL_LIMIT = 500
+BURST_WINDOW_SECONDS = 10.0
+TOP_INTERFACE_LIMIT = 10
+
+
+def _terminate(code):
+    os._exit(code)
+
+
+def _now_iso():
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _parse_limit():
+    raw = os.environ.get("MUAD_SKILL_REQUEST_LIMIT", "")
+    try:
+        value = int(str(raw).strip())
+    except (TypeError, ValueError):
+        return 0
+    return value if value > 0 else 0
+
+
+class TraceRecorder:
+    def __init__(self, spool_path, execution_id, limit):
+        self._spool_path = spool_path
+        self._enabled = bool(spool_path) and bool(execution_id)
+        self._limit = limit
+        self._lock = threading.Lock()
+        self._file = None
+        self._file_failed = False
+        self._counts = {}
+        self._hosts = {}
+        self._burst = deque()
+        self._max_burst = 0
+        self._total = 0
+        self._errors = 0
+        self._details = 0
+        self._truncated = False
+        self._aborted = False
+        self._summary_written = False
+
+    # -- request lifecycle ------------------------------------------------- #
+
+    def admit(self, host, method, path):
+        """Count one attempt and terminate before sending the N+1 request."""
+        terminate_now = False
+        already_aborted = False
+        with self._lock:
+            if self._aborted:
+                already_aborted = True
+            else:
+                self._total += 1
+                key = (host, method, path)
+                count = self._counts.get(key, 0) + 1
+                self._counts[key] = count
+                self._hosts[host] = self._hosts.get(host, 0) + 1
+                self._track_burst_locked()
+                if self._limit and count > self._limit:
+                    self._aborted = True
+                    self._write_abort_locked(host, method, path, count)
+                    self._write_summary_locked()
+                    terminate_now = True
+        if terminate_now or already_aborted:
+            _terminate(EXIT_REQUEST_LIMIT)
+
+    def complete(self, host, method, path, status, duration_ms, error_class, extra=None):
+        """Record the response (or transport failure) if the detail cap allows."""
+        event = {
+            "v": 1,
+            "ts": _now_iso(),
+            "kind": "http",
+            "host": host,
+            "method": method,
+            "path": path,
+            "status": status,
+            "durationMs": duration_ms,
+            "errorClass": error_class or "",
+        }
+        if extra:
+            event.update(extra)
+        with self._lock:
+            if status is None or status >= 400:
+                self._errors += 1
+            if self._details < DETAIL_LIMIT:
+                if self._write_locked(event):
+                    self._details += 1
+            else:
+                self._truncated = True
+
+    # -- spool ------------------------------------------------------------- #
+
+    def flush_summary(self):
+        with self._lock:
+            self._write_summary_locked()
+
+    def _track_burst_locked(self):
+        now = time.monotonic()
+        self._burst.append(now)
+        while self._burst and now - self._burst[0] > BURST_WINDOW_SECONDS:
+            self._burst.popleft()
+        if len(self._burst) > self._max_burst:
+            self._max_burst = len(self._burst)
+
+    def _write_abort_locked(self, host, method, path, count):
+        self._write_locked(
+            {
+                "v": 1,
+                "ts": _now_iso(),
+                "kind": "abort",
+                "reason": "request_limit",
+                "interface": "%s %s %s" % (method, host, path),
+                "count": count,
+                "limit": self._limit,
+            }
+        )
+
+    def _write_summary_locked(self):
+        if self._summary_written:
+            return
+        self._summary_written = True
+        top = sorted(
+            (
+                {"host": host, "method": method, "path": path, "count": count}
+                for (host, method, path), count in self._counts.items()
+            ),
+            key=lambda item: (-item["count"], item["host"], item["method"], item["path"]),
+        )[:TOP_INTERFACE_LIMIT]
+        self._write_locked(
+            {
+                "v": 1,
+                "ts": _now_iso(),
+                "kind": "summary",
+                "totalRequests": self._total,
+                "errorCount": self._errors,
+                "hosts": dict(self._hosts),
+                "topInterfaces": top,
+                "maxBurst10s": self._max_burst,
+                "truncated": self._truncated,
+                "aborted": self._aborted,
+            }
+        )
+        self._flush_locked()
+
+    def _write_locked(self, event):
+        if not self._enabled or self._file_failed:
+            return False
+        try:
+            if self._file is None:
+                fd = os.open(
+                    self._spool_path,
+                    os.O_WRONLY | os.O_CREAT | os.O_APPEND,
+                    0o600,
+                )
+                self._file = os.fdopen(fd, "a", encoding="utf-8")
+            self._file.write(json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n")
+            return True
+        except (OSError, ValueError):
+            self._disable_locked()
+            return False
+
+    def _flush_locked(self):
+        try:
+            if self._file is not None:
+                self._file.flush()
+                os.fsync(self._file.fileno())
+        except (OSError, ValueError):
+            self._disable_locked()
+
+    def _disable_locked(self):
+        self._file_failed = True
+        self._file = None
+
+
+_recorder = None
+_recorder_lock = threading.Lock()
+
+
+def get_recorder():
+    global _recorder
+    with _recorder_lock:
+        if _recorder is None:
+            _recorder = TraceRecorder(
+                os.environ.get("MUAD_TRACE_SPOOL", ""),
+                os.environ.get("MUAD_EXECUTION_ID", ""),
+                _parse_limit(),
+            )
+            atexit.register(_recorder.flush_summary)
+        return _recorder
+
+
+def flush_summary():
+    get_recorder().flush_summary()
+
+
+def reset():
+    global _recorder
+    with _recorder_lock:
+        _recorder = None

muad_skill_http-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: muad-skill-http
+Version: 0.1.0
+Summary: Trace-aware HTTP helpers and platform request client for muad skills
+Author: muad-openclaw maintainers
+Project-URL: Homepage, https://github.com/Michaelxwb/muad-openclaw
+Project-URL: Source, https://github.com/Michaelxwb/muad-openclaw/tree/main/tools/muad-skill-sdk
+Keywords: http,requests,tracing,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests<3,>=2.31
+
+# muad-skill-http
+
+Trace-aware HTTP helpers and a platform request client for muad skills.
+
+`platform_request()` sends business-platform requests through a platform session
+managed by `session-manager`. It assembles the browser defaults, platform host
+header, platform static headers, cookies, CSRF header and a fresh `Traceid`
+UUID v4 for every request, and re-asserts the mandatory headers last so caller
+headers cannot override them. Cookie and CSRF values never reach the trace
+spool.
+
+## Install
+
+```bash
+pip install muad-skill-http
+```
+
+## Usage
+
+```python
+from muad_skill_http import get, platform_request
+
+# Plain HTTP with trace accounting.
+response = get("https://example.com/api/v1/items")
+
+# Business-platform request: headers and Traceid are built by the SDK.
+response = platform_request("demo", "GET", "/api/v1/targets")
+```
+
+`get` / `post` / `put` / `patch` / `delete` / `head` / `options` / `request`
+wrap `requests` and record request counts for the current skill execution.
+
+### Runtime requirements for `platform_request`
+
+`platform_request` resolves the platform session from the skill runtime, not
+from the local machine. It needs:
+
+- `MUAD_SKILL_NAME` set to the running skill name;
+- a `session-manager` executable on `PATH` that answers
+  `session-manager get-state --skill-name <name>` with
+  `{"sessionStateFile": "..."}`;
+- a session state file containing the requested platform's credentials.
+
+Outside that environment it raises `muad_skill_http.PlatformSessionError`.
+Plain `get` / `post` calls work anywhere.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `MUAD_SKILL_NAME` | Skill name used to resolve the platform session. |
+| `MUAD_TRACE_SPOOL` | Optional JSONL trace spool path; paired with `MUAD_EXECUTION_ID`. |
+| `MUAD_EXECUTION_ID` | Execution id written to the trace spool. |
+| `MUAD_SKILL_REQUEST_LIMIT` | Per-execution interface request limit; unset or `0` means unlimited. Exceeding the limit exits with code `86`. |
+
+I/O failures while writing the trace spool are swallowed: auditing never breaks
+a skill request.
+
+## Development
+
+```bash
+python -m pytest test
+```
+
+Releases are published by pushing an `sdk-v*` tag; the tag must match
+`project.version` in `pyproject.toml`.

muad_skill_http-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+muad_skill_http/__init__.py,sha256=waAP4oLLoetZdR8h8HoMwijeMG2bvWk0aeIS6MYdFek,1201
+muad_skill_http/_http.py,sha256=qvWXMql8ikjQAhSJMIe3LYG5CcRP3cupvkKIATSnvmE,2754
+muad_skill_http/_normalize.py,sha256=zXDahA3n-_e-Pv0C5HePupXSRB-akBSJ0QQNyhzxecI,1449
+muad_skill_http/_platform.py,sha256=tkSTzeyeOnzXRmorq1-0pmGE35g1nhpSJCmQNO-o1d4,12745
+muad_skill_http/_trace.py,sha256=YsnqDjkhz74ILpgHVrPrZ2cxe-XdwS3o2wx-9pcT7WQ,6676
+muad_skill_http-0.1.0.dist-info/METADATA,sha256=lhAJw9oCP8Wes19qexTDenX7J_GNY0a5x0rQ73JHiQU,3222
+muad_skill_http-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+muad_skill_http-0.1.0.dist-info/top_level.txt,sha256=_qe_kcb4GVh2LH_Us3dCDITuwB7uk7kyqi7ZRakmXvQ,16
+muad_skill_http-0.1.0.dist-info/RECORD,,

muad_skill_http-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

muad_skill_http-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+muad_skill_http