portmark 0.1.0__tar.gz

portmark-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

portmark-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: portmark
+Version: 0.1.0
+Summary: Provider-neutral, capability-secured portable agent reference runtime
+License-Expression: MIT
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Dynamic: license-file

portmark-0.1.0/README.md

@@ -0,0 +1,211 @@
+# Portmark
+
+[![CI](https://github.com/Itsthewayofyou/portmark/actions/workflows/ci.yml/badge.svg)](https://github.com/Itsthewayofyou/portmark/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Run someone else's AI agent on your machine without trusting it.**
+
+An agent arrives as a signed envelope carrying its manifest, permit, state checkpoint, and
+component identity. Your host verifies the signature itself, intersects the agent's requested
+authority with your local policy, and mediates every single tool call. The agent's model
+proposes actions; it never executes them and never sees your credentials.
+
+## What the host is guaranteed
+
+These are enforced by the host, not requested politely from the agent:
+
+- **Your policy is a hard ceiling.** `effective_permit` intersects three sets: what the agent's
+  manifest asks for, what its permit grants, and what your host policy allows. An agent arriving
+  with a permit for `*` still gets only what you allow.
+  ([`security.py`](src/portmark/security.py), `intersect_grants`)
+- **Budgets take the minimum.** Steps, tool calls, and output bytes are each `min(agent, host)`.
+  A visitor cannot raise its own limits. ([`models.py`](src/portmark/models.py), `ResourceBudget.intersect`)
+- **Wasm capsules declaring any import are refused, not sandboxed.** The guest therefore has no
+  filesystem, network, process, environment, clock, randomness, or credential access at all.
+  ([`wasm_runner.mjs`](src/portmark/wasm_runner.mjs))
+- **Permits can only narrow on migration.** One hop, bound to the named destination, grants and
+  budgets cannot increase, and further delegation is disabled. A visiting agent cannot accept a
+  narrow permit at your door and widen it on the next hop.
+- **Every run is auditable.** A hash-chained audit log records the accepted agent, the active
+  policy version and hash, each proposal, and each executed tool call.
+
+Portmark runs entirely offline by default. The deterministic provider is for demonstrations and
+tests. `GenericHttpProvider` connects the same runtime to llama.cpp, Ollama through an adapter, a
+hosted model gateway, or anything implementing the small decision contract below.
+
+## Quickstart
+
+```bash
+git clone https://github.com/Itsthewayofyou/portmark.git
+cd portmark
+PYTHONPATH=src python -m portmark.cli demo "research modern mobile agents"
+```
+
+No installation and no network access required. Examples below use bash; on PowerShell, write
+`$env:PYTHONPATH = "src"` on its own line instead of the inline prefix.
+
+## Security boundary
+
+```text
+A2A request / local CLI
+        |
+signed agent envelope
+        v
+Host verification -> permit intersection -> provider proposal
+                                             |
+                                 host validates every action
+                                             v
+                                  capability-scoped tools
+```
+
+The provider proposes actions but never receives host credentials and never authorizes its own
+tool calls. The host enforces subject, audience, expiry, replay nonce, tool grants, argument
+constraints, step budgets, tool-call budgets, output limits, and a hash-chained audit log.
+
+Host policy can be loaded from JSON and every run records the active policy version and hash in
+the audit log. High-impact tools such as external payments, destructive actions, credentialed
+access, and data-exfiltration-risk actions require signed approval tokens bound to the task,
+permit nonce, tool arguments, and active policy hash. See [POLICY.md](POLICY.md) for the policy
+format, reload behavior, approval-token contract, and audit events.
+
+Migration requires `delegation_allowed` on the incoming permit. The source host can then create
+only a narrower, one-hop, destination-bound permit: the effective grants and budgets cannot
+increase, the audience changes to the named destination, the replay nonce is replaced, and
+further delegation is disabled. Both hosts must belong to the same configured trust domain in
+this reference implementation.
+
+Hosts can require signed confidential-computing attestation evidence before sensitive execution
+or delegated migration. The reference verifier binds the attested host identity, relying-party
+audience, approved measurement, freshness window, optional nonce, and verifier signature before
+the host runs the agent or emits a migration envelope. See [ATTESTATION.md](ATTESTATION.md) for
+the evidence format, verification flow, sealed-storage decision, and residual risks.
+
+Envelopes are signed with Ed25519 by default and verified through a key-ID-based trust registry.
+See [SIGNING_KEYS.md](SIGNING_KEYS.md) for key generation, rotation, revocation, and trust
+bootstrap guidance. The legacy HMAC signer is retained only for explicit dependency-free demos.
+
+## Run it
+
+Install the project for normal package usage:
+
+```bash
+python -m pip install -e .
+portmark demo "research modern mobile agents"
+```
+
+Execute the included Wasm capsule using the WIT-shaped `resume(context-json, checkpoint-json)`
+binding:
+
+```bash
+PYTHONPATH=src python -m portmark.cli --wasm-component capsules/research-agent.wasm.b64 demo "research modern mobile agents"
+```
+
+The host executes each capsule in a short-lived worker with a strict deadline and rejects every
+module declaring an import. Its signed SHA-256 digest is checked before execution. Tool actions
+returned by the capsule still pass through the same host permit and argument enforcement as
+model-provider proposals. See [WASM_COMPONENTS.md](WASM_COMPONENTS.md) for the WIT binding
+contract.
+
+Run tests:
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v
+```
+
+Run the A2A-facing HTTP service:
+
+```bash
+PYTHONPATH=src python -m portmark.cli serve --port 8080
+```
+
+Require bearer authentication for A2A message submission:
+
+```bash
+PORTMARK_A2A_TOKEN=change-me PYTHONPATH=src python -m portmark.cli serve --port 8080
+```
+
+The Agent Card is available at `/.well-known/agent-card.json`; signed envelopes are submitted to
+`/message:send` with the A2A JSON-RPC `message/send` method. See [A2A.md](A2A.md) for the Agent
+Card fields, request shape, authentication profile, and error behavior.
+
+Persist replay nonces, checkpoints, and audit heads with SQLite:
+
+```bash
+PYTHONPATH=src python -m portmark.cli --store-path runtime.sqlite demo "research modern mobile agents"
+```
+
+See [RUNTIME_STORAGE.md](RUNTIME_STORAGE.md) for the storage schema, transaction guarantees, and
+recovery behavior.
+
+Load policy from JSON:
+
+```bash
+PYTHONPATH=src python -m portmark.cli --policy-path examples/host-policy.json --reload-policy demo "research modern mobile agents"
+```
+
+See [OPERATIONS.md](OPERATIONS.md) for runtime configuration, trust registry format, policy
+updates, audit verification, backup/restore, and incident response.
+
+## Generic provider contract
+
+Start the CLI with `--provider-endpoint URL`. The runtime sends:
+
+```json
+{"state": {"goal": "..."}, "available_tools": ["catalog.search"]}
+```
+
+The provider responds with one decision:
+
+```json
+{"kind": "tool", "tool": "catalog.search", "arguments": {"query": "...", "limit": 3}}
+```
+
+or:
+
+```json
+{"kind": "complete", "content": {"answer": "..."}}
+```
+
+`MODEL_PROVIDER_TOKEN` optionally supplies a bearer token. It is held by the host adapter, not
+included in the portable envelope.
+
+## WebAssembly component boundary
+
+[`wit/portmark.wit`](wit/portmark.wit) defines the Wasm Component Model decision interface. The
+capsule exports a checkpoint-based `resume` operation that receives structured context and
+checkpoint JSON and returns a structured outcome. A compiled capsule therefore cannot directly
+acquire filesystem, network, process, database, or credential access; the host must explicitly
+validate and mediate every requested action.
+
+The runnable Node WebAssembly adapter uses the JSON-lowered WIT binding documented in
+[WASM_COMPONENTS.md](WASM_COMPONENTS.md). Strong migration is implemented as
+checkpoint-and-resume: native stacks, threads, sockets, and file descriptors never cross hosts.
+
+## Production status
+
+Portmark is **reference-complete with six named substitution points**. Signing and trust,
+transactional persistence, the A2A 1.0 surface, external policy with approval gates, WIT-shaped
+Wasm execution, and confidential-computing attestation are all implemented and covered by the
+regression suite. [PRODUCTION_TASKS.md](PRODUCTION_TASKS.md) holds the task-level record.
+
+It is a reference implementation: read it, fork it, and substitute the seams below. It is not
+intended as a drop-in production dependency.
+
+## Deployment integration points
+
+Portmark is provider-neutral by design. The following are deliberate seams for the deploying
+environment to fill, not unfinished work. Each has a working reference implementation and a
+stable interface to substitute against.
+
+| Seam | Reference implementation | What a production deployment supplies |
+| --- | --- | --- |
+| Trust registry | JSON registry loaded from `PORTMARK_TRUST_REGISTRY_PATH`, with key IDs, issuers, audiences, validity windows, and revocation | PKI- or KMS-backed key distribution and rotation |
+| Storage | `SQLiteRuntimeStore` behind the `RuntimeStore` protocol | a shared database for multi-host deployments |
+| Wasm bindings | WIT contract executed through a JSON-lowered adapter on Node | native Component Model bindings once a Python runtime exposes them |
+| A2A types | generated-style A2A 1.0 subset isolated in `a2a_types.py` | the official generated SDK when a Python package is published |
+| Attestation | signed mock evidence verified by `AttestationPolicy` against RATS-style roles | the target platform's TEE quote verifier and sealed-storage backend |
+| Approvals | locally signed approval tokens bound to task, nonce, arguments, and policy hash | an approval service tied to operator identity and change management |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

portmark-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "portmark"
+version = "0.1.0"
+description = "Provider-neutral, capability-secured portable agent reference runtime"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["cryptography>=42"]
+
+[project.scripts]
+portmark = "portmark.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+portmark = ["wasm_runner.mjs"]

portmark-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

portmark-0.1.0/src/portmark/__init__.py

@@ -0,0 +1,7 @@
+"""Portable, provider-neutral agent runtime."""
+
+from .host import AgentHost
+from .models import AgentEnvelope, AgentManifest, AgentState, Permit
+
+__all__ = ["AgentEnvelope", "AgentHost", "AgentManifest", "AgentState", "Permit"]
+

portmark-0.1.0/src/portmark/a2a.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import secrets
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from .a2a_types import A2ARequestError, error_response, make_agent_card, parse_jsonrpc_request, success_response, task_from_run_result
+from .host import AgentHost
+from .models import AgentEnvelope, AgentManifest, AgentState, AttestationEvidence, Permit, ResourceBudget, ToolGrant
+
+
+logger = logging.getLogger(__name__)
+MAX_REQUEST_BYTES = 1_000_000
+
+
+def envelope_from_dict(value: dict[str, Any]) -> AgentEnvelope:
+    manifest = AgentManifest(**{**value["manifest"], "requested_tools": tuple(value["manifest"]["requested_tools"])})
+    permit_value = value["permit"]
+    permit = Permit(
+        issuer=permit_value["issuer"], subject=permit_value["subject"], audience=permit_value["audience"],
+        expires_at=permit_value["expires_at"], nonce=permit_value["nonce"],
+        grants=tuple(ToolGrant(**grant) for grant in permit_value["grants"]),
+        budget=ResourceBudget(**permit_value.get("budget", {})),
+        delegation_allowed=permit_value.get("delegation_allowed", False),
+        attestation=AttestationEvidence(**permit_value["attestation"]) if permit_value.get("attestation") else None,
+    )
+    return AgentEnvelope(
+        manifest=manifest,
+        permit=permit,
+        state=AgentState(**value["state"]),
+        previous_audit_hash=value.get("previous_audit_hash", ""),
+        signature_key_id=value.get("signature_key_id", ""),
+        signature=value["signature"],
+    )
+
+
+@dataclass(frozen=True)
+class A2AAuthConfig:
+    bearer_token: str | None = None
+    realm: str = "portmark"
+
+    @property
+    def required(self) -> bool:
+        return bool(self.bearer_token)
+
+
+def make_handler(host: AgentHost, auth: A2AAuthConfig | None = None, enable_hsts: bool = False):
+    auth_config = auth or A2AAuthConfig()
+
+    class A2AHandler(BaseHTTPRequestHandler):
+        server_version = "PortableAgentA2A/1.0"
+
+        def _json(self, status: int, value: Any, headers: dict[str, str] | None = None) -> None:
+            payload = json.dumps(value).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Referrer-Policy", "no-referrer")
+            self.send_header("Permissions-Policy", "geolocation=(), microphone=(), camera=()")
+            self.send_header("X-Frame-Options", "DENY")
+            self.send_header("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'; base-uri 'none'")
+            if enable_hsts:
+                self.send_header("Strict-Transport-Security", "max-age=31536000")
+            if headers:
+                for key, value in headers.items():
+                    self.send_header(key, value)
+            self.end_headers()
+            self.wfile.write(payload)
+
+        def do_GET(self) -> None:
+            if self.path == "/.well-known/agent-card.json":
+                self._json(200, make_agent_card(self._base_url(), auth_config.required))
+            else:
+                self._json(404, {"error": "not found"})
+
+        def do_POST(self) -> None:
+            if self.path != "/message:send":
+                self._json(404, error_response(None, -32601, "method not found"))
+                return
+            if not self._authorized(auth_config):
+                self._json(
+                    401,
+                    error_response(None, -32001, "unauthorized"),
+                    {"WWW-Authenticate": f'Bearer realm="{auth_config.realm}"'},
+                )
+                return
+            request_id: str | int | None = None
+            try:
+                if self.headers.get("Content-Type", "").split(";", 1)[0].strip().lower() != "application/json":
+                    raise A2ARequestError(-32600, "invalid request", 415)
+                try:
+                    size = int(self.headers.get("Content-Length", "0"))
+                except ValueError as exc:
+                    raise A2ARequestError(-32600, "invalid request", 400) from exc
+                if size <= 0 or size > MAX_REQUEST_BYTES:
+                    raise A2ARequestError(-32600, "invalid request", 413)
+                try:
+                    payload = json.loads(self.rfile.read(size))
+                except json.JSONDecodeError as exc:
+                    raise A2ARequestError(-32700, "parse error", 400) from exc
+                request = parse_jsonrpc_request(payload)
+                request_id = request.id
+                envelope = envelope_from_dict(request.params.portmark_envelope)
+                result = host.run(envelope)
+                self._json(200, success_response(request.id, task_from_run_result(result)))
+            except A2ARequestError as exc:
+                self._json(exc.http_status, error_response(exc.request_id, exc.code, exc.message))
+            except Exception:
+                logger.exception("A2A message submission failed")
+                self._json(400, error_response(request_id, -32000, "message submission failed"))
+
+        def _base_url(self) -> str:
+            return f"http://{self.headers.get('Host', '127.0.0.1')}"
+
+        def _authorized(self, config: A2AAuthConfig) -> bool:
+            if not config.bearer_token:
+                return True
+            header = self.headers.get("Authorization", "")
+            prefix = "Bearer "
+            if not header.startswith(prefix):
+                return False
+            return secrets.compare_digest(header[len(prefix):], config.bearer_token)
+
+        def log_message(self, format: str, *args: Any) -> None:
+            return
+
+    return A2AHandler
+
+
+def auth_from_environment() -> A2AAuthConfig:
+    return A2AAuthConfig(os.environ.get("PORTMARK_A2A_TOKEN"))
+
+
+def serve(host: AgentHost, bind: str, port: int, auth: A2AAuthConfig | None = None, enable_hsts: bool = False) -> None:
+    ThreadingHTTPServer((bind, port), make_handler(host, auth or auth_from_environment(), enable_hsts)).serve_forever()

portmark-0.1.0/src/portmark/a2a_types.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+A2A_PROTOCOL_VERSION = "1.0"
+JSONRPC_VERSION = "2.0"
+MESSAGE_SEND_METHOD = "message/send"
+
+
+class A2ARequestError(RuntimeError):
+    def __init__(self, code: int, message: str, http_status: int = 400, request_id: str | int | None = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.http_status = http_status
+        self.request_id = request_id
+
+
+@dataclass(frozen=True)
+class AgentInterface:
+    url: str
+    protocolBinding: str = "JSONRPC"
+    protocolVersion: str = A2A_PROTOCOL_VERSION
+
+
+@dataclass(frozen=True)
+class AgentCapabilities:
+    streaming: bool = False
+    pushNotifications: bool = False
+    stateTransitionHistory: bool = False
+
+
+@dataclass(frozen=True)
+class AgentSkill:
+    id: str
+    name: str
+    description: str
+    inputModes: tuple[str, ...] = ("application/json",)
+    outputModes: tuple[str, ...] = ("application/json",)
+
+
+@dataclass(frozen=True)
+class SecurityScheme:
+    type: str
+    scheme: str | None = None
+    bearerFormat: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {key: value for key, value in asdict(self).items() if value is not None}
+
+
+@dataclass(frozen=True)
+class AgentCard:
+    name: str
+    description: str
+    url: str
+    version: str
+    supportedInterfaces: tuple[AgentInterface, ...]
+    capabilities: AgentCapabilities
+    defaultInputModes: tuple[str, ...]
+    defaultOutputModes: tuple[str, ...]
+    skills: tuple[AgentSkill, ...]
+    protocolVersion: str = A2A_PROTOCOL_VERSION
+    securitySchemes: dict[str, SecurityScheme] = field(default_factory=dict)
+    security: tuple[dict[str, tuple[str, ...]], ...] = ()
+    securityRequirements: tuple[dict[str, tuple[str, ...]], ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["securitySchemes"] = {key: scheme.to_dict() for key, scheme in self.securitySchemes.items()}
+        if not payload["securitySchemes"]:
+            payload.pop("securitySchemes")
+        if not payload["security"]:
+            payload.pop("security")
+        if not payload["securityRequirements"]:
+            payload.pop("securityRequirements")
+        return payload
+
+
+@dataclass(frozen=True)
+class Message:
+    messageId: str
+    role: str
+    parts: tuple[dict[str, Any], ...]
+    taskId: str | None = None
+    contextId: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class MessageSendParams:
+    message: Message
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def portmark_envelope(self) -> dict[str, Any]:
+        envelope = self.metadata.get("portmark_envelope")
+        if not isinstance(envelope, dict):
+            raise A2ARequestError(-32602, "invalid params")
+        return envelope
+
+
+@dataclass(frozen=True)
+class JSONRPCRequest:
+    jsonrpc: str
+    id: str | int | None
+    method: str
+    params: MessageSendParams
+
+
+@dataclass(frozen=True)
+class TaskStatus:
+    state: str
+
+
+@dataclass(frozen=True)
+class Task:
+    id: str
+    status: TaskStatus
+    artifacts: tuple[dict[str, Any], ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def make_agent_card(base_url: str, require_bearer_auth: bool) -> dict[str, Any]:
+    security_schemes: dict[str, SecurityScheme] = {}
+    security: tuple[dict[str, tuple[str, ...]], ...] = ()
+    if require_bearer_auth:
+        security_schemes = {"bearer": SecurityScheme("http", "bearer", "opaque")}
+        security = ({"bearer": ()},)
+    card = AgentCard(
+        name="Portable Wasm Agent Host",
+        description="Runs signed, capability-limited portable agents",
+        url=f"{base_url}/message:send",
+        version="0.1.0",
+        supportedInterfaces=(AgentInterface(f"{base_url}/message:send"),),
+        capabilities=AgentCapabilities(),
+        defaultInputModes=("application/json",),
+        defaultOutputModes=("application/json",),
+        skills=(AgentSkill("portmark", "Portmark agent execution", "Execute a signed Portmark agent envelope"),),
+        securitySchemes=security_schemes,
+        security=security,
+        securityRequirements=security,
+    )
+    return card.to_dict()
+
+
+def parse_jsonrpc_request(value: Any) -> JSONRPCRequest:
+    if not isinstance(value, dict):
+        raise A2ARequestError(-32600, "invalid request")
+    request_id = _valid_request_id(value.get("id"))
+    if value.get("jsonrpc") != JSONRPC_VERSION:
+        raise A2ARequestError(-32600, "invalid request", request_id=request_id)
+    method = value.get("method")
+    if not isinstance(method, str):
+        raise A2ARequestError(-32600, "invalid request", request_id=request_id)
+    if method != MESSAGE_SEND_METHOD:
+        raise A2ARequestError(-32601, "method not found", request_id=request_id)
+    return JSONRPCRequest(JSONRPC_VERSION, request_id, method, parse_message_send_params(value.get("params")))
+
+
+def parse_message_send_params(value: Any) -> MessageSendParams:
+    if not isinstance(value, dict):
+        raise A2ARequestError(-32602, "invalid params")
+    message = _parse_message(value.get("message"))
+    metadata = _optional_object(value.get("metadata"), "metadata")
+    params = MessageSendParams(message, metadata)
+    params.portmark_envelope
+    return params
+
+
+def task_from_run_result(result: Any) -> dict[str, Any]:
+    return Task(
+        id=result.task_id,
+        status=TaskStatus(_task_state(result.status)),
+        artifacts=(asdict(result),),
+        metadata={"portmark_status": result.status},
+    ).to_dict()
+
+
+def success_response(request_id: str | int | None, result: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": JSONRPC_VERSION, "id": request_id, "result": result}
+
+
+def error_response(request_id: str | int | None, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": JSONRPC_VERSION, "id": request_id, "error": {"code": code, "message": message}}
+
+
+def _parse_message(value: Any) -> Message:
+    if not isinstance(value, dict):
+        raise A2ARequestError(-32602, "invalid params")
+    message_id = value.get("messageId")
+    role = value.get("role")
+    parts = value.get("parts")
+    if not isinstance(message_id, str) or not message_id:
+        raise A2ARequestError(-32602, "invalid params")
+    if role not in {"user", "agent"}:
+        raise A2ARequestError(-32602, "invalid params")
+    if not isinstance(parts, list) or not parts or not all(isinstance(part, dict) for part in parts):
+        raise A2ARequestError(-32602, "invalid params")
+    return Message(
+        message_id,
+        role,
+        tuple(parts),
+        _optional_string(value.get("taskId"), "taskId"),
+        _optional_string(value.get("contextId"), "contextId"),
+        _optional_object(value.get("metadata"), "metadata"),
+    )
+
+
+def _optional_object(value: Any, name: str) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise A2ARequestError(-32602, "invalid params")
+    return value
+
+
+def _optional_string(value: Any, name: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value:
+        raise A2ARequestError(-32602, "invalid params")
+    return value
+
+
+def _valid_request_id(value: Any) -> str | int | None:
+    if value is None or isinstance(value, (str, int)):
+        return value
+    return None
+
+
+def _task_state(status: str) -> str:
+    return {"completed": "completed", "migrated": "completed", "failed": "failed"}.get(status, "working")