anip-stdio 0.11.0__tar.gz

anip_stdio-0.11.0/.gitignore

@@ -0,0 +1,32 @@
+.DS_Store
+*.swp
+*~
+.env
+node_modules/
+__pycache__/
+*.db
+*.db-wal
+*.db-shm
+.venv/
+anip-keys.json
+anip-keys
+dist/
+*.tsbuildinfo
+build/
+*.egg-info/
+.worktrees/
+.serena/
+
+# Java build outputs
+target/
+
+# Go binaries
+packages/go/flight-service
+packages/go/flights-gin
+*.exe
+
+# .NET build outputs
+bin/
+obj/
+*.user
+.vs/

anip_stdio-0.11.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: anip-stdio
+Version: 0.11.0
+Summary: ANIP stdio transport binding — JSON-RPC 2.0 over stdin/stdout
+Requires-Python: >=3.11
+Requires-Dist: anip-service==0.11.0

anip_stdio-0.11.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anip-stdio"
+version = "0.11.0"
+description = "ANIP stdio transport binding — JSON-RPC 2.0 over stdin/stdout"
+requires-python = ">=3.11"
+dependencies = [
+    "anip-service==0.11.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anip_stdio"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

anip_stdio-0.11.0/src/anip_stdio/__init__.py

@@ -0,0 +1,4 @@
+from .server import serve_stdio, AnipStdioServer
+from .client import AnipStdioClient
+
+__all__ = ["serve_stdio", "AnipStdioServer", "AnipStdioClient"]

anip_stdio-0.11.0/src/anip_stdio/client.py

@@ -0,0 +1,252 @@
+"""ANIP stdio client — spawns a subprocess and communicates via JSON-RPC 2.0."""
+from __future__ import annotations
+
+import asyncio
+import itertools
+from typing import Any
+
+from .framing import read_message, write_message
+
+
+class InvokeStream:
+    """Async iterator for streaming invoke progress. Terminal result in .result."""
+
+    def __init__(self, reader: asyncio.StreamReader, req_id: int) -> None:
+        self._reader = reader
+        self._req_id = req_id
+        self.result: dict[str, Any] | None = None
+
+    def __aiter__(self) -> InvokeStream:
+        return self
+
+    async def __anext__(self) -> dict[str, Any]:
+        while True:
+            msg = await read_message(self._reader)
+            if msg is None:
+                raise StopAsyncIteration
+
+            # Notification (progress)
+            if "method" in msg and msg["method"] == "anip.invoke.progress":
+                return msg["params"]
+
+            # Final response for our request
+            if "id" in msg and msg["id"] == self._req_id:
+                if "error" in msg:
+                    raise Exception(f"Invoke failed: {msg['error']}")
+                self.result = msg["result"]
+                raise StopAsyncIteration
+
+
+class AnipStdioClient:
+    """Async context manager that spawns an ANIP service subprocess and talks JSON-RPC 2.0.
+
+    IMPORTANT: This client is single-request-at-a-time. Do not issue concurrent
+    calls or overlap a streaming invoke with other requests — there is no response
+    demultiplexer. Concurrent request support is a future enhancement.
+    """
+
+    def __init__(self, *cmd: str) -> None:
+        self._cmd = cmd
+        self._proc: asyncio.subprocess.Process | None = None
+        self._id_counter = itertools.count(1)
+        self._stderr_task: asyncio.Task | None = None
+
+    async def __aenter__(self) -> AnipStdioClient:
+        self._proc = await asyncio.create_subprocess_exec(
+            *self._cmd,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        # Drain stderr in background to prevent pipe buffer deadlock.
+        # The stdio spec reserves stderr for logs/diagnostics — a chatty service
+        # can fill the pipe buffer and block if nobody reads it.
+        self._stderr_task = asyncio.create_task(self._drain_stderr())
+        return self
+
+    async def _drain_stderr(self) -> None:
+        """Read and discard stderr to prevent pipe buffer deadlock."""
+        assert self._proc is not None and self._proc.stderr is not None
+        try:
+            while True:
+                line = await self._proc.stderr.readline()
+                if not line:
+                    break
+        except Exception:
+            pass
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if self._proc is not None:
+            if self._proc.stdin is not None:
+                self._proc.stdin.close()
+            await self._proc.wait()
+        if self._stderr_task is not None:
+            self._stderr_task.cancel()
+            try:
+                await self._stderr_task
+            except asyncio.CancelledError:
+                pass
+
+    # --- Core RPC plumbing ---
+
+    async def _call(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a JSON-RPC request and return the result, skipping interleaved notifications."""
+        assert self._proc is not None and self._proc.stdin is not None and self._proc.stdout is not None
+
+        req_id = next(self._id_counter)
+        request = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": method,
+            "params": params or {},
+        }
+        await write_message(self._proc.stdin, request)
+
+        # Read messages until we get the response matching our request id
+        while True:
+            msg = await read_message(self._proc.stdout)
+            if msg is None:
+                raise ConnectionError("Subprocess closed stdout before responding")
+
+            # Skip notifications (no "id" field)
+            if "id" not in msg:
+                continue
+
+            if msg["id"] == req_id:
+                if "error" in msg:
+                    err = msg["error"]
+                    raise Exception(f"JSON-RPC error {err.get('code')}: {err.get('message')}")
+                return msg["result"]
+
+    # --- Typed public methods ---
+
+    async def discovery(self) -> dict[str, Any]:
+        """Call anip.discovery."""
+        return await self._call("anip.discovery")
+
+    async def manifest(self) -> dict[str, Any]:
+        """Call anip.manifest — returns {manifest, signature}."""
+        return await self._call("anip.manifest")
+
+    async def jwks(self) -> dict[str, Any]:
+        """Call anip.jwks — returns {keys: [...]}."""
+        return await self._call("anip.jwks")
+
+    async def issue_token(
+        self,
+        bearer: str,
+        *,
+        subject: str | None = None,
+        scope: list[str] | None = None,
+        capability: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Call anip.tokens.issue."""
+        params: dict[str, Any] = {"auth": {"bearer": bearer}}
+        if subject is not None:
+            params["subject"] = subject
+        if scope is not None:
+            params["scope"] = scope
+        if capability is not None:
+            params["capability"] = capability
+        params.update(kwargs)
+        return await self._call("anip.tokens.issue", params)
+
+    async def permissions(self, bearer: str) -> dict[str, Any]:
+        """Call anip.permissions."""
+        return await self._call("anip.permissions", {"auth": {"bearer": bearer}})
+
+    async def invoke(
+        self,
+        bearer: str,
+        capability: str,
+        parameters: dict[str, Any] | None = None,
+        *,
+        client_reference_id: str | None = None,
+        stream: bool = False,
+    ) -> dict[str, Any] | InvokeStream:
+        """Call anip.invoke. Returns result dict, or InvokeStream if stream=True."""
+        assert self._proc is not None and self._proc.stdin is not None and self._proc.stdout is not None
+
+        params: dict[str, Any] = {
+            "auth": {"bearer": bearer},
+            "capability": capability,
+        }
+        if parameters is not None:
+            params["parameters"] = parameters
+        if client_reference_id is not None:
+            params["client_reference_id"] = client_reference_id
+        if stream:
+            params["stream"] = True
+
+        req_id = next(self._id_counter)
+        request = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": "anip.invoke",
+            "params": params,
+        }
+        await write_message(self._proc.stdin, request)
+
+        if stream:
+            return InvokeStream(self._proc.stdout, req_id)
+
+        # Non-streaming: read until we get the matching response
+        while True:
+            msg = await read_message(self._proc.stdout)
+            if msg is None:
+                raise ConnectionError("Subprocess closed stdout before responding")
+            if "id" not in msg:
+                continue
+            if msg["id"] == req_id:
+                if "error" in msg:
+                    err = msg["error"]
+                    raise Exception(f"JSON-RPC error {err.get('code')}: {err.get('message')}")
+                return msg["result"]
+
+    async def audit_query(
+        self,
+        bearer: str,
+        *,
+        capability: str | None = None,
+        since: str | None = None,
+        invocation_id: str | None = None,
+        client_reference_id: str | None = None,
+        event_class: str | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        """Call anip.audit.query."""
+        params: dict[str, Any] = {"auth": {"bearer": bearer}}
+        if capability is not None:
+            params["capability"] = capability
+        if since is not None:
+            params["since"] = since
+        if invocation_id is not None:
+            params["invocation_id"] = invocation_id
+        if client_reference_id is not None:
+            params["client_reference_id"] = client_reference_id
+        if event_class is not None:
+            params["event_class"] = event_class
+        if limit is not None:
+            params["limit"] = limit
+        return await self._call("anip.audit.query", params)
+
+    async def checkpoints_list(self, limit: int = 10) -> dict[str, Any]:
+        """Call anip.checkpoints.list."""
+        return await self._call("anip.checkpoints.list", {"limit": limit})
+
+    async def checkpoints_get(
+        self,
+        id: str,
+        *,
+        include_proof: bool = False,
+        leaf_index: int | None = None,
+        consistency_from: str | None = None,
+    ) -> dict[str, Any]:
+        """Call anip.checkpoints.get."""
+        params: dict[str, Any] = {"id": id, "include_proof": include_proof}
+        if leaf_index is not None:
+            params["leaf_index"] = leaf_index
+        if consistency_from is not None:
+            params["consistency_from"] = consistency_from
+        return await self._call("anip.checkpoints.get", params)

anip_stdio-0.11.0/src/anip_stdio/framing.py

@@ -0,0 +1,19 @@
+"""Newline-delimited JSON framing for ANIP stdio transport."""
+import json
+import asyncio
+from typing import Any
+
+
+async def read_message(reader: asyncio.StreamReader) -> dict[str, Any] | None:
+    """Read one newline-delimited JSON message. Returns None on EOF."""
+    line = await reader.readline()
+    if not line:
+        return None
+    return json.loads(line.strip())
+
+
+async def write_message(writer: asyncio.StreamWriter, message: dict[str, Any]) -> None:
+    """Write one newline-delimited JSON message."""
+    data = json.dumps(message, separators=(",", ":")) + "\n"
+    writer.write(data.encode())
+    await writer.drain()

anip_stdio-0.11.0/src/anip_stdio/protocol.py

@@ -0,0 +1,109 @@
+"""JSON-RPC 2.0 protocol helpers for ANIP stdio transport."""
+from __future__ import annotations
+
+from typing import Any
+
+# --- Valid ANIP methods ---
+
+VALID_METHODS: frozenset[str] = frozenset({
+    "anip.discovery",
+    "anip.manifest",
+    "anip.jwks",
+    "anip.tokens.issue",
+    "anip.permissions",
+    "anip.invoke",
+    "anip.audit.query",
+    "anip.checkpoints.list",
+    "anip.checkpoints.get",
+})
+
+# --- JSON-RPC 2.0 error codes ---
+
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+AUTH_ERROR = -32001
+SCOPE_ERROR = -32002
+NOT_FOUND = -32004
+INTERNAL_ERROR = -32603
+
+# --- ANIP failure type to JSON-RPC error code mapping ---
+
+FAILURE_TYPE_TO_CODE: dict[str, int] = {
+    "authentication_required": AUTH_ERROR,
+    "invalid_token": AUTH_ERROR,
+    "token_expired": AUTH_ERROR,
+    "scope_insufficient": SCOPE_ERROR,
+    "budget_exceeded": SCOPE_ERROR,
+    "purpose_mismatch": SCOPE_ERROR,
+    "unknown_capability": NOT_FOUND,
+    "not_found": NOT_FOUND,
+    "internal_error": INTERNAL_ERROR,
+    "unavailable": INTERNAL_ERROR,
+    "concurrent_lock": INTERNAL_ERROR,
+}
+
+
+# --- Message constructors ---
+
+
+def make_response(request_id: int | str | None, result: Any) -> dict[str, Any]:
+    """Build a JSON-RPC 2.0 success response."""
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def make_error(
+    request_id: int | str | None,
+    code: int,
+    message: str,
+    data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a JSON-RPC 2.0 error response."""
+    error: dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        error["data"] = data
+    return {"jsonrpc": "2.0", "id": request_id, "error": error}
+
+
+def make_notification(method: str, params: dict[str, Any]) -> dict[str, Any]:
+    """Build a JSON-RPC 2.0 notification (no id)."""
+    return {"jsonrpc": "2.0", "method": method, "params": params}
+
+
+# --- Request validation ---
+
+
+def validate_request(msg: dict[str, Any]) -> str | None:
+    """Validate a JSON-RPC 2.0 request.
+
+    Returns None if valid, or an error description string if invalid.
+    """
+    if not isinstance(msg, dict):
+        return "Request must be a JSON object"
+    if msg.get("jsonrpc") != "2.0":
+        return "Missing or invalid 'jsonrpc' field (must be '2.0')"
+    if "method" not in msg:
+        return "Missing 'method' field"
+    if not isinstance(msg["method"], str):
+        return "'method' must be a string"
+    if "id" not in msg:
+        return "Missing 'id' field (notifications not supported as requests)"
+    return None
+
+
+# --- Auth extraction ---
+
+
+def extract_auth(params: dict[str, Any] | None) -> str | None:
+    """Extract bearer token from params.auth.bearer.
+
+    Returns the bearer string, or None if not present.
+    """
+    if params is None:
+        return None
+    auth = params.get("auth")
+    if auth is None:
+        return None
+    if not isinstance(auth, dict):
+        return None
+    return auth.get("bearer")

anip_stdio-0.11.0/src/anip_stdio/server.py

@@ -0,0 +1,282 @@
+"""ANIP stdio transport server — JSON-RPC 2.0 over stdin/stdout."""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import Any
+
+from anip_service import ANIPService
+from anip_service.types import ANIPError
+
+from .framing import read_message, write_message
+from .protocol import (
+    AUTH_ERROR,
+    FAILURE_TYPE_TO_CODE,
+    INTERNAL_ERROR,
+    INVALID_REQUEST,
+    METHOD_NOT_FOUND,
+    NOT_FOUND,
+    PARSE_ERROR,
+    VALID_METHODS,
+    extract_auth,
+    make_error,
+    make_notification,
+    make_response,
+    validate_request,
+)
+
+
+class AnipStdioServer:
+    """JSON-RPC 2.0 server wrapping an ANIPService for stdio transport."""
+
+    def __init__(self, service: ANIPService) -> None:
+        self._service = service
+
+    # --- Public dispatch ---
+
+    async def handle_request(self, msg: dict[str, Any]) -> dict[str, Any] | list[dict[str, Any]]:
+        """Validate and dispatch a JSON-RPC request to the appropriate handler.
+
+        Returns a single JSON-RPC response dict, or for streaming invocations
+        a list of [notification..., response].
+        """
+        error_desc = validate_request(msg)
+        if error_desc is not None:
+            return make_error(msg.get("id"), INVALID_REQUEST, error_desc)
+
+        request_id = msg["id"]
+        method = msg["method"]
+        params = msg.get("params") or {}
+
+        if method not in VALID_METHODS:
+            return make_error(request_id, METHOD_NOT_FOUND, f"Unknown method: {method}")
+
+        handler = self._DISPATCH.get(method)
+        if handler is None:
+            return make_error(request_id, INTERNAL_ERROR, f"No handler for {method}")
+
+        try:
+            result = await handler(self, params)
+        except ANIPError as exc:
+            code = FAILURE_TYPE_TO_CODE.get(exc.error_type, INTERNAL_ERROR)
+            return make_error(request_id, code, exc.detail, {
+                "type": exc.error_type,
+                "detail": exc.detail,
+                "retry": exc.retry,
+            })
+        except Exception as exc:
+            return make_error(request_id, INTERNAL_ERROR, str(exc))
+
+        # Streaming invoke returns (notifications, result)
+        if isinstance(result, tuple) and len(result) == 2:
+            notifications, final_result = result
+            messages: list[dict[str, Any]] = list(notifications)
+            messages.append(make_response(request_id, final_result))
+            return messages
+
+        return make_response(request_id, result)
+
+    # --- Method handlers ---
+
+    async def _handle_anip_discovery(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self._service.get_discovery()
+
+    async def _handle_anip_manifest(self, params: dict[str, Any]) -> dict[str, Any]:
+        body_bytes, signature = self._service.get_signed_manifest()
+        return {"manifest": json.loads(body_bytes), "signature": signature}
+
+    async def _handle_anip_jwks(self, params: dict[str, Any]) -> dict[str, Any]:
+        return self._service.get_jwks()
+
+    async def _handle_anip_tokens_issue(self, params: dict[str, Any]) -> dict[str, Any]:
+        bearer = extract_auth(params)
+        if bearer is None:
+            raise ANIPError("authentication_required", "This method requires auth.bearer")
+
+        # Try bootstrap auth (API key) first, then ANIP JWT
+        principal = await self._service.authenticate_bearer(bearer)
+        if principal is None:
+            raise ANIPError("invalid_token", "Bearer token not recognized")
+
+        # Build the token request body from params
+        body: dict[str, Any] = {}
+        for key in ("subject", "scope", "capability", "purpose_parameters",
+                     "parent_token", "ttl_hours", "caller_class"):
+            if key in params:
+                body[key] = params[key]
+
+        return await self._service.issue_token(principal, body)
+
+    async def _handle_anip_permissions(self, params: dict[str, Any]) -> dict[str, Any]:
+        token = await self._resolve_jwt(params)
+        perm = self._service.discover_permissions(token)
+        return perm.model_dump() if hasattr(perm, "model_dump") else perm
+
+    async def _handle_anip_invoke(
+        self, params: dict[str, Any],
+    ) -> dict[str, Any] | tuple[list[dict[str, Any]], dict[str, Any]]:
+        token = await self._resolve_jwt(params)
+
+        capability = params.get("capability")
+        if not capability:
+            raise ANIPError("unknown_capability", "Missing 'capability' in params")
+
+        parameters = params.get("parameters", {})
+        client_reference_id = params.get("client_reference_id")
+        stream = params.get("stream", False)
+
+        if stream:
+            notifications: list[dict[str, Any]] = []
+
+            async def _progress_sink(payload: dict[str, Any]) -> None:
+                notifications.append(
+                    make_notification("anip.invoke.progress", payload)
+                )
+
+            result = await self._service.invoke(
+                capability, token, parameters,
+                client_reference_id=client_reference_id,
+                stream=True,
+                _progress_sink=_progress_sink,
+            )
+            return (notifications, result)
+
+        result = await self._service.invoke(
+            capability, token, parameters,
+            client_reference_id=client_reference_id,
+        )
+        return result
+
+    async def _handle_anip_audit_query(self, params: dict[str, Any]) -> dict[str, Any]:
+        token = await self._resolve_jwt(params)
+
+        filters: dict[str, Any] = {}
+        for key in ("capability", "since", "invocation_id",
+                     "client_reference_id", "event_class", "limit"):
+            if key in params:
+                filters[key] = params[key]
+
+        return await self._service.query_audit(token, filters)
+
+    async def _handle_anip_checkpoints_list(self, params: dict[str, Any]) -> dict[str, Any]:
+        limit = params.get("limit", 10)
+        return await self._service.get_checkpoints(limit)
+
+    async def _handle_anip_checkpoints_get(self, params: dict[str, Any]) -> dict[str, Any]:
+        checkpoint_id = params.get("id")
+        if not checkpoint_id:
+            raise ANIPError("not_found", "Missing 'id' in params")
+
+        options: dict[str, Any] = {}
+        for key in ("include_proof", "leaf_index", "consistency_from"):
+            if key in params:
+                options[key] = params[key]
+
+        result = await self._service.get_checkpoint(checkpoint_id, options)
+        if result is None:
+            raise ANIPError("not_found", f"Checkpoint not found: {checkpoint_id}")
+        return result
+
+    # --- Internal helpers ---
+
+    async def _resolve_jwt(self, params: dict[str, Any]) -> Any:
+        """Extract and verify a JWT bearer token from params.
+
+        Returns the resolved DelegationToken.
+        Raises ANIPError if auth is missing or invalid.
+        """
+        bearer = extract_auth(params)
+        if bearer is None:
+            raise ANIPError("authentication_required", "This method requires auth.bearer")
+        return await self._service.resolve_bearer_token(bearer)
+
+    # --- Dispatch table ---
+
+    _DISPATCH: dict[str, Any] = {
+        "anip.discovery": _handle_anip_discovery,
+        "anip.manifest": _handle_anip_manifest,
+        "anip.jwks": _handle_anip_jwks,
+        "anip.tokens.issue": _handle_anip_tokens_issue,
+        "anip.permissions": _handle_anip_permissions,
+        "anip.invoke": _handle_anip_invoke,
+        "anip.audit.query": _handle_anip_audit_query,
+        "anip.checkpoints.list": _handle_anip_checkpoints_list,
+        "anip.checkpoints.get": _handle_anip_checkpoints_get,
+    }
+
+
+class _StdioWriter:
+    """Minimal async writer wrapping sys.stdout.buffer."""
+
+    def __init__(self):
+        self._out = sys.stdout.buffer
+
+    def write(self, data: bytes) -> None:
+        self._out.write(data)
+
+    async def drain(self) -> None:
+        self._out.flush()
+
+    def close(self) -> None:
+        pass
+
+
+def _make_stdio_streams():
+    """Create async reader/writer for stdin/stdout without connect_*_pipe."""
+    reader = asyncio.StreamReader()
+
+    async def _feed_stdin():
+        loop = asyncio.get_event_loop()
+        while True:
+            line = await loop.run_in_executor(None, sys.stdin.buffer.readline)
+            if not line:
+                reader.feed_eof()
+                break
+            reader.feed_data(line)
+
+    asyncio.get_event_loop().create_task(_feed_stdin())
+    writer = _StdioWriter()
+    return reader, writer
+
+
+async def serve_stdio(
+    service: ANIPService,
+    reader: asyncio.StreamReader | None = None,
+    writer: asyncio.StreamWriter | None = None,
+) -> None:
+    """Run the ANIP stdio server, reading JSON-RPC from reader and writing to writer.
+
+    If reader/writer are not provided, connects stdin/stdout as asyncio streams.
+    """
+    if reader is None or writer is None:
+        # Use a simple sync wrapper for stdin/stdout.
+        # This avoids connect_read_pipe/connect_write_pipe which fail
+        # when stdin/stdout are not real pipes (e.g., terminals, redirected files).
+        reader, writer = _make_stdio_streams()
+
+    server = AnipStdioServer(service)
+    await service.start()
+
+    try:
+        while True:
+            try:
+                msg = await read_message(reader)
+            except json.JSONDecodeError as exc:
+                error_resp = make_error(None, PARSE_ERROR, f"Parse error: {exc}")
+                await write_message(writer, error_resp)
+                continue
+
+            if msg is None:
+                break  # EOF
+
+            response = await server.handle_request(msg)
+
+            if isinstance(response, list):
+                for item in response:
+                    await write_message(writer, item)
+            else:
+                await write_message(writer, response)
+    finally:
+        await service.shutdown()
+        service.stop()

anip_stdio-0.11.0/tests/_serve_fixture.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Minimal ANIP stdio server for testing the client."""
+import asyncio
+
+from anip_service import ANIPService, Capability, InvocationContext
+from anip_core import (
+    CapabilityDeclaration,
+    CapabilityInput,
+    CapabilityOutput,
+    SideEffect,
+    SideEffectType,
+)
+from anip_stdio import serve_stdio
+
+
+async def _echo_handler(ctx: InvocationContext, params: dict) -> dict:
+    return {"message": params.get("message", "")}
+
+
+service = ANIPService(
+    service_id="test-stdio-client",
+    capabilities=[
+        Capability(
+            declaration=CapabilityDeclaration(
+                name="echo",
+                description="Echo",
+                contract_version="1.0",
+                inputs=[CapabilityInput(name="message", type="string", description="msg")],
+                output=CapabilityOutput(type="object", fields=["message"]),
+                side_effect=SideEffect(type=SideEffectType.READ),
+                minimum_scope=["test"],
+            ),
+            handler=_echo_handler,
+        ),
+    ],
+    storage=":memory:",
+    authenticate=lambda bearer: "user@test.com" if bearer == "test-key" else None,
+)
+
+asyncio.run(serve_stdio(service))

anip_stdio-0.11.0/tests/test_client.py

@@ -0,0 +1,67 @@
+"""Tests for ANIP stdio client."""
+import os
+import sys
+
+import pytest
+
+from anip_stdio.client import AnipStdioClient
+
+SERVE_SCRIPT = os.path.join(os.path.dirname(__file__), "_serve_fixture.py")
+
+
+@pytest.mark.asyncio
+async def test_discovery():
+    async with AnipStdioClient(sys.executable, SERVE_SCRIPT) as client:
+        result = await client.discovery()
+        assert "anip_discovery" in result
+        assert result["anip_discovery"]["protocol"] == "anip/0.11"
+
+
+@pytest.mark.asyncio
+async def test_manifest():
+    async with AnipStdioClient(sys.executable, SERVE_SCRIPT) as client:
+        result = await client.manifest()
+        assert "manifest" in result
+        assert "signature" in result
+
+
+@pytest.mark.asyncio
+async def test_jwks():
+    async with AnipStdioClient(sys.executable, SERVE_SCRIPT) as client:
+        result = await client.jwks()
+        assert "keys" in result
+
+
+@pytest.mark.asyncio
+async def test_full_flow():
+    async with AnipStdioClient(sys.executable, SERVE_SCRIPT) as client:
+        # Issue token
+        tok = await client.issue_token(
+            "test-key", subject="agent:bot", scope=["test"], capability="echo",
+        )
+        assert tok["issued"] is True
+        jwt = tok["token"]
+
+        # Invoke
+        result = await client.invoke(jwt, "echo", {"message": "hello stdio"})
+        assert result["success"] is True
+        assert result["result"]["message"] == "hello stdio"
+
+        # Permissions
+        perms = await client.permissions(jwt)
+        assert "available" in perms
+
+        # Audit
+        audit = await client.audit_query(jwt, capability="echo")
+        assert len(audit["entries"]) > 0
+
+        # Checkpoints
+        cps = await client.checkpoints_list()
+        assert "checkpoints" in cps
+
+
+@pytest.mark.asyncio
+async def test_auth_error():
+    async with AnipStdioClient(sys.executable, SERVE_SCRIPT) as client:
+        with pytest.raises(Exception, match="32001|auth|Auth"):
+            await client.invoke("bad-token", "echo", {"message": "fail"})

anip_stdio-0.11.0/tests/test_protocol.py

@@ -0,0 +1,158 @@
+"""Unit tests for JSON-RPC 2.0 protocol helpers."""
+from anip_stdio.protocol import (
+    AUTH_ERROR,
+    FAILURE_TYPE_TO_CODE,
+    INTERNAL_ERROR,
+    INVALID_REQUEST,
+    METHOD_NOT_FOUND,
+    NOT_FOUND,
+    PARSE_ERROR,
+    SCOPE_ERROR,
+    VALID_METHODS,
+    extract_auth,
+    make_error,
+    make_notification,
+    make_response,
+    validate_request,
+)
+
+
+# --- VALID_METHODS ---
+
+class TestValidMethods:
+    def test_method_count(self):
+        assert len(VALID_METHODS) == 9
+
+    def test_all_methods_present(self):
+        expected = {
+            "anip.discovery", "anip.manifest", "anip.jwks",
+            "anip.tokens.issue", "anip.permissions", "anip.invoke",
+            "anip.audit.query", "anip.checkpoints.list", "anip.checkpoints.get",
+        }
+        assert VALID_METHODS == expected
+
+
+# --- Error code mapping ---
+
+class TestErrorCodeMapping:
+    def test_auth_errors(self):
+        for t in ("authentication_required", "invalid_token", "token_expired"):
+            assert FAILURE_TYPE_TO_CODE[t] == AUTH_ERROR
+
+    def test_scope_errors(self):
+        for t in ("scope_insufficient", "budget_exceeded", "purpose_mismatch"):
+            assert FAILURE_TYPE_TO_CODE[t] == SCOPE_ERROR
+
+    def test_not_found_errors(self):
+        for t in ("unknown_capability", "not_found"):
+            assert FAILURE_TYPE_TO_CODE[t] == NOT_FOUND
+
+    def test_internal_errors(self):
+        for t in ("internal_error", "unavailable", "concurrent_lock"):
+            assert FAILURE_TYPE_TO_CODE[t] == INTERNAL_ERROR
+
+
+# --- make_response ---
+
+class TestMakeResponse:
+    def test_basic(self):
+        resp = make_response(1, {"key": "value"})
+        assert resp == {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "result": {"key": "value"},
+        }
+
+    def test_null_id(self):
+        resp = make_response(None, "ok")
+        assert resp["id"] is None
+
+    def test_string_id(self):
+        resp = make_response("abc-123", [1, 2, 3])
+        assert resp["id"] == "abc-123"
+        assert resp["result"] == [1, 2, 3]
+
+
+# --- make_error ---
+
+class TestMakeError:
+    def test_basic(self):
+        resp = make_error(1, -32600, "Invalid request")
+        assert resp["jsonrpc"] == "2.0"
+        assert resp["id"] == 1
+        assert resp["error"]["code"] == -32600
+        assert resp["error"]["message"] == "Invalid request"
+        assert "data" not in resp["error"]
+
+    def test_with_data(self):
+        resp = make_error(2, -32001, "Auth required", {"type": "authentication_required"})
+        assert resp["error"]["data"]["type"] == "authentication_required"
+
+    def test_null_id(self):
+        resp = make_error(None, PARSE_ERROR, "Parse error")
+        assert resp["id"] is None
+
+
+# --- make_notification ---
+
+class TestMakeNotification:
+    def test_basic(self):
+        notif = make_notification("anip.invoke.progress", {"invocation_id": "inv-1"})
+        assert notif["jsonrpc"] == "2.0"
+        assert notif["method"] == "anip.invoke.progress"
+        assert notif["params"]["invocation_id"] == "inv-1"
+        assert "id" not in notif
+
+
+# --- validate_request ---
+
+class TestValidateRequest:
+    def test_valid_request(self):
+        msg = {"jsonrpc": "2.0", "id": 1, "method": "anip.discovery"}
+        assert validate_request(msg) is None
+
+    def test_missing_jsonrpc(self):
+        msg = {"id": 1, "method": "anip.discovery"}
+        assert validate_request(msg) is not None
+
+    def test_wrong_jsonrpc(self):
+        msg = {"jsonrpc": "1.0", "id": 1, "method": "anip.discovery"}
+        assert validate_request(msg) is not None
+
+    def test_missing_method(self):
+        msg = {"jsonrpc": "2.0", "id": 1}
+        assert validate_request(msg) is not None
+
+    def test_non_string_method(self):
+        msg = {"jsonrpc": "2.0", "id": 1, "method": 42}
+        assert validate_request(msg) is not None
+
+    def test_missing_id(self):
+        msg = {"jsonrpc": "2.0", "method": "anip.discovery"}
+        assert validate_request(msg) is not None
+
+    def test_not_a_dict(self):
+        assert validate_request("not a dict") is not None  # type: ignore[arg-type]
+
+
+# --- extract_auth ---
+
+class TestExtractAuth:
+    def test_extracts_bearer(self):
+        params = {"auth": {"bearer": "my-token"}}
+        assert extract_auth(params) == "my-token"
+
+    def test_no_params(self):
+        assert extract_auth(None) is None
+
+    def test_no_auth(self):
+        assert extract_auth({"capability": "echo"}) is None
+
+    def test_auth_not_dict(self):
+        assert extract_auth({"auth": "string"}) is None
+
+    def test_no_bearer(self):
+        assert extract_auth({"auth": {"type": "basic"}}) is None
+
+    def test_empty_params(self):
+        assert extract_auth({}) is None

anip_stdio-0.11.0/tests/test_server.py

@@ -0,0 +1,268 @@
+"""Integration tests for the ANIP stdio server — all 9 methods through handle_request()."""
+from __future__ import annotations
+
+import pytest
+from anip_service import ANIPService, Capability, InvocationContext
+from anip_core import (
+    CapabilityDeclaration,
+    CapabilityInput,
+    CapabilityOutput,
+    ResponseMode,
+    SideEffect,
+    SideEffectType,
+)
+
+from anip_stdio.server import AnipStdioServer
+
+
+# --- Test capability: echo ---
+
+def _echo_capability() -> Capability:
+    async def handler(ctx: InvocationContext, params: dict) -> dict:
+        return {"echo": params.get("message", ""), "invocation_id": ctx.invocation_id}
+
+    return Capability(
+        declaration=CapabilityDeclaration(
+            name="echo",
+            description="Echo the input back",
+            inputs=[CapabilityInput(name="message", type="string", required=True, description="message")],
+            output=CapabilityOutput(type="object", fields=["echo"]),
+            side_effect=SideEffect(type=SideEffectType.READ),
+            minimum_scope=["echo"],
+            response_modes=[ResponseMode.UNARY, ResponseMode.STREAMING],
+        ),
+        handler=handler,
+    )
+
+
+# --- Fixtures ---
+
+@pytest.fixture
+def service():
+    return ANIPService(
+        service_id="test-stdio-service",
+        capabilities=[_echo_capability()],
+        storage=":memory:",
+        authenticate=lambda bearer: "human:test@example.com" if bearer == "test-api-key" else None,
+    )
+
+
+@pytest.fixture
+def server(service):
+    return AnipStdioServer(service)
+
+
+def _req(method: str, params: dict | None = None, request_id: int = 1) -> dict:
+    """Build a JSON-RPC request."""
+    return {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params or {}}
+
+
+# --- Helper to issue a token via the server ---
+
+async def _issue_token(server: AnipStdioServer) -> str:
+    """Issue a token through the server and return the JWT string."""
+    resp = await server.handle_request(_req("anip.tokens.issue", {
+        "auth": {"bearer": "test-api-key"},
+        "subject": "agent:test-agent",
+        "scope": ["echo"],
+        "capability": "echo",
+        "caller_class": "internal",
+    }))
+    assert "result" in resp, f"Expected result, got: {resp}"
+    assert resp["result"]["issued"] is True
+    return resp["result"]["token"]
+
+
+# --- Tests ---
+
+class TestDiscovery:
+    async def test_returns_protocol_version(self, server):
+        resp = await server.handle_request(_req("anip.discovery"))
+        assert "result" in resp
+        assert "anip_discovery" in resp["result"]
+        assert "protocol" in resp["result"]["anip_discovery"]
+
+    async def test_contains_capabilities(self, server):
+        resp = await server.handle_request(_req("anip.discovery"))
+        caps = resp["result"]["anip_discovery"]["capabilities"]
+        assert "echo" in caps
+
+
+class TestManifest:
+    async def test_returns_manifest_and_signature(self, server):
+        resp = await server.handle_request(_req("anip.manifest"))
+        assert "result" in resp
+        result = resp["result"]
+        assert "manifest" in result
+        assert "signature" in result
+        assert isinstance(result["manifest"], dict)
+        assert isinstance(result["signature"], str)
+
+
+class TestJWKS:
+    async def test_returns_keys(self, server):
+        resp = await server.handle_request(_req("anip.jwks"))
+        assert "result" in resp
+        assert "keys" in resp["result"]
+        assert isinstance(resp["result"]["keys"], list)
+
+
+class TestTokensIssue:
+    async def test_issue_with_api_key(self, server):
+        resp = await server.handle_request(_req("anip.tokens.issue", {
+            "auth": {"bearer": "test-api-key"},
+            "subject": "agent:test-agent",
+            "scope": ["echo"],
+            "capability": "echo",
+        }))
+        assert "result" in resp
+        result = resp["result"]
+        assert result["issued"] is True
+        assert "token" in result
+        assert "token_id" in result
+        assert "expires" in result
+
+    async def test_issue_without_auth_returns_error(self, server):
+        resp = await server.handle_request(_req("anip.tokens.issue", {
+            "subject": "agent:test-agent",
+            "scope": ["echo"],
+        }))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32001
+
+    async def test_issue_with_bad_key_returns_error(self, server):
+        resp = await server.handle_request(_req("anip.tokens.issue", {
+            "auth": {"bearer": "wrong-key"},
+            "subject": "agent:test-agent",
+            "scope": ["echo"],
+        }))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32001
+
+
+class TestInvoke:
+    async def test_invoke_with_jwt(self, server):
+        token_jwt = await _issue_token(server)
+        resp = await server.handle_request(_req("anip.invoke", {
+            "auth": {"bearer": token_jwt},
+            "capability": "echo",
+            "parameters": {"message": "hello"},
+            "client_reference_id": "ref-001",
+        }))
+        assert "result" in resp
+        result = resp["result"]
+        assert result["success"] is True
+        assert result["result"]["echo"] == "hello"
+        assert "invocation_id" in result
+
+    async def test_invoke_without_auth_returns_error(self, server):
+        resp = await server.handle_request(_req("anip.invoke", {
+            "capability": "echo",
+            "parameters": {"message": "hello"},
+        }))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32001
+
+    async def test_invoke_streaming(self, server):
+        token_jwt = await _issue_token(server)
+        resp = await server.handle_request(_req("anip.invoke", {
+            "auth": {"bearer": token_jwt},
+            "capability": "echo",
+            "parameters": {"message": "streamed"},
+            "stream": True,
+        }))
+        # Streaming returns a list: [notifications..., final_response]
+        assert isinstance(resp, list)
+        assert len(resp) >= 1
+        final = resp[-1]
+        assert "result" in final
+        assert final["result"]["success"] is True
+
+
+class TestPermissions:
+    async def test_discover_permissions(self, server):
+        token_jwt = await _issue_token(server)
+        resp = await server.handle_request(_req("anip.permissions", {
+            "auth": {"bearer": token_jwt},
+        }))
+        assert "result" in resp
+        # PermissionResponse has available/restricted/denied
+        result = resp["result"]
+        assert "available" in result or "restricted" in result or "denied" in result
+
+    async def test_permissions_without_auth(self, server):
+        resp = await server.handle_request(_req("anip.permissions", {}))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32001
+
+
+class TestAuditQuery:
+    async def test_audit_after_invocation(self, server):
+        token_jwt = await _issue_token(server)
+
+        # Invoke something to create audit entries
+        await server.handle_request(_req("anip.invoke", {
+            "auth": {"bearer": token_jwt},
+            "capability": "echo",
+            "parameters": {"message": "audit-test"},
+        }))
+
+        # Query audit
+        resp = await server.handle_request(_req("anip.audit.query", {
+            "auth": {"bearer": token_jwt},
+            "capability": "echo",
+        }))
+        assert "result" in resp
+        result = resp["result"]
+        assert "entries" in result
+        assert "count" in result
+
+    async def test_audit_without_auth(self, server):
+        resp = await server.handle_request(_req("anip.audit.query", {}))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32001
+
+
+class TestCheckpointsList:
+    async def test_list_checkpoints(self, server):
+        resp = await server.handle_request(_req("anip.checkpoints.list", {"limit": 5}))
+        assert "result" in resp
+        result = resp["result"]
+        assert "checkpoints" in result
+        assert isinstance(result["checkpoints"], list)
+
+
+class TestCheckpointsGet:
+    async def test_get_missing_checkpoint(self, server):
+        resp = await server.handle_request(_req("anip.checkpoints.get", {
+            "id": "cp-nonexistent",
+        }))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32004
+
+    async def test_get_missing_id(self, server):
+        resp = await server.handle_request(_req("anip.checkpoints.get", {}))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32004
+
+
+class TestErrorHandling:
+    async def test_unknown_method(self, server):
+        resp = await server.handle_request(_req("anip.nonexistent"))
+        assert "error" in resp
+        assert resp["error"]["code"] == -32601
+
+    async def test_invalid_request_missing_jsonrpc(self, server):
+        resp = await server.handle_request({"id": 1, "method": "anip.discovery"})
+        assert "error" in resp
+        assert resp["error"]["code"] == -32600
+
+    async def test_invalid_request_missing_id(self, server):
+        resp = await server.handle_request({"jsonrpc": "2.0", "method": "anip.discovery"})
+        assert "error" in resp
+        assert resp["error"]["code"] == -32600
+
+    async def test_invalid_request_missing_method(self, server):
+        resp = await server.handle_request({"jsonrpc": "2.0", "id": 1})
+        assert "error" in resp
+        assert resp["error"]["code"] == -32600