zu-core 0.2.0__tar.gz

zu_core-0.2.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Zu runtime artifacts
+*.db
+zu.db
+zu.yaml.local
+zu_review.jsonl
+*.review.jsonl
+# Per-agent cost telemetry ledger — machine-local run history, not source.
+cost.jsonl
+# A recorded replay path is learned per-run and machine-local — regenerated on
+# every successful run, not source. The agent ships; its track does not.
+track.json
+# …except the flagship example ships its track on purpose, as a demo of the
+# record/replay convergence (committed; re-runs show as ordinary modifications).
+!examples/agents/vet-appointment/track.json
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Claude Code local session state
+.claude/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Microsoft Office temp/lock files
+~$*
+
+# Internal design / strategy docs — kept local, never in the public repo
+*.docx
+*.pdf
+# BUILD.md is the internal build-sequence / deferred-gaps ledger — kept local.
+# (ARCHITECTURE.md is public: an onboarding agent needs the structural map.)
+docs/BUILD.md
+
+# Local secret — API key for live validation, never commit
+zu_demo_key.md
+*_key.md
+
+# Local PyPI publish token — never commit
+/pypi
+
+# Local Discord credentials (bot token / app secrets) — never commit
+/discord

zu_core-0.2.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: zu-core
+Version: 0.2.0
+Summary: Zu core: contracts, ports, registry, loop, event bus
+Project-URL: Homepage, https://github.com/k3-mt/zu
+Project-URL: Repository, https://github.com/k3-mt/zu
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# zu-core
+
+The small, stable core of Zu: the typed contracts, the six ports, the plugin
+registry, the interpreter loop, and the event bus. **It depends only on the
+standard library and Pydantic** — it physically cannot import a model SDK, a
+browser, or any concrete adapter. It should be readable in an afternoon.
+
+## What's inside
+
+| Module | Responsibility |
+|--------|----------------|
+| `contracts.py` | `TaskSpec`, `Result`, and the frozen `Event` envelope (types namespaced `harness.*` / `data.*`). |
+| `ports.py` | The six `Protocol` ports + the capability envelope (`CAP_*`, `EGRESS_OPEN`, `declared_envelope`). |
+| `registry.py` | The one registry the loop reads (entry points, decorators, config). |
+| `loop.py` | The interpreter loop: provider → tool → detectors → finalise → validators, with the escalation ladder and budgets. |
+| `bus.py` | The event bus: append-before-notify, with isolated destinations. |
+| `events.py` | The event taxonomy (the stable set of `harness.*` / `data.*` type constants). |
+| `sinks.py` | The in-memory default `EventSink`. |
+| `eventstore.py` / `codec.py` / `projections.py` | Shared filter contract, the encryption-at-rest seam, and rebuildable read-side views. |
+
+## The six ports
+
+`ModelProvider`, `Tool`, `Detector`, `Validator`, `SandboxBackend`, `EventSink`
+— each a runtime-checkable structural `Protocol`. A plugin implements the
+*shape*; it never subclasses a framework.
+
+This package registers **no plugins** — it defines the contracts every other
+package plugs into.
+
+## Tests
+
+`uv run pytest packages/zu-core` — deterministic, offline.

zu_core-0.2.0/README.md

@@ -0,0 +1,32 @@
+# zu-core
+
+The small, stable core of Zu: the typed contracts, the six ports, the plugin
+registry, the interpreter loop, and the event bus. **It depends only on the
+standard library and Pydantic** — it physically cannot import a model SDK, a
+browser, or any concrete adapter. It should be readable in an afternoon.
+
+## What's inside
+
+| Module | Responsibility |
+|--------|----------------|
+| `contracts.py` | `TaskSpec`, `Result`, and the frozen `Event` envelope (types namespaced `harness.*` / `data.*`). |
+| `ports.py` | The six `Protocol` ports + the capability envelope (`CAP_*`, `EGRESS_OPEN`, `declared_envelope`). |
+| `registry.py` | The one registry the loop reads (entry points, decorators, config). |
+| `loop.py` | The interpreter loop: provider → tool → detectors → finalise → validators, with the escalation ladder and budgets. |
+| `bus.py` | The event bus: append-before-notify, with isolated destinations. |
+| `events.py` | The event taxonomy (the stable set of `harness.*` / `data.*` type constants). |
+| `sinks.py` | The in-memory default `EventSink`. |
+| `eventstore.py` / `codec.py` / `projections.py` | Shared filter contract, the encryption-at-rest seam, and rebuildable read-side views. |
+
+## The six ports
+
+`ModelProvider`, `Tool`, `Detector`, `Validator`, `SandboxBackend`, `EventSink`
+— each a runtime-checkable structural `Protocol`. A plugin implements the
+*shape*; it never subclasses a framework.
+
+This package registers **no plugins** — it defines the contracts every other
+package plugs into.
+
+## Tests
+
+`uv run pytest packages/zu-core` — deterministic, offline.

zu_core-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "zu-core"
+version = "0.2.0"
+description = "Zu core: contracts, ports, registry, loop, event bus"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2"]        # nothing else — the core stays SDK-free
+
+[project.urls]
+Homepage = "https://github.com/k3-mt/zu"
+Repository = "https://github.com/k3-mt/zu"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zu_core"]

zu_core-0.2.0/src/zu_core/__init__.py

@@ -0,0 +1,142 @@
+"""Zu core — the small, stable runtime: contracts, ports, registry, loop, bus.
+
+Depends only on the standard library and Pydantic. It contains no model SDK,
+no domain branching, and no knowledge of any specific tool or provider.
+"""
+
+from __future__ import annotations
+
+from . import events
+from .bus import EventBus, SubscriberFailure
+from .codec import IdentityCodec, KeyProvider, PayloadCodec, decode_payload, encode_payload
+from .content import Action, Audio, Content, ContentPart, Image, Observation, Text
+from .contracts import Budget, Event, Result, Status, TaskSpec
+from .eventstore import ALLOWED_EVENT_FILTERS, event_matches, validate_filter
+from .ports import (
+    CAP_FS_READ,
+    CAP_FS_WRITE,
+    CAP_NET,
+    CAP_SANDBOX,
+    CAP_SUBPROCESS,
+    EGRESS_OPEN,
+    INTERFACE_ATTR,
+    INTERFACE_VERSION,
+    Capabilities,
+    Detector,
+    EventSink,
+    Finish,
+    ModelProvider,
+    ModelRequest,
+    ModelResponse,
+    Policy,
+    RunContext,
+    SandboxBackend,
+    Scope,
+    Severity,
+    Tool,
+    ToolCall,
+    ToolSpec,
+    Trigger,
+    TriggerEvent,
+    Validator,
+    Verdict,
+    declared_envelope,
+)
+from .projections import SessionState, SessionStore
+from .registry import (
+    REGISTRY,
+    IncompatibleInterfaceError,
+    LoadFailure,
+    Registry,
+    backend,
+    check_interface,
+    detector,
+    policy,
+    provider,
+    sink,
+    tool,
+    trigger,
+    validator,
+)
+from .security import SecurityBlock
+from .sinks import MemoryEventSink
+from .view import RENDER_KEYS, scope_event, scope_payload
+
+__all__ = [
+    # contracts
+    "Budget",
+    "Event",
+    "Result",
+    "Status",
+    "TaskSpec",
+    # multimodal content (the policy currency)
+    "Content",
+    "ContentPart",
+    "Text",
+    "Image",
+    "Audio",
+    "Observation",
+    "Action",
+    # event bus + taxonomy + projections + sinks + codec
+    "EventBus",
+    "SubscriberFailure",
+    "SessionStore",
+    "SessionState",
+    "MemoryEventSink",
+    "events",
+    "ALLOWED_EVENT_FILTERS",
+    "event_matches",
+    "validate_filter",
+    "IdentityCodec",
+    "PayloadCodec",
+    "KeyProvider",
+    "encode_payload",
+    "decode_payload",
+    "SecurityBlock",
+    "scope_event",
+    "scope_payload",
+    "RENDER_KEYS",
+    # ports
+    "CAP_NET",
+    "CAP_SANDBOX",
+    "CAP_FS_READ",
+    "CAP_FS_WRITE",
+    "CAP_SUBPROCESS",
+    "EGRESS_OPEN",
+    "INTERFACE_VERSION",
+    "INTERFACE_ATTR",
+    "declared_envelope",
+    "Capabilities",
+    "Detector",
+    "EventSink",
+    "Finish",
+    "ModelProvider",
+    "ModelRequest",
+    "ModelResponse",
+    "Policy",
+    "RunContext",
+    "SandboxBackend",
+    "Scope",
+    "Severity",
+    "Tool",
+    "ToolCall",
+    "ToolSpec",
+    "Trigger",
+    "TriggerEvent",
+    "Validator",
+    "Verdict",
+    # registry
+    "REGISTRY",
+    "LoadFailure",
+    "IncompatibleInterfaceError",
+    "check_interface",
+    "Registry",
+    "backend",
+    "detector",
+    "policy",
+    "provider",
+    "sink",
+    "tool",
+    "trigger",
+    "validator",
+]

zu_core-0.2.0/src/zu_core/bus.py

@@ -0,0 +1,129 @@
+"""The event bus — one source of truth, projected to destinations (step 3).
+
+There is exactly **one canonical event store** (an ``EventSink``) — the single
+source of truth for a run. The bus, on every publish:
+
+  1. **appends to the canonical store first** — durability before any side
+     effect. If that write fails, the failure propagates: you cannot have a run
+     whose source of truth is missing a record.
+  2. **then fans out to destinations** — projections (derived read models like
+     the session store) and secondary sinks (a shipper to OTel, a central log).
+     Each destination is isolated: one that raises does not stop the others,
+     and its failure is recorded (bounded) rather than disappearing.
+
+The canonical store defaults to an in-memory sink and is swapped for a durable
+one (SQLite, Postgres, the hosted central log) by configuration — same port,
+same semantics. Reads (`query`/`stream`/`count`) delegate to the canonical
+store, so there is never a second, divergent copy of the log in the bus.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections import deque
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import NamedTuple
+
+from .contracts import Event
+from .ports import EventSink
+from .sinks import MemoryEventSink
+
+log = logging.getLogger("zu.bus")
+
+Subscriber = Callable[[Event], "Awaitable[None] | None"]
+
+
+class SubscriberFailure(NamedTuple):
+    """A destination that raised while handling an event — recorded, not lost."""
+
+    subscriber: Subscriber
+    event: Event
+    error: Exception
+
+
+class EventBus:
+    def __init__(
+        self,
+        sink: EventSink | None = None,
+        *,
+        max_recorded_failures: int = 1000,
+    ) -> None:
+        # The single source of truth. Defaults to in-memory; configure a durable
+        # sink for production. Never accompanied by a second in-bus copy.
+        self.sink: EventSink = sink if sink is not None else MemoryEventSink()
+        self._subscribers: list[Subscriber] = []
+        # Secondary sinks attached via ``add_destination`` — tracked so ``aclose``
+        # can release their resources (e.g. a sqlite connection) too.
+        self._destinations: list[EventSink] = []
+        # Bounded so a long-lived bus can't leak memory via recorded failures.
+        self.subscriber_failures: deque[SubscriberFailure] = deque(
+            maxlen=max_recorded_failures
+        )
+
+    def subscribe(self, fn: Subscriber) -> None:
+        """Register a destination: a projection or any per-event handler."""
+        self._subscribers.append(fn)
+
+    def add_destination(self, sink: EventSink) -> None:
+        """Project the stream to a secondary sink (e.g. a shipper), isolated.
+
+        The secondary sink is a destination, not the source of truth: its
+        failures are isolated like any other subscriber's, never propagated.
+        """
+
+        async def _ship(event: Event) -> None:
+            await sink.append(event)
+
+        self._destinations.append(sink)
+        self.subscribe(_ship)
+
+    async def aclose(self) -> None:
+        """Release the canonical store and every secondary destination that holds
+        a resource (e.g. a sqlite connection). ``close`` is an optional capability
+        on a sink — a sink without one (the in-memory default, the per-append
+        jsonl sink) is simply skipped. Each close is isolated so one failure does
+        not strand the others. Idempotent: safe to call more than once.
+
+        The embed facade assembles a fresh bus per run, so calling this in a
+        ``finally`` is what keeps a long-lived ``Zu`` instance from leaking one
+        connection per ``run()``."""
+        for sink in [self.sink, *self._destinations]:
+            closer = getattr(sink, "close", None)
+            if closer is None:
+                continue
+            try:
+                result = closer()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:  # noqa: BLE001 - one close failure must not strand the rest
+                log.warning("sink %r failed to close: %s", sink, exc)
+
+    async def publish(self, event: Event) -> None:
+        # 1. canonical store first; a failure here propagates (source of truth).
+        await self.sink.append(event)
+
+        # 2. fan out to destinations, isolating any crash.
+        for fn in self._subscribers:
+            try:
+                result = fn(event)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as exc:  # noqa: BLE001 - one crash must not stop the rest
+                self.subscriber_failures.append(SubscriberFailure(fn, event, exc))
+                log.warning("destination %r failed on %s: %s", fn, event.type, exc)
+
+    # --- reads delegate to the single source of truth ---------------------
+
+    async def query(
+        self, flt: dict | None = None, *, limit: int | None = None, after_seq: int = 0
+    ) -> list[Event]:
+        return await self.sink.query(flt, limit=limit, after_seq=after_seq)
+
+    def stream(
+        self, flt: dict | None = None, *, batch_size: int = 500
+    ) -> AsyncIterator[Event]:
+        return self.sink.stream(flt, batch_size=batch_size)
+
+    async def count(self, flt: dict | None = None) -> int:
+        return await self.sink.count(flt)

zu_core-0.2.0/src/zu_core/codec.py

@@ -0,0 +1,98 @@
+"""Payload codec seam — the encryption-at-rest boundary for durable sinks.
+
+Encryption-at-rest is deferred as a *cipher* but not as a *format*: an
+append-only log is the worst place to retrofit encryption (you accumulate
+immutable plaintext), so the on-disk envelope is fixed now and the cipher is
+swappable later. Every stored payload blob begins with a one-byte **version
+tag** identifying the codec that wrote it, so a log can hold rows written by
+different codecs (e.g. plaintext rows from before encryption was enabled) and
+still be read back — the durable sink decodes each row by its own tag.
+
+Default is `IdentityCodec` (plaintext, zero dependencies). A real AES-256-GCM
+codec ships behind zu-backends' optional ``[encryption]`` extra. The AES codec
+binds the row's indexed columns as associated data (AAD), so a ciphertext can't
+be moved to — or have its index columns edited on — a different row. The default
+`IdentityCodec` is plaintext and provides *no* integrity: it accepts the ``aad``
+argument for interface parity but cannot bind it (there is no authentication tag
+over plaintext), so the move-resistance guarantee applies only once a cipher is
+configured. Managed keys (KMS / envelope encryption / rotation) are a future
+stage; the codec asks for a key, so swapping an env-var key for a KMS provider
+later is a contained change with no on-disk format impact.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PayloadCodec(Protocol):
+    version: int  # 0-255; the tag byte written as the first byte of each blob
+
+    def encode_body(self, plaintext: str, aad: bytes) -> bytes: ...
+
+    def decode_body(self, body: bytes, aad: bytes) -> str: ...
+
+
+@runtime_checkable
+class KeyProvider(Protocol):
+    """Supplies symmetric data keys *by id*, so a codec can rotate keys and a
+    deployment can source them from the KMS/secret store of its choice (AWS KMS,
+    GCP KMS, Vault, an HSM, …) — the choice belongs to whoever runs Zu, never
+    baked in here. The codec never holds a long-lived master key: it asks the
+    provider for the *current* key id when writing, and for a specific key id
+    (read back off the stored blob) when decrypting an older row.
+
+    Key rotation is the answer to AES-GCM's nonce-scaling bound too: a fresh
+    random 96-bit nonce is safe to ~2^32 events under one key, so rotating the
+    data key (a new ``current_key_id``) resets that budget while old rows keep
+    decrypting under their own key id. Implement this against a KMS to get
+    managed keys with no on-disk format change."""
+
+    @property
+    def current_key_id(self) -> str: ...
+
+    def key(self, key_id: str) -> bytes: ...
+
+
+class IdentityCodec:
+    """Plaintext. The default: no dependencies, fully queryable on disk.
+
+    ``aad`` is accepted for interface parity with authenticated codecs but is
+    intentionally unused: plaintext carries no authentication tag, so there is
+    nothing to bind it to. The AAD row-binding guarantee is a property of the
+    AES codec only — see the module docstring.
+    """
+
+    version = 0
+
+    def encode_body(self, plaintext: str, aad: bytes) -> bytes:
+        return plaintext.encode("utf-8")
+
+    def decode_body(self, body: bytes, aad: bytes) -> str:
+        return body.decode("utf-8")
+
+
+def encode_payload(codec: PayloadCodec, plaintext: str, aad: bytes = b"") -> bytes:
+    """Tag-then-body: [version byte][codec-specific body]."""
+    if not 0 <= codec.version <= 255:
+        raise ValueError(f"codec.version must be a byte (0-255), got {codec.version}")
+    return bytes([codec.version]) + codec.encode_body(plaintext, aad)
+
+
+def decode_payload(
+    blob: bytes, aad: bytes, registry: Mapping[int, PayloadCodec]
+) -> str:
+    """Dispatch on the leading version byte so mixed-codec logs read back."""
+    if not blob:
+        raise ValueError("empty payload blob")
+    version = blob[0]
+    codec = registry.get(version)
+    if codec is None:
+        raise ValueError(
+            f"no codec registered for payload version {version}; "
+            "cannot decode (was this row written with an encryption codec "
+            "that is not installed/configured?)"
+        )
+    return codec.decode_body(blob[1:], aad)

zu_core-0.2.0/src/zu_core/content.py

@@ -0,0 +1,138 @@
+"""Typed multimodal content — the modality-agnostic currency of the loop.
+
+The policy port (today an LLM, tomorrow a world model or an embodied
+controller) consumes an :class:`Observation` and emits an :class:`Action`. For
+that single seam to serve every modality, the *observation* must carry typed
+content — text, image, audio, sensor — rather than a bare string, and the
+*action* must be typed rather than a guessed-at dict. These models are that
+currency (Engineering Design §8.2, §9).
+
+Design notes that are load-bearing:
+
+* **Frozen value objects.** A piece of content is a fact about what was
+  observed; it is never mutated in place. Like :class:`Event`, the envelope is
+  frozen.
+* **Discriminated union.** ``Observation.content`` is a list of a closed set of
+  parts, tagged by ``kind`` so Pydantic can round-trip it from JSON on the event
+  log without ambiguity. New modalities are added here (a new ``Content``
+  subclass + a new ``kind``), never by smuggling an untyped blob through.
+* **Binary is base64 on the wire.** :class:`Image`/:class:`Audio` carry raw
+  ``bytes`` in memory but serialise as base64 in JSON mode, so an observation is
+  safe to journal or hand to the codec without a decode error. Media payloads
+  are large; what lands on the event log is the caller's choice (a reference or
+  a scoped copy), but the contract itself never crashes a ``model_dump``.
+* **Additive, not a rewrite.** Tools still return plain dicts and the
+  interpreter loop still speaks ``ModelRequest``/``ModelResponse``. These types
+  are the seam the perception-reduction tools (the Action Surface), the
+  HuggingFace task-model adapter, and the generalised Policy port build on; they
+  do not disturb the existing contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Content(BaseModel):
+    """Frozen base for one piece of observed content.
+
+    A concrete part declares a ``kind`` discriminator so a heterogeneous
+    ``list[Content]`` round-trips from JSON unambiguously.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+
+class Text(Content):
+    kind: Literal["text"] = "text"
+    text: str
+
+
+class Image(Content):
+    # base64 in/out in JSON mode so a binary payload never breaks model_dump(mode="json").
+    model_config = ConfigDict(frozen=True, ser_json_bytes="base64", val_json_bytes="base64")
+
+    kind: Literal["image"] = "image"
+    data: bytes
+    mime: str = "image/png"
+
+
+class Audio(Content):
+    model_config = ConfigDict(frozen=True, ser_json_bytes="base64", val_json_bytes="base64")
+
+    kind: Literal["audio"] = "audio"
+    data: bytes
+    mime: str = "audio/wav"
+
+
+# The closed set of content parts, tagged by ``kind``. Extend it by adding a
+# ``Content`` subclass with a new ``kind`` literal and listing it here — the one
+# place modality support is declared.
+ContentPart = Annotated[Text | Image | Audio, Field(discriminator="kind")]
+
+
+class Observation(BaseModel):
+    """The typed input side of the policy — heavy perceptual input, one shape.
+
+    The :class:`Observation` is what a perception-reduction step (the Action
+    Surface, a UI-element detector, a lidar reducer) fills compactly, and what
+    the policy reads to choose its next :class:`Action`.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    content: list[ContentPart] = Field(default_factory=list)
+
+    @classmethod
+    def from_text(cls, text: str) -> Observation:
+        """Build a text-only observation — the common case and the bridge from
+        the loop's existing string/dict observations."""
+        return cls(content=[Text(text=text)])
+
+    def text(self) -> str:
+        """The concatenated text of every :class:`Text` part (newline-joined).
+
+        How a text policy, a grounding validator, or a text-classifier detector
+        reads an observation without caring which other modalities ride along.
+        """
+        return "\n".join(p.text for p in self.content if isinstance(p, Text))
+
+    def parts(self, kind: str) -> list[ContentPart]:
+        """Every part of a given ``kind`` (``"text"`` | ``"image"`` | ``"audio"``)."""
+        return [p for p in self.content if p.kind == kind]
+
+
+class Action(BaseModel):
+    """The typed output side of the policy.
+
+    An LLM policy returns a ``tool_call`` (or final ``text``); a world-model or
+    embodied controller returns a ``command`` carrying a control action. The
+    harness, bus, detectors, validation, and envelope are unchanged across all
+    three — which is the whole point of typing the action rather than the policy
+    (Engineering Design §9.2).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    kind: Literal["text", "tool_call", "command"]
+    payload: dict = Field(default_factory=dict)
+
+    @classmethod
+    def text(cls, text: str) -> Action:
+        """A final-answer action."""
+        return cls(kind="text", payload={"text": text})
+
+    @classmethod
+    def tool_call(cls, name: str, args: dict | None = None) -> Action:
+        """A request to invoke a tool by name — the LLM-policy shape. The
+        payload mirrors :class:`zu_core.ports.ToolCall` (``name`` + ``args``) so
+        a Policy adapter can bridge the two without a lossy translation."""
+        return cls(kind="tool_call", payload={"name": name, "args": args or {}})
+
+    @classmethod
+    def command(cls, **payload: object) -> Action:
+        """A low-level control action — the world-model / embodied-controller
+        shape (e.g. ``Action.command(actuator="gait", vector=[...])``)."""
+        return cls(kind="command", payload=dict(payload))