cdx-manager 0.18.4 → 0.18.5

package/src/commands/maintenance.py

@@ -595,11 +595,15 @@ def _align_tray_companion(ctx, target_version):
     warning, not a reason to call a good update bad.
     """
     from ..tray_install import align_companion
-    from ..tray_instance import companion_instance
 
     try:
         base_dir = ctx["service"]["base_dir"]
-        result = align_companion(base_dir, target_version, download=ctx.get("download_asset"))
+        result = align_companion(
+            base_dir, target_version,
+            download=ctx.get("download_asset"),
+            env=ctx.get("env"),
+            spawn=ctx.get("spawn_detached"),
+        )
     except Exception as error:  # noqa: BLE001 - the update already succeeded
         return [{"code": "tray_companion_not_aligned", "message": f"The tray companion was left as it was: {error}"}]
 
@@ -614,21 +618,26 @@ def _align_tray_companion(ctx, target_version):
             ),
         }]
 
+    if result.get("restarted"):
+        return [{
+            "code": "tray_companion_updated",
+            "message": f"Updated the tray companion to {target_version} and restarted it.",
+        }]
+
     warnings = [{
         "code": "tray_companion_updated",
         "message": f"Updated the tray companion to {target_version} as well.",
     }]
-    # A running companion keeps executing the binary it started with. Saying so
-    # beats leaving someone to wonder why the menu still looks old, and beats
-    # quitting an application they did not ask us to touch.
-    try:
-        if companion_instance(env=ctx.get("env")).get("pid"):
-            warnings.append({
-                "code": "tray_companion_restart_pending",
-                "message": "The running tray is still the previous build. Quit it from its menu and run: cdx tray launch",
-            })
-    except Exception:  # noqa: BLE001
-        pass
+    # It was replaced but is not running. Only worth saying when there was one
+    # to bring back: a user who had no tray open did not lose anything.
+    if result.get("restart_reason") and result.get("restart_reason") != "no tray was running":
+        warnings.append({
+            "code": "tray_companion_restart_pending",
+            "message": (
+                f"The tray companion did not restart: {result['restart_reason']} "
+                "Run: cdx tray launch"
+            ),
+        })
     return warnings
 
 

package/src/commands/tray.py

@@ -42,10 +42,13 @@ from ..tray_install import (
     uninstall,
 )
 from ..tray_instance import companion_instance
+from ..tray_plugins import ADAPTERS, collect_cards, enabled_plugins, set_plugin_enabled
+from ..tray_terminal import REFUSAL as TERMINAL_REFUSAL
+from ..tray_terminal import clear_terminal, set_terminal, terminal_preference
 
 TRAY_ACTIONS = (
     "status", "install", "launch", "uninstall", "autostart", "doctor",
-    "events", "ack", "heartbeat", "alerts",
+    "events", "ack", "heartbeat", "alerts", "plugin", "terminal",
 )
 
 # Codes rather than prose, so a caller can branch on them.
@@ -86,9 +89,23 @@ def handle_tray(rest, ctx):
         return _tray_heartbeat(args, ctx)
     if action == "alerts":
         return _tray_alerts(args, ctx)
+    if action == "plugin":
+        return _tray_plugin(args, ctx)
+    if action == "terminal":
+        return _tray_terminal(args, ctx)
     return _tray_install(args, ctx)
 
 
+def _plugin_cache(ctx):
+    """The per-process card cache.
+
+    `cdx tray status` is a fresh process per poll, so this only helps within one
+    invocation today. It exists as the seam the TTL is honoured through, and the
+    place a longer-lived cache would go without every adapter learning about it.
+    """
+    return ctx.setdefault("plugin_cache", {})
+
+
 def _tray_status(args, ctx):
     parsed = _parse_flag_args(args, {
         "--json": {"key": "json", "type": "bool", "default": False},
@@ -103,11 +120,21 @@ def _tray_status(args, ctx):
         force_refresh=parsed["refresh"],
         cache_only=not parsed["refresh"],
     )
+    # Enabled integrations contribute a card each. A manual refresh passes no
+    # cache, so it is what actually re-asks them; a poll reuses a card for its
+    # TTL and does not make an integration pay the tray's rate.
+    cards = collect_cards(
+        ctx["service"]["base_dir"],
+        env=ctx.get("env"),
+        cache=None if parsed["refresh"] else _plugin_cache(ctx),
+    )
     snapshot = build_snapshot(
         rows,
         datetime.now(timezone.utc),
         ctx["version"],
         refreshable=not any(row.get("active") for row in rows),
+        plugins=cards,
+        terminal=terminal_preference(ctx["service"]["base_dir"]),
     )
     # Pending alerts ride along with the snapshot rather than costing their own
     # call. Across WSL every invocation is a `wsl.exe` crossing measured at
@@ -210,11 +237,63 @@ def _confirm_autostart():
     return answer.strip().lower() in ("", "y", "yes")
 
 
+def _confirm_alerts():
+    answer = input("Notify you when an agent finishes a turn or waits for you? [Y/n] ")
+    return answer.strip().lower() in ("", "y", "yes")
+
+
+def _accepted(parsed, ctx, on_flag, off_flag, confirm):
+    """One consent, resolved the same way for each question.
+
+    Two rules make it predictable. An explicit flag always wins, so a script
+    gets what it asked for and never a prompt. And in the absence of one, only
+    an interactive human-readable run asks — a piped or `--json` invocation
+    declines rather than deciding on someone's behalf.
+    """
+    if parsed[off_flag]:
+        return False, f"skipped with --{off_flag.replace('_', '-')}"
+    if parsed[on_flag] or parsed["yes"]:
+        return True, None
+    if ctx["stdin_is_tty"] and not parsed["json"] and confirm():
+        return True, None
+    return False, None
+
+
+def _enable_alerts_everywhere(ctx):
+    """Turn alerts on for every session that can have them, and for future ones.
+
+    The two halves are one promise: a user who accepted alerts means the tray
+    tells them when an agent needs them, not that it does so for the sessions
+    that happened to exist at the moment they answered.
+
+    Providers with no hook mechanism are left alone rather than written to with
+    a setting they will ignore.
+    """
+    from ..agent_notify import supports_agent_alerts
+    from ..tray_defaults import set_alerts_default
+
+    service = ctx["service"]
+    set_alerts_default(service["base_dir"], True)
+    enabled, codex = [], False
+    for session in service["list_sessions"]():
+        if not supports_agent_alerts(session["provider"]):
+            continue
+        if (session.get("launch") or {}).get("notify") is True:
+            continue
+        service["set_launch_settings"](session["name"], {"notify": True})
+        enabled.append(session["name"])
+        codex = codex or session["provider"] == "codex"
+    return {"sessions": enabled, "codex_trust_required": codex}
+
+
 def _tray_install(args, ctx):
     parsed = _parse_flag_args(args, {
         "--json": {"key": "json", "type": "bool", "default": False},
         "--yes": {"key": "yes", "type": "bool", "default": False},
+        "--autostart": {"key": "autostart", "type": "bool", "default": False},
         "--no-autostart": {"key": "no_autostart", "type": "bool", "default": False},
+        "--alerts": {"key": "alerts", "type": "bool", "default": False},
+        "--no-alerts": {"key": "no_alerts", "type": "bool", "default": False},
     }, TRAY_USAGE, positionals_key="args", max_positionals=0)
     env = ctx.get("env")
     target = current_target()
@@ -255,24 +334,41 @@ def _tray_install(args, ctx):
     # what people resent about desktop software. Asking keeps the reason and
     # drops the friction; a non-interactive run declines rather than deciding.
     autostart_on = False
-    autostart_reason = None
-    if parsed["no_autostart"]:
-        autostart_reason = "skipped with --no-autostart"
-    elif parsed["yes"] or (ctx["stdin_is_tty"] and not parsed["json"] and _confirm_autostart()):
+    wanted, autostart_reason = _accepted(parsed, ctx, "autostart", "no_autostart", _confirm_autostart)
+    if wanted:
         try:
             autostart_enable(state["executable"], env=env, run=ctx.get("spawn_sync"))
             autostart_on = True
         except Exception as error:  # noqa: BLE001
             autostart_reason = str(error)
-    else:
+    elif autostart_reason is None:
         autostart_reason = "not enabled; run: cdx tray autostart on"
 
+    # The second question, asked separately because it is a different decision
+    # with a different cost: one adds a login item, the other writes hooks into
+    # each provider's own configuration.
+    alerts_on = False
+    alerts_reason = None
+    alerts_result = {"sessions": [], "codex_trust_required": False}
+    wanted, alerts_reason = _accepted(parsed, ctx, "alerts", "no_alerts", _confirm_alerts)
+    if wanted:
+        try:
+            alerts_result = _enable_alerts_everywhere(ctx)
+            alerts_on = True
+        except Exception as error:  # noqa: BLE001 - the install itself succeeded
+            alerts_reason = str(error)
+    elif alerts_reason is None:
+        alerts_reason = "not enabled; run: cdx set --all --notify on"
+
     if parsed["json"]:
         _write_json(ctx, _json_success(
             "tray.install", message,
             target=state["target"], executable=state["executable"],
             sha256=state["sha256"], applied=True,
             started=started, autostart=autostart_on,
+            alerts=alerts_on,
+            alerts_sessions=alerts_result["sessions"],
+            codex_trust_required=alerts_result["codex_trust_required"],
         ))
         return 0
     ctx["out"](f"{message}\n{_dim(state['executable'], ctx['use_color'])}\n")
@@ -280,6 +376,149 @@ def _tray_install(args, ctx):
     ctx["out"](
         f"{'It will start at login.' if autostart_on else f'Startup: {autostart_reason}'}\n"
     )
+    if alerts_on:
+        count = len(alerts_result["sessions"])
+        covered = f"{count} session(s)" if count else "no existing session"
+        ctx["out"](
+            f"Agent alerts: on for {covered}, and for new ones — "
+            "hooks install at each session's next launch.\n"
+        )
+        if alerts_result["codex_trust_required"]:
+            # Said here rather than discovered later: Codex puts an approval
+            # prompt in front of the user at the next launch, and cdx will not
+            # write that trust on their behalf.
+            ctx["out"]("Codex will ask you once to approve the cdx hook plugin.\n")
+    else:
+        ctx["out"](f"Agent alerts: {alerts_reason}\n")
+    return 0
+
+
+PLUGIN_UNKNOWN = "tray_plugin_unknown"
+TERMINAL_INVALID = "tray_terminal_invalid"
+
+
+def _tray_terminal(args, ctx):
+    """Choose the terminal a session row opens, or go back to the default.
+
+    A refusal is a refusal, not a silent normalisation: a value that cannot be
+    stored says why, and nothing is written. Storing a sanitized version of what
+    someone typed would make the rule invisible exactly where it matters.
+    """
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, TRAY_USAGE, positionals_key="args", max_positionals=2)
+    positional = parsed["args"] or ["status"]
+    mode = positional[0]
+    base_dir = ctx["service"]["base_dir"]
+
+    if mode == "clear":
+        clear_terminal(base_dir)
+    elif mode == "set":
+        if len(positional) < 2:
+            raise CdxError(TRAY_USAGE)
+        try:
+            set_terminal(base_dir, positional[1])
+        except ValueError:
+            return _refuse(ctx, parsed["json"], "tray.terminal", TERMINAL_INVALID, TERMINAL_REFUSAL)
+    elif mode != "status":
+        raise CdxError(TRAY_USAGE)
+
+    chosen = terminal_preference(base_dir)
+    message = (
+        f"Tray session rows open {chosen}." if chosen
+        else "Tray session rows open this platform's default terminal."
+    )
+    if parsed["json"]:
+        _write_json(ctx, _json_success(
+            "tray.terminal", message, terminal=chosen, applied=mode in ("set", "clear"),
+        ))
+        return 0
+    ctx["out"](f"{message}\n")
+    if chosen:
+        # Said once, at the moment it is chosen: the companion falls back
+        # silently, and a user whose terminal never opens should know that is
+        # the designed behaviour rather than a broken setting.
+        ctx["out"](f"{_dim('If it is not installed, the platform default opens instead.', ctx['use_color'])}\n")
+    return 0
+
+
+def _tray_plugin(args, ctx):
+    """Turn an integration on or off, and say what is on.
+
+    Explicit in both directions and reversible, because an integration runs
+    another tool's command on the user's behalf: nothing here has a default that
+    turns something on, and `disable` is not a hidden setting.
+    """
+    parsed = _parse_flag_args(args, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, TRAY_USAGE, positionals_key="args", max_positionals=2)
+    positional = parsed["args"] or ["status"]
+    mode = positional[0]
+    if mode not in ("enable", "disable", "status", "run"):
+        raise CdxError(TRAY_USAGE)
+    base_dir = ctx["service"]["base_dir"]
+
+    if mode == "run":
+        return _tray_plugin_run(positional[1:], parsed, ctx)
+
+    if mode in ("enable", "disable"):
+        if len(positional) < 2:
+            raise CdxError(TRAY_USAGE)
+        name = positional[1]
+        if name not in ADAPTERS:
+            return _refuse(
+                ctx, parsed["json"], "tray.plugin", PLUGIN_UNKNOWN,
+                f"No tray integration is called {name}. Known: {', '.join(sorted(ADAPTERS))}.",
+            )
+        set_plugin_enabled(base_dir, name, mode == "enable")
+
+    enabled = enabled_plugins(base_dir)
+    available = _available_plugins(ctx, enabled)
+    message = (
+        f"Tray integrations enabled: {', '.join(enabled)}" if enabled
+        else "No tray integration is enabled."
+    )
+    if parsed["json"]:
+        _write_json(ctx, _json_success(
+            "tray.plugin", message, enabled=enabled, known=sorted(ADAPTERS),
+            activatable=available, applied=mode in ("enable", "disable"),
+        ))
+        return 0
+    ctx["out"](f"{message}\n")
+    for name in available:
+        # Said once, as an offer rather than a nudge repeated on every command:
+        # the tool is here, the card is not on, and this is how to turn it on.
+        ctx["out"](f"{_dim(f'{name} is installed but not enabled. Run: cdx tray plugin enable {name}', ctx['use_color'])}\n")
+    return 0
+
+
+def _available_plugins(ctx, enabled):
+    """Integrations whose tool is installed and whose card is not enabled."""
+    from ..logics_view import resolve_logics_manager
+
+    if "logics" in enabled or not resolve_logics_manager(ctx.get("env") or {}):
+        return []
+    return ["logics"]
+
+
+def _tray_plugin_run(rest, parsed, ctx):
+    """Perform one card action, named by its id.
+
+    The tray sends an id back rather than a command, and this is where that
+    matters: the id is matched against what CDX knows how to do, and anything
+    else is refused. There is no path from a card to a shell.
+    """
+    from ..tray_plugin_actions import perform_action
+
+    if not rest:
+        raise CdxError(TRAY_USAGE)
+    result = perform_action(rest[0], ctx)
+    if not result["ok"]:
+        return _refuse(ctx, parsed["json"], "tray.plugin.run", result["code"], result["message"])
+    if parsed["json"]:
+        _write_json(ctx, _json_success("tray.plugin.run", result["message"], applied=True))
+        return 0
+    ctx["out"](f"{result['message']}\n")
     return 0
 
 

package/src/session_service.py

@@ -614,6 +614,28 @@ def rename_session(base_dir, store, source_name, dest_name):
     return result["session"]
 
 
+def _launch_defaults_for(base_dir, provider):
+    """The launch settings a new session starts with.
+
+    Agent alerts are the one setting that can be inherited, and only from an
+    explicit answer given during `cdx tray install`. Without this, accepting
+    alerts once covered the sessions that existed at that moment and silently
+    excluded every session created afterwards.
+    """
+    from .agent_notify import supports_agent_alerts
+    from .tray_defaults import alerts_default
+
+    launch = dict(DEFAULT_LAUNCH_SETTINGS)
+    try:
+        if supports_agent_alerts(provider) and alerts_default(base_dir):
+            launch["notify"] = True
+    except OSError:
+        # An unreadable default is no default. Creating the session matters
+        # more than inheriting a preference.
+        pass
+    return launch
+
+
 def create_session(base_dir, env, store, name, provider=DEFAULT_PROVIDER):
     _validate_new_session_name(name)
     normalized_provider = _normalize_provider(provider)
@@ -639,7 +661,7 @@ def create_session(base_dir, env, store, name, provider=DEFAULT_PROVIDER):
         "lastLaunchedAt": None,
         "lastStatusAt": None,
         "lastStatus": None,
-        "launch": dict(DEFAULT_LAUNCH_SETTINGS),
+        "launch": _launch_defaults_for(base_dir, normalized_provider),
         "auth": {
             "status": "unknown",
             "lastCheckedAt": None,

package/src/tray_contract.py

@@ -23,7 +23,7 @@ from .status_view import _format_reset_time
 
 SCHEMA_NAME = "cdx.tray.snapshot"
 SCHEMA_MAJOR = 1
-SCHEMA_MINOR = 0
+SCHEMA_MINOR = 2
 
 # Below this much remaining capacity a session cannot usefully take work. Shared
 # with the ranking's own usability threshold so the tray and `cdx next` do not
@@ -223,7 +223,7 @@ def tooltip_for(worst):
     return "CDX · " + " · ".join(parts)
 
 
-def build_snapshot(rows, now, cdx_version, refreshable=True):
+def build_snapshot(rows, now, cdx_version, refreshable=True, plugins=None, terminal=None):
     """The whole contract, from the rows `cdx status` already returns.
 
     `icon` carries no session name, account, or figure: it is what shows while
@@ -254,6 +254,15 @@ def build_snapshot(rows, now, cdx_version, refreshable=True):
         "sessions": sessions,
         "refreshable": bool(refreshable),
         "actions": ["refresh", "open_terminal"],
+        # Zero or more bounded cards from enabled integrations. A minor-version
+        # addition: a companion that predates it ignores the key and shows
+        # exactly what it showed before.
+        "plugins": list(plugins or []),
+        # Which terminal a session row should open, or None for the platform's
+        # own. Carried here rather than kept by the companion, because every
+        # other durable tray preference already lives in CDX and a second store
+        # is a second thing to keep in step.
+        "terminal": terminal,
     }
 
 

package/src/tray_defaults.py

@@ -0,0 +1,48 @@
+"""What a newly created session inherits, once the user has said yes once.
+
+Accepting agent alerts during `cdx tray install` has to mean two different
+things, and only saying one of them is what made the feature feel broken: the
+sessions that exist today get alerts, and the ones created tomorrow get them
+too. Without the second, a user who accepted alerts finds their next session
+silent and has no reason to suspect a per-session opt-in they never saw.
+
+Stored beside the mute state rather than in the session file, because it is not
+a property of any session: it is the answer to a question asked once, and a
+session created later has to be able to read it.
+"""
+import json
+import os
+
+STATE_VERSION = 1
+
+
+def state_path(base_dir):
+    return os.path.join(base_dir, "tray", "defaults.json")
+
+
+def alerts_default(base_dir):
+    """Whether a new supported session starts with alerts on.
+
+    Off unless explicitly accepted. Anything unreadable, unrecognised or from a
+    version this build does not know reads as off: inheriting an opt-in from a
+    file we cannot understand would enable provider hooks nobody agreed to.
+    """
+    try:
+        with open(state_path(base_dir), encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        return False
+    if not isinstance(state, dict) or state.get("version") != STATE_VERSION:
+        return False
+    return state.get("notify") is True
+
+
+def set_alerts_default(base_dir, enabled):
+    """Record the answer, and report what it now is."""
+    path = state_path(base_dir)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temp = f"{path}.{os.getpid()}.tmp"
+    with open(temp, "w", encoding="utf-8") as handle:
+        json.dump({"version": STATE_VERSION, "notify": bool(enabled)}, handle, indent=2)
+    os.replace(temp, path)
+    return bool(enabled)

package/src/tray_events.py

@@ -101,12 +101,18 @@ def tray_is_listening(base_dir, now=None):
 
 # --- the hook's side -------------------------------------------------------
 
-def publish(base_dir, title, message, kind="complete", now=None, event_id=None):
+def publish(base_dir, title, message, kind="complete", now=None, event_id=None, details=None):
     """Hand one event to the tray. Returns True only if it was written.
 
     False means the caller must deliver it directly, so every failure here has
     to be a False and never an exception: the alternative is a provider hook
     that raises inside someone's agent turn.
+
+    `details` carries the same event as fields, so a companion does not have to
+    read a sentence to know which session it belongs to. It is written beside
+    the rendered title and message, never instead of them: a companion that
+    predates the fields ignores an unknown key and shows what it always showed,
+    and a newer one handed a malformed `details` still has the sentence.
     """
     now = time.time() if now is None else now
     try:
@@ -119,6 +125,8 @@ def publish(base_dir, title, message, kind="complete", now=None, event_id=None):
             "title": title,
             "message": message,
         }
+        if isinstance(details, dict) and details:
+            event["details"] = details
         path = events_path(base_dir)
         os.makedirs(os.path.dirname(path), exist_ok=True)
         line = json.dumps(event, ensure_ascii=False) + "\n"