firstops 0.2.0__py3-none-any.whl

firstops/__init__.py

@@ -0,0 +1,58 @@
+"""FirstOps SDK — secure MCP proxy sidecar with DPoP authentication and management API."""
+
+from firstops._runtime import (
+    Runtime,
+    init,
+    llm_base_url,
+    mcp_url,
+    runtime,
+    shutdown,
+)
+from firstops.client import (
+    Agent,
+    Connection,
+    FirstOps,
+    FirstOpsError,
+    ParamDefinition,
+    ServerTemplate,
+)
+from firstops.coverage import capability, coverage_report, ungoverned_tools
+from firstops.enforcement import EnforcementClient
+from firstops.events import ActionEvent, Decision
+from firstops.llm import anthropic_client, configure_llm_env, openai_client
+from firstops.proxy import current_agent_id, is_running
+from firstops.tools import FirstOpsPolicyError, tool
+
+__all__ = [
+    # management client
+    "FirstOps",
+    "FirstOpsError",
+    "Agent",
+    "Connection",
+    "ServerTemplate",
+    "ParamDefinition",
+    # runtime
+    "init",
+    "shutdown",
+    "runtime",
+    "Runtime",
+    "is_running",
+    "current_agent_id",
+    # base API — tool governance
+    "tool",
+    "FirstOpsPolicyError",
+    # base API — LLM chain-link + MCP
+    "llm_base_url",
+    "mcp_url",
+    "openai_client",
+    "anthropic_client",
+    "configure_llm_env",
+    # enforcement surface
+    "EnforcementClient",
+    "ActionEvent",
+    "Decision",
+    # coverage honesty
+    "capability",
+    "coverage_report",
+    "ungoverned_tools",
+]

firstops/_identity.py

@@ -0,0 +1,59 @@
+"""Shared agent identity — the loaded key, DPoP signer, and gateway URL.
+
+Established once per process and shared by the MCP sidecar proxy and the
+enforcement (EvaluateHook) client, so a single agent identity backs every
+signed request the SDK makes. Key material never leaves this object.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from firstops.dpop import create_proof, jwk_thumbprint, load_private_key
+
+
+@dataclass
+class Identity:
+    """An agent's signing identity. Construct via :func:`build_identity`."""
+
+    agent_id: str
+    gateway_url: str  # normalized, no trailing slash
+    _key: ec.EllipticCurvePrivateKey
+
+    @property
+    def bearer_token(self) -> str:
+        return f"fo_agent_{self.agent_id}"
+
+    @property
+    def jkt(self) -> str:
+        """RFC 7638 JWK thumbprint of this identity's key."""
+        return jwk_thumbprint(self._key)
+
+    def proof(self, method: str, url: str) -> str:
+        """Create a DPoP proof (RFC 9449) for an HTTP method + target URL.
+
+        The htu claim is the URL with query and fragment stripped, matching the
+        gateway's **byte-exact** htu binding. We strip via string slicing (not a
+        urlparse round-trip) so we do NOT alter scheme/host casing — any
+        normalization the SDK applies that sentinel does not would 401 every
+        proof, which `evaluate()` silently converts to a fail-open allow.
+        """
+        htu = url.split("#", 1)[0].split("?", 1)[0]
+        return create_proof(self._key, method, htu)
+
+
+def build_identity(agent_id: str, private_key_pem: str, gateway_url: str) -> Identity:
+    """Load the key and validate the gateway URL, returning an Identity.
+
+    Raises:
+        ValueError: if ``gateway_url`` is malformed or the key is not P-256.
+    """
+    gateway = gateway_url.rstrip("/")
+    parsed = urlparse(gateway)
+    if not parsed.scheme or not parsed.netloc:
+        raise ValueError(f"invalid gateway_url: {gateway_url}")
+    key = load_private_key(private_key_pem)
+    return Identity(agent_id=agent_id, gateway_url=gateway, _key=key)

firstops/_runtime.py

@@ -0,0 +1,150 @@
+"""Process-wide FirstOps runtime — the single entrypoint an agent calls.
+
+``firstops.init()`` establishes the agent identity, builds the enforcement
+client (the EvaluateHook spine), and starts the dual-mode sidecar (MCP terminal
++ LLM chain-link). The returned :class:`Runtime` handle is what tool decorators
+and harness adapters use to forward action events; it is also stored
+process-globally so ``firstops.shutdown()`` works without a handle.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+from firstops import proxy
+from firstops._identity import Identity, build_identity
+from firstops.enforcement import EnforcementClient
+
+_DEFAULT_PORT = 9322
+_DEFAULT_GATEWAY = "https://api.firstops.dev"
+
+# Default LLM upstreams. Override per-provider via ``init(llm_upstreams=...)``
+# to point the chain-link at a customer's existing gateway instead.
+_DEFAULT_LLM_UPSTREAMS = {
+    "openai": "https://api.openai.com",
+    "anthropic": "https://api.anthropic.com",
+}
+
+_lock = threading.Lock()
+_runtime: Runtime | None = None
+
+
+@dataclass
+class Runtime:
+    """Handle to the live FirstOps runtime for this process."""
+
+    identity: Identity
+    enforcement: EnforcementClient
+    port: int
+    llm_upstreams: dict[str, str]
+
+
+def init(
+    agent_id: str,
+    private_key_pem: str,
+    *,
+    port: int = _DEFAULT_PORT,
+    gateway_url: str = _DEFAULT_GATEWAY,
+    llm_upstreams: dict[str, str] | None = None,
+) -> Runtime:
+    """Establish identity, the enforcement client, and the dual-mode sidecar.
+
+    Idempotent for the same identity: the sidecar refuses to switch agents
+    mid-flight (raises ``RuntimeError``); re-initializing with the same
+    parameters returns the existing runtime.
+
+    Args:
+        llm_upstreams: per-provider upstream base URLs for the LLM chain-link.
+            Merged over the defaults (openai/anthropic public endpoints). Point
+            a provider at your own gateway to chain in front of it.
+
+    Returns:
+        The process :class:`Runtime` handle.
+    """
+    global _runtime
+
+    gateway = gateway_url.rstrip("/")
+    upstreams = dict(_DEFAULT_LLM_UPSTREAMS)
+    if llm_upstreams:
+        upstreams.update(llm_upstreams)
+
+    with _lock:
+        if _runtime is not None:
+            # Idempotent re-confirm — proxy.init owns the mismatch guard.
+            proxy.init(
+                agent_id=agent_id,
+                private_key_pem=private_key_pem,
+                port=port,
+                gateway_url=gateway,
+                enforcement=_runtime.enforcement,
+                llm_upstreams=_runtime.llm_upstreams,
+            )
+            return _runtime
+
+        identity = build_identity(agent_id, private_key_pem, gateway)
+        enforcement = EnforcementClient(identity)
+        proxy.init(
+            agent_id=agent_id,
+            private_key_pem=private_key_pem,
+            port=port,
+            gateway_url=gateway,
+            enforcement=enforcement,
+            llm_upstreams=upstreams,
+        )
+        _runtime = Runtime(
+            identity=identity,
+            enforcement=enforcement,
+            port=port,
+            llm_upstreams=upstreams,
+        )
+        return _runtime
+
+
+def shutdown() -> None:
+    """Stop the sidecar and tear down the runtime. Idempotent.
+
+    Lifecycle: call at process/agent teardown, **not** concurrently with
+    in-flight governed calls. ``EnforcementClient.evaluate`` is fully
+    fail-open, so a racing ``evaluate()`` during shutdown degrades to an
+    allow (never a crash or hang) — but the supported pattern is init-once,
+    run, shutdown-once.
+    """
+    global _runtime
+    proxy.shutdown()
+    with _lock:
+        if _runtime is not None:
+            _runtime.enforcement.close()
+            _runtime = None
+
+
+def runtime() -> Runtime | None:
+    """Return the live runtime, or None if init() has not been called."""
+    with _lock:
+        return _runtime
+
+
+def llm_base_url(provider: str = "openai") -> str:
+    """Return the local sidecar base URL to point an LLM client at.
+
+    Point your client's ``base_url`` (or ``OPENAI_BASE_URL`` /
+    ``ANTHROPIC_BASE_URL``) here; the sidecar governs the request and forwards
+    to the configured upstream.
+    """
+    rt = runtime()
+    if rt is None:
+        raise RuntimeError("firstops.init() must be called before llm_base_url()")
+    base = f"http://127.0.0.1:{rt.port}/llm/{provider}"
+    return base + "/v1" if provider == "openai" else base
+
+
+def mcp_url(connection_id: str) -> str:
+    """Return the local sidecar URL to point an MCP client at for a connection.
+
+    The sidecar DPoP-signs each request and forwards it to the FirstOps gateway,
+    which brokers the upstream credentials — the agent never holds them.
+    """
+    rt = runtime()
+    if rt is None:
+        raise RuntimeError("firstops.init() must be called before mcp_url()")
+    return f"http://127.0.0.1:{rt.port}/mcp/proxy/{connection_id}"

firstops/channels.py

@@ -0,0 +1,38 @@
+"""Channel classification for tool calls.
+
+Mirrors the daemon's tool_name → channel mapping so sentinel sees SDK tool
+calls the same way it sees coding-agent hook events. MCP tools (named
+``mcp__<server>__<tool>``) classify as the MCP channel; everything else a
+decorated tool does is ``system_tools``. LLM traffic is stamped ``llm``
+directly by the sidecar's LLM route, not by this classifier.
+"""
+
+from __future__ import annotations
+
+from firstops.events import CHANNEL_MCP, CHANNEL_SYSTEM_TOOLS, MCPInfo
+
+_MCP_PREFIX = "mcp__"
+
+
+def classify(tool_name: str) -> str:
+    """Return the channel a tool call belongs to.
+
+    A name is MCP only if it's a *well-formed* ``mcp__<server>__<tool>`` (so
+    classify and :func:`mcp_info` always agree — we never emit a ``channel=mcp``
+    event with no mcp metadata). A malformed ``mcp__`` name (e.g. ``mcp__foo``)
+    is treated as ``system_tools``.
+    """
+    if mcp_info(tool_name) is not None:
+        return CHANNEL_MCP
+    return CHANNEL_SYSTEM_TOOLS
+
+
+def mcp_info(tool_name: str) -> MCPInfo | None:
+    """Parse ``mcp__<server>__<tool>`` into MCPInfo, or None if not a well-formed MCP name."""
+    if not tool_name.startswith(_MCP_PREFIX):
+        return None
+    parts = tool_name.split("__")
+    # Require non-empty server and tool segments.
+    if len(parts) >= 3 and parts[1] and "__".join(parts[2:]):
+        return MCPInfo(server=parts[1], tool="__".join(parts[2:]))
+    return None