anna-app-runtime-local 0.2.0a1__tar.gz

anna_app_runtime_local-0.2.0a1/.gitignore

@@ -0,0 +1,167 @@
+# matrix agent repository
+matrix/
+
+# git diff files
+git.diff
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+# setuptools sdist MANIFEST (only at repo root — must NOT swallow the
+# packages/anna-app-schema/manifest/ schema bundle directory).
+/MANIFEST
+
+# PyInstaller
+# Anchored to repo root for the same reason — `*.manifest` is too broad
+# and was matching schema bundle files. Re-add specific paths if a real
+# PyInstaller .manifest ever ships.
+/*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project specific
+*.tmp
+*.bak
+
+# Security - RSA keys
+private_key.pem
+*.pem
+!public_key.pem
+
+scripts/nats_auth
+# Anna App runtime cache
+static/anna-apps-cache/

anna_app_runtime_local-0.2.0a1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,67 @@
+# 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/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "anna-app-runtime-local"
+version = "0.2.0a1"
+description = "Local-dev in-memory runtime for Anna Apps. Wraps anna-app-core's dispatcher with an InMemoryWindowStore + WebSocket bridge."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Talent AI" }]
+keywords = ["anna", "anna-app", "executa", "dev", "harness"]
+
+# v0.2 — truly standalone. Runtime deps:
+#   * `anna-app-core` provides the dispatcher + manifest schema + protocol.
+#   * Everything else (bridge, store, token mint) is pure stdlib.
+dependencies = [
+    "anna-app-core>=0.2.0a1,<0.3",
+]
+
+[project.scripts]
+anna-app-bridge = "anna_app_runtime_local.bridge:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/anna_app_runtime_local"]

anna_app_runtime_local-0.2.0a1/src/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-0.2.0a1/src/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()