@maudecode/talaria-web 1.18.0 → 1.20.0

package/sidecar/talaria_sidecar/methods/gateway_sessions.py

@@ -0,0 +1,418 @@
+"""Authenticated observations, fenced controls and diagnostic creation through an existing native owner.
+
+Never ensure/start a gateway, build an Agent, or write its transcript locally.
+Each call owns its connection and subscription; cancellation only detaches it.
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager, closing, suppress
+from importlib.util import find_spec
+import json
+from pathlib import Path
+import re
+import sqlite3
+
+from ..errors import InvalidParams
+from ..home import profile_home_param, scoped_home
+
+_ACTIONS = {"snapshot", "watch", "context_detail", "submit", "receipt", "cancel", "steer_queued", "replace_queued", "interrupt", "approval", "clarify",
+            "clarify_lock", "discard", "mutate", "export"}
+_EXPORT_MAX_BYTES = 4 * 1024 * 1024
+# A restart's after-turn wait keeps the owner reachable only to finish its parked turn (the owner's
+# RESTART_WAIT_WS_METHODS); new work waits for the next owner.
+_RESTART_ACTIONS = {"snapshot", "watch", "receipt", "approval", "clarify", "clarify_lock", "interrupt"}
+_CAPABILITIES = {"durable-admission-v1", "event-replay-v1"}
+_CONTROL_REFUSALS = {"native_clarify_batch_unavailable", "owner_controls_unverified"}
+_CREATE_FIELDS = {"request_id", "source", "cwd", "model", "provider", "base_url", "toolsets", "safe_mode", "ignore_user_config"}
+
+
+def _batch_locks() -> bool:
+    """v0.22.3 owners serve ``clarify.lock``, so an attached viewer can answer a clarify batch per question."""
+    return find_spec("gateway.session_clarify_lock") is not None
+
+
+def _restart_wait(home: Path) -> bool:
+    """Whether the owner has entered a restart's after-turn wait since a watch attached. The owner announces
+    it on no socket, and the watch must not send on its own: a socket opened before the wait is cut when it does."""
+    from hermes_cli import gateway_runtime
+    if not hasattr(gateway_runtime, "attachable"):
+        return False
+    try:
+        found = gateway_runtime.discover_gateway_endpoint(home)
+    except Exception:  # noqa: BLE001 - a failed probe leaves the watch as it was; every action rediscovers anyway
+        return False
+    return found.state != "ready" and gateway_runtime.attachable(found)
+
+
+def _control_refusal(home: Path, sid: str) -> str | None:
+    """Only canonical PendingControls can be recovered before v0.22.3. Never infer a missing batch.
+
+    Read the owner's committed admission in a read-only connection; opening SessionDB here
+    would run its schema writer alongside the owner. Compression keeps the logical target.
+    """
+    try:
+        with closing(sqlite3.connect((home / "state.db").as_uri() + "?mode=ro", uri=True, timeout=2)) as db:
+            rows = db.execute("""SELECT payload_json FROM session_admissions
+                WHERE target_session_id=? AND status IN ('queued', 'started')""", (sid,))
+            for (raw,) in rows:
+                payload = json.loads(raw)
+                policy = payload.get("cli_turn_v1", {})
+                if not isinstance(policy, dict):
+                    return "owner_controls_unverified"
+                if "clarify_batch" in policy and not isinstance(policy["clarify_batch"], bool):
+                    return "owner_controls_unverified"
+                if policy.get("clarify_batch") is True and not _batch_locks():
+                    return "native_clarify_batch_unavailable"
+    except (sqlite3.Error, OSError, ValueError, TypeError, AttributeError):
+        return "owner_controls_unverified"
+    return None
+
+
+def _snapshot(value: dict) -> dict:
+    # Raw conversation rows contain private principal/admission metadata; the client needs
+    # display rows, not those bindings or the inventory's system prompt and credential hint.
+    message_keys = {"role", "content", "tool_calls", "tool_call_id", "name", "timestamp", "message_id", "row_id",
+                    "reasoning", "reasoning_content", "display_kind", "finish_reason"}
+    info_keys = {"title", "model", "cwd", "source", "provider", "config_warning"}
+    return {**value, "messages": [{k: v for k, v in row.items() if k in message_keys} for row in value["messages"]],
+            "info": {k: v for k, v in value["info"].items() if k in info_keys}}
+
+
+def _refused(state: str, reason: str) -> dict:
+    return {"state": state, "reason": reason, "snapshot": None, "receipt": None}
+
+
+@asynccontextmanager
+async def _connect(home: Path, endpoint):
+    from hermes_constants import get_hermes_home
+    from hermes_cli.gateway_client import GatewayClientError, connect_gateway
+
+    # The supplied endpoint selects the native client's attach-only branch. The home
+    # override is mandatory so its bootstrap ticket cannot fall back to the launch profile.
+    if Path(get_hermes_home()).resolve() != home:
+        raise GatewayClientError("profile_mismatch")
+    async with connect_gateway(endpoint) as client:
+        websocket = client.websocket
+        # GatewayClient queues server requests as events. Drain continuously, including
+        # during an RPC, so unsupported sudo/secure inputs never wait for a Web renderer.
+        events = asyncio.Queue(maxsize=4096)
+
+        async def drain():
+            while True:
+                frame = await client.events.get()
+                if isinstance(frame, dict) and frame.get("method") in {"sudo", "secret"} and "id" in frame:
+                    await websocket.send(json.dumps({"jsonrpc": "2.0", "id": frame["id"], "result": {"value": ""}}))
+                else:
+                    await events.put(frame)
+
+        reader = asyncio.create_task(drain())
+        try:
+            yield client, events
+        finally:
+            reader.cancel()
+            with suppress(asyncio.CancelledError):
+                await reader
+
+
+def _served(home: Path, endpoint, *, allow_verified: bool = False) -> bool:
+    if not endpoint.control_home or Path(endpoint.control_home).resolve() == home:
+        return False
+    if not allow_verified:
+        return True
+    # The private control socket reports the owner's boot revision, not the sidecar's
+    # checkout or a version label. The authenticated describe must still match below.
+    try:
+        record = json.loads((Path(__file__).resolve().parents[2] / "agent_support.json").read_text())
+        revisions = record["nativeContracts"]["served-local-policy-v1"]
+        return (not isinstance(revisions, list)
+                or not all(isinstance(sha, str) and re.fullmatch(r"[0-9a-f]{40}", sha) for sha in revisions)
+                or getattr(endpoint, "code_sha", None) not in revisions)
+    except (OSError, ValueError, KeyError, TypeError):
+        return True
+
+
+def _owner_refusal(described: dict, endpoint) -> dict | None:
+    if (not isinstance(described, dict)
+            or described.get("instance_id") != endpoint.instance_id
+            or described.get("profile_id") != endpoint.profile_id
+            or type(described.get("authority_epoch")) is not int
+            or described.get("authority_epoch") != endpoint.authority_epoch
+            or not isinstance(described.get("capabilities"), list)
+            or not all(isinstance(capability, str) for capability in described["capabilities"])
+            or not _CAPABILITIES.issubset(described.get("capabilities", []))):
+        return _refused("incompatible", "owner_capabilities")
+    return None
+
+
+async def _run(ctx, params: dict, home: Path, discovery) -> dict:
+    from hermes_cli.gateway_client import GatewayRPCError
+
+    endpoint = discovery.endpoint
+    if _served(home, endpoint, allow_verified=True):
+        return _refused("incompatible", "served_profile_sessions_unavailable")
+    restarting = discovery.state != "ready"
+    if restarting and params["action"] not in _RESTART_ACTIONS:
+        return _refused("refused", "gateway_restarting")
+    subscription = None
+    async with _connect(home, endpoint) as (client, events):
+        described = await client.rpc("runtime.describe")
+        if refusal := _owner_refusal(described, endpoint):
+            return refusal
+        sid = params["session_id"]
+
+        async def snapshot():
+            nonlocal subscription, sid
+            value = await client.rpc("session.resume", session_id=sid)
+            sid = value["session_id"]
+            # Native attach reuses this actor's subscription; overflow retires it before
+            # a replacement is issued. A resume does not accumulate live subscriptions.
+            subscription = value["subscription_id"]
+            if reason := await asyncio.to_thread(_control_refusal, home, sid):
+                raise GatewayRPCError(reason)
+            return _snapshot(value)
+
+        receipt = lock = None
+        try:
+            if params["action"] == "export":
+                # No resume/subscription or mutation: the owner selects its current physical target.
+                fmt = "md" if params["format"] == "markdown" else params["format"]
+                value = await asyncio.wait_for(client.rpc("session.export", session_id=sid,
+                    format=fmt, redact=params["redact"], _timeout=25), timeout=30)
+                if (not isinstance(value, dict) or value.get("format") != fmt
+                        or not isinstance(value.get("filename"), str) or not 0 < len(value["filename"]) <= 255
+                        or not isinstance(value.get("content"), str)):
+                    return _refused("refused", "owner_export_invalid")
+                if len(value["content"]) > _EXPORT_MAX_BYTES or len(value["content"].encode("utf-8")) > _EXPORT_MAX_BYTES:
+                    return _refused("refused", "export_too_large")
+                return {"state": "attached", "reason": None, "snapshot": None, "receipt": None,
+                        "export": {"format": params["format"], "filename": value["filename"], "content": value["content"]}}
+            snap = await snapshot()
+            action = params["action"]
+            common = {"session_id": sid}
+            if action == "context_detail":
+                from ..context_detail import project, unavailable
+                # The authorized native read owns lookup and prompt interpretation. No local Agent is built.
+                try:
+                    payload = await client.rpc("session.context_breakdown", **common)
+                    usage = None
+                    with suppress(Exception):
+                        usage = await client.rpc("session.stats", **common)
+                    after = await snapshot()
+                    marks = ("session_id", "stored_session_id", "authority_epoch", "replay_epoch", "revision", "execution_generation", "running", "last_sequence")
+                    stable = all(snap.get(k) == after.get(k) for k in marks) and snap.get("info") == after.get("info")
+                    detail = project(payload, usage=usage, running=after.get("running") is True) if stable else unavailable("changed")
+                except Exception:  # unsupported owners and failed reads never authorize a fallback Agent
+                    detail = unavailable("unsupported")
+                return {"state": "attached", "reason": None, "snapshot": snap, "receipt": None, "context_detail": detail}
+            if action == "submit":
+                # The caller retains this identity across lost ACKs. An ambiguous error never
+                # causes this adapter to generate a replacement or replay started work.
+                receipt = await client.rpc("prompt.submit", **common, submission_id=params["request_id"], text=params["text"])
+            elif action == "receipt":
+                receipt = await client.rpc("prompt.receipt", **common, admission_id=params["admission_id"])
+            elif action in {"cancel", "discard"}:
+                method = "prompt.cancel" if action == "cancel" else "prompt.resolve_unknown"
+                receipt = await client.rpc(method, **common, admission_id=params["admission_id"],
+                    **({"execution_generation": params["execution_generation"]} if action == "discard" else {}))
+            elif action in {"steer_queued", "replace_queued"}:
+                receipt = await client.rpc("prompt." + action, **common, admission_id=params["admission_id"],
+                    **({"submission_id": params["submission_id"], "text": params["text"]} if action == "replace_queued" else {}))
+            elif action == "interrupt":
+                await client.rpc("session.interrupt", **common, execution_generation=params["execution_generation"])
+            elif action == "clarify_lock":
+                # The lock that answers the last question settles the batch with every locked answer.
+                lock = await client.rpc("clarify.lock", request_id=params["request_id"],
+                                        question_id=params["question_id"], answer=params["answer"])
+            elif action in {"approval", "clarify"}:
+                await client.rpc(action + ".respond", **common, prompt_id=params["prompt_id"],
+                    execution_generation=params["execution_generation"],
+                    **({"choice": params["choice"]} if action == "approval" else {"answer": params["text"]}))
+            elif action == "mutate":
+                receipt = await client.rpc("session.mutate", **common, request_id=params["request_id"],
+                    expected_revision=params["expected_revision"], expected_generation=params["execution_generation"],
+                    operation=params["operation"], payload=params["payload"], _timeout=660)
+            if action not in {"snapshot", "watch"}:
+                snap = await snapshot()
+            result = {"state": "attached", "reason": None, "snapshot": snap, "receipt": receipt, "restarting": restarting,
+                      **({"lock": lock} if action == "clarify_lock" else {})}
+            if action != "watch":
+                return result
+            # Display negotiation is best effort on older owners. It changes no persisted config.
+            if isinstance(params.get("show_reasoning"), bool):
+                with suppress(GatewayRPCError, TimeoutError):
+                    await client.rpc("config.set", **common, key="show_reasoning",
+                                     value="1" if params["show_reasoning"] else "0", _timeout=10)
+            ctx.emit("snapshot", {**result, "replaying": True})
+            epoch, sequence = snap["replay_epoch"], snap["last_sequence"]
+            # Rebuild the active turn's display from retained events, even when its initial
+            # tokens predate this viewer. A gap replaces the subscription, never invents replay.
+            replay = await client.rpc("session.events.since", **common, replay_epoch=epoch, last_sequence=0)
+            if replay.get("snapshot_required"):
+                snap = await snapshot()
+                ctx.emit("snapshot", {**result, "snapshot": snap, "replay_gap": True, "replaying": True})
+                epoch, sequence = snap["replay_epoch"], snap["last_sequence"]
+            else:
+                for event in replay["events"]:
+                    if event.get("session_id") != sid or event.get("replay_epoch") != epoch:
+                        continue
+                    if (event.get("type") in {"session.updated", "notification.show", "notification.clear"}
+                            or event.get("execution_generation") == snap["execution_generation"]
+                            or event.get("type") == "session.info" and event.get("payload", {}).get("execution_generation") == snap["execution_generation"]):
+                        ctx.emit("event", event)
+                sequence = replay["last_sequence"]
+            ctx.emit("replay_complete", {})
+            checked = asyncio.get_running_loop().time()
+            while not ctx.cancelled:
+                try:
+                    frame = await asyncio.wait_for(events.get(), .25)
+                except TimeoutError:
+                    now = asyncio.get_running_loop().time()
+                    if not restarting and now - checked >= 2:
+                        checked = now
+                        # One-way for this owner: its next state is exit, which ends the watch.
+                        if restarting := await asyncio.to_thread(_restart_wait, home):
+                            result["restarting"] = True
+                            ctx.emit("restarting", {"restarting": True})
+                    continue
+                if isinstance(frame, Exception):
+                    raise frame
+                if frame.get("method") == "clarify" and "id" in frame:
+                    if not _batch_locks():
+                        raise GatewayRPCError("native_clarify_batch_unavailable")
+                    # The owner asks attached viewers only, once; its later request.cancel event settles it.
+                    request = frame.get("params", {})
+                    if request.get("session_id") == sid:
+                        ctx.emit("clarify_batch", {"request_id": frame["id"], "questions": request.get("questions", [])})
+                    continue
+                if frame.get("method") != "event":
+                    continue
+                event = frame.get("params", {})
+                if event.get("session_id") != sid:
+                    continue
+                if event.get("type") == "session.info":
+                    if reason := await asyncio.to_thread(_control_refusal, home, sid):
+                        raise GatewayRPCError(reason)
+                if (event.get("type") == "session.replay_gap" or event.get("replay_epoch") != epoch
+                        or event.get("seq", sequence + 1) > sequence + 1):
+                    current = await snapshot()
+                    # A queued frame from an obsolete epoch is not a gap in the current subscription.
+                    if (event.get("type") != "session.replay_gap" and event.get("replay_epoch") != epoch
+                            and current["replay_epoch"] == epoch):
+                        continue
+                    snap = current
+                    ctx.emit("snapshot", {**result, "snapshot": snap, "replay_gap": True})
+                    epoch, sequence = snap["replay_epoch"], snap["last_sequence"]
+                    continue
+                if event.get("seq", 0) <= sequence:
+                    continue
+                sequence = event["seq"]
+                ctx.emit("event", event)
+            return result
+        except GatewayRPCError as exc:
+            if params["action"] == "export":
+                return _refused("refused", "export_too_large" if str(exc) == "export_too_large" else "owner_export_unsupported")
+            return {**_refused("incompatible" if str(exc) in _CONTROL_REFUSALS else "refused", str(exc)), "receipt": receipt}
+        except Exception:  # noqa: BLE001 - native transport/contract failures never authorize another writer
+            # A received receipt remains admission proof even if the following observation
+            # disconnects. Losing that ACK would invite a new request identity for admitted work.
+            return {**_refused("unavailable", "owner_connection_lost"), "receipt": receipt}
+        finally:
+            if subscription:
+                with suppress(Exception):
+                    await client.rpc("session.detach", session_id=sid, subscription_id=subscription)
+
+
+def session(ctx, params: dict) -> dict:
+    home = profile_home_param(params).resolve()
+    action = params.get("action", "snapshot")
+    sid = params.get("session_id")
+    if action not in _ACTIONS or not isinstance(sid, str) or not sid.strip() or sid != sid.strip():
+        raise InvalidParams("session_id and supported action are required")
+    params = {**params, "action": action}
+    if action == "export" and (params.get("format") not in ("json", "markdown", "html")
+                               or not isinstance(params.get("redact"), bool)):
+        raise InvalidParams("export requires an allowed format and redaction policy")
+    required = {
+        "submit": ("request_id", "text"), "receipt": ("admission_id",), "cancel": ("admission_id",),
+        "steer_queued": ("admission_id",), "replace_queued": ("admission_id", "submission_id", "text"),
+        "interrupt": ("execution_generation",), "approval": ("execution_generation", "prompt_id", "choice"),
+        "clarify": ("execution_generation", "prompt_id", "text"), "clarify_lock": ("request_id", "question_id", "answer"), "discard": ("execution_generation", "admission_id"),
+        "mutate": ("request_id", "expected_revision", "execution_generation", "operation", "payload"),
+    }.get(action, ())
+    if any(key not in params for key in required):
+        raise InvalidParams("missing gateway session action fields")
+    return _with_owner(home, lambda discovery: _run(ctx, params, home, discovery))
+
+
+def _with_owner(home: Path, run) -> dict:
+    try:
+        from hermes_constants import set_hermes_home_override, reset_hermes_home_override  # noqa: F401
+        from hermes_cli import gateway_runtime
+        from hermes_cli.gateway_client import connect_gateway  # noqa: F401
+    except ImportError:
+        return _refused("incompatible", "native_sessions_unavailable")
+    # v0.22.3 also admits a restart's after-turn wait, so a parked approval or clarify can still be answered.
+    attachable = getattr(gateway_runtime, "attachable", lambda found: found.state == "ready")
+    with scoped_home(home):
+        discovery = gateway_runtime.discover_gateway_endpoint(home)
+        if discovery.endpoint is None or not attachable(discovery):
+            return _refused("stopped" if discovery.state in {"stopped", "absent"} else "unavailable", discovery.reason_code or discovery.state)
+        try:
+            return asyncio.run(run(discovery))
+        except Exception:  # noqa: BLE001 - native transport/contract failures never authorize another writer
+            # Do not expose peer diagnostics, endpoint paths or bootstrap credentials.
+            return _refused("unavailable", "owner_connection_lost")
+
+
+async def _create(params: dict, home: Path, discovery) -> dict:
+    """Mint one diagnostic session through the owner, which freezes the bypass in its creation
+    policy and runs every turn in a fresh private worker. Talaria never imports the Agent with
+    that policy, flips a process global or passes it through the environment."""
+    from hermes_cli.gateway_client import GatewayRPCError
+
+    endpoint = discovery.endpoint
+    if _served(home, endpoint):
+        return _refused("incompatible", "served_profile_sessions_unavailable")
+    if discovery.state != "ready":
+        return _refused("unavailable", "gateway_restarting")
+    async with _connect(home, endpoint) as (client, _):
+        described = await client.rpc("runtime.describe")
+        if refusal := _owner_refusal(described, endpoint):
+            return refusal
+        accepted = set((described.get("session_create") or {}).get("parameters", []))
+        if "local-cli-create-v1" not in described.get("capabilities", []) or not _CREATE_FIELDS.issubset(accepted):
+            return _refused("incompatible", "execution_mode_unavailable")
+        if params.get("probe") is True:
+            return {"state": "attached", "reason": None, "snapshot": None, "receipt": None}
+        fields = {key: params[key] for key in ("cwd", "model", "provider", "base_url", "toolsets") if params.get(key) is not None}
+        try:
+            # Safe implies config-only; the owner normalizes it too. No credential is sent or receipted.
+            created = await client.rpc("session.create", request_id=params["request_id"], source="cli", **fields,
+                                       safe_mode=params["execution_mode"] == "safe", ignore_user_config=True)
+        except GatewayRPCError as exc:
+            return _refused("refused", str(exc))
+        with suppress(Exception):
+            await client.rpc("session.detach", session_id=created["session_id"], subscription_id=created["subscription_id"])
+        return {"state": "attached", "reason": None, "snapshot": _snapshot(created), "receipt": None}
+
+
+def _text(params: dict, key: str, required: bool = True) -> bool:
+    value = params.get(key)
+    if value is None:
+        return not required
+    return isinstance(value, str) and bool(value) and value == value.strip()
+
+
+def create(params: dict) -> dict:
+    """``probe`` answers whether this owner can create diagnostic sessions, without creating one."""
+    home = profile_home_param(params).resolve()
+    toolsets = params.get("toolsets")
+    if params.get("probe") is not True and (
+            params.get("execution_mode") not in {"ignore_config", "safe"}
+            or not _text(params, "request_id") or len(params["request_id"]) > 128
+            or not _text(params, "model") or not _text(params, "cwd") or not Path(params["cwd"]).is_absolute()
+            or not _text(params, "provider", False) or not _text(params, "base_url", False)
+            or toolsets is not None and (not isinstance(toolsets, list) or not all(isinstance(t, str) and t for t in toolsets))):
+        raise InvalidParams("execution_mode, request_id, model and an absolute cwd are required")
+    return _with_owner(home, lambda discovery: _create(params, home, discovery))

package/sidecar/talaria_sidecar/methods/goals.py

@@ -1,7 +1,8 @@
 """``goals.*``: Hermes persistent session goals (ported from api/goals.py).
 
-The server passes the session's ``profile_home`` and the configured turn
-budget; the sidecar never reads WebUI settings itself.
+The server passes the session's ``profile_home``, its workspace and the configured
+turn budget; the sidecar never reads WebUI settings itself. ``/goal`` parses through
+the Agent's own ``dispatch_goal_command``, like its CLI, gateway and TUI.
 """
 
 from __future__ import annotations
@@ -14,7 +15,7 @@ from pathlib import Path
 from typing import Any
 
 from ..errors import InvalidParams, RpcError
-from ..home import profile_home_param, scoped_home
+from ..home import profile_home_param, scoped_home, session_workspace
 from ..rpc import CallContext
 
 log = logging.getLogger("talaria_sidecar.goals")
@@ -29,17 +30,18 @@ def _native():
 
 
 class _Manager:
-    """Native GoalManager scoped to one profile home."""
+    """Native GoalManager scoped to one profile home and the session's workspace, where its gates run."""
 
-    def __init__(self, session_id: str, profile_home: Path, default_max_turns: int):
+    def __init__(self, session_id: str, profile_home: Path, default_max_turns: int, workspace: str | None = None):
         _, default, GoalManager, _, _ = _native()
         self.session_id = session_id
         self.profile_home = profile_home
+        self.workspace = workspace
         with scoped_home(profile_home):
             self._manager = GoalManager(session_id=session_id, default_max_turns=int(default_max_turns or default or 20))
 
     def scoped(self, func, *args, **kwargs):
-        with scoped_home(self.profile_home):
+        with scoped_home(self.profile_home), session_workspace(self.workspace):
             return func(*args, **kwargs)
 
     @property
@@ -123,13 +125,22 @@ def _decision_payload(decision: dict, state: Any) -> dict:
         turns_used, max_turns = _turns_from_message(str(decision.get("message") or ""))
     if status == "done":
         return {**decision, "message_key": "goal_achieved", "message_args": [reason]}
-    if status == "paused":
+    if status == "paused" and str(getattr(state, "paused_reason", "") or "").startswith("turn budget exhausted"):
         return {**decision, "message_key": "goal_paused_budget_exhausted", "message_args": [turns_used, max_turns]}
     if decision.get("should_continue"):
         return {**decision, "message_key": "goal_continuing", "message_args": [turns_used, max_turns, reason]}
     return decision
 
 
+def _parked(mgr: _Manager) -> dict | None:
+    """TAL-808: an active goal's live wait barrier, as the Agent's own ``is_waiting`` (which clears a satisfied one) sees it."""
+    if not mgr.is_waiting():
+        return None
+    state = mgr.state
+    until = float(getattr(state, "waiting_until", 0.0) or 0.0)
+    return {"reason": getattr(state, "waiting_reason", None) or None, "until": until or None}
+
+
 def _inactive(reason: str, status=None) -> dict:
     return {"status": status, "should_continue": False, "continuation_prompt": None, "verdict": "inactive", "reason": reason, "message": ""}
 
@@ -139,7 +150,41 @@ def _manager_from(params: dict) -> _Manager:
     if not session_id:
         raise InvalidParams("session_id is required")
     max_turns = params.get("default_max_turns") or 20
-    return _Manager(session_id, profile_home_param(params), int(max_turns))
+    return _Manager(session_id, profile_home_param(params), int(max_turns), str(params.get("workspace") or "") or None)
+
+
+#: Older Agents run gates in their launch directory, where a gate checks another project and can pass for it.
+_GATES_NEED_WORKSPACE = "Goal gates need Hermes Agent 0.21.6 or later, which runs them in the session workspace."
+
+
+def _gates_run_in_workspace() -> bool:
+    from hermes_cli import goals as agent_goals
+
+    return hasattr(agent_goals, "_gate_workspace")
+
+
+#: The response ``action`` of each control verb the Agent dispatches; any other command sets the goal.
+_CONTROL_ACTIONS = {
+    "": "status", "status": "status", "show": "show", "pause": "pause", "resume": "resume", "continue": "resume",
+    "unpause": "resume", "clear": "clear", "stop": "clear", "done": "clear", "unwait": "unwait", "wait": "wait", "gate": "gate",
+}
+
+
+def _localized(action: str, state: Any, had_goal: bool) -> dict:
+    """``message_key``/``message_args`` for the verbs Web already localizes; other verbs show the Agent's text."""
+    status = str(getattr(state, "status", "") or "")
+    goal = str(getattr(state, "goal", "") or "")
+    if action == "status":
+        return {k: v for k, v in _status_payload(state).items() if k != "message"}
+    if action == "set":
+        return {"message_key": "goal_set", "message_args": [int(getattr(state, "max_turns", 0) or 0), goal]}
+    if action == "pause":
+        return {"message_key": "goal_paused", "message_args": [goal]} if had_goal and status == "paused" else {"message_key": "goal_no_goal"}
+    if action == "resume":
+        return {"message_key": "goal_resumed", "message_args": [goal]} if had_goal and status == "active" else {"message_key": "goal_no_goal"}
+    if action == "clear":
+        return {"message_key": "goal_cleared" if had_goal else "goal_no_goal"}
+    return {}
 
 
 def register(registry) -> None:
@@ -147,45 +192,35 @@ def register(registry) -> None:
     def get(ctx: CallContext, params: dict) -> dict:
         mgr = _manager_from(params)
         state = mgr.state
-        return {"goal": _state_payload(state), "active": bool(state is not None and getattr(state, "status", None) == "active"), **_status_payload(state)}
+        active = bool(state is not None and getattr(state, "status", None) == "active")
+        return {"goal": _state_payload(state), "active": active, "parked": _parked(mgr) if active else None, **_status_payload(state)}
 
     @registry.method("goals.command")
     def command(ctx: CallContext, params: dict) -> dict:
-        """/goal <args> with the same semantics as the gateway command."""
+        """/goal <args> through the Agent's ``dispatch_goal_command``, as its TUI runs it."""
         mgr = _manager_from(params)
+        try:
+            from hermes_cli import goals as agent_goals
+            from hermes_cli.goal_command import dispatch_goal_command, is_goal_control
+        except Exception as exc:  # noqa: BLE001
+            raise RpcError(f"Hermes goals unavailable: {exc}", condition="goals_unavailable")
         text = str(params.get("args") or "").strip()
-        lower = text.lower()
-        stream_running = bool(params.get("stream_running", False))
-        if not text or lower == "status":
-            state = mgr.state
-            return _payload(action="status", state=state, **_status_payload(state))
-        if lower == "pause":
-            state = mgr.pause(reason="user-paused")
-            if state is None:
-                return _payload(ok=False, action="pause", error="no_goal", message="No goal set.", message_key="goal_no_goal")
-            return _payload(action="pause", message=f"⏸ Goal paused: {state.goal}", message_key="goal_paused", message_args=[str(state.goal)], state=state)
-        if lower == "resume":
-            state = mgr.resume()
-            if state is None:
-                return _payload(ok=False, action="resume", error="no_goal", message="No goal to resume.", message_key="goal_no_goal")
-            return _payload(action="resume", message=f"▶ Goal resumed: {state.goal}\nSend a new message, or type continue, to kick it off.", message_key="goal_resumed", message_args=[str(state.goal)], state=state)
-        if lower in ("clear", "stop", "done"):
-            had = bool(mgr.has_goal())
-            mgr.clear()
-            return _payload(action="clear", message="Goal cleared." if had else "No active goal.", message_key="goal_cleared" if had else "goal_no_goal", state=mgr.state)
-        if stream_running:
+        tokens = text.lower().split()
+        action = _CONTROL_ACTIONS.get(tokens[0] if tokens else "", "set") if is_goal_control(text) else "set"
+        if action == "set" and params.get("stream_running"):
             return _payload(ok=False, action="set", error="agent_running", message="Agent is running — use /goal status / pause / clear mid-run, or /stop before setting a new goal.")
-        try:
-            state = mgr.set(text)
-        except ValueError as exc:
-            return _payload(ok=False, action="set", error="invalid_goal", message=f"Invalid goal: {exc}")
-        return _payload(
-            action="set",
-            message=(f"⊙ Goal set ({state.max_turns}-turn budget): {state.goal}\n"
-                     "I'll keep working until the goal is done, you pause/clear it, or the budget is exhausted.\n"
-                     "Controls: /goal status · /goal pause · /goal resume · /goal clear"),
-            message_key="goal_set", message_args=[state.max_turns, state.goal], state=state, kickoff_prompt=state.goal,
-        )
+        if tokens[:2] == ["gate", "add"] and not _gates_run_in_workspace():
+            return _payload(ok=False, action="gate", error="gates_unsupported", state=mgr.state, message=_GATES_NEED_WORKSPACE)
+        had_goal = bool(mgr.has_goal())
+        # Only goal-setting text reads it: a re-pasted goal kicks off without repeating itself.
+        last_user_message = mgr.scoped(agent_goals.last_user_message_from_db, mgr.session_id) if action == "set" else None
+        result = mgr.scoped(dispatch_goal_command, mgr._manager, text, authorize_gate=lambda: None, last_user_message=last_user_message)
+        state = mgr.state
+        if result.error:
+            return _payload(ok=False, action=action, error="invalid_goal" if action == "set" else "invalid_command", message=result.output, state=state)
+        # A running turn's judge continues a resumed goal itself.
+        kickoff = result.prompt if result.prompt and not params.get("stream_running") else None
+        return _payload(action=action, message=result.output, state=state, kickoff_prompt=kickoff, **_localized(action, state, had_goal))
 
     @registry.method("goals.snapshot")
     def snapshot(ctx: CallContext, params: dict) -> dict:
@@ -212,6 +247,11 @@ def register(registry) -> None:
         try:
             if not mgr.is_active():
                 return _inactive("no active goal", getattr(mgr.state, "status", None) if mgr.state is not None else None)
+            # Gates set on a newer Agent persist across a channel switch; this one would run them outside the workspace.
+            if getattr(mgr.state, "gates", None) and not _gates_run_in_workspace():
+                mgr.pause(reason="gates need Hermes Agent 0.21.6 or later")
+                return {"status": "paused", "should_continue": False, "continuation_prompt": None, "verdict": "gate_failed", "reason": "gates not run",
+                        "message": f"⏸ Goal paused — quality gates not run. {_GATES_NEED_WORKSPACE} /goal gate clear, then /goal resume."}
             decision = mgr.evaluate_after_turn(str(params.get("last_response") or ""), user_initiated=bool(params.get("user_initiated", True)))
         except Exception as exc:  # noqa: BLE001 - never fail a turn on goal evaluation
             log.debug("goal evaluation failed", exc_info=True)