anna-app-runtime-local 0.2.0a1__py3-none-any.whl

anna_app_runtime_local/__init__.py

@@ -0,0 +1,29 @@
+"""Local-dev in-memory runtime for Anna Apps.
+
+See README.md for architecture notes.
+"""
+
+from __future__ import annotations
+
+from .executa import ExecutaPool, ExecutaSpec
+from .session import LocalDispatcherSession, LocalSessionError
+from .store import InMemoryWindowSession, InMemoryWindowStore
+from .token import (
+    DevTokenError,
+    mint_dev_token,
+    verify_dev_token,
+)
+
+__all__ = [
+    "LocalDispatcherSession",
+    "LocalSessionError",
+    "InMemoryWindowStore",
+    "InMemoryWindowSession",
+    "ExecutaPool",
+    "ExecutaSpec",
+    "mint_dev_token",
+    "verify_dev_token",
+    "DevTokenError",
+]
+
+__version__ = "0.1.0"

anna_app_runtime_local/bridge.py

@@ -0,0 +1,236 @@
+"""Stdio JSON-RPC 2.0 bridge for the anna-app-cli harness.
+
+Spoken by `anna-app-cli/src/harness/bridge.ts` over `python-shell`.
+
+Protocol: one JSON envelope per line on stdin / stdout.
+
+Methods (request → response):
+
+    session.create     { user_id, manifest, view?, entry_payload?, app_slug? }
+                       → { session_id, window_uuid, token, expires_in }
+
+    session.call       { session_id, ns, method, args? }
+                       → { ok: true, result: <dict> }
+                       | { ok: false, error: { code, message, details } }
+
+    session.drain_events { session_id }
+                       → { events: [<event>, ...] }
+
+    session.close      { session_id }
+                       → { ok: true }
+
+    session.refresh_token { session_id }
+                       → { token, expires_in }
+
+    executas.register  { executas: [{tool_id, project_dir, command?}, ...] }
+                       → { registered: [tool_id, ...] }
+
+    ping               {}  → { pong: true }
+
+All other request methods → JSON-RPC error -32601 (Method not found).
+Malformed envelopes → -32700.
+
+Exit cleanly on EOF.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import traceback
+from typing import Any
+
+from .executa import ExecutaPool, ExecutaSpec
+from .session import LocalDispatcherSession, LocalSessionError
+from .store import InMemoryWindowStore
+from .token import mint_dev_token
+
+
+class _Bridge:
+    def __init__(self) -> None:
+        self._sessions: dict[str, LocalDispatcherSession] = {}
+        self._next_id = 1
+        # Process-wide singletons: one executa pool + one in-memory store
+        # shared by every harness session (mirrors how production has a
+        # single dispatcher per user).
+        self._executa_pool = ExecutaPool()
+        self._store = InMemoryWindowStore(executa_pool=self._executa_pool)
+
+    def _new_session_id(self) -> str:
+        sid = f"sess-{self._next_id}"
+        self._next_id += 1
+        return sid
+
+    async def handle(self, req: dict[str, Any]) -> dict[str, Any]:
+        method = req.get("method")
+        params = req.get("params") or {}
+        rpc_id = req.get("id")
+
+        try:
+            if method == "ping":
+                result: Any = {"pong": True}
+
+            elif method == "session.create":
+                session = LocalDispatcherSession.create(
+                    user_id=int(params.get("user_id", 1)),
+                    manifest_dict=params["manifest"],
+                    view=params.get("view"),
+                    entry_payload=params.get("entry_payload"),
+                    runtime_state=params.get("runtime_state"),
+                    app_slug=params.get("app_slug"),
+                    store=self._store,
+                )
+                sid = self._new_session_id()
+                self._sessions[sid] = session
+                token, expires_in = mint_dev_token(
+                    window_uuid=session.window_uuid,
+                    user_id=session.window.user_id,
+                    app_id=session.window.app_id,
+                    version_id=session.window.version_id,
+                )
+                result = {
+                    "session_id": sid,
+                    "window_uuid": session.window_uuid,
+                    "token": token,
+                    "expires_in": expires_in,
+                    "view": session.window.view,
+                    "view_meta": _view_meta(session),
+                }
+
+            elif method == "session.call":
+                sid = params["session_id"]
+                session = self._sessions.get(sid)
+                if session is None:
+                    return _err(rpc_id, -32602, f"unknown session_id: {sid}")
+                try:
+                    out = await session.call(
+                        params["ns"],
+                        params["method"],
+                        params.get("args") or {},
+                    )
+                    result = {"ok": True, "result": out}
+                except LocalSessionError as e:
+                    result = {"ok": False, "error": e.to_dict()}
+
+            elif method == "session.drain_events":
+                sid = params["session_id"]
+                session = self._sessions.get(sid)
+                if session is None:
+                    return _err(rpc_id, -32602, f"unknown session_id: {sid}")
+                result = {"events": session.drain_events()}
+
+            elif method == "session.close":
+                sid = params["session_id"]
+                self._sessions.pop(sid, None)
+                result = {"ok": True}
+
+            elif method == "session.refresh_token":
+                sid = params["session_id"]
+                session = self._sessions.get(sid)
+                if session is None:
+                    return _err(rpc_id, -32602, f"unknown session_id: {sid}")
+                token, expires_in = mint_dev_token(
+                    window_uuid=session.window_uuid,
+                    user_id=session.window.user_id,
+                    app_id=session.window.app_id,
+                    version_id=session.window.version_id,
+                )
+                result = {"token": token, "expires_in": expires_in}
+
+            elif method == "executas.register":
+                # params: {executas: [{tool_id, project_dir, command?}, ...]}
+                items = params.get("executas") or []
+                registered: list[str] = []
+                for it in items:
+                    spec = ExecutaSpec(
+                        tool_id=it["tool_id"],
+                        project_dir=it["project_dir"],
+                        command=it.get("command"),
+                    )
+                    self._executa_pool.register(spec)
+                    registered.append(spec.tool_id)
+                result = {"registered": registered}
+
+            else:
+                return _err(rpc_id, -32601, f"method not found: {method}")
+
+            return {"jsonrpc": "2.0", "id": rpc_id, "result": result}
+
+        except KeyError as e:
+            return _err(rpc_id, -32602, f"missing required param: {e}")
+        except Exception as e:  # pragma: no cover — defensive
+            return _err(
+                rpc_id,
+                -32603,
+                f"internal: {e}",
+                {"traceback": traceback.format_exc()},
+            )
+
+
+def _err(
+    rpc_id: Any, code: int, message: str, data: dict | None = None
+) -> dict[str, Any]:
+    err: dict[str, Any] = {"code": code, "message": message}
+    if data:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "id": rpc_id, "error": err}
+
+
+def _view_meta(session: LocalDispatcherSession) -> dict[str, Any] | None:
+    """Return the chosen view's metadata as a plain dict (for harness sizing)."""
+    ui = session.manifest.ui
+    if ui is None:
+        return None
+    for v in ui.views:
+        if v.name == session.window.view:
+            return v.model_dump(mode="json", exclude_none=True)
+    return None
+
+
+async def _run() -> None:
+    bridge = _Bridge()
+    loop = asyncio.get_event_loop()
+    reader = asyncio.StreamReader()
+    protocol = asyncio.StreamReaderProtocol(reader)
+    await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+
+    # Announce readiness so the Node side can start sending.
+    sys.stdout.write(
+        json.dumps({"jsonrpc": "2.0", "method": "_ready", "params": {}}) + "\n"
+    )
+    sys.stdout.flush()
+
+    while True:
+        line = await reader.readline()
+        if not line:
+            return
+        text = line.decode("utf-8").strip()
+        if not text:
+            continue
+        try:
+            req = json.loads(text)
+        except json.JSONDecodeError:
+            sys.stdout.write(json.dumps(_err(None, -32700, "parse error")) + "\n")
+            sys.stdout.flush()
+            continue
+        if not isinstance(req, dict):
+            sys.stdout.write(
+                json.dumps(_err(None, -32600, "request must be an object")) + "\n"
+            )
+            sys.stdout.flush()
+            continue
+        resp = await bridge.handle(req)
+        sys.stdout.write(json.dumps(resp) + "\n")
+        sys.stdout.flush()
+
+
+def main() -> None:
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

anna_app_runtime_local/executa.py

@@ -0,0 +1,223 @@
+"""Stdio JSON-RPC client for Executa plugins (used by the harness).
+
+Mirrors the contract that Anna's NATS-side Agent uses when it spawns a
+plugin via the minted `[project.scripts]` entry: the plugin reads one
+JSON envelope per line on stdin and writes one per line on stdout.
+
+Methods spoken to the plugin:
+
+    describe   {}                                      → plugin MANIFEST
+    invoke     {tool: <method>, arguments: <dict>}     → {success, data | error, ...}
+    health     {}                                      → {status: "ok", ...}
+
+The harness reuses one warm subprocess per `tool_id` for the lifetime of
+the dev session. First call lazy-spawns; subsequent calls reuse the same
+process. The pool is keyed on `tool_id` because the plugin's executable
+is named after the minted id.
+
+The class is intentionally tiny — it does NOT mock NATS retry / Agent
+credential resolution. Production handlers wrap NATS responses in an
+extra envelope; we do the same here so the dispatcher's two-layer
+unwrap (`call_rpc → InvokeResult`) works unchanged.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ExecutaSpec:
+    """How to launch one Executa plugin from the harness."""
+
+    tool_id: str
+    project_dir: str
+    # Optional override; default = ["uv","run","--project",project_dir,tool_id]
+    command: list[str] | None = None
+
+
+@dataclass
+class _ExecutaProcess:
+    spec: ExecutaSpec
+    proc: asyncio.subprocess.Process
+    next_id: int = 1
+    pending: dict[int, asyncio.Future] = field(default_factory=dict)
+    reader_task: asyncio.Task | None = None
+    closed: bool = False
+
+
+class ExecutaPool:
+    """Lazy pool of `_ExecutaProcess` instances keyed by `tool_id`."""
+
+    def __init__(self, specs: dict[str, ExecutaSpec] | None = None) -> None:
+        self._specs: dict[str, ExecutaSpec] = dict(specs or {})
+        self._procs: dict[str, _ExecutaProcess] = {}
+        # Serialise spawns so concurrent first-calls don't double-spawn.
+        self._spawn_lock = asyncio.Lock()
+
+    def register(self, spec: ExecutaSpec) -> None:
+        self._specs[spec.tool_id] = spec
+
+    def is_registered(self, tool_id: str) -> bool:
+        return tool_id in self._specs
+
+    async def invoke(
+        self, *, tool_id: str, tool_name: str, tool_args: dict
+    ) -> dict[str, Any]:
+        """Send `invoke` to the plugin and return the *outer* envelope.
+
+        Outer shape mirrors what `nexus.tools.nats_rpc_base.call_rpc()`
+        returns in production:
+            {"success": True/False, "data": <plugin_result>,
+             "command_id": "local"}
+        which the dispatcher then unwraps.
+        """
+        proc = await self._get_or_spawn(tool_id)
+        try:
+            inner = await self._rpc(
+                proc,
+                method="invoke",
+                params={"tool": tool_name, "arguments": tool_args},
+            )
+        except _PluginError as e:
+            # Plugin returned a JSON-RPC error envelope; treat as
+            # NATS-layer success carrying a tool-layer failure so the
+            # dispatcher's two-layer unwrap surfaces a `tool_failed`.
+            return {
+                "success": True,
+                "data": {"success": False, "error": str(e)},
+                "command_id": "local",
+            }
+        # The plugin's own contract is `{success, data | error, ...}`.
+        return {"success": True, "data": inner, "command_id": "local"}
+
+    async def shutdown(self) -> None:
+        for tool_id, p in list(self._procs.items()):
+            await self._kill(p)
+            del self._procs[tool_id]
+
+    # -- internals -----------------------------------------------------------
+
+    async def _get_or_spawn(self, tool_id: str) -> _ExecutaProcess:
+        existing = self._procs.get(tool_id)
+        if existing and not existing.closed:
+            return existing
+        async with self._spawn_lock:
+            existing = self._procs.get(tool_id)
+            if existing and not existing.closed:
+                return existing
+            spec = self._specs.get(tool_id)
+            if spec is None:
+                # Mirror dispatcher's HostRpcError signal but stay layer-clean.
+                raise KeyError(
+                    f"executa '{tool_id}' is not registered with the harness"
+                )
+            cmd = spec.command or [
+                "uv",
+                "run",
+                "--project",
+                spec.project_dir,
+                tool_id,
+            ]
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=spec.project_dir,
+            )
+            ep = _ExecutaProcess(spec=spec, proc=proc)
+            ep.reader_task = asyncio.create_task(self._reader_loop(ep))
+            asyncio.create_task(self._stderr_loop(ep))
+            self._procs[tool_id] = ep
+            return ep
+
+    async def _rpc(
+        self,
+        ep: _ExecutaProcess,
+        *,
+        method: str,
+        params: dict,
+        timeout: float = 65.0,
+    ) -> Any:
+        rpc_id = ep.next_id
+        ep.next_id += 1
+        env = {"jsonrpc": "2.0", "id": rpc_id, "method": method, "params": params}
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        ep.pending[rpc_id] = fut
+        assert ep.proc.stdin is not None
+        ep.proc.stdin.write((json.dumps(env) + "\n").encode("utf-8"))
+        await ep.proc.stdin.drain()
+        try:
+            return await asyncio.wait_for(fut, timeout=timeout)
+        except asyncio.TimeoutError:
+            ep.pending.pop(rpc_id, None)
+            raise _PluginError(f"executa '{ep.spec.tool_id}' timed out")
+
+    async def _reader_loop(self, ep: _ExecutaProcess) -> None:
+        assert ep.proc.stdout is not None
+        try:
+            while True:
+                line = await ep.proc.stdout.readline()
+                if not line:
+                    break
+                try:
+                    msg = json.loads(line.decode("utf-8"))
+                except Exception:
+                    continue  # ignore non-JSON noise
+                rpc_id = msg.get("id")
+                fut = ep.pending.pop(rpc_id, None) if rpc_id is not None else None
+                if fut is None or fut.done():
+                    continue
+                if "error" in msg:
+                    err = msg["error"] or {}
+                    fut.set_exception(
+                        _PluginError(
+                            f"[{err.get('code', '?')}] {err.get('message', 'unknown error')}"
+                        )
+                    )
+                else:
+                    fut.set_result(msg.get("result"))
+        finally:
+            ep.closed = True
+            for fut in ep.pending.values():
+                if not fut.done():
+                    fut.set_exception(_PluginError("executa process exited"))
+            ep.pending.clear()
+
+    async def _stderr_loop(self, ep: _ExecutaProcess) -> None:
+        assert ep.proc.stderr is not None
+        prefix = f"[executa:{ep.spec.tool_id}]"
+        while True:
+            line = await ep.proc.stderr.readline()
+            if not line:
+                break
+            sys.stderr.write(f"{prefix} {line.decode('utf-8', 'replace')}")
+
+    async def _kill(self, ep: _ExecutaProcess) -> None:
+        try:
+            if ep.proc.stdin is not None:
+                ep.proc.stdin.close()
+        except Exception:
+            pass
+        try:
+            ep.proc.terminate()
+        except Exception:
+            pass
+        try:
+            await asyncio.wait_for(ep.proc.wait(), timeout=2.0)
+        except asyncio.TimeoutError:
+            try:
+                ep.proc.kill()
+            except Exception:
+                pass
+
+
+class _PluginError(Exception):
+    """Internal: plugin returned JSON-RPC error or timed out."""
+
+    pass

anna_app_runtime_local/session.py

@@ -0,0 +1,114 @@
+"""High-level session API: glue between an `InMemoryWindowStore` and the
+production `dispatch()` function.
+
+Each `LocalDispatcherSession` owns one `InMemoryWindowSession` (= one
+iframe instance). The harness creates one per `(slug, view)` pair. The
+session also holds the parsed `AppManifest` so every `call()` re-uses
+the same authoritative ACL.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from .store import InMemoryWindowSession, InMemoryWindowStore
+
+
+class LocalSessionError(Exception):
+    """Wraps `HostRpcError` from production dispatcher with structured info."""
+
+    def __init__(self, code: str, message: str, details: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"code": self.code, "message": self.message, "details": self.details}
+
+
+class LocalDispatcherSession:
+    """One harness window. Construct via `LocalDispatcherSession.create(…)`."""
+
+    def __init__(
+        self,
+        *,
+        store: InMemoryWindowStore,
+        window: InMemoryWindowSession,
+        manifest: Any,  # AppManifest, but typed loosely to avoid early import
+    ):
+        self.store = store
+        self.window = window
+        self.manifest = manifest
+
+    @property
+    def window_uuid(self) -> str:
+        return self.window.window_uuid
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        user_id: int,
+        manifest_dict: dict,
+        view: str | None = None,
+        entry_payload: dict | None = None,
+        runtime_state: dict | None = None,
+        app_id: int = 1,
+        version_id: int = 1,
+        bundle_id: int = 1,
+        app_slug: str | None = None,
+        store: InMemoryWindowStore | None = None,
+    ) -> "LocalDispatcherSession":
+        from anna_app_core import AppManifest
+
+        manifest = AppManifest.model_validate(manifest_dict)
+
+        if store is None:
+            store = InMemoryWindowStore()
+        if user_id not in (store._users or {}):
+            store.register_user(user_id)
+
+        # Default view = first one with default=True, else first.
+        chosen_view = view
+        if chosen_view is None and manifest.ui is not None:
+            for v in manifest.ui.views:
+                if v.default:
+                    chosen_view = v.name
+                    break
+            if chosen_view is None and manifest.ui.views:
+                chosen_view = manifest.ui.views[0].name
+
+        window = InMemoryWindowSession(
+            window_uuid=str(uuid.uuid4()),
+            user_id=user_id,
+            app_id=app_id,
+            version_id=version_id,
+            bundle_id=bundle_id,
+            view=chosen_view or "main",
+            entry_payload=dict(entry_payload or {}),
+            runtime_state=dict(runtime_state or {}),
+            app_slug=app_slug,
+        )
+        store.attach_session(window)
+        return cls(store=store, window=window, manifest=manifest)
+
+    async def call(self, ns: str, method: str, args: dict | None = None) -> dict:
+        """Dispatch one envelope. Raises `LocalSessionError` on host errors."""
+        from anna_app_core import HostRpcError, dispatch
+
+        try:
+            return await dispatch(
+                self.store,
+                window=self.window,  # type: ignore[arg-type]
+                manifest=self.manifest,
+                ns=ns,
+                method=method,
+                args=args or {},
+            )
+        except HostRpcError as e:
+            raise LocalSessionError(e.code, e.message, e.details) from e
+
+    def drain_events(self) -> list[dict[str, Any]]:
+        return self.store.drain_events()

anna_app_runtime_local/store.py

@@ -0,0 +1,178 @@
+"""In-memory `WindowStoreProtocol` implementation for local dev / tests.
+
+Mirrors the attributes that production's `AnnaAppWindowSession` exposes to
+the dispatcher handlers: see `src/models/anna_app.py` (`window.user_id`,
+`window.window_uuid`, `window.title`, `window.runtime_state`, etc.).
+
+Heavy operations (`open_sibling_window`, `invoke_executa_tool`) raise
+`NotImplementedError` for the 3a slice — handlers translate that into
+`HostRpcError("not_implemented", …)`. A future 3b will plug a stdio
+plugin runner into `invoke_executa_tool`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Deque, Optional
+
+# Keep this in sync with `src/services/anna_app_runtime_service.py`
+# (`MAX_RUNTIME_STATE_BYTES`). We do not import it because the wheel must
+# remain runnable without nexus settings (which require env vars).
+MAX_RUNTIME_STATE_BYTES = 256 * 1024
+
+
+@dataclass
+class _FakeUser:
+    """Minimal stand-in for `src.models.user.User` returned by `get_user()`.
+
+    Production handlers only read `user.id` (and `default_agent_client_id`
+    inside `tools.invoke`, which the in-memory store stubs out anyway).
+    """
+
+    id: int
+    default_agent_client_id: Optional[str] = None
+
+
+@dataclass
+class InMemoryWindowSession:
+    """Mirror of `AnnaAppWindowSession` for the harness.
+
+    Field set is the strict subset that the production dispatcher handlers
+    read or write. Adding a field here when the dispatcher starts using a
+    new attribute is the supported way to keep the harness in sync.
+    """
+
+    window_uuid: str
+    user_id: int
+    app_id: int
+    version_id: int
+    bundle_id: int
+    view: str
+    title: Optional[str] = None
+    entry_payload: dict = field(default_factory=dict)
+    runtime_state: dict = field(default_factory=dict)
+    geometry: dict = field(default_factory=dict)
+    status: str = "active"
+    source: str = "harness"
+    conversation_session_uuid: Optional[str] = None
+    last_focus_at: datetime = field(default_factory=datetime.utcnow)
+    closed_reason: Optional[str] = None
+    closed_at: Optional[datetime] = None
+    app_slug: Optional[str] = None  # harness-only, helpful for logging
+
+
+class InMemoryWindowStore:
+    """`WindowStoreProtocol` impl backed by Python dicts + a deque of events.
+
+    Not thread-safe; the harness runs everything on a single asyncio loop.
+    """
+
+    def __init__(
+        self,
+        *,
+        users: dict[int, _FakeUser] | None = None,
+        executa_pool: Any | None = None,
+    ):
+        self._users: dict[int, _FakeUser] = users or {}
+        self._events: Deque[dict[str, Any]] = deque()
+        self._committed = 0  # for tests
+        # Optional `ExecutaPool` for `tools.invoke`. Lazy-imported to keep the
+        # module load light when only window/storage tests run.
+        self._executa_pool = executa_pool
+
+    def set_executa_pool(self, pool: Any) -> None:
+        self._executa_pool = pool
+
+    # ---- helper API used by the bridge -------------------------------------
+
+    def register_user(
+        self, user_id: int, *, default_agent_client_id: str | None = None
+    ) -> _FakeUser:
+        u = _FakeUser(id=user_id, default_agent_client_id=default_agent_client_id)
+        self._users[user_id] = u
+        return u
+
+    def drain_events(self) -> list[dict[str, Any]]:
+        out = list(self._events)
+        self._events.clear()
+        return out
+
+    @property
+    def commit_count(self) -> int:
+        return self._committed
+
+    # ---- WindowStoreProtocol -----------------------------------------------
+
+    async def commit(self) -> None:
+        self._committed += 1
+
+    async def get_user(self, user_id: int) -> _FakeUser | None:
+        return self._users.get(user_id)
+
+    async def replace_runtime_state(
+        self, *, user: Any, window_uuid: str, state: dict
+    ) -> None:
+        # Mirror of `runtime.replace_runtime_state`'s size guard.
+        from anna_app_core import WindowError
+
+        encoded = json.dumps(state).encode("utf-8")
+        if len(encoded) > MAX_RUNTIME_STATE_BYTES:
+            raise WindowError(
+                f"runtime_state exceeds {MAX_RUNTIME_STATE_BYTES} bytes "
+                f"(got {len(encoded)})"
+            )
+        # Mutate the live `InMemoryWindowSession` for this window.
+        for sess in self._sessions_iter():
+            if sess.window_uuid == window_uuid:
+                sess.runtime_state = dict(state)
+                return
+        raise WindowError(f"window {window_uuid} not registered with store")
+
+    async def emit_event(
+        self, user_id: int, kind: str, payload: dict[str, Any]
+    ) -> None:
+        self._events.append(
+            {
+                "user_id": user_id,
+                "kind": kind,
+                "payload": payload,
+                "ts": datetime.utcnow().isoformat() + "Z",
+            }
+        )
+
+    async def open_sibling_window(self, *, window, view_name, payload):
+        raise NotImplementedError(
+            "open_sibling_window is not available in the local harness "
+            "(slice 3a). Planned for 3b."
+        )
+
+    async def invoke_executa_tool(self, *, user_id, plugin_name, tool_name, tool_args):
+        # `plugin_name` carries the dispatcher's resolved plugin segment
+        # which equals the minted `tool_id` for mint-only ids.
+        if self._executa_pool is None or not self._executa_pool.is_registered(
+            plugin_name
+        ):
+            raise NotImplementedError(
+                f"executa '{plugin_name}' is not registered with the harness"
+            )
+        return await self._executa_pool.invoke(
+            tool_id=plugin_name, tool_name=tool_name, tool_args=tool_args
+        )
+
+    # ---- session registration ---------------------------------------------
+
+    # The session module attaches a list of `InMemoryWindowSession` to the
+    # store via this attribute. Kept private so the public API stays small.
+
+    _sessions: list[InMemoryWindowSession] | None = None
+
+    def attach_session(self, sess: InMemoryWindowSession) -> None:
+        if self._sessions is None:
+            self._sessions = []
+        self._sessions.append(sess)
+
+    def _sessions_iter(self):
+        return list(self._sessions or [])

anna_app_runtime_local/token.py

@@ -0,0 +1,113 @@
+"""Local HMAC dev tokens (NOT interoperable with production JWTs).
+
+Production uses a JWT signed with the nexus signing key (see
+`mint_window_token` in `src/services/anna_app_runtime_service.py`). The
+harness deliberately uses a separate scheme so:
+
+- The bridge does not need access to nexus settings / signing keys.
+- A leaked harness token can never authenticate against production.
+- Production's `_is_tool_allowed` already rejects `tool-dev-…` prefixes,
+  closing the loop on dev mints accidentally being uploaded.
+
+Format:  base64url(payload_json) + "." + base64url(hmac_sha256(payload, key))
+
+The key lives at `~/.anna-app/dev.key` (mode 600, generated on first
+use). TTL defaults to 30 s to surface SDK refresh bugs early.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import stat
+import time
+from pathlib import Path
+from typing import Any
+
+DEFAULT_TTL_SECONDS = 30
+_DEV_KEY_PATH = Path(os.environ.get("ANNA_APP_DEV_KEY") or "~/.anna-app/dev.key")
+
+
+class DevTokenError(ValueError):
+    """Raised on malformed / expired / signature-mismatched tokens."""
+
+
+def _key_path() -> Path:
+    return _DEV_KEY_PATH.expanduser()
+
+
+def _ensure_key() -> bytes:
+    p = _key_path()
+    if p.exists():
+        return p.read_bytes()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    key = secrets.token_bytes(32)
+    p.write_bytes(key)
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)  # 0o600
+    except OSError:
+        # Windows: best-effort.
+        pass
+    return key
+
+
+def _b64url_encode(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(s: str) -> bytes:
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def mint_dev_token(
+    *,
+    window_uuid: str,
+    user_id: int,
+    app_id: int = 0,
+    version_id: int = 0,
+    scopes: list[str] | None = None,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+) -> tuple[str, int]:
+    """Return ``(token, expires_in)``."""
+    now = int(time.time())
+    payload: dict[str, Any] = {
+        "iss": "anna-app-runtime-local",
+        "aud": "anna-app-window",
+        "sub": str(user_id),
+        "iat": now,
+        "exp": now + ttl_seconds,
+        "wid": window_uuid,
+        "uid": user_id,
+        "aid": app_id,
+        "vid": version_id,
+        "scopes": scopes or [],
+    }
+    body_b = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    sig = hmac.new(_ensure_key(), body_b, hashlib.sha256).digest()
+    return f"{_b64url_encode(body_b)}.{_b64url_encode(sig)}", ttl_seconds
+
+
+def verify_dev_token(token: str) -> dict[str, Any]:
+    if not isinstance(token, str) or "." not in token:
+        raise DevTokenError("malformed token")
+    body_b64, sig_b64 = token.split(".", 1)
+    try:
+        body_b = _b64url_decode(body_b64)
+        sig = _b64url_decode(sig_b64)
+    except (ValueError, base64.binascii.Error) as e:
+        raise DevTokenError(f"base64 decode failed: {e}") from e
+    expected = hmac.new(_ensure_key(), body_b, hashlib.sha256).digest()
+    if not hmac.compare_digest(sig, expected):
+        raise DevTokenError("bad signature")
+    try:
+        payload = json.loads(body_b)
+    except json.JSONDecodeError as e:
+        raise DevTokenError(f"payload not json: {e}") from e
+    if int(payload.get("exp", 0)) < int(time.time()):
+        raise DevTokenError("token expired")
+    return payload

anna_app_runtime_local-0.2.0a1.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: anna-app-runtime-local
+Version: 0.2.0a1
+Summary: Local-dev in-memory runtime for Anna Apps. Wraps anna-app-core's dispatcher with an InMemoryWindowStore + WebSocket bridge.
+Author: Talent AI
+License: Proprietary
+Keywords: anna,anna-app,dev,executa,harness
+Requires-Python: >=3.10
+Requires-Dist: anna-app-core<0.3,>=0.2.0a1
+Description-Content-Type: text/markdown
+
+# anna-app-runtime-local
+
+Local-dev in-memory runtime for Anna Apps. Reuses the production
+[`anna_app_rpc_dispatcher`](../../src/services/anna_app_rpc_dispatcher.py)
+through `WindowStoreProtocol` so harness behaviour is byte-identical to
+nexus production.
+
+## How it shares code with production
+
+This package does not vendor a copy of the dispatcher. Instead it:
+
+1. Imports `dispatch`, `WindowStoreProtocol`, `HostRpcError` from
+   `src.services.anna_app_rpc_dispatcher` (matrix-nexus source).
+2. Provides `InMemoryWindowStore` — a `WindowStoreProtocol` impl that
+   keeps state in dictionaries and queues SSE events in memory.
+3. Wires the production `dispatch(store, …)` against in-memory state.
+
+Because the wheel imports `src.services.…` directly, the bridge process
+must be launched from a Python environment that has matrix-nexus on
+`PYTHONPATH` (typically: `cd matrix-nexus && uv run python -m
+anna_app_runtime_local.bridge`).
+
+## Public surface
+
+```python
+from anna_app_runtime_local import LocalDispatcherSession, mint_dev_token
+
+session = LocalDispatcherSession.create(
+    user_id=1,
+    app_slug="focus-flow",
+    manifest_dict={...},  # parsed manifest.json
+    view="main",
+    entry_payload={"topic": "ECM"},
+)
+result = await session.call("storage", "set", {"key": "x", "value": 42})
+events = session.drain_events()  # list[dict] for SSE relay
+```
+
+## stdio bridge
+
+```bash
+python -m anna_app_runtime_local.bridge
+```
+
+Speaks JSON-RPC 2.0 over stdin/stdout (one envelope per line). Methods:
+
+- `session.create` → `{ session_id, window_uuid, token, view, view_meta }`
+- `session.call`   → forwards to `dispatch()`; returns `{ ok, result | error }`
+- `session.drain_events` → flushes queued SSE events
+- `session.close`  → drops the session
+- `session.refresh_token` → re-mints a dev token for an active session
+- `executas.register` → registers `{tool_id, project_dir, command?}` for
+  `tools.invoke`; first call lazy-spawns `uv run --project <dir> <tool_id>`
+  and reuses the warm subprocess.
+
+The Node-side harness (`anna-app-cli/src/harness/bridge.ts`) speaks this
+protocol over `python-shell`.
+
+## Local HMAC tokens
+
+`mint_dev_token / verify_dev_token` use a per-user key at
+`~/.anna-app/dev.key` (mode 600, generated on first use). TTL defaults
+to 30 s — shorter than production's 120 s — to surface SDK refresh bugs
+early.
+
+These tokens are **not interoperable** with the production JWT path;
+production's `_is_tool_allowed` already rejects `tool-dev-…` prefixes.

anna_app_runtime_local-0.2.0a1.dist-info/RECORD

@@ -0,0 +1,10 @@
+anna_app_runtime_local/__init__.py,sha256=o__2hxoCQOM5buEoqFrrfcecDAXDMCoXpBxpaqC-_X4,635
+anna_app_runtime_local/bridge.py,sha256=qWAUhniNS0u1JdifxkqYChYbWGQLLOyPmAD6o8QKXmU,8281
+anna_app_runtime_local/executa.py,sha256=GqGm5Bx4kDLXk0YzEUC-z4vU-HrawiA13uLsZiQS2mo,8045
+anna_app_runtime_local/session.py,sha256=PHIOHBC3eODrdHE4caviEKfh9aowEVwqXLPkOjhU2Bk,3735
+anna_app_runtime_local/store.py,sha256=wDP7HWND2T9P3v1_B0SrjslPMixXSYtF6zPKJb9di5M,6311
+anna_app_runtime_local/token.py,sha256=EJXdifn7gr2JSTNPWw1Oiu0AOhib2XzM0Y-5FBemFMw,3455
+anna_app_runtime_local-0.2.0a1.dist-info/METADATA,sha256=Oejp6jSIUbmtvBa6eqiA2Oqdu_gpTkfPTlrjVZlLIwg,2901
+anna_app_runtime_local-0.2.0a1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+anna_app_runtime_local-0.2.0a1.dist-info/entry_points.txt,sha256=Sl0TKryZ1EpHarXAPrVkOAF0vFAYpieC8qC8NME9dy0,71
+anna_app_runtime_local-0.2.0a1.dist-info/RECORD,,

anna_app_runtime_local-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

anna_app_runtime_local-0.2.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+anna-app-bridge = anna_app_runtime_local.bridge:main