anna-app-core 0.2.0a1__py3-none-any.whl

anna_app_core/__init__.py

@@ -0,0 +1,58 @@
+"""anna-app-core: stable contract surface shared by matrix-nexus and
+anna-app-runtime-local.
+
+v0.2.0a1 — full extraction. The complete RPC dispatcher, manifest pydantic
+schemas, and helper functions now live here; matrix-nexus re-exports them
+for backward compatibility (see README.md).
+"""
+
+from .acl import host_api_allows
+from .dispatcher import dispatch
+from .errors import HostRpcError, WindowError, WindowPermissionError
+from .manifest import (
+    AppDevConfig,
+    AppManifest,
+    ManifestExecutaRef,
+    UiBundleSection,
+    UiHostApiSpec,
+    UiManifestSection,
+    UiSize,
+    UiViewSpec,
+    WindowViewMeta,
+)
+from .protocols import WindowStoreProtocol
+from .runtime import scopes_from_manifest, select_view, view_meta
+from .versions import DISPATCHER_VERSION, SDK_VERSION
+
+__version__ = "0.2.0a1"
+
+__all__ = [
+    # errors
+    "HostRpcError",
+    "WindowError",
+    "WindowPermissionError",
+    # protocols
+    "WindowStoreProtocol",
+    # acl
+    "host_api_allows",
+    # dispatcher
+    "dispatch",
+    # manifest schemas
+    "AppManifest",
+    "AppDevConfig",
+    "ManifestExecutaRef",
+    "UiBundleSection",
+    "UiHostApiSpec",
+    "UiManifestSection",
+    "UiSize",
+    "UiViewSpec",
+    "WindowViewMeta",
+    # runtime helpers
+    "select_view",
+    "scopes_from_manifest",
+    "view_meta",
+    # versions
+    "DISPATCHER_VERSION",
+    "SDK_VERSION",
+    "__version__",
+]

anna_app_core/acl.py

@@ -0,0 +1,66 @@
+"""Host-API ACL check.
+
+Accepts either a typed ``AppManifest`` (preferred — production + harness)
+or a plain ``dict`` (e.g. JSON-loaded manifest before pydantic validation).
+
+Mirrors the pre-extraction implementation in
+``matrix-nexus/src/services/anna_app_runtime_service.py::host_api_allows``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Union
+
+from .manifest import AppManifest
+
+
+def _ui_host_api(
+    manifest: Union[AppManifest, dict[str, Any]],
+) -> dict[str, list[str]] | None:
+    """Return the ``ui.host_api`` mapping (ns -> list[method]) or ``None``
+    if the manifest has no UI section."""
+    if isinstance(manifest, AppManifest):
+        if manifest.ui is None:
+            return None
+        api = manifest.ui.host_api
+        return {
+            "tools": api.tools,
+            "chat": api.chat,
+            "artifact": api.artifact,
+            "llm": api.llm,
+            "fs": api.fs,
+            "storage": api.storage,
+            "prefs": api.prefs,
+        }
+    ui = manifest.get("ui") if isinstance(manifest, dict) else None
+    if ui is None:
+        return None
+    return ui.get("host_api") or {}
+
+
+def host_api_allows(
+    manifest: Union[AppManifest, dict[str, Any]],
+    ns: str,
+    method: str,
+) -> bool:
+    """Return ``True`` iff ``ns.method`` is granted by the manifest's ACL.
+
+    `window.*` is always granted. ``tools.invoke`` and ``tools.list`` are
+    granted whenever the ``tools`` set is non-empty (per-tool gating happens
+    inside the handler).
+    """
+    if ns == "window":
+        return True
+    api_map = _ui_host_api(manifest)
+    if api_map is None:
+        return False
+    methods = api_map.get(ns)
+    if not methods:
+        return False
+    if "*" in methods:
+        return True
+    if method in methods:
+        return True
+    if ns == "tools" and method in ("invoke", "list"):
+        return True
+    return False

anna_app_core/dispatcher.py

@@ -0,0 +1,505 @@
+"""Anna App UI Runtime — RPC dispatcher (host-side, runtime-agnostic).
+
+Single source of truth for every host_api handler from design §8.2. Run with
+either:
+
+* `SqlAlchemyWindowStore(db)` (production, in matrix-nexus) — auto-wrapped
+  by nexus's compatibility shim ``src/services/anna_app_rpc_dispatcher.py``.
+* `InMemoryWindowStore()` (local-dev harness, ``anna-app-runtime-local``).
+
+Both satisfy `WindowStoreProtocol`; the same handler bodies (ACL gating,
+tool-id splitting, event payload shapes) execute in either environment.
+
+Namespaces (design §8.2):
+
+================ ============== =================== ==========================
+namespace        method         scope               status
+================ ============== =================== ==========================
+window           hello          (always)            ✅
+window           ready          (always)            ✅
+window           set_title      window              ✅
+window           resize         window              ✅
+window           focus          window              ✅
+window           close          window              ✅
+window           open_view      window              ✅
+window           report_error   (always)            ✅
+tools            invoke         tools.invoke        ✅ (Executa via NATS)
+tools            list           tools               ✅
+chat             read_history   chat.read           ⏳ stub (Phase 3)
+chat             write_message  chat.write_message  ⏳ stub (Phase 3)
+chat             append_artifact chat.append_artifact ✅
+artifact         create/update/delete                ⏳ stub
+llm              complete       llm.complete        ⏳ stub (Phase 3)
+fs               read/write     fs.*                ⏳ stub (Phase 3)
+storage          get/set/delete storage.*           ✅ (runtime_state)
+prefs            get            prefs.read          ⏳ stub
+================ ============== =================== ==========================
+
+When changing public behaviour here, bump ``DISPATCHER_VERSION`` in
+``versions.py`` and update ``packages/VERSIONS.md``.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Awaitable, Callable
+
+from .acl import host_api_allows
+from .errors import HostRpcError, WindowError, WindowPermissionError
+from .manifest import AppManifest
+from .protocols import WindowStoreProtocol
+from .runtime import _scopes_from_manifest, _select_view, _view_meta
+
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# window.* handlers
+# -----------------------------------------------------------------------------
+
+
+async def _h_window_hello(
+    store: WindowStoreProtocol,
+    *,
+    window: Any,
+    manifest: AppManifest,
+    args: dict,
+) -> dict:
+    """Initial handshake — returns capabilities + view_meta + entry/runtime."""
+    view = _select_view(manifest, window.view)
+    return {
+        "capabilities": {
+            "host_api_version": "0.1.0",
+            "scopes": _scopes_from_manifest(manifest),
+        },
+        "view_meta": _view_meta(view).model_dump(),
+        "entry_payload": window.entry_payload or {},
+        "runtime_state": window.runtime_state or {},
+        "geometry": window.geometry or {},
+        "is_resume": bool(window.runtime_state),
+    }
+
+
+async def _h_window_ready(store, *, window, manifest, args) -> dict:
+    return {"ok": True}
+
+
+async def _h_window_set_title(store, *, window, manifest, args) -> dict:
+    title = str(args.get("title", ""))[:200]
+    window.title = title
+    await store.commit()
+    await store.emit_event(
+        window.user_id,
+        "title_changed",
+        {"window_uuid": window.window_uuid, "title": title},
+    )
+    return {"title": title}
+
+
+async def _h_window_resize(store, *, window, manifest, args) -> dict:
+    try:
+        w = int(args.get("w"))
+        h = int(args.get("h"))
+    except (TypeError, ValueError):
+        raise HostRpcError("invalid_arg", "w/h must be integers")
+    geo = dict(window.geometry or {})
+    geo.update({"w": w, "h": h})
+    window.geometry = geo
+    await store.commit()
+    await store.emit_event(
+        window.user_id,
+        "geometry_changed",
+        {"window_uuid": window.window_uuid, "geometry": geo},
+    )
+    return {"w": w, "h": h}
+
+
+async def _h_window_focus(store, *, window, manifest, args) -> dict:
+    window.last_focus_at = datetime.utcnow()
+    await store.commit()
+    await store.emit_event(
+        window.user_id,
+        "window_focus_changed",
+        {
+            "window_uuid": window.window_uuid,
+            "last_focus_at": window.last_focus_at.isoformat(),
+        },
+    )
+    return {"focused": True}
+
+
+async def _h_window_close(store, *, window, manifest, args) -> dict:
+    reason = str(args.get("reason") or "iframe_close")[:80]
+    window.status = "closed"
+    window.closed_at = datetime.utcnow()
+    window.closed_reason = reason
+    await store.commit()
+    await store.emit_event(
+        window.user_id,
+        "close_view",
+        {"window_uuid": window.window_uuid, "reason": reason},
+    )
+    return {"closed": True}
+
+
+async def _h_window_open_view(store, *, window, manifest, args) -> dict:
+    """Allow the iframe to summon a sibling view of the same app."""
+    view_name = args.get("view")
+    payload = args.get("payload") or {}
+    try:
+        detail, opened_new = await store.open_sibling_window(
+            window=window, view_name=view_name, payload=payload
+        )
+    except NotImplementedError:
+        raise HostRpcError(
+            "not_implemented", "window.open_view is not available in this runtime"
+        )
+    except WindowError as e:
+        raise HostRpcError("invalid_view", str(e))
+    await store.emit_event(
+        window.user_id,
+        "open_view",
+        {
+            "window_uuid": detail.window_uuid,
+            "app": detail.app,
+            "view": detail.view,
+            "view_meta": detail.view_meta.model_dump(),
+            "bundle_url": detail.bundle_url,
+            "sdk_url": detail.sdk_url,
+            "token": detail.token,
+            "entry_payload": detail.entry_payload,
+            "conversation_session_uuid": detail.conversation_session_uuid,
+            "source": "iframe_open_view",
+            "opened_new": opened_new,
+        },
+    )
+    return {"window_uuid": detail.window_uuid, "opened_new": opened_new}
+
+
+async def _h_window_report_error(store, *, window, manifest, args) -> dict:
+    err = args.get("error") or {}
+    logger.warning(
+        "anna_app iframe error wid=%s: %s",
+        window.window_uuid,
+        str(err)[:500],
+    )
+    return {"acknowledged": True}
+
+
+# -----------------------------------------------------------------------------
+# tools.* handlers
+# -----------------------------------------------------------------------------
+
+
+def _split_tool_id(
+    tool_id: str, *, explicit_method: str | None = None
+) -> tuple[str, str]:
+    """Resolve ``(plugin_name, tool_name)`` for NATS routing.
+
+    Mint-only tool_ids (``tool-{handle}-{slug}-{uniq}``) contain no
+    separator, so the bundle now passes the target method explicitly via
+    ``args.method``. The legacy ``plugin.tool`` / ``plugin__tool`` form
+    is still accepted for back-compat.
+    """
+    if explicit_method:
+        method = explicit_method.strip()
+        if not method:
+            raise HostRpcError("invalid_arg", "method must be a non-empty string")
+        return tool_id, method
+    for sep in ("__", "."):
+        if sep in tool_id:
+            head, tail = tool_id.split(sep, 1)
+            return head, tail
+    raise HostRpcError(
+        "invalid_arg",
+        f"tool_id '{tool_id}' has no plugin.tool separator and no "
+        "`method` arg was provided",
+    )
+
+
+def _is_tool_allowed(manifest: AppManifest, tool_id: str) -> bool:
+    if manifest.ui is None:
+        return False
+    refs = manifest.ui.host_api.tools
+    required_ids = {r.tool_id for r in manifest.required_executas}
+    optional_ids = {r.tool_id for r in manifest.optional_executas}
+    for ref in refs:
+        if ref == "required:*" and tool_id in required_ids:
+            return True
+        if ref == "optional:*" and tool_id in optional_ids:
+            return True
+        if ref == tool_id:
+            return True
+        if ref.endswith(f":{tool_id}"):
+            return True
+    return False
+
+
+async def _h_tools_list(store, *, window, manifest, args) -> dict:
+    """List the executa tool_ids that this window is allowed to invoke."""
+    allowed: list[str] = []
+    required_ids = [r.tool_id for r in manifest.required_executas]
+    optional_ids = [r.tool_id for r in manifest.optional_executas]
+    for tid in required_ids + optional_ids:
+        if _is_tool_allowed(manifest, tid):
+            allowed.append(tid)
+    return {"tools": [{"tool_id": tid} for tid in allowed]}
+
+
+async def _h_tools_invoke(store, *, window, manifest, args) -> dict:
+    tool_id = args.get("tool_id")
+    tool_args = args.get("args") or {}
+    method = args.get("method")
+    if not isinstance(tool_id, str) or not tool_id:
+        raise HostRpcError("invalid_arg", "tool_id is required")
+    if method is not None and not isinstance(method, str):
+        raise HostRpcError("invalid_arg", "method must be a string when provided")
+    if not _is_tool_allowed(manifest, tool_id):
+        raise HostRpcError(
+            "permission_denied",
+            f"tool '{tool_id}' not whitelisted by host_api.tools",
+        )
+
+    plugin_name, tool_name = _split_tool_id(tool_id, explicit_method=method)
+
+    try:
+        result = await store.invoke_executa_tool(
+            user_id=window.user_id,
+            plugin_name=plugin_name,
+            tool_name=tool_name,
+            tool_args=tool_args,
+        )
+    except NotImplementedError:
+        raise HostRpcError(
+            "not_implemented", "tools.invoke is not available in this runtime"
+        )
+
+    logger.info(
+        "anna-app tools.invoke raw result for %s.%s: %r",
+        plugin_name,
+        tool_name,
+        result,
+    )
+
+    # Unwrap two layers of envelope so the iframe sees the plugin's payload
+    # directly. Either layer reporting failure is surfaced as a HostRpcError
+    # so the SDK rejects the promise instead of silently returning a wrapper.
+    def _summary(d: Any) -> str:
+        if isinstance(d, dict):
+            return f"keys={sorted(d.keys())!r}"
+        return f"type={type(d).__name__}"
+
+    if not isinstance(result, dict) or not result.get("success", False):
+        raise HostRpcError(
+            "executa_unavailable",
+            (
+                str(result.get("error") or f"executa RPC failed ({_summary(result)})")
+                if isinstance(result, dict)
+                else f"executa RPC failed ({_summary(result)})"
+            ),
+        )
+    invoke = result.get("data") or {}
+    if not isinstance(invoke, dict) or not invoke.get("success", False):
+        raise HostRpcError(
+            "tool_failed",
+            (
+                str(
+                    invoke.get("error") or f"tool returned failure ({_summary(invoke)})"
+                )
+                if isinstance(invoke, dict)
+                else f"tool returned failure ({_summary(invoke)})"
+            ),
+        )
+    payload = invoke.get("data")
+    return payload if isinstance(payload, dict) else {}
+
+
+# -----------------------------------------------------------------------------
+# chat.* handlers
+# -----------------------------------------------------------------------------
+
+
+async def _h_chat_append_artifact(store, *, window, manifest, args) -> dict:
+    """Append an ``app_event`` artifact to the associated conversation."""
+    artifact = args.get("artifact") or {}
+    if not isinstance(artifact, dict):
+        raise HostRpcError("invalid_arg", "artifact must be an object")
+    artifact = {
+        "kind": str(artifact.get("kind", "app_event"))[:40],
+        "app_slug": artifact.get("app_slug"),
+        "summary": str(artifact.get("summary", ""))[:1000],
+        "payload_ref": artifact.get("payload_ref"),
+        "data": artifact.get("data"),
+        "ts": datetime.utcnow().isoformat(),
+        "window_uuid": window.window_uuid,
+    }
+    await store.emit_event(
+        window.user_id,
+        "artifact_appended",
+        {"window_uuid": window.window_uuid, "artifact": artifact},
+    )
+    artifact_id = f"app-{window.window_uuid[:8]}-{int(datetime.utcnow().timestamp())}"
+    return {"artifact_id": artifact_id}
+
+
+async def _h_chat_write_message(store, *, window, manifest, args) -> dict:
+    """Stub: emit a synthetic event to chat (full thread persistence Phase 3)."""
+    role = args.get("role", "assistant")
+    content = str(args.get("content", ""))[:4000]
+    await store.emit_event(
+        window.user_id,
+        "chat_message_from_app",
+        {
+            "window_uuid": window.window_uuid,
+            "role": role,
+            "content": content,
+        },
+    )
+    return {"message_id": f"msg-{int(datetime.utcnow().timestamp() * 1000)}"}
+
+
+async def _h_chat_read_history(store, *, window, manifest, args) -> dict:
+    raise HostRpcError("not_implemented", "chat.read_history is Phase 3")
+
+
+# -----------------------------------------------------------------------------
+# storage.* handlers (operate on window.runtime_state)
+# -----------------------------------------------------------------------------
+
+
+async def _h_storage_get(store, *, window, manifest, args) -> dict:
+    key = str(args.get("key", ""))
+    if not key:
+        raise HostRpcError("invalid_arg", "key required")
+    return {"value": (window.runtime_state or {}).get(key)}
+
+
+async def _h_storage_set(store, *, window, manifest, args) -> dict:
+    key = str(args.get("key", ""))
+    if not key:
+        raise HostRpcError("invalid_arg", "key required")
+    value = args.get("value")
+    state = dict(window.runtime_state or {})
+    state[key] = value
+    user = await store.get_user(window.user_id)
+    try:
+        await store.replace_runtime_state(
+            user=user, window_uuid=window.window_uuid, state=state
+        )
+    except WindowError as e:
+        raise HostRpcError("too_large", str(e))
+    await store.emit_event(
+        window.user_id,
+        "runtime_state_synced",
+        {"window_uuid": window.window_uuid, "patch": {key: value}},
+    )
+    return {"ok": True}
+
+
+async def _h_storage_delete(store, *, window, manifest, args) -> dict:
+    key = str(args.get("key", ""))
+    if not key:
+        raise HostRpcError("invalid_arg", "key required")
+    state = dict(window.runtime_state or {})
+    state.pop(key, None)
+    user = await store.get_user(window.user_id)
+    await store.replace_runtime_state(
+        user=user, window_uuid=window.window_uuid, state=state
+    )
+    await store.emit_event(
+        window.user_id,
+        "runtime_state_synced",
+        {"window_uuid": window.window_uuid, "patch": {key: None}},
+    )
+    return {"ok": True}
+
+
+# -----------------------------------------------------------------------------
+# Stub handlers (Phase 3 surface)
+# -----------------------------------------------------------------------------
+
+
+async def _h_not_implemented(store, *, window, manifest, args) -> dict:
+    raise HostRpcError("not_implemented", "endpoint not yet available")
+
+
+# -----------------------------------------------------------------------------
+# Dispatch table
+# -----------------------------------------------------------------------------
+
+Handler = Callable[..., Awaitable[dict]]
+
+_DISPATCH: dict[tuple[str, str], Handler] = {
+    # window
+    ("window", "hello"): _h_window_hello,
+    ("window", "ready"): _h_window_ready,
+    ("window", "set_title"): _h_window_set_title,
+    ("window", "resize"): _h_window_resize,
+    ("window", "focus"): _h_window_focus,
+    ("window", "close"): _h_window_close,
+    ("window", "open_view"): _h_window_open_view,
+    ("window", "report_error"): _h_window_report_error,
+    # tools
+    ("tools", "list"): _h_tools_list,
+    ("tools", "invoke"): _h_tools_invoke,
+    # chat
+    ("chat", "append_artifact"): _h_chat_append_artifact,
+    ("chat", "write_message"): _h_chat_write_message,
+    ("chat", "read_history"): _h_chat_read_history,
+    # storage
+    ("storage", "get"): _h_storage_get,
+    ("storage", "set"): _h_storage_set,
+    ("storage", "delete"): _h_storage_delete,
+    # phase 3 stubs
+    ("artifact", "create"): _h_not_implemented,
+    ("artifact", "update"): _h_not_implemented,
+    ("artifact", "delete"): _h_not_implemented,
+    ("llm", "complete"): _h_not_implemented,
+    ("fs", "read"): _h_not_implemented,
+    ("fs", "write"): _h_not_implemented,
+    ("prefs", "get"): _h_not_implemented,
+}
+
+
+_NO_AUTH_NEEDED = {("window", "hello"), ("window", "ready"), ("window", "report_error")}
+
+
+async def dispatch(
+    store: WindowStoreProtocol,
+    *,
+    window: Any,
+    manifest: AppManifest,
+    ns: str,
+    method: str,
+    args: dict,
+) -> dict:
+    """Route an envelope to the right handler.
+
+    Caller has already verified the window token and loaded ``window`` +
+    ``manifest``. ``store`` is any object satisfying `WindowStoreProtocol`.
+
+    Production callers (matrix-nexus) wrap their `AsyncSession` as
+    `SqlAlchemyWindowStore` before calling here. The local-dev harness
+    passes its `InMemoryWindowStore` directly.
+    """
+    handler = _DISPATCH.get((ns, method))
+    if handler is None:
+        raise HostRpcError("unknown_method", f"{ns}.{method} is not defined")
+    if (ns, method) not in _NO_AUTH_NEEDED:
+        if not host_api_allows(manifest, ns, method):
+            raise HostRpcError(
+                "permission_denied",
+                f"manifest does not grant '{ns}.{method}'",
+            )
+    try:
+        return await handler(store, window=window, manifest=manifest, args=args or {})
+    except HostRpcError:
+        raise
+    except WindowPermissionError as e:
+        raise HostRpcError("permission_denied", str(e))
+    except WindowError as e:
+        raise HostRpcError("invalid_arg", str(e))
+    except Exception as e:  # pragma: no cover
+        logger.exception("rpc handler crashed")
+        raise HostRpcError("internal", f"handler crashed: {e}")

anna_app_core/errors.py

@@ -0,0 +1,33 @@
+"""Error types crossing the host<->app RPC boundary.
+
+These mirror `matrix-nexus/src/services/anna_app_runtime_service.py` and
+`matrix-nexus/src/services/anna_app_rpc_dispatcher.py`. The nexus copies
+will be replaced with re-export shims in the Phase 7 follow-up; for now
+the definitions are duplicated to keep `anna-app-core` truly standalone.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class WindowError(ValueError):
+    """Application-level failure (mapped to HTTP 4xx in the nexus router)."""
+
+
+class WindowPermissionError(WindowError):
+    """Raised when a `host_api` ACL check fails."""
+
+
+class HostRpcError(Exception):
+    """Structured error returned by RPC handlers.
+
+    Carries a stable `code` (e.g. ``not_implemented``, ``permission_denied``)
+    so frontends can branch deterministically without scraping messages.
+    """
+
+    def __init__(self, code: str, message: str, *, details: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details

anna_app_core/manifest.py

@@ -0,0 +1,163 @@
+"""Pydantic schemas for the Anna App manifest + window view metadata.
+
+Source-of-truth lives here (anna-app-core). matrix-nexus re-exports these
+from `src/schemas/anna_app.py` so existing nexus imports keep working.
+
+NOTE: nexus also has many *non*-manifest schemas (`AnnaApp`, `AnnaAppVersion`,
+`UserExecuta`, …) that are intentionally kept in nexus — they touch the DB
+and have nothing to do with the local-dev contract.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# -----------------------------------------------------------------------------
+# Manifest
+# -----------------------------------------------------------------------------
+
+
+class ManifestExecutaRef(BaseModel):
+    tool_id: str = Field(..., min_length=1, max_length=200)
+    min_version: Optional[str] = Field(None, max_length=40)
+    version: Optional[str] = Field(
+        None,
+        max_length=40,
+        description=(
+            "Executa snapshot version to pin. Omit or use 'latest' to "
+            "auto-freeze the current Executa state at publish time."
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+# UI manifest section (Anna App UI Runtime §5)
+# -----------------------------------------------------------------------------
+
+
+class UiSize(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    w: int = Field(..., ge=120, le=4096)
+    h: int = Field(..., ge=120, le=4096)
+
+
+class UiBundleSection(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    format: str = Field("static-spa", max_length=20)
+    entry: str = Field(..., min_length=1, max_length=200)
+    external_origins: list[str] = Field(default_factory=list)
+
+
+class UiViewSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(..., min_length=1, max_length=40)
+    title: str = Field(..., min_length=1, max_length=120)
+    default: bool = Field(False)
+    entry: Optional[str] = Field(None, max_length=300)
+    min_size: Optional[UiSize] = None
+    default_size: Optional[UiSize] = None
+    max_size: Optional[UiSize] = None
+    resizable: bool = Field(True)
+    movable: bool = Field(True)
+    single_instance: bool = Field(False)
+    summary_template: Optional[str] = Field(None, max_length=400)
+    icon: Optional[str] = Field(None, max_length=200)
+
+
+class UiHostApiSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tools: list[str] = Field(default_factory=list)
+    chat: list[str] = Field(default_factory=list)
+    artifact: list[str] = Field(default_factory=list)
+    llm: list[str] = Field(default_factory=list)
+    fs: list[str] = Field(default_factory=list)
+    storage: list[str] = Field(default_factory=list)
+    prefs: list[str] = Field(default_factory=list)
+    window: list[str] = Field(default_factory=list)
+
+
+class UiManifestSection(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    bundle: UiBundleSection
+    views: list[UiViewSpec] = Field(default_factory=list)
+    host_api: UiHostApiSpec = Field(default_factory=UiHostApiSpec)
+    csp_overrides: dict[str, list[str]] = Field(default_factory=dict)
+    state_merge: str = Field("last_writer_wins", max_length=20)
+
+
+class AppDevConfig(BaseModel):
+    """Optional ``manifest.dev`` block — local-harness-only configuration.
+
+    Production dispatcher ignores this field at runtime (it is declared here
+    so ``extra="forbid"`` doesn't reject it). ``anna-app publish`` SHOULD
+    strip ``dev`` from the manifest before upload; mirroring nexus's
+    historical "drop unknown keys" behaviour.
+
+    See design doc §8 for field semantics. All fields are intentionally loose
+    (`Any`) so the harness can evolve independently from the wire schema.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    fixtures: Optional[list[str]] = Field(
+        default=None,
+        description="Glob patterns for fixture JSONL files relative to manifest dir.",
+    )
+    mocks: Optional[dict[str, Any]] = Field(
+        default=None,
+        description="Per-(ns,method) static response mocks, keyed by 'ns.method'.",
+    )
+    seed_storage: Optional[dict[str, Any]] = Field(
+        default=None,
+        description="Initial runtime_state for `anna-app dev` sessions.",
+    )
+    user_id: Optional[int] = Field(
+        default=None,
+        description="Override the default harness user_id (default: 1).",
+    )
+
+
+class AppManifest(BaseModel):
+    """App Manifest schema (stored in ``anna_app_versions.manifest``).
+
+    Adding a field here MUST be coordinated with ``anna-app-schema`` JSON
+    Schema bundle and ``DISPATCHER_VERSION`` in `versions.py`.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_: int = Field(1, alias="schema", ge=1, le=2)
+    permissions: list[str] = Field(default_factory=list)
+    required_executas: list[ManifestExecutaRef] = Field(default_factory=list)
+    optional_executas: list[ManifestExecutaRef] = Field(default_factory=list)
+    system_prompt_addendum: Optional[str] = Field(None, max_length=4000)
+    user_message_prefix_template: Optional[str] = Field(None, max_length=500)
+    tags: list[str] = Field(default_factory=list)
+    ui: Optional[UiManifestSection] = None
+    # Phase 8: harness-only block; production ignores at runtime.
+    dev: Optional[AppDevConfig] = None
+
+
+# -----------------------------------------------------------------------------
+# Window view metadata (RPC response shape for window.hello)
+# -----------------------------------------------------------------------------
+
+
+class WindowViewMeta(BaseModel):
+    name: str
+    title: str
+    entry: Optional[str] = None
+    min_size: Optional[UiSize] = None
+    default_size: Optional[UiSize] = None
+    max_size: Optional[UiSize] = None
+    resizable: bool = True
+    movable: bool = True
+    single_instance: bool = False

anna_app_core/protocols.py

@@ -0,0 +1,50 @@
+"""Window store protocol.
+
+The minimum persistence + side-effect surface the RPC dispatcher requires
+from a backing store. Production wires `SqlAlchemyWindowStore(db)` (nexus).
+The local-dev harness provides `InMemoryWindowStore`. Both satisfy this
+contract so the *exact same* dispatcher code runs in either environment.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WindowStoreProtocol(Protocol):
+    """See ``anna-app-core/README.md`` for the externally-published contract.
+
+    Heavy operations (`open_sibling_window`, `invoke_executa_tool`) MAY
+    raise `NotImplementedError` in stripped-down impls; the dispatcher
+    surfaces those as `HostRpcError("not_implemented", ...)`.
+    """
+
+    async def commit(self) -> None: ...
+
+    async def get_user(self, user_id: int) -> Any | None: ...
+
+    async def replace_runtime_state(
+        self, *, user: Any, window_uuid: str, state: dict
+    ) -> None: ...
+
+    async def emit_event(
+        self, user_id: int, kind: str, payload: dict[str, Any]
+    ) -> None: ...
+
+    async def open_sibling_window(
+        self,
+        *,
+        window: Any,
+        view_name: str | None,
+        payload: dict,
+    ) -> tuple[Any, bool]: ...
+
+    async def invoke_executa_tool(
+        self,
+        *,
+        user_id: int,
+        plugin_name: str,
+        tool_name: str,
+        tool_args: dict,
+    ) -> Any: ...

anna_app_core/runtime.py

@@ -0,0 +1,73 @@
+"""Pure helper functions over `AppManifest`.
+
+Used by the dispatcher (and re-exported by nexus's
+``src/services/anna_app_runtime_service.py`` for backward compatibility).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .errors import WindowError
+from .manifest import AppManifest, UiViewSpec, WindowViewMeta
+
+
+def select_view(manifest: AppManifest, view_name: Optional[str]) -> UiViewSpec:
+    """Pick the ``UiViewSpec`` matching ``view_name`` (or the default view)."""
+    if manifest.ui is None or not manifest.ui.views:
+        raise WindowError("app has no UI views")
+    if view_name is None:
+        for v in manifest.ui.views:
+            if v.default:
+                return v
+        return manifest.ui.views[0]
+    for v in manifest.ui.views:
+        if v.name == view_name:
+            return v
+    raise WindowError(f"unknown view '{view_name}'")
+
+
+def scopes_from_manifest(manifest: AppManifest) -> list[str]:
+    """Flatten ``manifest.ui.host_api`` into ``"<ns>.<method>"`` strings."""
+    if manifest.ui is None:
+        return []
+    out: list[str] = []
+    api = manifest.ui.host_api
+    for ns, methods in {
+        "tools": api.tools,
+        "chat": api.chat,
+        "artifact": api.artifact,
+        "llm": api.llm,
+        "fs": api.fs,
+        "storage": api.storage,
+        "prefs": api.prefs,
+        "window": api.window,
+    }.items():
+        for m in methods:
+            out.append(f"{ns}.{m}")
+    if "window.*" not in out:
+        out.append("window.*")
+    return out
+
+
+def view_meta(view: UiViewSpec) -> WindowViewMeta:
+    """Project a ``UiViewSpec`` into the wire-shape ``WindowViewMeta``."""
+    return WindowViewMeta(
+        name=view.name,
+        title=view.title,
+        entry=view.entry,
+        min_size=view.min_size,
+        default_size=view.default_size,
+        max_size=view.max_size,
+        resizable=view.resizable,
+        movable=view.movable,
+        single_instance=view.single_instance,
+    )
+
+
+# Underscore aliases preserve nexus's historical `runtime._select_view` /
+# `runtime._view_meta` / `runtime._scopes_from_manifest` access patterns so
+# the dispatcher's existing call sites work after the move.
+_select_view = select_view
+_scopes_from_manifest = scopes_from_manifest
+_view_meta = view_meta

anna_app_core/versions.py

@@ -0,0 +1,9 @@
+"""Pinned protocol/SDK versions.
+
+These mirror the values in ``packages/anna-app-schema/`` and the central
+``packages/VERSIONS.md`` matrix. Any bump here is a breaking change for
+the wire protocol; coordinate with the schema bundle.
+"""
+
+DISPATCHER_VERSION = "0.1.0"
+SDK_VERSION = "0.1.0"

anna_app_core-0.2.0a1.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: anna-app-core
+Version: 0.2.0a1
+Summary: Anna App platform core: manifest schemas, RPC dispatcher, protocols, errors. Shared by matrix-nexus and the local-dev runtime.
+Project-URL: Documentation, https://github.com/talentai/matrix-nexus/blob/main/docs/design/anna-app-local-dev-and-test.md
+Author: Talent AI
+License: MIT
+Keywords: anna,anna-app,executa
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3.0,>=2.0
+Description-Content-Type: text/markdown
+
+# anna-app-core
+
+Shared protocol/error/ACL primitives for the [Anna App](https://github.com/talentai/matrix-nexus/blob/main/docs/design/anna-app-local-dev-and-test.md) platform.
+
+This package is intentionally tiny. It exposes the **stable contract surface**
+that both `matrix-nexus` (production host) and `anna-app-runtime-local` (local
+dev harness) can depend on without pulling each other's runtime.
+
+## What's here (v0.1.x)
+
+- `WindowStoreProtocol` — minimum surface RPC handlers expect from a window store
+- `HostRpcError`, `WindowError`, `WindowPermissionError` — error types crossing the boundary
+- `host_api_allows(manifest_dict, ns, method) -> bool` — pure ACL check (manifest passed as `dict`)
+- `DISPATCHER_VERSION` / `SDK_VERSION` constants
+
+## What's NOT here yet
+
+- The full `dispatch()` function — still lives in `matrix-nexus`
+  (`src/services/anna_app_rpc_dispatcher.py`). Planned for `anna-app-core>=0.2`
+  once `event_stream` + `runtime_service` are abstracted behind protocols.
+- Pydantic `AppManifest` — see `anna-app-schema` (JSON Schema bundle).
+
+## Versioning
+
+`0.1.0a1` is the first PyPI release (alpha). Pin policy lives in the central
+[VERSIONS.md](../VERSIONS.md).

anna_app_core-0.2.0a1.dist-info/RECORD

@@ -0,0 +1,11 @@
+anna_app_core/__init__.py,sha256=OKAEUfSCtAMs860pcfgnx39kbzXad9TQWmb749Wf6Ew,1394
+anna_app_core/acl.py,sha256=efTr5wK2ooWK57hHyZSQzGwZHVJnbLMHhN9Q9VLOru0,1901
+anna_app_core/dispatcher.py,sha256=PexHuhN2SssG3xK6d_lpxwsFkJPce6G_u1d1khb12TQ,18195
+anna_app_core/errors.py,sha256=of6NxDwzorhaOZy8OukLH-hUZQmaEpZvWYnBNKJG2Oc,1072
+anna_app_core/manifest.py,sha256=BA6BUChfDGoPy8pwK-4d4f3BMFy9YTfjcGL1qhnRv6o,5876
+anna_app_core/protocols.py,sha256=_mqAxmIwJ25uO6f1LU3uqzFI4ZJRsGjmupmjoWTSRq8,1436
+anna_app_core/runtime.py,sha256=cEY32RUQ2h5Ynz8z8DDascl6UzvE0C3UkSl4DGF29r0,2288
+anna_app_core/versions.py,sha256=moCI1M1yAofqmJjErP9a64yEIJTZkq07zvYF8cAIYIE,289
+anna_app_core-0.2.0a1.dist-info/METADATA,sha256=PnNWhPQ-fKc_2aTmq_FrBq9iArcvI2yhMvZzimtxU3M,1681
+anna_app_core-0.2.0a1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+anna_app_core-0.2.0a1.dist-info/RECORD,,

anna_app_core-0.2.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any