Merge remote-tracking branch 'origin/main' into tmi/issue-2515-m59

Author: itomek

docs/plans/email-full-autonomy.mdx

@@ -8,11 +8,13 @@ icon: "wand-magic-sparkles"
 
 > **Status:** Phases 1–5 shipped — trust engine, autonomous cycle, closed
 > learning loop, REST control surface, automatic correction capture, the
-> proactive eval harness, AND the scheduled driver (`AutonomyScheduler` +
-> `run_autonomy_job`, opt-in via `GAIA_EMAIL_AUTONOMY_ENABLED`), all tested.
-> Remaining follow-ups: registering `run_autonomy_job` on the core `DaemonClock`
-> for the daemon-supervised path (cross-process, tracked with #2156), and the npm
-> thin-client CLI (`gaia email autonomy …`) wrapping the REST surface.
+> proactive eval harness, the scheduled driver (`AutonomyScheduler` +
+> `run_autonomy_job`, opt-in via `GAIA_EMAIL_AUTONOMY_ENABLED`), AND the
+> `gaia email autonomy {status|set-level|pause|resume|run|trust|kill}`
+> thin-client CLI (#2516) wrapping the REST surface over the daemon relay,
+> all tested. Remaining follow-up: registering `run_autonomy_job` on the core
+> `DaemonClock` for the daemon-supervised path (cross-process, tracked with
+> #2156).
 >
 > **Milestone:** [Autonomy + Messaging Expansion [OSS]](https://github.com/amd/gaia/milestone/6)
 >

docs/reference/cli.mdx

@@ -1072,6 +1072,28 @@ gaia email -v -q "Triage my inbox"  # verbose logs for benchmarking
 
 [→ Full Email Triage Agent Documentation](/guides/email)
 
+#### `gaia email autonomy` — autonomy control
+
+A thin client over the sidecar's `/v1/email/agent/autonomy*` REST routes, relayed
+through the daemon like every other `gaia email` command (same auth path — no
+sidecar bearer ever reaches the CLI).
+
+```bash
+gaia email autonomy status                    # current level + trust summary
+gaia email autonomy trust                     # earned-trust ledger
+gaia email autonomy set-level earn_trust       # set the level explicitly
+gaia email autonomy pause                      # stop autonomous activity
+gaia email autonomy resume --level earn_trust  # resume (default: earn_trust)
+gaia email autonomy kill                       # kill switch — level -> off
+gaia email autonomy run --max-messages 25      # trigger one cycle now
+```
+
+All subcommands share one persistent `--session-id` (default `cli`) — autonomy
+state lives on that session's in-memory agent, not on disk, so a level you set
+stays set across invocations that use the same session. `run` refuses with an
+actionable error while the level is `off` (#2528) instead of silently reporting
+that nothing happened.
+
 ---
 
 ### SD Command

hub/agents/email/npm/CHANGELOG.md

@@ -6,6 +6,12 @@ behind any entry — API shapes, endpoints, and version semantics — see
 
 ## Unreleased
 
+- **Triggering an autonomy cycle while autonomy is switched off now tells you
+  so, instead of quietly reporting nothing happened.** `POST
+  /v1/email/agent/autonomy/run` used to return the same "nothing to do"
+  response whether autonomy was disabled or had genuinely run and found
+  nothing — there was no way to tell which. It now returns an error naming
+  the current level and how to turn autonomy back on.
 - **Asking the agent to draft a reply or forward now actually drafts one,
   instead of asking you to write it.** The agent would correctly find the
   right email, then ask you to supply the reply or forward text — the exact

hub/agents/email/npm/SKILL.md

@@ -319,7 +319,11 @@ a negative outcome that pulls the sender/category back below the trust bar. (Pos
 accrual — trust *rising* as suggestions are accepted or left standing — is not yet wired, so
 today the ledger only ratchets trust down.) Every auto-action is reversible with undo. A bad
 `level` returns **400**; an unknown session returns **404**; undoing an unknown/expired
-`action_id` returns **409**.
+`action_id` returns **409**; `/run` while the level is `off` returns **409** too — it refuses
+rather than returning the same 200 shape a real, found-nothing cycle would (#2528).
+
+The Python host also ships a thin-client CLI over this same surface:
+`gaia email autonomy {status|set-level|pause|resume|run|trust|kill}` (#2516).
 
 ## Running in a server / long-lived app
 

hub/agents/email/npm/SPEC.md

@@ -246,7 +246,7 @@ emits the canonical event vocabulary.
 | `GET /v1/email/agent/memory/{id}` | Memory status without changing it. |
 | `GET /v1/email/agent/autonomy/{id}` | Inspectable autonomy status: `{ level, enabled, trust_min_samples, trust_threshold, trusted_scope_count, scopes[] }` — the earned-trust ledger, never a black box. |
 | `POST /v1/email/agent/autonomy` | Set the autonomy level, `{ session_id, level }` where level ∈ `off` \| `suggest` \| `earn_trust` \| `full` (`off` = kill switch). Bad level → **400**. |
-| `POST /v1/email/agent/autonomy/run` | Trigger one observe→decide→act cycle, `{ session_id, max_messages? }` → `{ level, executed[], proposals[], decisions[], skipped }`. `decisions[]` (#2529) is a per-message log — `{ message_id, tool, action, outcome, reason, sender }` for every candidate considered, whatever the outcome — so a held-back decision (importance guard, confirm floor) is explained, not silent. The daemon clock / scheduler drives this in production. |
+| `POST /v1/email/agent/autonomy/run` | Trigger one observe→decide→act cycle, `{ session_id, max_messages? }` → `{ level, executed[], proposals[], decisions[], skipped }`. `decisions[]` (#2529) is a per-message log — `{ message_id, tool, action, outcome, reason, sender }` for every candidate considered, whatever the outcome — so a held-back decision (importance guard, confirm floor) is explained, not silent. The daemon clock / scheduler drives this in production. Refused with **409** while the session's level is `off` — the kill switch is never mistakable for "ran and found nothing to do" (#2528). |
 | `POST /v1/email/agent/autonomy/undo` | Reverse one auto-executed action and record the correction against its trust scope, `{ session_id, action_id }` → `{ action_id, action_type, message_id, undone, correction_captured }` (#2529). `action_id` comes from a prior `executed[]` entry. Unknown/expired/already-undone id → **409**; an action_type with no reversal implemented → **400**. `correction_captured` is `false` (mutation still reversed) when `action_id` wasn't an autonomy-executed action. |
 
 Sessions are in-process and single-tenant (the sidecar hosts one user's agent); one turn

hub/agents/email/python/CHANGELOG.md

@@ -9,6 +9,19 @@ contract version is tracked separately as
 
 ### Added
 
+- **`gaia email autonomy` CLI (#2516).** A thin client over the session-scoped
+  `/v1/email/agent/autonomy*` REST surface, relayed through the daemon like
+  every other `gaia email` command (no second auth scheme): `status`,
+  `set-level`, `pause`, `resume`, `run`, `trust`, `kill`. Closes the gap where
+  the code and the plan doc both described this command before it existed.
+
+### Fixed
+
+- **`POST /autonomy/run` refuses instead of silently no-oping while autonomy
+  is `off` (#2528).** Previously the route returned HTTP 200 with the same
+  empty-report shape whether autonomy was disabled or had genuinely run and
+  found nothing to do — a caller could not tell the two apart. It now returns
+  **409**, naming the current level and how to change it.
 - **The autonomy trust model can now be exercised end to end — broader candidates, an undo
   surface, and per-message decisions (#2529).** The proactive `earn_trust`/`full` loop's
   candidate generator (`_autonomy_candidate`) only ever proposed `archive`, so the rest of
@@ -81,6 +94,17 @@ contract version is tracked separately as
   `recoverable` flag through to the wire; a recoverable error folds to a
   non-terminal status line instead of a terminal `error`, so the retry can
   reach completion and the user still sees the failure as it happens.
+- **A failed memory startup is now visible in chat, and blames the right
+  cause (#2519).** When the embedding model wasn't reachable, memory quietly
+  disabled itself: a log line and a REST field said so, but the agent's
+  answers made it look like a missing feature ("I don't have a tool to view
+  saved preferences") rather than a broken one. The agent now prints a
+  startup warning naming the real problem and the fix. It also used to blame
+  every failure on `GAIA_MEMORY_DISABLED=1` or a stopped Lemonade — the
+  common real case is neither: Lemonade is running fine but the embedding
+  model was never pulled. The message now tells those two apart and gives
+  the matching remedy (pull the model vs. start Lemonade), since acting on
+  the wrong one wastes the user's time.
 - **`draft_reply` / `draft_forward` actually draft instead of asking for the
   text to draft (#2524).** Asked to draft a reply or forward, the agent
   correctly located the source message and then asked the user to supply the

hub/agents/email/python/gaia_agent_email/agent.py

@@ -83,7 +83,11 @@ class never passes ``use_claude=True`` / ``use_chatgpt=True`` to
 
 from gaia.agents.base.agent import Agent
 from gaia.agents.base.console import AgentConsole
-from gaia.agents.base.memory import MemoryMixin
+from gaia.agents.base.memory import (
+    MEMORY_UNAVAILABLE_MODEL_NOT_PULLED,
+    MEMORY_UNAVAILABLE_SERVICE_UNREACHABLE,
+    MemoryMixin,
+)
 from gaia.agents.base.tools import _TOOL_REGISTRY
 from gaia.agents.registry import get_embedding_model_for_device
 from gaia.connectors.errors import AuthRequiredError, ConnectorsError
@@ -684,6 +688,19 @@ def __init__(self, config: Optional[EmailAgentConfig] = None):
             ),
         )
 
+        # Surface the degraded-memory state where the user actually is
+        # (#2519): before this, a failed embedding connectivity probe only
+        # logged a WARNING and set a REST field nobody was looking at, so a
+        # user in chat saw the agent quietly claim it never had memory tools
+        # rather than being told memory failed to come up and how to fix it.
+        # Skip the deliberate GAIA_MEMORY_DISABLED=1 opt-out here — that's an
+        # explicit choice (used by tests/CI), not a silent degradation.
+        if getattr(self, "_memory_unavailable_reason", None) in (
+            MEMORY_UNAVAILABLE_MODEL_NOT_PULLED,
+            MEMORY_UNAVAILABLE_SERVICE_UNREACHABLE,
+        ):
+            self.console.print_warning(self.memory_unavailable_message())
+
         # Exact ctx pin (#1892): set the instance-scoped override on the
         # concrete LemonadeClient this agent chats through. Post-super(),
         # the client lives at self.chat.llm_client._backend (AgentSDK →
@@ -760,19 +777,19 @@ def memory_status(self) -> dict:
         """Report the current memory state without changing it.
 
         Returns ``{"enabled", "available", "message"}`` where ``available`` is
-        whether a memory store exists this session (False when disabled at startup
-        via ``GAIA_MEMORY_DISABLED`` or when Lemonade was unreachable) and
-        ``enabled`` is the effective on/off state (``available`` and not incognito).
+        whether a memory store exists this session and ``enabled`` is the
+        effective on/off state (``available`` and not incognito). When
+        unavailable, ``message`` names the REAL cause — env opt-out, the
+        embedding model never having been pulled into a running Lemonade, or
+        Lemonade itself being unreachable — via
+        ``MemoryMixin.memory_unavailable_message()`` (#2519). These are
+        distinct failures with distinct remedies; conflating them (as this
+        method used to) sends the user down the wrong fix.
         """
         available = getattr(self, "_memory_store", None) is not None
         enabled = self.is_memory_enabled()
         if not available:
-            message = (
-                "Memory is unavailable this session: it was disabled at startup "
-                "(GAIA_MEMORY_DISABLED=1) or the Lemonade embedding service was "
-                "unreachable when the agent started. Start lemonade-server and "
-                "restart the agent to enable it."
-            )
+            message = self.memory_unavailable_message()
         elif enabled:
             message = "Memory is enabled: personalization and persistence are active."
         else:
@@ -1306,9 +1323,8 @@ def _autonomy_policy(self) -> "trust.TrustPolicy":
         """Build the earn-trust policy from current config + the confirm-floor.
 
         Rebuilt per cycle so a runtime ``autonomy_level`` change (e.g. via the
-        the forthcoming ``gaia email autonomy`` CLI) takes effect on the next
-        heartbeat without
-        reconstructing the agent.
+        ``gaia email autonomy set-level`` CLI) takes effect on the next
+        heartbeat without reconstructing the agent.
         """
         ledger = trust.TrustLedger(
             min_samples=self.config.autonomy_trust_min_samples,
@@ -1640,9 +1656,10 @@ def autonomy_status(self) -> Dict[str, Any]:
         Returns the current level, the trust thresholds, and the earned-trust
         ledger — every ``(action, scope)`` with its positive/negative tally and
         whether it has crossed the bar. This is the single read-model the
-        planned ``gaia email autonomy status`` / ``trust`` CLI, the REST surface, and
-        the Agent-UI panel all render, so autonomy behavior is always
-        explainable ("archives news@x because 12/12 correct").
+        ``gaia email autonomy status`` / ``trust`` CLI and the REST surface
+        both render (a future Agent-UI panel is not yet built), so autonomy
+        behavior is always explainable ("archives news@x because 12/12
+        correct").
         """
         ledger = trust.TrustLedger(
             min_samples=self.config.autonomy_trust_min_samples,
@@ -1678,8 +1695,8 @@ def run_autonomy_cycle(
     ) -> Dict[str, Any]:
         """Driver-facing entry: run a cycle and persist proposals to GoalStore.
 
-        This is the seam a ``DaemonClock`` job / the planned ``gaia email autonomy`` CLI
-        invokes (mirroring ``run_briefing_job`` for the briefing feature).
+        This is the seam a ``DaemonClock`` job / the ``gaia email autonomy run``
+        CLI invokes (mirroring ``run_briefing_job`` for the briefing feature).
         Returns a JSON-serializable report — the ``Proposal`` objects are
         replaced by their persisted dict form.
         """

hub/agents/email/python/gaia_agent_email/agent_routes.py

@@ -52,6 +52,7 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 from gaia.logger import get_logger
+from gaia_agent_email import trust
 
 logger = get_logger(__name__)
 
@@ -402,11 +403,25 @@ async def set_autonomy(request: AutonomyLevelRequest) -> Dict[str, Any]:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
 
-@router.post("/autonomy/run")
+@router.post(
+    "/autonomy/run",
+    responses={
+        409: {
+            "description": (
+                "Autonomy is off for this session — the kill switch refuses "
+                "the run instead of silently doing nothing (#2528)."
+            )
+        }
+    },
+)
 async def run_autonomy(request: AutonomyRunRequest) -> Dict[str, Any]:
     """Trigger one observe->decide->act cycle now (the daemon/CLI driver seam).
 
     Runs on a worker thread — the cycle does mailbox I/O and local inference.
+    Refuses with HTTP 409 while the session's autonomy level is ``off`` (#2528)
+    — without this, "autonomy is disabled" and "autonomy ran and found
+    nothing to do" return the identical 200 shape, and a caller can't tell
+    them apart.
     """
     session = registry.get(request.session_id)
     if session is None:
@@ -416,6 +431,18 @@ async def run_autonomy(request: AutonomyRunRequest) -> Dict[str, Any]:
         raise HTTPException(
             status_code=501, detail="This agent build does not expose autonomy."
         )
+    status_fn = getattr(session.agent, "autonomy_status", None)
+    level = status_fn().get("level") if callable(status_fn) else None
+    if level == trust.LEVEL_OFF:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                f"Autonomy is off for session '{request.session_id}' — the run "
+                "was refused, not silently skipped. POST /v1/email/agent/autonomy "
+                f'{{"session_id": "{request.session_id}", '
+                '"level": "suggest|earn_trust|full"} to enable it first.'
+            ),
+        )
     return await asyncio.to_thread(runner, {"max_messages": request.max_messages})
 
 

hub/agents/email/python/gaia_agent_email/spec_html.py

@@ -867,6 +867,42 @@ def render_endpoint_spec_html() -> str:
   <p class="desc">Report the session agent's memory state without changing it:
     <code>{ enabled, available, message }</code>.</p>
 </div>
+
+<div class="endpoint-block">
+  <span class="method-badge">GET</span>
+  <span class="path">/v1/email/agent/autonomy/{session_id}</span>
+  <p class="desc">Inspectable snapshot of the autonomy engine — level, trust
+    thresholds, and the earned-trust ledger:
+    <code>{ level, enabled, trust_min_samples, trust_threshold,
+    trusted_scope_count, scopes:[{ action_type, scope, positive, negative,
+    total, score, trusted }] }</code>. This is the read-model
+    <code>gaia email autonomy status</code> / <code>trust</code> render, so
+    autonomy behavior is always explainable. 404 if the session is unknown.</p>
+</div>
+
+<div class="endpoint-block">
+  <span class="method-badge">POST</span>
+  <span class="path">/v1/email/agent/autonomy</span>
+  <p class="desc">Set the autonomy level at runtime — pause/resume/kill.
+    Body: <code>{ "session_id": str, "level": "off"|"suggest"|"earn_trust"|"full" }</code>.
+    <code>off</code> is the kill switch. Returns
+    <code>{ level, enabled }</code>. <b>400</b> on an unknown level; 404 if
+    the session is unknown.</p>
+</div>
+
+<div class="endpoint-block">
+  <span class="method-badge">POST</span>
+  <span class="path">/v1/email/agent/autonomy/run</span>
+  <p class="desc">Trigger one observe-&gt;decide-&gt;act autonomy cycle now —
+    the <code>gaia email autonomy run</code> / daemon-scheduler driver seam.
+    Body: <code>{ "session_id": str, "max_messages"?: int (1-200, default 25) }</code>.
+    Returns <code>{ level, executed:[...], proposals:[...], skipped,
+    already_proposed }</code>. <b>409</b> while the session's level is
+    <code>off</code> — the kill switch refuses the run instead of returning
+    the same 200 shape a real, found-nothing cycle would (#2528), so a caller
+    can always tell "disabled" apart from "ran and found nothing to do". 404
+    if the session is unknown.</p>
+</div>
 """
 
     body = f"""<!DOCTYPE html>

hub/agents/email/python/gaia_agent_email/trust.py

@@ -99,7 +99,7 @@ class TrustDecision:
     """The policy's verdict for one candidate action.
 
     ``action`` is the disposition; ``reason`` is a human-readable rationale
-    surfaced in the activity feed and the planned ``gaia email autonomy`` output;
+    surfaced in the activity feed and the ``gaia email autonomy`` CLI output;
     ``confidence`` is the ledger trust score in ``[0, 1]`` (1.0 for the
     hard-coded floor and for explicit preferences).
     """