portmark 0.1.0__py3-none-any.whl

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/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/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")

portmark/cli.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+
+from .a2a import A2AAuthConfig, serve
+from .config import RuntimeConfig
+from .factory import make_demo_envelope, make_host
+from .logging_config import configure_logging
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Provider-neutral portable agent runtime")
+    parser.add_argument("--host-id", help="host identity used for permit audience and signing issuer")
+    parser.add_argument("--provider-endpoint", help="generic HTTP model-provider endpoint")
+    parser.add_argument("--wasm-component", help="Wasm capsule (.wasm or .wat) implementing the WIT resume ABI")
+    parser.add_argument("--store-path", help="SQLite path for durable nonces, checkpoints, and audit heads")
+    parser.add_argument("--policy-path", help="JSON host policy path")
+    parser.add_argument("--trust-registry-path", help="JSON trust registry path for envelope signing keys")
+    parser.add_argument("--reload-policy", action="store_true", help="reload the JSON host policy before each run")
+    parser.add_argument("--log-level", help="logging level")
+    parser.add_argument("--log-json", action="store_true", help="emit structured JSON logs")
+    parser.add_argument("--enable-hsts", action="store_true", help="emit HSTS header when served behind HTTPS")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    demo = subparsers.add_parser("demo")
+    demo.add_argument("goal", nargs="?", default="find portable agent architecture references")
+    server = subparsers.add_parser("serve")
+    server.add_argument("--bind", default="127.0.0.1")
+    server.add_argument("--port", type=int, default=8080)
+    server.add_argument("--a2a-token", help="require this bearer token for A2A message/send requests")
+    args = parser.parse_args()
+    from .storage import SQLiteRuntimeStore
+
+    config = RuntimeConfig.from_environment().merged_with_args(args)
+    configure_logging(config.log_level, config.log_json)
+    store = SQLiteRuntimeStore(config.store_path) if config.store_path else None
+    host = make_host(
+        config.provider_endpoint,
+        host_id=config.host_id,
+        wasm_component=config.wasm_component,
+        store=store,
+        policy_path=config.policy_path,
+        trust_registry_path=config.trust_registry_path,
+        reload_policy=config.reload_policy,
+    )
+    if args.command == "demo":
+        provider = "wasm" if config.wasm_component else ("http" if config.provider_endpoint else "deterministic")
+        result = host.run(make_demo_envelope(host, args.goal, provider))
+        print(json.dumps(asdict(result), indent=2))
+    else:
+        serve(host, args.bind, args.port, A2AAuthConfig(config.a2a_token) if config.a2a_token else None, config.enable_hsts)
+
+
+if __name__ == "__main__":
+    main()

portmark/component_bindings.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import Any
+
+from .models import AgentState, ProviderDecision
+
+
+WIT_PACKAGE = "portmark:agent@1.0.0"
+WIT_WORLD = "portmark"
+WIT_ABI = "portmark-json-lowered-v1"
+
+
+def component_context(state: AgentState, available_tools: tuple[str, ...]) -> dict[str, Any]:
+    return {
+        "wit": {"package": WIT_PACKAGE, "world": WIT_WORLD, "abi": WIT_ABI},
+        "state": asdict(state),
+        "available_tools": list(available_tools),
+    }
+
+
+def component_checkpoint(state: AgentState) -> dict[str, Any]:
+    return {
+        "task_id": state.task_id,
+        "step": state.step,
+        "tool_calls": state.tool_calls,
+        "memory": state.memory,
+        "messages": state.messages,
+    }
+
+
+def encode_component_input(value: dict[str, Any]) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"))
+
+
+def decode_component_decision(raw: str, available_tools: tuple[str, ...]) -> ProviderDecision:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise RuntimeError("Wasm component returned malformed decision JSON") from error
+    if not isinstance(value, dict):
+        raise RuntimeError("Wasm component decision must be a JSON object")
+    outcome = value.get("outcome")
+    if outcome == "tool":
+        request = value.get("request")
+        if not isinstance(request, dict):
+            raise RuntimeError("Wasm component tool decision is missing a request")
+        name = request.get("name")
+        if not isinstance(name, str) or not name:
+            raise RuntimeError("Wasm component tool decision has an invalid tool name")
+        if name not in available_tools:
+            return ProviderDecision("fail", content={"error": "required capability unavailable"})
+        arguments = _decode_json_object(request.get("arguments_json", "{}"), "tool arguments")
+        return ProviderDecision("tool", name, arguments)
+    if outcome == "completed":
+        return ProviderDecision("complete", content=_decode_json_value(value.get("content_json", "null"), "completion content"))
+    if outcome == "awaiting-input":
+        return ProviderDecision("await_input", content=_decode_json_value(value.get("content_json", "null"), "awaiting-input content"))
+    if outcome == "migrate":
+        destination = value.get("destination")
+        if not isinstance(destination, str) or not destination:
+            raise RuntimeError("Wasm component migration decision has an invalid destination")
+        return ProviderDecision("migrate", destination=destination)
+    if outcome == "failed":
+        return ProviderDecision("fail", content=_decode_json_value(value.get("content_json", "null"), "failure content"))
+    if outcome == "suspended":
+        return ProviderDecision("await_input", content=_decode_json_value(value.get("content_json", "null"), "suspension content"))
+    raise RuntimeError("Wasm component returned an unknown outcome")
+
+
+def _decode_json_object(raw: Any, label: str) -> dict[str, Any]:
+    value = _decode_json_value(raw, label)
+    if not isinstance(value, dict):
+        raise RuntimeError(f"Wasm component {label} must decode to a JSON object")
+    return value
+
+
+def _decode_json_value(raw: Any, label: str) -> Any:
+    if not isinstance(raw, str):
+        raise RuntimeError(f"Wasm component {label} must be encoded as a JSON string")
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise RuntimeError(f"Wasm component {label} is malformed JSON") from error

portmark/config.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    host_id: str = "host:local-demo"
+    provider_endpoint: str | None = None
+    wasm_component: str | None = None
+    store_path: str | None = None
+    policy_path: str | None = None
+    trust_registry_path: str | None = None
+    reload_policy: bool = False
+    a2a_token: str | None = None
+    log_level: str = "INFO"
+    log_json: bool = False
+    enable_hsts: bool = False
+
+    @classmethod
+    def from_environment(cls) -> "RuntimeConfig":
+        return cls(
+            host_id=os.environ.get("PORTMARK_HOST_ID", "host:local-demo"),
+            provider_endpoint=os.environ.get("PORTMARK_PROVIDER_ENDPOINT"),
+            wasm_component=os.environ.get("PORTMARK_WASM_COMPONENT"),
+            store_path=os.environ.get("PORTMARK_STORE_PATH"),
+            policy_path=os.environ.get("PORTMARK_POLICY_PATH"),
+            trust_registry_path=os.environ.get("PORTMARK_TRUST_REGISTRY_PATH"),
+            reload_policy=os.environ.get("PORTMARK_RELOAD_POLICY") == "1",
+            a2a_token=os.environ.get("PORTMARK_A2A_TOKEN"),
+            log_level=os.environ.get("PORTMARK_LOG_LEVEL", "INFO"),
+            log_json=os.environ.get("PORTMARK_LOG_JSON") == "1",
+            enable_hsts=os.environ.get("PORTMARK_ENABLE_HSTS") == "1",
+        )
+
+    def merged_with_args(self, args) -> "RuntimeConfig":
+        return RuntimeConfig(
+            host_id=args.host_id or self.host_id,
+            provider_endpoint=args.provider_endpoint or self.provider_endpoint,
+            wasm_component=args.wasm_component or self.wasm_component,
+            store_path=args.store_path or self.store_path,
+            policy_path=args.policy_path or self.policy_path,
+            trust_registry_path=args.trust_registry_path or self.trust_registry_path,
+            reload_policy=bool(args.reload_policy or self.reload_policy),
+            a2a_token=getattr(args, "a2a_token", None) or self.a2a_token,
+            log_level=args.log_level or self.log_level,
+            log_json=bool(args.log_json or self.log_json),
+            enable_hsts=bool(args.enable_hsts or self.enable_hsts),
+        )

portmark/factory.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+import time
+
+from .host import AgentHost
+from .models import AgentEnvelope, AgentManifest, AgentState, Permit, ResourceBudget, ToolGrant
+from .policy import load_host_policy
+from .providers import DeterministicProvider, GenericHttpProvider, WasmDecisionProvider
+from .security import AttestationPolicy, EnvelopeSigner, EnvelopeSigningIdentity, HmacEnvelopeSigner, HostPolicy, load_trust_registry
+from .storage import RuntimeStore, SQLiteRuntimeStore
+from .tools import demo_registry
+
+
+HOST_ID = "host:local-demo"
+
+
+def signer_from_environment(host_id: str = HOST_ID, trust_registry_path: str | None = None) -> EnvelopeSigningIdentity:
+    registry = load_trust_registry(trust_registry_path) if trust_registry_path else None
+    raw_private_key = os.environ.get("PORTMARK_ED25519_PRIVATE_KEY_B64")
+    if raw_private_key:
+        import base64
+
+        padding = "=" * (-len(raw_private_key) % 4)
+        private_key = base64.urlsafe_b64decode(raw_private_key + padding)
+        return EnvelopeSigner.from_private_key_bytes(
+            os.environ.get("PORTMARK_SIGNING_KEY_ID", "env-ed25519-key"),
+            os.environ.get("PORTMARK_SIGNING_ISSUER", host_id),
+            private_key,
+            tuple(os.environ.get("PORTMARK_ALLOWED_AUDIENCES", host_id).split(",")),
+            registry,
+        )
+    if os.environ.get("PORTMARK_ALLOW_LEGACY_HMAC") == "1":
+        raw = os.environ.get("PORTMARK_SIGNING_KEY", "development-only-signing-key-change-me")
+        return HmacEnvelopeSigner(hashlib.sha256(raw.encode()).digest())
+    return EnvelopeSigner.generate(issuer=host_id, allowed_audiences=(host_id,))
+
+
+def make_host(
+    provider_endpoint: str | None = None,
+    host_id: str = HOST_ID,
+    signer: EnvelopeSigningIdentity | None = None,
+    wasm_component: str | None = None,
+    store: RuntimeStore | None = None,
+    attestation_policy: AttestationPolicy | None = None,
+    policy_path: str | None = None,
+    trust_registry_path: str | None = None,
+    reload_policy: bool = False,
+) -> AgentHost:
+    providers = {"deterministic": DeterministicProvider()}
+    if provider_endpoint:
+        providers["http"] = GenericHttpProvider(provider_endpoint, os.environ.get("MODEL_PROVIDER_TOKEN"))
+    if wasm_component:
+        providers["wasm"] = WasmDecisionProvider.from_file(wasm_component)
+    configured_policy_path = policy_path or os.environ.get("PORTMARK_POLICY_PATH")
+    configured_trust_registry_path = trust_registry_path or os.environ.get("PORTMARK_TRUST_REGISTRY_PATH")
+    policy_loader = (lambda: load_host_policy(configured_policy_path, host_id)) if configured_policy_path else None
+    policy = policy_loader() if policy_loader else HostPolicy(
+        host_id,
+        grants=(ToolGrant("catalog.search", {"max_limit": 5}), ToolGrant("payments.reserve", {"max_amount": 100, "currency": "USD"})),
+        budget=ResourceBudget(max_steps=10, max_tool_calls=5, max_output_bytes=65_536),
+        tool_impacts={"catalog.search": "low", "payments.reserve": "external-payment"},
+    )
+    configured_store = store
+    if configured_store is None and os.environ.get("PORTMARK_STORE_PATH"):
+        configured_store = SQLiteRuntimeStore(os.environ["PORTMARK_STORE_PATH"])
+    return AgentHost(
+        host_id,
+        signer or signer_from_environment(host_id, configured_trust_registry_path),
+        policy,
+        demo_registry(),
+        providers,
+        configured_store,
+        attestation_policy,
+        policy_loader,
+        reload_policy,
+    )
+
+
+def make_demo_envelope(host: AgentHost, goal: str, provider: str = "deterministic") -> AgentEnvelope:
+    configured = host.providers.get(provider)
+    digest = getattr(configured, "component_digest", "python:reference-agent-v1")
+    manifest = AgentManifest("agent:demo", "1.0.0", provider, ("catalog.search", "payments.reserve"), digest)
+    permit = Permit(
+        issuer=getattr(host.signer, "issuer", host.host_id), subject=manifest.agent_id, audience=host.host_id,
+        expires_at=int(time.time()) + 3600, nonce=secrets.token_hex(16),
+        grants=(ToolGrant("catalog.search", {"max_limit": 3}),),
+        budget=ResourceBudget(max_steps=6, max_tool_calls=2, max_output_bytes=32_768),
+    )
+    return host.signer.seal(AgentEnvelope(manifest, permit, AgentState(secrets.token_hex(8), goal)))