@maudecode/talaria-web 0.0.0

package/sidecar/scripts/replay_sidecar.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""A scripted sidecar that replays the recorded fixtures and stages an approval.
+
+The App contract runner and other consumers that need Web's HTTP surface but no
+Hermes Agent point the server at this script with
+``HERMES_WEBUI_SIDECAR_COMMAND='["python3", "<web>/sidecar/scripts/replay_sidecar.py"]'``.
+Every recorded method answers with its first fixture (placeholders resolved to the
+disposable home); ``chat.start`` emits one ``approval`` frame for
+``pattern_key`` ``talaria_contract_fixture`` so the approval SSE stream can be
+exercised end to end, then completes with a synthetic response. Nothing here
+touches ``~/.hermes``, a model provider, or the network.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+from pathlib import Path
+
+SIDECAR_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SIDECAR_ROOT))
+
+from talaria_sidecar.rpc import RpcServer  # noqa: E402
+
+FIXTURES = SIDECAR_ROOT.parent / "packages" / "contracts" / "fixtures" / "sidecar"
+APPROVAL_PATTERN_KEY = "talaria_contract_fixture"
+APPROVAL_COMMAND = "printf talaria-contract"
+_APPROVAL_ANSWERED = threading.Event()
+
+
+def _substitutions() -> list[tuple[str, str]]:
+    home = os.environ.get("HERMES_HOME") or str(Path.home() / ".hermes")
+    agent = os.environ.get("TALARIA_SIDECAR_AGENT_DIR") or os.environ.get("HERMES_WEBUI_AGENT_DIR") or str(SIDECAR_ROOT)
+    return [("<profile>", home), ("<home>", home), ("<user-home>", str(Path(home).parent)), ("<agent>", agent), ("<python>", sys.executable)]
+
+
+def _resolve(value, subs):
+    if isinstance(value, str):
+        for token, replacement in subs:
+            value = value.replace(token, replacement)
+        return value
+    if isinstance(value, list):
+        return [_resolve(item, subs) for item in value]
+    if isinstance(value, dict):
+        return {key: _resolve(item, subs) for key, item in value.items()}
+    return value
+
+
+def _replay(entry: dict):
+    def handler(ctx, params):
+        for frame in entry.get("stream") or []:
+            ctx.emit(frame["event"], frame.get("data") or {})
+        return entry["result"]
+    return handler
+
+
+def _chat_start(ctx, params: dict) -> dict:
+    _APPROVAL_ANSWERED.clear()
+    ctx.emit("approval", {"request_id": "talaria-contract-approval", "pattern_key": APPROVAL_PATTERN_KEY, "command": APPROVAL_COMMAND, "tool_name": "terminal", "cwd": params.get("workspace") or ""})
+    # Like a real turn, stay pending until the approval is answered (or the request is cancelled / times out).
+    for _ in range(200):
+        if _APPROVAL_ANSWERED.wait(0.1) or ctx.cancelled:
+            break
+    ctx.emit("token", {"text": "talaria-contract"})
+    history = [*params.get("conversation_history", []), {"role": "user", "content": params.get("user_message", "")}, {"role": "assistant", "content": "talaria-contract"}]
+    return {
+        "status": "completed", "messages": history, "final_response": "talaria-contract", "error": None, "result_status": "completed",
+        "tool_limit_reached": False, "usage": {"prompt_tokens": 0, "completion_tokens": 0, "cache_read_tokens": 0, "cache_write_tokens": 0, "estimated_cost_usd": None},
+        "context": {}, "model": params.get("model") or "replay", "provider": params.get("model_provider") or "replay", "compressed": False,
+        "agent_session_id": params.get("session_id", ""), "token_sent": True, "pending_steer": "", "live_tool_calls": [],
+    }
+
+
+def _approval_respond(ctx, params: dict) -> dict:
+    _APPROVAL_ANSWERED.set()
+    return {"ok": True, "resolved": 1, "choice": str(params.get("choice") or "once")}
+
+
+def _shutdown(ctx, params: dict) -> dict:
+    ctx.server.request_shutdown(int(params.get("exit_code") or 0))
+    return {"ok": True}
+
+
+def build_methods() -> dict:
+    subs = _substitutions()
+    methods = {}
+    for path in sorted(FIXTURES.glob("*.json")):
+        for method, entries in json.loads(path.read_text()).items():
+            if entries:
+                methods[method] = _replay(_resolve(entries[0], subs))
+    handshake = methods["runtime.handshake"]
+    methods["runtime.handshake"] = lambda ctx, params: {**handshake(ctx, params), "rpc_version": params.get("rpc_version", 1)}
+    methods["chat.start"] = _chat_start
+    methods["chat.interrupt"] = lambda ctx, params: {"ok": True, "reason": "replay"}
+    methods["chat.steer"] = lambda ctx, params: {"accepted": True, "fallback": None}
+    methods["chat.evict_agent"] = lambda ctx, params: {"evicted": False}
+    methods["approval.respond"] = _approval_respond
+    methods["approval.pending"] = lambda ctx, params: {"pending": []}
+    methods["approval.set_yolo"] = lambda ctx, params: {"yolo_enabled": bool(params.get("enabled")), "released": 0}
+    methods["runtime.shutdown"] = _shutdown
+    return methods
+
+
+def main() -> int:
+    out = os.fdopen(os.dup(sys.stdout.fileno()), "wb", buffering=0)
+    sys.stdout = sys.stderr
+    return RpcServer(build_methods(), stdout=out).serve_forever()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/sidecar/scripts/test.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Run the sidecar pytest suite. pytest runs on any Python >= 3.11 (a private
+# venv under sidecar/.venv); the sidecar itself is spawned on the pinned
+# Agent's venv interpreter discovered by tests/conftest.py.
+set -euo pipefail
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+runner="${HERMES_WEBUI_TEST_PYTHON:-python3}"
+venv="$here/.venv"
+if [[ ! -x "$venv/bin/python" ]]; then
+  "$runner" -m venv "$venv"
+  "$venv/bin/python" -m pip install --quiet --disable-pip-version-check "pytest>=8,<10"
+fi
+state="${TMPDIR:-/tmp}/talaria-sidecar-tests.$$"
+mkdir -p "$state"
+trap 'rm -rf -- "$state"' EXIT
+cd "$here"
+# GitHub's relocated Linux Python needs LD_LIBRARY_PATH; nothing else from the caller's environment leaks in.
+env -i PATH="$PATH" HOME="$state" TMPDIR="$state" ${LD_LIBRARY_PATH:+LD_LIBRARY_PATH="$LD_LIBRARY_PATH"} \
+  HERMES_WEBUI_AGENT_DIR="${HERMES_WEBUI_AGENT_DIR:-$HOME/.hermes/hermes-agent}" \
+  HERMES_WEBUI_PYTHON="${HERMES_WEBUI_PYTHON:-}" \
+  PYTHONPATH="$here" \
+  "$venv/bin/python" -m pytest -q "$@"

package/sidecar/talaria_sidecar/__init__.py

@@ -0,0 +1,10 @@
+"""Talaria Web sidecar: the only process that imports Hermes Agent code.
+
+Spawned by the Talaria Web server on the Agent's own venv interpreter with the
+Agent checkout on ``PYTHONPATH``. Speaks newline-delimited JSON-RPC 2.0 over
+stdio (docs/architecture/sidecar-rpc.md). Standard library only.
+"""
+
+from __future__ import annotations
+
+SIDECAR_RPC_VERSION = 1

package/sidecar/talaria_sidecar/__main__.py

@@ -0,0 +1,46 @@
+"""``python -m talaria_sidecar``: serve JSON-RPC over stdio until stdin closes."""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+from .methods import build_methods
+from .rpc import DEFAULT_MAX_CALLS, RpcServer
+from .runtime import AgentRuntime
+
+
+def _claim_stdout():
+    """Reserve the real stdout for RPC frames; everything else goes to stderr.
+
+    Agent code prints freely (profile deletion confirmations, pip output,
+    warnings). A single stray line on stdout would corrupt the JSON-RPC
+    channel, so the transport keeps a private duplicate of fd 1 and both
+    ``sys.stdout`` and fd 1 itself are redirected to stderr.
+    """
+    rpc_fd = os.dup(sys.stdout.fileno())
+    os.dup2(sys.stderr.fileno(), sys.stdout.fileno())
+    sys.stdout = sys.stderr
+    return os.fdopen(rpc_fd, "wb", buffering=0)
+
+
+def main() -> int:
+    rpc_out = _claim_stdout()
+    logging.basicConfig(stream=sys.stderr, level=os.environ.get("TALARIA_SIDECAR_LOG_LEVEL", "INFO"), format="[sidecar] %(levelname)s %(name)s: %(message)s")
+    hermes_home = Path(os.environ.get("HERMES_HOME") or Path.home() / ".hermes").expanduser()
+    # Every turn here has a human behind the Web UI: flagged actions must ask (approval cards), never auto-approve.
+    os.environ.setdefault("HERMES_EXEC_ASK", "1")
+    agent_dir = os.environ.get("TALARIA_SIDECAR_AGENT_DIR") or os.environ.get("HERMES_WEBUI_AGENT_DIR")
+    runtime = AgentRuntime(hermes_home, Path(agent_dir) if agent_dir else None)
+    if runtime.agent_dir is not None and str(runtime.agent_dir) not in sys.path:
+        # Append, never prepend: the Agent venv's site-packages must win over
+        # any same-named module in the checkout (api/config.py has the history).
+        sys.path.append(str(runtime.agent_dir))
+    server = RpcServer(build_methods(runtime), stdout=rpc_out, max_calls=int(os.environ.get("TALARIA_SIDECAR_MAX_CALLS") or DEFAULT_MAX_CALLS))
+    return server.serve_forever()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/sidecar/talaria_sidecar/errors.py

@@ -0,0 +1,41 @@
+"""JSON-RPC error codes shared by every sidecar method."""
+
+from __future__ import annotations
+
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+# Application errors. ``data.condition`` is the string the server forwards to
+# HTTP clients as the ``condition`` field of a 503/409 envelope.
+APPLICATION_ERROR = -32000
+CANCELLED = -32001
+
+
+class RpcError(Exception):
+    """Raise from a method to answer with a JSON-RPC error object."""
+
+    def __init__(self, message: str, *, code: int = APPLICATION_ERROR, condition: str | None = None, data: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        self.data = dict(data or {})
+        if condition:
+            self.data["condition"] = condition
+
+    def to_json(self) -> dict:
+        error = {"code": self.code, "message": str(self)}
+        if self.data:
+            error["data"] = self.data
+        return error
+
+
+class InvalidParams(RpcError):
+    def __init__(self, message: str, **data):
+        super().__init__(message, code=INVALID_PARAMS, data=data or None)
+
+
+class Cancelled(RpcError):
+    def __init__(self, message: str = "cancelled"):
+        super().__init__(message, code=CANCELLED, condition="cancelled")

package/sidecar/talaria_sidecar/home.py

@@ -0,0 +1,103 @@
+"""Profile-home and credential scoping for Agent calls.
+
+The Python backend pinned Hermes Agent's process-global HERMES_HOME per request
+with a shared lock. Inside the sidecar every method receives the explicit
+``profile_home`` the server resolved, and runs under Hermes Agent's own
+context-local override when the installed Agent exposes it
+(``hermes_constants.set_hermes_home_override``), falling back to a locked
+process-wide swap of ``HERMES_HOME`` for older Agents.
+
+Credentials are scoped the same way the Agent's multiplexing gateway does it
+(``agent.secret_scope``): the profile's own ``.env`` (plus its external secret
+sources) is installed as the context-local secret scope for the call. For a
+named profile the call also runs under multiplex semantics, so a miss never
+falls through to ``os.environ`` — the default profile's keys, which the server
+copied into the process environment at startup, cannot be resolved by another
+profile. If the installed Agent has no secret scope, named-profile calls fail
+closed instead of running with the inherited environment.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+from pathlib import Path
+
+from .errors import InvalidParams, RpcError
+
+_ENV_LOCK = threading.RLock()
+_PROCESS_HOME = Path(os.environ.get("HERMES_HOME") or Path.home() / ".hermes").expanduser()
+
+
+def _is_named_profile(home: Path) -> bool:
+    try:
+        return home.resolve() != _PROCESS_HOME.resolve()
+    except OSError:
+        return True
+
+
+@contextlib.contextmanager
+def _secret_scope(home: Path):
+    """Install ``home``'s credential scope for the call; named profiles run under multiplex semantics."""
+    named = _is_named_profile(home)
+    try:
+        from agent.secret_scope import (
+            build_profile_secret_scope,
+            reset_multiplex_context,
+            reset_secret_scope,
+            set_multiplex_context,
+            set_secret_scope,
+        )
+    except Exception:  # noqa: BLE001 - older Agent without a secret scope
+        if named:
+            raise RpcError(
+                "profile credential isolation is unavailable in this Hermes Agent; named-profile calls are refused",
+                condition="agent_incompatible",
+            )
+        yield
+        return
+    scope_token = set_secret_scope(build_profile_secret_scope(home))
+    mux_token = set_multiplex_context(True) if named else None
+    try:
+        yield
+    finally:
+        if mux_token is not None:
+            reset_multiplex_context(mux_token)
+        reset_secret_scope(scope_token)
+
+
+def profile_home_param(params: dict, key: str = "profile_home") -> Path:
+    raw = params.get(key)
+    if not isinstance(raw, str) or not raw.strip():
+        raise InvalidParams(f"{key} is required")
+    return Path(raw).expanduser()
+
+
+@contextlib.contextmanager
+def scoped_home(home: Path):
+    """Run the body with Hermes Agent resolving ``get_hermes_home()`` to ``home``."""
+    home = Path(home).expanduser()
+    try:
+        from hermes_constants import reset_hermes_home_override, set_hermes_home_override
+    except Exception:  # noqa: BLE001 - older Agent without context-local homes
+        set_hermes_home_override = reset_hermes_home_override = None
+    if set_hermes_home_override is not None:
+        token = set_hermes_home_override(home)
+        try:
+            with _secret_scope(home):
+                yield home
+        finally:
+            reset_hermes_home_override(token)
+        return
+    with _ENV_LOCK:
+        previous = os.environ.get("HERMES_HOME")
+        os.environ["HERMES_HOME"] = str(home)
+        try:
+            with _secret_scope(home):
+                yield home
+        finally:
+            if previous is None:
+                os.environ.pop("HERMES_HOME", None)
+            else:
+                os.environ["HERMES_HOME"] = previous

package/sidecar/talaria_sidecar/methods/__init__.py

@@ -0,0 +1,37 @@
+"""Method registry: one module per RPC namespace (docs/architecture/sidecar-rpc.md)."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from ..rpc import CallContext, Handler
+from ..runtime import AgentRuntime
+
+
+class Registry:
+    def __init__(self, runtime: AgentRuntime):
+        self.runtime = runtime
+        self.methods: dict[str, Handler] = {}
+
+    def method(self, name: str, *, requires_agent: bool = True) -> Callable[[Callable], Callable]:
+        def register(func: Callable) -> Callable:
+            def handler(ctx: CallContext, params: dict):
+                if requires_agent:
+                    self.runtime.load()
+                    self.runtime.ensure_current()
+                return func(ctx, params)
+
+            self.methods[name] = handler
+            return func
+
+        return register
+
+
+def build_methods(runtime: AgentRuntime) -> dict[str, Handler]:
+    registry = Registry(runtime)
+    from . import aux, chat, commands, config, cron, gateway, goals, kanban, mcp, process, profiles, providers, skills, state_db, stt, text, usage, worktree  # noqa: WPS433
+    from . import runtime as runtime_methods
+
+    for module in (runtime_methods, goals, commands, kanban, state_db, profiles, skills, mcp, stt, cron, providers, aux, text, process, usage, gateway, worktree, chat, config):
+        module.register(registry)
+    return registry.methods

package/sidecar/talaria_sidecar/methods/aux.py

@@ -0,0 +1,160 @@
+"""``aux.*``: auxiliary LLM calls through ``agent.auxiliary_client``."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import uuid
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+log = logging.getLogger("talaria_sidecar.aux")
+
+
+_RUNTIME_FIELDS = ("provider", "model", "base_url", "api_key", "api_mode", "acp_command", "acp_args", "credential_pool")
+
+
+def resolve_main_runtime(hint: dict | None) -> dict | None:
+    """Expand a ``{model, provider}`` hint into the resolved main-model runtime (predecessor ``_auxiliary_main_runtime``).
+
+    A hint that already carries a credential is passed through untouched."""
+    if not isinstance(hint, dict):
+        return None
+    if hint.get("api_key") or hint.get("base_url"):
+        return hint
+    from .chat import _resolve_runtime
+
+    model = str(hint.get("model") or "").strip()
+    provider = str(hint.get("provider") or "").strip() or None
+    try:
+        runtime = _resolve_runtime(provider, model)
+    except RpcError:
+        return hint
+    out = {field: runtime.get(field) for field in _RUNTIME_FIELDS if runtime.get(field) is not None}
+    out["model"] = model or str(runtime.get("model") or "")
+    out["provider"] = provider or runtime.get("provider")
+    return out
+
+
+def _main_model_completion(messages: list, runtime: dict, *, task: str) -> dict:
+    """Predecessor fallback: run the main model through ``AIAgent`` with no tools when no auxiliary client answers."""
+    from .chat import _agent_class
+
+    AIAgent = _agent_class()
+
+    system = "\n".join(str(m.get("content") or "") for m in messages if m.get("role") == "system") or None
+    user = "\n".join(str(m.get("content") or "") for m in messages if m.get("role") == "user")
+    kwargs = dict(model=runtime.get("model"), provider=runtime.get("provider"), base_url=runtime.get("base_url"), api_key=runtime.get("api_key"),
+                  platform="webui", quiet_mode=True, enabled_toolsets=[], session_id=f"{task}-{uuid.uuid4().hex[:8]}")
+    for name in ("api_mode", "acp_command", "acp_args", "credential_pool"):
+        if runtime.get(name) is not None:
+            kwargs[name] = runtime[name]
+    agent = AIAgent(**kwargs)
+    result = agent.run_conversation(user_message=user, system_message=system, conversation_history=[], task_id=kwargs["session_id"])
+    return {"model": str(runtime.get("model") or ""), "text": str((result or {}).get("final_response") or "").strip(), "usage": None}
+
+
+def complete(task: str, messages: list, *, main_runtime: dict | None, max_tokens: int | None, temperature: float | None, ctx: CallContext, main_fallback: bool = False) -> dict:
+    """One auxiliary completion; streams ``token`` frames when the client supports it.
+
+    With ``main_fallback`` the main model answers (through ``AIAgent``) when no auxiliary client is configured or the
+    auxiliary call fails, as the predecessor's git commit-message route did."""
+    try:
+        from agent.auxiliary_client import get_text_auxiliary_client
+    except Exception as exc:  # noqa: BLE001
+        raise RpcError(f"auxiliary client unavailable: {exc}", condition="aux_unavailable") from exc
+    main_runtime = resolve_main_runtime(main_runtime)
+    try:
+        client, model = get_text_auxiliary_client(task, main_runtime=main_runtime)
+    except TypeError:
+        client, model = get_text_auxiliary_client(task)
+    if client is None or not model:
+        if main_fallback and main_runtime and main_runtime.get("model"):
+            return _main_model_completion(messages, main_runtime, task=task)
+        raise RpcError(f"no auxiliary model configured for task {task!r}", condition="aux_unconfigured")
+    if main_fallback and main_runtime and main_runtime.get("model"):
+        try:
+            return _stream_completion(client, model, messages, max_tokens=max_tokens, temperature=temperature, ctx=ctx)
+        except RpcError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - predecessor fell back to the main model
+            log.debug("auxiliary %s call failed; falling back to the main model: %s", task, exc)
+            return _main_model_completion(messages, main_runtime, task=task)
+    return _stream_completion(client, model, messages, max_tokens=max_tokens, temperature=temperature, ctx=ctx)
+
+
+def _stream_completion(client, model: str, messages: list, *, max_tokens: int | None, temperature: float | None, ctx: CallContext) -> dict:
+    kwargs: dict = {"model": model, "messages": messages}
+    if max_tokens:
+        kwargs["max_tokens"] = int(max_tokens)
+    if temperature is not None:
+        kwargs["temperature"] = float(temperature)
+    text_parts: list[str] = []
+    usage = None
+    try:
+        stream = client.chat.completions.create(stream=True, **kwargs)
+        for chunk in stream:
+            ctx.check_cancelled()
+            choices = getattr(chunk, "choices", None) or []
+            delta = getattr(choices[0], "delta", None) if choices else None
+            piece = getattr(delta, "content", None) if delta is not None else None
+            if piece:
+                text_parts.append(piece)
+                ctx.emit("token", {"text": piece})
+            chunk_usage = getattr(chunk, "usage", None)
+            if chunk_usage is not None:
+                usage = _usage_dict(chunk_usage)
+    except RpcError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - fall back to a non-streaming call
+        log.debug("streaming auxiliary call failed (%s); retrying without stream", exc)
+        response = client.chat.completions.create(**kwargs)
+        text_parts = [str(response.choices[0].message.content or "")]
+        usage = _usage_dict(getattr(response, "usage", None))
+    return {"model": str(model), "text": "".join(text_parts).strip(), "usage": usage}
+
+
+def _usage_dict(usage) -> dict | None:
+    if usage is None:
+        return None
+    out = {}
+    for key in ("prompt_tokens", "completion_tokens", "total_tokens"):
+        value = getattr(usage, key, None)
+        if isinstance(value, int):
+            out[key] = value
+    return out or None
+
+
+def register(registry) -> None:
+    @registry.method("aux.complete")
+    def complete_(ctx: CallContext, params: dict) -> dict:
+        task = str(params.get("task") or "").strip()
+        messages = params.get("messages")
+        if not task:
+            raise InvalidParams("task is required")
+        if not isinstance(messages, list) or not messages:
+            raise InvalidParams("messages must be a non-empty list")
+        main_runtime = params.get("main_runtime") if isinstance(params.get("main_runtime"), dict) else None
+        with scoped_home(profile_home_param(params)):
+            return complete(task, messages, main_runtime=main_runtime, max_tokens=params.get("max_tokens"), temperature=params.get("temperature"), ctx=ctx, main_fallback=bool(params.get("main_fallback")))
+
+    @registry.method("aux.resolve")
+    def resolve(ctx: CallContext, params: dict) -> dict:
+        """Which model would serve ``task`` (no call made)."""
+        task = str(params.get("task") or "").strip()
+        if not task:
+            raise InvalidParams("task is required")
+        main_runtime = params.get("main_runtime") if isinstance(params.get("main_runtime"), dict) else None
+        with scoped_home(profile_home_param(params)):
+            try:
+                from agent.auxiliary_client import get_text_auxiliary_client
+
+                try:
+                    client, model = get_text_auxiliary_client(task, main_runtime=resolve_main_runtime(main_runtime))
+                except TypeError:
+                    client, model = get_text_auxiliary_client(task)
+            except Exception as exc:  # noqa: BLE001
+                return {"configured": False, "model": None, "error": f"{type(exc).__name__}: {exc}"}
+        return {"configured": bool(client is not None and model), "model": str(model) if model else None}