contextos-client 0.1.0a13__py3-none-any.whl

contextos/__init__.py

@@ -0,0 +1,76 @@
+"""ContextOS kernel for Python, in-process.
+
+The kernel is pure and deterministic: no I/O, no clock, no randomness. Verdicts
+(deny, rejected, insufficient evidence) are returned as results; ``ContextOSError``
+is raised only for unusable input.
+
+    import contextos
+    compiled = contextos.compile(pack=pack, request=request, run_context=run_context)
+    decision = contextos.evaluate_authorization(authorization_input)
+"""
+
+import json
+from typing import Any, Optional
+
+try:
+    from . import _native
+except ImportError:  # the HTTP client (contextos.client) works without the extension
+    _native = None
+
+__version__ = getattr(_native, "__version__", "0.1.0-alpha.13")
+
+
+class ContextOSError(Exception):
+    """Raised when the kernel cannot evaluate the input."""
+
+    def __init__(self, code: str, message: str, detail: Any = None):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.detail = detail
+
+
+def call(operation: str, payload: Any) -> Any:
+    """Runs one kernel operation; see the embed facade for the operation list."""
+    if _native is None:
+        raise ContextOSError("native_unavailable", "the in-process kernel is not built: run `pip install ./bindings/python` (needs maturin and Rust); contextos.client works without it")
+    response = json.loads(_native.call(operation, json.dumps(payload, allow_nan=False)))
+    if "error" in response:
+        error = response["error"]
+        raise ContextOSError(error.get("code", "error"), error.get("message", ""), error.get("detail"))
+    return response["ok"]
+
+
+def compile(pack: dict, request: dict, run_context: dict, deps: Optional[dict] = None) -> dict:
+    """Compiles a Context Pack into a CompiledContext."""
+    return call("compile", {"pack": pack, "request": request, "run_context": run_context, "deps": deps or {}})
+
+
+def evaluate_authorization(authorization_input: dict) -> dict:
+    """Conjunctive authorization of one action binding."""
+    return call("evaluate_authorization", authorization_input)
+
+
+def digest_action_binding(binding: dict) -> str:
+    """RFC 8785 digest of an ActionBinding."""
+    return call("digest_action_binding", binding)["action_digest"]
+
+
+def negotiate(contract: dict, support: dict, features: dict) -> dict:
+    """Negotiates an execution contract against the standard profile registry."""
+    return call("negotiate", {"contract": contract, "support": support, "features": features})
+
+
+def validate(schema: str, instance: Any, definition: Optional[str] = None) -> dict:
+    """Validates a payload against a published ContextOS schema."""
+    return call("validate", {"schema": schema, "def": definition, "instance": instance})
+
+
+def canonicalize(value: Any) -> dict:
+    """RFC 8785 canonical JSON and its sha256 digest."""
+    return call("canonicalize", value)
+
+
+__all__ = [
+    "ContextOSError", "call", "compile", "evaluate_authorization", "digest_action_binding",
+    "negotiate", "validate", "canonicalize", "__version__",
+]

contextos/aio.py

@@ -0,0 +1,119 @@
+"""The ``contextosd`` client for asyncio agents (ADK, the OpenAI Agents SDK, LlamaIndex,
+Microsoft Agent Framework, Pydantic AI and other async frameworks).
+
+``AsyncClient`` and ``AsyncRun`` have the methods of ``Client`` and ``Run`` as
+coroutines. The client stays standard-library only: each request runs the synchronous
+client in a worker thread (``asyncio.to_thread``), so the event loop never blocks on
+the network while urllib keeps handling TLS, proxies and retries. Outcomes raise the
+same exceptions (``ToolPaused``, ``BudgetExhausted``, ...)::
+
+    from contextos.aio import AsyncClient
+    from contextos.client import governed_tool
+
+    client = AsyncClient("https://contextos.internal", token=os.environ["CONTEXTOS_TOKEN"])
+    run = await client.admit(admission_body)
+
+    @governed_tool(run, "adp_orders.lookup")     # an async tool, since run is an AsyncRun
+    async def lookup_order(order_id: str) -> dict: ...
+
+    async with run.budgeted_model_call(tokens=2000):
+        response = await model.generate(...)
+
+Concurrent calls share the default thread pool; pass ``executor`` to bound them
+separately.
+"""
+import asyncio
+import contextlib
+import functools
+from concurrent.futures import Executor
+from typing import Any, AsyncIterator, List, Optional
+
+from .client import Client, Run
+
+__all__ = ["AsyncClient", "AsyncRun"]
+
+
+class _Async:
+    """Exposes a synchronous object's methods as coroutines run in a worker thread;
+    plain attributes read through. A returned ``Run`` comes back as an ``AsyncRun``."""
+
+    def __init__(self, target: Any, executor: Optional[Executor]):
+        self._target = target
+        self._executor = executor
+
+    async def _call(self, function, *args: Any, **kwargs: Any) -> Any:
+        args = tuple(a._target if isinstance(a, AsyncRun) else a for a in args)
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(self._executor, functools.partial(function, *args, **kwargs))
+        if isinstance(result, Run):
+            return self if result is self._target else AsyncRun(result, self._executor)
+        return result
+
+    def __getattr__(self, name: str) -> Any:
+        attribute = getattr(self._target, name)
+        if not callable(attribute):
+            return attribute
+
+        @functools.wraps(attribute)
+        async def method(*args: Any, **kwargs: Any) -> Any:
+            return await self._call(attribute, *args, **kwargs)
+
+        return method
+
+
+class AsyncClient(_Async):
+    """``Client`` for asyncio; see the module docstring."""
+
+    def __init__(self, base_url: str, token: str, timeout: float = 30.0, max_retries: int = 3,
+                 executor: Optional[Executor] = None, *, allow_http: bool = False):
+        super().__init__(Client(base_url, token, timeout, max_retries, allow_http=allow_http), executor)
+
+    def __repr__(self) -> str:
+        return f"Async{self._target!r}"
+
+    async def admit(self, body: dict, principal_chain: Optional[List[dict]] = None) -> "AsyncRun":
+        return await self._call(self._target.admit, body, principal_chain)
+
+    async def attach(self, run_id: str, trace_id: str, principal_chain: List[dict]) -> "AsyncRun":
+        return await self._call(self._target.attach, run_id, trace_id, principal_chain)
+
+    async def audit_entries(self, start: int = 1, page: int = 500) -> AsyncIterator[dict]:
+        """Yields the tenant's signed audit entries in order, a page per request."""
+        cursor: Optional[int] = start
+        while cursor is not None:
+            batch = await self._call(self._target.request, "GET", "/v1/audit/entries",
+                                     query={"from": cursor, "limit": page})
+            for entry in batch["entries"]:
+                yield entry
+            cursor = batch.get("next")
+
+
+class AsyncRun(_Async):
+    """``Run`` for asyncio; see the module docstring."""
+
+    def __init__(self, run: Run, executor: Optional[Executor] = None):
+        super().__init__(run, executor)
+
+    def __repr__(self) -> str:
+        return f"Async{self._target!r}"
+
+    async def call_tool(self, capability_id: str, args: dict, **options: Any) -> dict:
+        return await self._call(self._target.call_tool, capability_id, args, **options)
+
+    def metering_headers(self, reservation_id: str) -> dict:
+        return self._target.metering_headers(reservation_id)
+
+    @contextlib.asynccontextmanager
+    async def budgeted_model_call(self, *, tokens: int, cost_cents: int = 0,
+                                  metered: bool = False) -> AsyncIterator[str]:
+        """As ``Run.budgeted_model_call``: reserves before one model call and settles
+        after it; ``metered=True`` leaves settlement to a metering LLM gateway."""
+        reservation = await self._call(self._target.reserve_usage, "model_call", tokens=tokens, cost_cents=cost_cents)
+        settle = self._target._settle_open if metered else self._target.settle_usage
+        try:
+            yield reservation
+        except BaseException:
+            await self._call(settle, reservation)
+            raise
+        if not metered:
+            await self._call(settle, reservation)

contextos/client.py

@@ -0,0 +1,602 @@
+"""HTTP client for ``contextosd``: govern an agent's tool calls from Python.
+
+Standard library only. Typical use::
+
+    from contextos.client import Client, governed_tool
+
+    client = Client("https://contextos.internal", token=os.environ["CONTEXTOS_TOKEN"])
+    run = client.admit(admission_body)          # holds the executor generation
+    result = run.call_tool("adp_payments.issue_refund",
+                           {"order_id": "ord_881", "amount_minor": 1200},
+                           idempotency_key="refund:ord_881",
+                           approval_mode="destructive",
+                           evidence_refs=["kg:order:ord_881#snapshot"])
+
+    @governed_tool(run, "adp_orders.lookup", approval_mode="read_only")
+    def lookup_order(order_id: str): ...     # body never runs; the gateway dispatches
+
+Results that are not plain success raise typed exceptions, so agent code cannot
+mistake a pause, a refusal or an unknown outcome for a result:
+
+- ``ToolPaused``: approval pending, input required, or the outcome is unknown and
+  must be reconciled (never retry it blindly);
+- ``ToolBlocked``: authority, policy, constraints or budget refused it;
+- ``ToolRejected``: malformed, unsurfaced or incompatible reuse;
+- ``ToolFailed``: the provider definitively did not apply the effect.
+
+A model-call reservation the run cannot afford raises ``BudgetExhausted``. For asyncio
+agents, ``contextos.aio`` has the same client as coroutines.
+
+The client retries only requests the server did not process (``429``, ``503``),
+honouring ``Retry-After``. It never retries a tool call after a lost response on
+its own: the gateway's operation ledger makes a retry with the same idempotency key
+safe, but deciding to retry is the caller's.
+"""
+
+import contextlib
+import functools
+import inspect
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+import warnings
+from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple
+
+from .errors import (_HTTP_ERRORS, _OUTCOMES, BudgetExhausted, ContextOSHTTPError, IncompatibleServer, ToolBlocked,
+                     ToolFailed, ToolOutcome, ToolPaused, ToolRejected, VersionMismatchWarning, _pause_kind)
+
+GENERATION_HEADER = "ContextOS-Executor-Generation"
+# On a model request, these tell a metering LLM gateway which reservation to settle
+# with the usage it measures (see examples/metering-proxy).
+RUN_HEADER = "ContextOS-Run-Id"
+RESERVATION_HEADER = "ContextOS-Usage-Reservation"
+# The HTTP API generation this client speaks; a server reports its own in
+# ``GET /v1/deployment``.
+API_VERSION = "v1"
+# This client's release (scripts/package_clients.py checks it against Cargo.toml).
+CLIENT_VERSION = "0.1.0-alpha.13"
+
+
+def _check_versions(deployment: Any, client_version: str) -> dict:
+    """Raises on a different API generation; warns on a different or unreported release."""
+    deployment = deployment if isinstance(deployment, dict) else {}
+    api, runtime = deployment.get("api_version"), deployment.get("runtime_version")
+    if api is not None and api != API_VERSION:
+        raise IncompatibleServer(f"contextosd speaks API {api}; this client speaks {API_VERSION}")
+    if runtime is None:
+        warnings.warn(f"contextosd does not report its release (older than this client, {client_version}); "
+                      "use the same release on both sides", VersionMismatchWarning, stacklevel=4)
+    elif runtime != client_version:
+        warnings.warn(f"contextosd is release {runtime}; this client is {client_version}. "
+                      "Use the same release on both sides", VersionMismatchWarning, stacklevel=4)
+    return {"api_version": api, "runtime_version": runtime, "client_version": client_version}
+
+
+def task_scope(root_run_id: str, purpose_id: str, capability_id: str, *, resources: List[str] = (),
+               destinations: List[str] = (), classification: str = "CONFIDENTIAL",
+               amount: Optional[tuple] = None, argument_constraints: List[dict] = ()) -> dict:
+    """One `AuthorityGrant` scope for a task authorization: this capability, on these
+    resources, to these destinations, up to ``amount`` = ``(minor_units, currency)``."""
+    scope: Dict[str, Any] = {
+        "root_run_id": root_run_id, "purpose_ids": [purpose_id], "capability_ids": [capability_id],
+        "resource_ids": list(resources), "destination_ids": list(destinations),
+        "classification_labels": [classification], "argument_constraints": list(argument_constraints)}
+    if amount is not None:
+        scope["amount_ceiling"] = {"minor_units": amount[0], "currency": amount[1]}
+    return scope
+
+
+def task_authorization(issued_by: dict, scopes: List[dict], *, out_of_scope: str = "deny",
+                       read_only: str = "allow", confirmation_ref: Optional[dict] = None,
+                       max_effects: Optional[int] = None, amount_total: Optional[Tuple[int, str]] = None) -> dict:
+    """What the principal authorized for a run, for ``admit(body)`` as
+    ``body["task_authorization"]``. Effects outside every scope are refused
+    (``out_of_scope="deny"``) or wait for an exact approval (``"ask"``, raised as
+    ``ToolPaused`` with ``kind == "approval"``). ``max_effects`` and ``amount_total``
+    (``(minor_units, currency)``) bound the task as a whole, across all its effects."""
+    task: Dict[str, Any] = {"issued_by": issued_by, "scopes": scopes, "out_of_scope": out_of_scope,
+                            "read_only": read_only}
+    if confirmation_ref is not None:
+        task["confirmation_ref"] = confirmation_ref
+    limits: Dict[str, Any] = {}
+    if max_effects is not None:
+        limits["max_effects"] = max_effects
+    if amount_total is not None:
+        limits["amount_total"] = {"minor_units": amount_total[0], "currency": amount_total[1]}
+    if limits:
+        task["limits"] = limits
+    return task
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Refuses redirects: urllib would resend the bearer token to wherever one points."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect())
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+
+class Client:
+    """A connection to one ``contextosd`` deployment, authenticated as one caller.
+
+    The token is sent only to ``base_url``: redirects are not followed (a ``3xx`` raises
+    ``ContextOSHTTPError``), and plain ``http`` is refused except to a loopback address
+    unless ``allow_http=True`` (for example inside a private network you trust).
+
+    Before its first admission the client reads ``GET /v1/deployment`` once: a server
+    with another API generation raises ``IncompatibleServer``, another release warns
+    with ``VersionMismatchWarning``. ``check_server=False`` skips it."""
+
+    def __init__(self, base_url: str, token: str, timeout: float = 30.0, max_retries: int = 3, *,
+                 allow_http: bool = False, check_server: bool = True):
+        parsed = urllib.parse.urlsplit(base_url)
+        if parsed.scheme not in ("https", "http") or not parsed.hostname:
+            raise ValueError("base_url must be an http(s) URL")
+        if parsed.scheme == "http" and parsed.hostname not in _LOOPBACK and not allow_http:
+            raise ValueError("base_url is plain http to a remote host: the token would travel in the clear; "
+                             "use https, or pass allow_http=True")
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._server_checked = not check_server
+
+    def __repr__(self) -> str:  # never print the token
+        return f"Client({self.base_url!r})"
+
+    def request(self, method: str, path: str, body: Any = None, generation: Optional[int] = None,
+                query: Optional[Dict[str, Any]] = None) -> Any:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        data = None if body is None else json.dumps(body, allow_nan=False).encode()
+        headers = {"Authorization": f"Bearer {self._token}", "Accept": "application/json"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        if generation is not None:
+            headers[GENERATION_HEADER] = str(generation)
+        for attempt in range(self.max_retries + 1):
+            request = urllib.request.Request(url, data=data, method=method, headers=headers)
+            try:
+                with _OPENER.open(request, timeout=self.timeout) as response:
+                    payload = response.read()
+                    return json.loads(payload) if payload else None
+            except urllib.error.HTTPError as error:
+                payload = error.read()
+                try:
+                    decoded = json.loads(payload) if payload else {}
+                except ValueError:
+                    decoded = {}
+                # Not processed: safe to retry after the server's hint.
+                if error.code in (429, 503) and attempt < self.max_retries:
+                    time.sleep(_retry_after(error.headers.get("Retry-After"), attempt))
+                    continue
+                failure = decoded.get("error") if isinstance(decoded, dict) else None
+                if isinstance(failure, dict):
+                    code = failure.get("code", "error")
+                    raise _HTTP_ERRORS.get(code, ContextOSHTTPError)(error.code, code, failure.get("message", ""),
+                                                                     failure.get("detail")) from None
+                # Lifecycle refusals return their outcome body with 409.
+                raise ContextOSHTTPError(error.code, "refused", json.dumps(decoded), decoded) from None
+        raise AssertionError("unreachable")
+
+    def check_server(self) -> dict:
+        """Compares the server's API generation and release with this client's (see the
+        class docstring) and returns the three versions."""
+        versions = _check_versions(self.request("GET", "/v1/deployment"), CLIENT_VERSION)
+        self._server_checked = True
+        return versions
+
+    def admit(self, body: dict, principal_chain: Optional[List[dict]] = None) -> "Run":
+        """Admits a run (``POST /v1/runs``) and returns a handle that owns it."""
+        if not self._server_checked:
+            self.check_server()
+        admitted = self.request("POST", "/v1/runs", body)
+        context = body.get("run_context", {})
+        agent = (context.get("agent") or {}).get("agent_id")
+        chain = principal_chain or ([{"kind": "agent", "id": agent}] if agent else [])
+        return Run(self, admitted["run_id"], context.get("trace_id", ""), admitted["executor_generation"], chain,
+                   admitted)
+
+    def attach(self, run_id: str, trace_id: str, principal_chain: List[dict]) -> "Run":
+        """A handle on an existing run, at its current generation (no takeover)."""
+        status = self.request("GET", f"/v1/runs/{_quote(run_id)}")
+        return Run(self, run_id, trace_id, status["executor_generation"], principal_chain, status)
+
+    def amend_task_authorization(self, run_id: str, expected_revision: int, task: dict) -> dict:
+        """Corrects what a run's principal authorized. Narrowing is open to the executor;
+        widening needs an ``authorize`` token that does not run tasks, the principal's
+        ``confirmation_ref`` and the same ``issued_by``. Returns the new revision."""
+        return self.request("PUT", f"/v1/runs/{_quote(run_id)}/task-authorization",
+                            {"expected_revision": expected_revision, "task_authorization": task})
+
+    def reconcile(self, run_id: str, operation_id: str, *, outcome: Optional[str] = None,
+                  evidence_ref: Optional[dict] = None) -> dict:
+        """Resolves another principal's unknown effect as an independent reconciler (a
+        token with ``reconcile`` that did not admit the run): by provider query, or by
+        asserting ``outcome`` with evidence. No executor generation is sent."""
+        body = {"source": "provider"} if outcome is None else \
+            {"source": "operator", "outcome": outcome, "evidence_ref": evidence_ref}
+        return self.request("POST", f"/v1/runs/{_quote(run_id)}/operations/{_quote(operation_id)}/reconcile", body)
+
+    def report_outcome(self, run_id: str, operation_id: str, attestation: str) -> dict:
+        """Relays an outcome witness's signed reading (a compact JWS) for an applied effect
+        whose capability declares an outcome contract. Needs the ``outcome:report`` scope;
+        the signature, not the caller, is what the runtime trusts."""
+        return self.request("POST", f"/v1/runs/{_quote(run_id)}/operations/{_quote(operation_id)}/outcome",
+                            {"attestation": attestation})
+
+    def score(self, run_id: str, record_id: str, evaluator_ref: str, *, policy: float, utility: float,
+              safety: float) -> dict:
+        """Scores a recorded decision as an independent evaluator (a client whose token
+        has only the `evaluate` scope). The runtime adds the measured cost and latency."""
+        return self.request("POST", f"/v1/runs/{_quote(run_id)}/decisions/{_quote(record_id)}/scores",
+                            {"evaluator_ref": evaluator_ref, "policy": policy, "utility": utility, "safety": safety})
+
+    def file_feedback(self, run_id: str, kind: str, target_surface: str, summary: str, *,
+                      decision_record_id: Optional[str] = None, expected_outcome: Optional[str] = None) -> dict:
+        """Files an operator correction or override against a run as an independent
+        reviewer (`evaluate` scope); the run's replay case becomes its replay obligation."""
+        body: Dict[str, Any] = {"kind": kind, "target_surface": target_surface, "summary": summary}
+        if decision_record_id is not None:
+            body["decision_record_id"] = decision_record_id
+        if expected_outcome is not None:
+            body["expected_outcome"] = expected_outcome
+        return self.request("POST", f"/v1/runs/{_quote(run_id)}/feedback", body)
+
+    def open_escalations(self, limit: int = 500) -> dict:
+        """The tenant's open policy escalations, oldest first (`audit:read`)."""
+        return self.request("GET", "/v1/escalations", query={"limit": limit})
+
+    def resolve_escalation(self, escalation_id: str, resolution: str, reason: str) -> dict:
+        """Records how a human resolved an escalation, `handled` or `dismissed` (`control`).
+        Grants nothing: an action the human approves is retried through policy."""
+        return self.request("POST", f"/v1/escalations/{_quote(escalation_id)}/resolve",
+                            {"resolution": resolution, "reason": reason})
+
+    def open_feedback(self, limit: int = 500) -> dict:
+        """The tenant's open feedback, oldest first: the replay corpus a change must pass."""
+        return self.request("GET", "/v1/feedback", query={"limit": limit})
+
+    def close_feedback(self, feedback_id: str, status: str, *, artifact_type: str, artifact_id: str,
+                       sha256: str) -> dict:
+        """Closes feedback as fixed, still_failing, invalid or superseded, with a reference
+        to the evidence (`control` scope)."""
+        return self.request("POST", f"/v1/feedback/{_quote(feedback_id)}/close", {
+            "status": status,
+            "evidence_ref": {"artifact_type": artifact_type, "artifact_id": artifact_id, "sha256": sha256}})
+
+    def revoke(self, kind: str, target: str, reason: str) -> dict:
+        """Kill switch (a client whose token has the `control` scope): revokes a `tenant`,
+        `pack`, `agent`, `adapter` or `capability` from the next dispatch and admission."""
+        return self.request("POST", "/v1/revocations", {"kind": kind, "target": target, "reason": reason})
+
+    def restore(self, kind: str, target: str, reason: str) -> dict:
+        """Restores a revoked target."""
+        return self.request("POST", "/v1/revocations/restore", {"kind": kind, "target": target, "reason": reason})
+
+    def revocations(self) -> dict:
+        """The tenant's revoked targets."""
+        return self.request("GET", "/v1/revocations")
+
+    def audit_entries(self, start: int = 1, page: int = 500):
+        """Yields the tenant's signed audit entries in order."""
+        cursor: Optional[int] = start
+        while cursor is not None:
+            batch = self.request("GET", "/v1/audit/entries", query={"from": cursor, "limit": page})
+            yield from batch["entries"]
+            cursor = batch.get("next")
+
+
+class Run:
+    """One admitted run, held by this executor at ``executor_generation``."""
+
+    def __init__(self, client: Client, run_id: str, trace_id: str, executor_generation: int,
+                 principal_chain: List[dict], admitted: Optional[dict] = None):
+        self.client = client
+        self.run_id = run_id
+        self.trace_id = trace_id
+        self.executor_generation = executor_generation
+        self.principal_chain = principal_chain
+        self.admitted = admitted or {}
+        # Peer notices that came with the latest tool result (peer data, never instructions).
+        self.last_notices: Optional[dict] = None
+
+    def __repr__(self) -> str:
+        return f"Run({self.run_id!r}, generation={self.executor_generation})"
+
+    def _path(self, suffix: str = "") -> str:
+        return f"/v1/runs/{_quote(self.run_id)}{suffix}"
+
+    def _post(self, suffix: str, body: Any = None) -> Any:
+        return self.client.request("POST", self._path(suffix), body if body is not None else {},
+                                   generation=self.executor_generation)
+
+    def envelope(self, capability_id: str, args: dict, *, approval_mode: str, idempotency_key: Optional[str] = None,
+                 evidence_refs: Optional[List[str]] = None, tool_call_id: Optional[str] = None) -> dict:
+        """The ``contextos.tool_call.v1`` envelope for a call."""
+        return {
+            "envelope_version": "contextos.tool_call.v1",
+            "tool_call_id": tool_call_id or f"tc_{uuid.uuid4().hex}",
+            "run_id": self.run_id, "trace_id": self.trace_id, "capability_id": capability_id, "args": args,
+            "principal_chain": self.principal_chain, "approval_mode_requested": approval_mode,
+            "approval_mode_effective": approval_mode, "approval_mode_highest": approval_mode,
+            "evidence_refs": evidence_refs or [], "idempotency_key": idempotency_key,
+        }
+
+    def call_tool(self, capability_id: str, args: dict, *, approval_mode: str = "read_only",
+                  idempotency_key: Optional[str] = None, evidence_refs: Optional[List[str]] = None,
+                  tool_call_id: Optional[str] = None) -> dict:
+        """Governs and dispatches one tool call; returns its output or raises a ``ToolOutcome``."""
+        envelope = self.envelope(capability_id, args, approval_mode=approval_mode, idempotency_key=idempotency_key,
+                                 evidence_refs=evidence_refs, tool_call_id=tool_call_id)
+        response = self._post("/tool-calls", envelope)
+        self.last_notices = (response.get("result", {}).get("metadata") or {}).get("notices")
+        return _outcome(response)
+
+    def provide_input(self, paused: ToolPaused, envelope: dict, responses: dict) -> dict:
+        """Answers a tool's input requests and continues the same operation."""
+        body = {"tool_call": envelope, "input_responses": responses}
+        return _outcome(self._post(f"/operations/{_quote(paused.operation_id or '')}/input", body))
+
+    def reconcile(self, operation_id: str, *, outcome: Optional[str] = None,
+                  evidence_ref: Optional[dict] = None) -> dict:
+        """Resolves an unknown effect: by provider query, or by asserting ``outcome`` with evidence.
+        The run's own principal may only assert ``confirmed``; ``not_applied`` and ``partial``
+        need an independent reconciler (``Client.reconcile``)."""
+        body = {"source": "provider"} if outcome is None else \
+            {"source": "operator", "outcome": outcome, "evidence_ref": evidence_ref}
+        return self._post(f"/operations/{_quote(operation_id)}/reconcile", body)
+
+    def compensations(self) -> dict:
+        """The run's compensable effects and where each stands (``state``)."""
+        return self.client.request("GET", self._path("/compensations"))
+
+    def compensate(self, operation_id: str, *, tool_call_id: Optional[str] = None) -> dict:
+        """Compensates one applied effect with its declared compensating capability, governed
+        as a new operation; returns its output or raises a ``ToolOutcome``."""
+        body = {"tool_call_id": tool_call_id or f"tc_{uuid.uuid4().hex}"}
+        return _outcome(self._post(f"/operations/{_quote(operation_id)}/compensate", body))
+
+    def compensate_all(self) -> dict:
+        """Compensates the run's applied effects newest first, stopping at any in doubt.
+        Returns ``{"status": "compensated" | "stopped", "steps", "stopped_at"}``."""
+        return self._post("/compensate")
+
+    def record_decision(self, decision_key: str, status: str, *, decision_version: str = "1",
+                        outcome: Optional[str] = None, tool_calls: Optional[List[dict]] = None, **fields: Any) -> dict:
+        """Records a DecisionRecord; returns ``{"record", "replay_packet"}``."""
+        body = {"decision_key": decision_key, "decision_version": decision_version, "status": status,
+                "tool_calls": tool_calls or [], **fields}
+        if outcome is not None:
+            body["outcome"] = outcome
+        return self._post("/decisions", body)
+
+    def delegate(self, child_admission: dict, envelope: dict) -> "Run":
+        """Admits a child run in a narrowed lane (``AgentDelegationEnvelope``). Its
+        budget is reserved from this run; this run must hold the current generation."""
+        body = dict(child_admission, delegation=envelope)
+        admitted = self.client.request("POST", "/v1/runs", body, generation=self.executor_generation)
+        context = child_admission.get("run_context", {})
+        return Run(self.client, admitted["run_id"], context.get("trace_id", self.trace_id), admitted["executor_generation"],
+                   self.principal_chain, admitted)
+
+    def close_child(self, child: "Run", decision: str = "accept") -> dict:
+        """Closes a delegated child, settling its spend into this run."""
+        return self.client.request("POST", f"/v1/runs/{_quote(child.run_id)}/close", {"decision": decision},
+                                   generation=self.executor_generation)
+
+    def checkpoint(self, state: Any, expected_revision: int) -> dict:
+        """Saves the orchestrator's state as the next checkpoint revision."""
+        return self._post("/checkpoint", {"expected_revision": expected_revision, "state": state})
+
+    def latest_checkpoint(self) -> dict:
+        """The latest checkpoint (`state`, `revision`), e.g. after taking the run over."""
+        return self.client.request("GET", self._path("/checkpoint"), generation=self.executor_generation)
+
+    def publish_work(self, task_id: str, title: str, acceptance_criteria: str, *,
+                     dependencies: Optional[List[str]] = None) -> dict:
+        """Publish immutable task metadata shared with this root's descendants.
+        Claims and worker-reported evidence confer no tool authority."""
+        return self._post("/work", {"task_id": task_id, "title": title,
+                                   "acceptance_criteria": acceptance_criteria, "dependencies": dependencies or []})
+
+    def work_tasks(self, *, after: Optional[str] = None, limit: int = 100) -> dict:
+        """A live page of tasks; restart from the beginning to see new earlier ids."""
+        query: Dict[str, Any] = {"limit": limit}
+        if after is not None:
+            query["after"] = after
+        return self.client.request("GET", self._path("/work"), query=query, generation=self.executor_generation)
+
+    def work_task(self, task_id: str) -> dict:
+        """Inspect current revision and lease, including predecessor provenance."""
+        return self.client.request("GET", self._path(f"/work/{_quote(task_id)}"), generation=self.executor_generation)
+
+    def update_work(self, task_id: str, action: str, expected_revision: int, *, lease_epoch: Optional[int] = None,
+                    lease_seconds: Optional[int] = None, evidence_refs: Optional[List[dict]] = None) -> dict:
+        """Conditionally claim, renew, release or report completion. After a lost
+        response or conflict, inspect the task. Reclaiming a lease does not establish
+        that the previous worker's external effects are safe to repeat."""
+        body: Dict[str, Any] = {"action": action, "expected_revision": expected_revision}
+        if lease_epoch is not None:
+            body["lease_epoch"] = lease_epoch
+        if lease_seconds is not None:
+            body["lease_seconds"] = lease_seconds
+        if evidence_refs is not None:
+            body["evidence_refs"] = evidence_refs
+        return self._post(f"/work/{_quote(task_id)}", body)
+
+    def publish_finding(self, finding_id: str, statement: str, *, kind: str = "claim",
+                        depends_on: Optional[List[str]] = None, basis_operation_id: Optional[str] = None,
+                        basis_run_id: Optional[str] = None, refutes: Optional[str] = None,
+                        urgent: bool = False) -> dict:
+        """Shares a finding with the team: a ``claim``, or an ``observed`` finding bound to a
+        recorded tool call (``basis_operation_id``, in ``basis_run_id`` or this run) whose
+        facts the runtime takes from its operation ledger; an observation that ``refutes``
+        a peer's finding can then invalidate it. ``urgent`` notifies the team."""
+        body: Dict[str, Any] = {"finding_id": finding_id, "kind": kind, "statement": statement,
+                                "depends_on": depends_on or [], "urgent": urgent}
+        if basis_operation_id is not None:
+            body["kind"] = "observed"
+            body["basis"] = {"operation_id": basis_operation_id}
+            if basis_run_id is not None:
+                body["basis"]["run_id"] = basis_run_id
+        if refutes is not None:
+            body["refutes"] = refutes
+        return self._post("/findings", body)
+
+    def findings(self, *, after: Optional[str] = None, limit: int = 100) -> dict:
+        """A page of the team's findings with status (active, suspect, invalidated)."""
+        query: Dict[str, Any] = {"limit": limit}
+        if after is not None:
+            query["after"] = after
+        return self.client.request("GET", self._path("/findings"), query=query, generation=self.executor_generation)
+
+    def invalidate_finding(self, finding_id: str, reason: str, *, refuted_by: Optional[str] = None) -> dict:
+        """Falsifies a finding: withdraw your own, or cite an observed finding refuting a
+        peer's. Its dependents become suspect and the team is notified."""
+        body: Dict[str, Any] = {"reason": reason}
+        if refuted_by is not None:
+            body["refuted_by"] = refuted_by
+        return self._post(f"/findings/{_quote(finding_id)}/invalidate", body)
+
+    def notices(self, *, limit: int = 20) -> dict:
+        """This run's unacknowledged peer notices; reading does not acknowledge them."""
+        return self.client.request("GET", self._path("/notices"), query={"limit": limit},
+                                   generation=self.executor_generation)
+
+    def ack_notices(self, through: int) -> dict:
+        """Acknowledges notices through sequence ``through`` once the agent has seen them."""
+        return self._post("/notices/ack", {"through": through})
+
+    def reserve_usage(self, kind: str, *, tokens: int = 0, cost_cents: int = 0) -> str:
+        """Reserves budget for a `model_call` or a `replan`; returns the reservation id."""
+        return self._post("/usage/reserve", {"kind": kind, "tokens": tokens, "cost_cents": cost_cents})["reservation_id"]
+
+    def settle_usage(self, reservation_id: str) -> dict:
+        """Settles a reservation as the executor: the whole reservation is charged. Pass
+        the reservation id to your metering gateway instead to settle measured usage."""
+        return self._post("/usage/settle", {"reservation_id": reservation_id})
+
+    def metering_headers(self, reservation_id: str) -> Dict[str, str]:
+        """Headers for a model request that a metering LLM gateway settles with the
+        usage it measures (``budgeted_model_call(..., metered=True)``)."""
+        return {RUN_HEADER: self.run_id, RESERVATION_HEADER: reservation_id}
+
+    @contextlib.contextmanager
+    def budgeted_model_call(self, *, tokens: int, cost_cents: int = 0, metered: bool = False) -> Iterator[str]:
+        """Reserves budget for one model call and settles it afterwards, even if the call
+        raises. Raises ``BudgetExhausted`` before the call when the run cannot afford it.
+
+        ``metered=True`` leaves settlement to a metering LLM gateway (send
+        ``metering_headers(reservation)`` with the model request), which charges what it
+        measured. If the call raises, a reservation the gateway did not settle is settled
+        here, charging all of it: unknown usage is never free."""
+        reservation = self.reserve_usage("model_call", tokens=tokens, cost_cents=cost_cents)
+        try:
+            yield reservation
+        except BaseException:
+            if metered:
+                self._settle_open(reservation)
+            else:
+                self.settle_usage(reservation)
+            raise
+        if not metered:
+            self.settle_usage(reservation)
+
+    def _settle_open(self, reservation_id: str) -> None:
+        try:
+            self.settle_usage(reservation_id)
+        except ContextOSHTTPError as error:
+            if error.status != 404:  # 404: already settled by the gateway
+                raise
+
+    def status(self) -> dict:
+        return self.client.request("GET", self._path())
+
+    def take_over(self) -> "Run":
+        """Takes the run over from whichever executor held it; the old one becomes stale."""
+        current = self.status()["executor_generation"]
+        taken = self.client.request("POST", self._path("/takeover"), {"expected_generation": current})
+        self.executor_generation = taken["executor_generation"]
+        return self
+
+    def complete(self) -> dict:
+        return self._post("/complete")
+
+    def fail(self) -> dict:
+        return self._post("/fail")
+
+    def cancel(self) -> dict:
+        return self.client.request("POST", self._path("/cancel"), {})
+
+    def evidence(self) -> dict:
+        return self.client.request("GET", self._path("/evidence"))
+
+
+def governed_tool(run: Run, capability_id: str, *, approval_mode: str = "read_only",
+                  idempotency_key: Optional[Callable[..., str]] = None,
+                  evidence_refs: Optional[List[str]] = None,
+                  tool_call_id: Optional[Callable[..., str]] = None) -> Callable[[Callable[..., Any]], Callable[..., dict]]:
+    """Turns a tool's signature into a governed call: arguments are bound by name and
+    sent through the gateway; the decorated body never runs locally.
+
+    ``idempotency_key`` derives the operation key from the call's arguments, so a
+    retried agent step maps to the same operation and cannot apply twice.
+    ``tool_call_id`` derives the call's id the same way, so a DecisionRecord can cite it.
+    With an ``AsyncRun`` (``contextos.aio``) the governed function is a coroutine.
+    """
+
+    def wrap(function: Callable[..., Any]) -> Callable[..., Any]:
+        signature = inspect.signature(function)
+
+        def dispatch(args: Any, kwargs: Any) -> Any:
+            bound = signature.bind(*args, **kwargs)
+            bound.apply_defaults()
+            arguments = dict(bound.arguments)
+            key = idempotency_key(**arguments) if idempotency_key else None
+            call_id = tool_call_id(**arguments) if tool_call_id else None
+            return run.call_tool(capability_id, arguments, approval_mode=approval_mode, idempotency_key=key,
+                                 evidence_refs=evidence_refs, tool_call_id=call_id)
+
+        if inspect.iscoroutinefunction(run.call_tool):
+            @functools.wraps(function)
+            async def call_async(*args: Any, **kwargs: Any) -> dict:
+                return await dispatch(args, kwargs)
+
+            return call_async
+
+        @functools.wraps(function)
+        def call(*args: Any, **kwargs: Any) -> dict:
+            return dispatch(args, kwargs)
+
+        return call
+
+    return wrap
+
+
+def _outcome(response: dict) -> dict:
+    result, report = response["result"], response["report"]
+    status = result.get("status")
+    if status in ("ok", "completed"):
+        return result.get("output") or {}
+    raise _OUTCOMES.get(status, ToolOutcome)(result, report)
+
+
+def _retry_after(header: Optional[str], attempt: int) -> float:
+    try:
+        return min(float(header), 30.0) if header else min(0.2 * 2 ** attempt, 5.0)
+    except ValueError:
+        return min(0.2 * 2 ** attempt, 5.0)
+
+
+def _quote(segment: str) -> str:
+    if segment in ("", ".", ".."):
+        raise ValueError(f"invalid path segment {segment!r}")
+    return urllib.parse.quote(segment, safe="")

contextos/errors.py

@@ -0,0 +1,91 @@
+"""What the ``contextosd`` client raises: refused requests, governed tool outcomes that
+are not plain success, and an incompatible server. Import them from
+``contextos.client``, which re-exports every name here."""
+from typing import Any, List, Optional
+
+
+class ContextOSHTTPError(Exception):
+    """The server refused the request (4xx/5xx other than a governed tool result)."""
+
+    def __init__(self, status: int, code: str, message: str, detail: Any = None):
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.detail = detail
+
+
+class BudgetExhausted(ContextOSHTTPError):
+    """The run's budget cannot fit a model-call or replan reservation (``reasons``
+    says which limit). Stop the loop: retrying the same reservation cannot succeed."""
+
+    @property
+    def reasons(self) -> List[str]:
+        return self.detail if isinstance(self.detail, list) else []
+
+
+_HTTP_ERRORS = {"budget_exhausted": BudgetExhausted}
+
+
+class IncompatibleServer(Exception):
+    """The server speaks a different HTTP API generation than this client."""
+
+
+class VersionMismatchWarning(UserWarning):
+    """The server is a different ContextOS release than this client. Releases before
+    1.0 may change the API, so use the same release on both sides."""
+
+
+class ToolOutcome(Exception):
+    """A governed tool call that did not simply succeed."""
+
+    def __init__(self, result: dict, report: dict):
+        self.result = result
+        self.report = report
+        self.status = result.get("status")
+        self.reason_codes: List[str] = report.get("reason_codes", [])
+        self.obligations: List[str] = report.get("obligations", [])
+        self.operation_id: Optional[str] = report.get("operation_id")
+        super().__init__(f"{self.status}: {', '.join(self.reason_codes) or result.get('error') or ''}")
+
+
+class ToolPaused(ToolOutcome):
+    """Approval pending, input required, or an unknown outcome awaiting reconciliation."""
+
+    @property
+    def kind(self) -> str:
+        """What the pause waits on: ``approval`` (redeem by re-sending the same call once
+        approved), ``input`` (answer with ``provide_input``), ``unknown_outcome`` (the
+        effect may have happened: reconcile), ``duplicate`` (this operation was already
+        requested and is not repeated) or ``other``."""
+        return _pause_kind(self.obligations, self.reason_codes)
+
+    @property
+    def input_requests(self) -> Optional[dict]:
+        return (self.result.get("output") or {}).get("result", {}).get("inputRequests")
+
+
+class ToolBlocked(ToolOutcome):
+    """Authority, policy, constraints or budget refused the call."""
+
+
+class ToolRejected(ToolOutcome):
+    """The call was malformed, not surfaced to this run, or reused an operation key."""
+
+
+class ToolFailed(ToolOutcome):
+    """The provider definitively did not apply the effect."""
+
+
+def _pause_kind(obligations: List[str], reason_codes: List[str]) -> str:
+    if "await_approval" in obligations:
+        return "approval"
+    if "provide_requested_input" in obligations:
+        return "input"
+    if "reconcile_effect_before_retry" in obligations:
+        return "unknown_outcome"
+    if "retry_unsafe" in reason_codes or "reconcile_existing_operation" in obligations:
+        return "duplicate"
+    return "other"
+
+
+_OUTCOMES = {"paused": ToolPaused, "blocked": ToolBlocked, "rejected": ToolRejected, "failed": ToolFailed}

contextos_client-0.1.0a13.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.1
+Name: contextos-client
+Version: 0.1.0a13
+Summary: ContextOS kernel: governed context, authorization and durable effects for AI agents
+License: Apache-2.0
+Requires-Python: >=3.9
+Project-URL: Source, https://github.com/contextosai/ContextOS
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+
+# ContextOS for Python
+
+Two modules, one package:
+
+- `contextos.client` (and `contextos.aio` for asyncio) talks to `contextosd` over
+  HTTP. Standard library only: no compiled code, no dependencies.
+- `contextos` itself is the kernel, in-process, through a compiled extension
+  (`contextos._native`). You need it only to embed the kernel without a server.
+
+## Install
+
+```sh
+pip install --pre contextos-client
+```
+
+Published on PyPI as `contextos-client` from 0.1.0-alpha.13; the module is still
+`import contextos`. Linux (x86_64 and aarch64, glibc 2.28 or newer) and macOS on
+Apple silicon get a wheel with the compiled kernel. Every other platform gets
+a pure-Python wheel with the HTTP client only; kernel calls there raise
+`native_unavailable`. Use the client release that matches your `contextosd`: before its
+first admission the client warns (`VersionMismatchWarning`) when the server is another
+release, and refuses (`IncompatibleServer`) a server with another API generation.
+
+## The HTTP client (most agents)
+
+From a checkout instead of the package index, put the package on your path or copy
+`bindings/python/contextos/` into your project:
+
+```sh
+export PYTHONPATH=/path/to/ContextOS/bindings/python
+python3 -c "from contextos.client import Client; print('ok')"
+```
+
+Try it against a local server: `./examples/dev-server.sh` prints `CONTEXTOS_URL` and
+`CONTEXTOS_TOKEN`, and `examples/support-refund/requests/run.json` is a run you can
+admit. `examples/frameworks/` shows the client inside eleven agent frameworks.
+
+## The embedded kernel
+
+The platform wheels above include it. To build the extension yourself, use
+[maturin](https://www.maturin.rs/) (needs the Rust toolchain):
+
+```sh
+python3 -m pip install maturin
+python3 -m pip install ./bindings/python    # or: cd bindings/python && maturin develop
+python3 -c "import contextos; print(contextos.__version__)"
+```
+
+Without it, `import contextos` still works for the client; kernel calls raise an error
+that says to build the extension.

contextos_client-0.1.0a13.dist-info/RECORD

@@ -0,0 +1,9 @@
+contextos/__init__.py,sha256=pgUa4PhD2hR5b-lw8MZELmkxA4cqqVmvJq5NsP744Vo,2976
+contextos/client.py,sha256=fl98lzwx8AxDQsm-eutKwqpzQ_Jl-UDo8C5m-Mb4XbE,33434
+contextos/errors.py,sha256=IVU4Td2ihJxkASw2m_eQsHpuRnqd9ZxabStzUhc5DO4,3432
+contextos/aio.py,sha256=6uUycooyBXtueitp82GopKw7hXC0MlKiBYrPUSfg_2o,5129
+contextos_client-0.1.0a13.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+contextos_client-0.1.0a13.dist-info/licenses/NOTICE,sha256=lMzC_abhf9T5x-5zPUG6WWLFdhu1O493F4S0xljAOg4,894
+contextos_client-0.1.0a13.dist-info/METADATA,sha256=4r6Dy--DAe4EsXRFVd1huYHsacorOBNBqK6OKCWQSes,2413
+contextos_client-0.1.0a13.dist-info/WHEEL,sha256=j5NxlqV4xFdG6alboEDVE7NM2YEmUYICLhdZyMk-S7I,99
+contextos_client-0.1.0a13.dist-info/RECORD,,

contextos_client-0.1.0a13.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: contextos package_clients.py
+Root-Is-Purelib: true
+Tag: py3-none-any

contextos_client-0.1.0a13.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

contextos_client-0.1.0a13.dist-info/licenses/NOTICE

@@ -0,0 +1,20 @@
+ContextOS
+Copyright 2026 The ContextOS Authors
+
+This product includes software developed as part of the ContextOS project
+(https://github.com/contextosai/ContextOS), licensed under the Apache License,
+Version 2.0 (see LICENSE).
+
+Third-party dependency licenses and attribution are in THIRD_PARTY_NOTICES.txt.
+
+conformance/reference/ includes the unmodified deterministic TypeScript reference
+and synthetic fixtures from contextosai/contextosai, revision
+7e2462fd931a79e3777ede81fb382e0cbf2ff46c.
+Copyright (c) 2025-2026 ContextOS; licensed under Apache-2.0.
+
+Documentation prose in docs/ and the Markdown guides is licensed under the
+Creative Commons Attribution 4.0 International license (see LICENSE-docs);
+code examples within it are licensed under Apache-2.0.
+
+"ContextOS" and its logo are trademarks of the ContextOS project; neither
+license grants rights to use them (see TRADEMARKS.md).