cdx-manager 0.12.4 → 0.15.0

package/src/config.py

@@ -7,6 +7,76 @@ PROVIDER_ANTIGRAVITY = "antigravity"
 PROVIDER_OLLAMA = "ollama"
 PROVIDERS = (PROVIDER_CODEX, PROVIDER_CLAUDE, PROVIDER_ANTIGRAVITY, PROVIDER_OLLAMA)
 
+# The values cdx accepts, defined once. Every validator, normalizer, and
+# `cdx schema --json` derives from these. They used to be restated in
+# cli_args, provider_runtime, and session_service — six copies for two
+# concepts — which let `cdx set` and `cdx run` disagree about the same
+# setting, and let `cdx schema --json` describe only one of them.
+# config.py owns them because it is the leaf: everything imports it and it
+# imports nothing of ours, so no ownership choice here can create a cycle.
+
+# Ordered weakest to strongest; the order is meaningful for comparisons such
+# as `--min-reasoning-effort`, so consumers must not re-sort it.
+REASONING_EFFORT_VALUES = ("minimal", "low", "medium", "high", "xhigh")
+
+# The canonical permissions, i.e. what cdx stores and what providers are
+# mapped from.
+PERMISSION_VALUES = ("review", "default", "auto", "full")
+
+# Provider-native spellings accepted as input and normalized to the
+# canonical value above, so a user can paste what their provider calls it.
+PERMISSION_ALIASES = {
+    "workspace-write": "default",
+    "read-only": "review",
+    "danger-full-access": "full",
+}
+
+# Everything accepted as input for a permission, canonical values first.
+PERMISSION_INPUT_VALUES = PERMISSION_VALUES + tuple(PERMISSION_ALIASES)
+
+# A budget is a ceiling, so the only bound worth enforcing is the one a caller
+# could cross by accident. Zero and negatives express nothing; the upper bound
+# catches a misplaced decimal rather than stating a policy. Defined here, not in
+# each parser, because `cdx set` and `cdx run` validating the same setting from
+# separate literals is how they came to disagree before.
+MAX_LAUNCH_BUDGET_USD = 10000
+
+MAX_LAUNCH_EXTRA_ARGS_LENGTH = 512
+
+
+def split_extra_args(value):
+    """Passthrough arguments as an argv list, or None if the string is malformed.
+
+    POSIX splitting on every platform, deliberately. The alternative - following
+    the host's own quoting rules - would make the same `cdx set` mean different
+    things on Windows and on macOS, and these strings travel between machines
+    through `cdx export`. One rule everywhere is worth more than matching the
+    local shell, especially since cdx never invokes a shell: the result is
+    passed as argv, so nothing here is ever re-interpreted.
+    """
+    import shlex
+
+    if value is None:
+        return None
+    try:
+        return shlex.split(str(value), posix=True)
+    except ValueError:
+        return None
+
+
+def normalize_permission(value):
+    """Canonical form of a permission input, or None if it is not one.
+
+    Returning None rather than raising keeps the error message and error code
+    the caller's business: `cdx run` and `cdx set` word their failures
+    differently, but they must agree on what is valid.
+    """
+    if value is None:
+        return None
+    text = str(value).strip().lower()
+    text = PERMISSION_ALIASES.get(text, text)
+    return text if text in PERMISSION_VALUES else None
+
 
 def get_cdx_home(env=None):
     if env is None:

package/src/errors.py

@@ -2,3 +2,20 @@ class CdxError(Exception):
     def __init__(self, message, exit_code=1):
         super().__init__(message)
         self.exit_code = exit_code
+
+
+class CdxArgumentError(CdxError):
+    """A usage failure that names its own machine-readable code and arguments.
+
+    Programmatic callers used to get a single `invalid_request` code carrying the
+    whole human usage line, which made a missing `--cwd` indistinguishable from
+    passing a session name and `--provider` together. Raising this instead lets
+    the JSON payload report `code` plus the offending `arguments` as data, so a
+    caller never has to match on message text.
+    """
+
+    def __init__(self, message, *, code, arguments=(), allowed=None, exit_code=1):
+        super().__init__(message, exit_code)
+        self.code = code
+        self.arguments = tuple(arguments)
+        self.allowed = tuple(allowed) if allowed is not None else None

package/src/health.py

@@ -9,10 +9,23 @@ from datetime import datetime, timezone
 from urllib.parse import quote, unquote
 
 from .cli_render import _pad_table, _style
-from .config import PROVIDER_CODEX
-from .provider_runtime import codex_auth_diagnostic
+from .config import PROVIDER_ANTIGRAVITY, PROVIDER_CLAUDE, PROVIDER_CODEX, PROVIDER_OLLAMA
+from .provider_runtime import (
+    HEADLESS_CODEX_PERMISSION_ARGS,
+    LAUNCH_PERMISSION_ARGS,
+    codex_auth_diagnostic,
+)
 from .status_source import _extract_account_identity
 
+# The executable each provider is driven through, where it differs from the
+# provider name.
+PROVIDER_CLI_COMMANDS = {
+    PROVIDER_CODEX: "codex",
+    PROVIDER_CLAUDE: "claude",
+    PROVIDER_ANTIGRAVITY: "agy",
+    PROVIDER_OLLAMA: "ollama",
+}
+
 
 def _encode(name):
     return quote(name, safe="")
@@ -36,7 +49,14 @@ def _issue(status, code, message, detail=None, repairable=False):
     }
 
 
-def collect_health_report(service, base_dir, env=None, spawn_sync=None):
+def collect_health_report(service, base_dir, env=None, spawn_sync=None, check_provider_flags=False):
+    """Health report for the cdx home, sessions, and provider CLIs.
+
+    `check_provider_flags` is opt-in because it costs a provider CLI
+    invocation per configured provider. When it is off the report still says
+    so, rather than omitting the check silently — an absent check must not
+    read as a passing one.
+    """
     env = env or os.environ
     issues = []
 
@@ -96,6 +116,15 @@ def collect_health_report(service, base_dir, env=None, spawn_sync=None):
 
     issues.extend(_codex_shared_account_id_issues(codex_diagnostics))
     issues.extend(_collect_profile_issues(base_dir, session_names))
+    if check_provider_flags:
+        issues.extend(_provider_flag_issues(service, env, spawn_sync))
+    else:
+        issues.append(_issue(
+            "WARN",
+            "provider_permission_flags_unchecked",
+            "Provider permission flags were not verified; run cdx doctor --check-provider-flags",
+            {"reason": "opt_in", "cost": "one provider CLI invocation per configured provider"},
+        ))
     return {"base_dir": base_dir, "issues": issues, "summary": summarize_health(issues)}
 
 
@@ -143,6 +172,125 @@ def _extract_version(text):
     return match.group(1) if match else None
 
 
+def _mapped_provider_flags(provider):
+    """Every distinct flag cdx would pass to this provider, by permission.
+
+    Read off the same mappings the launch specs use, so a permission added
+    there is automatically covered here rather than quietly unverified.
+    Values (a sandbox name, a config expression) are not flags and are not
+    checked — only the options themselves.
+    """
+    mappings = {}
+    interactive = LAUNCH_PERMISSION_ARGS.get(provider)
+    if interactive is None:
+        # No entry at all means nobody declared this provider's mapping, which
+        # is different from declaring that it has none.
+        return {}
+    for permission, args in interactive.items():
+        mappings.setdefault(permission, set()).update(
+            arg for arg in args if arg.startswith("-")
+        )
+    if provider == PROVIDER_CODEX:
+        for permission, args in HEADLESS_CODEX_PERMISSION_ARGS.items():
+            mappings.setdefault(permission, set()).update(
+                arg for arg in args if arg.startswith("-")
+            )
+    return {permission: sorted(flags) for permission, flags in mappings.items() if flags}
+
+
+def _provider_help_text(command, env, spawn_sync=None):
+    """The provider CLI's own option list, or None if it cannot be obtained.
+
+    Help output is the cheapest authoritative answer to "does this CLI accept
+    this flag". Launching a real run would be authoritative too, and far more
+    expensive for a diagnostic.
+    """
+    try:
+        if spawn_sync:
+            result = spawn_sync(command, ["--help"], {"env": env, "timeout": 10})
+            if isinstance(result, dict):
+                text = f"{result.get('stdout') or ''}\n{result.get('stderr') or ''}"
+            else:
+                text = f"{getattr(result, 'stdout', '') or ''}\n{getattr(result, 'stderr', '') or ''}"
+        else:
+            completed = subprocess.run(
+                [command, "--help"], env=env, capture_output=True, text=True, timeout=10, check=False,
+            )
+            text = f"{completed.stdout or ''}\n{completed.stderr or ''}"
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return text if text.strip() else None
+
+
+def _provider_flag_issues(service, env, spawn_sync=None):
+    """Verify the flags cdx maps for each permission exist in the provider CLI.
+
+    GitHub issue #8 was exactly this going unchecked: `--experimental-yolo` was
+    mapped for ollama, a flag that CLI never had, and nothing noticed until a
+    user ran `permission=full` on an ollama session.
+
+    An unverifiable mapping reports WARN, never OK: "we could not check" is the
+    state that bug lived in for months, and it must not read as a pass.
+    """
+    issues = []
+    providers = sorted({
+        session.get("provider") for session in service["list_sessions"]()
+        if session.get("provider")
+    })
+    for provider in providers:
+        command = PROVIDER_CLI_COMMANDS.get(provider, provider)
+        mappings = _mapped_provider_flags(provider)
+        if not mappings:
+            issues.append(_issue(
+                "OK",
+                f"{provider}_permission_flags",
+                f"{provider} maps no permission to CLI flags; nothing to verify",
+                {"provider": provider, "command": command, "mapped": {}},
+            ))
+            continue
+        if not shutil.which(command, path=env.get("PATH")):
+            issues.append(_issue(
+                "WARN",
+                f"{provider}_permission_flags",
+                f"{provider} CLI not installed; mapped permission flags could not be verified",
+                {"provider": provider, "command": command, "mapped": mappings},
+            ))
+            continue
+        help_text = _provider_help_text(command, env, spawn_sync)
+        if help_text is None:
+            issues.append(_issue(
+                "WARN",
+                f"{provider}_permission_flags",
+                f"{provider} CLI help could not be read; mapped permission flags could not be verified",
+                {"provider": provider, "command": command, "mapped": mappings},
+            ))
+            continue
+        missing = {
+            permission: [flag for flag in flags if flag not in help_text]
+            for permission, flags in mappings.items()
+        }
+        missing = {permission: flags for permission, flags in missing.items() if flags}
+        detail = {"provider": provider, "command": command, "mapped": mappings, "missing": missing}
+        if missing:
+            described = "; ".join(
+                f"{permission}: {', '.join(flags)}" for permission, flags in sorted(missing.items())
+            )
+            issues.append(_issue(
+                "FAIL",
+                f"{provider}_permission_flags",
+                f"{provider} CLI does not accept flags cdx maps ({described})",
+                detail,
+            ))
+        else:
+            issues.append(_issue(
+                "OK",
+                f"{provider}_permission_flags",
+                f"{provider} CLI accepts every flag cdx maps for its permissions",
+                detail,
+            ))
+    return issues
+
+
 def _provider_capability_hints(command):
     if command == "codex":
         return [

package/src/notify.py

@@ -7,11 +7,11 @@ import time
 from datetime import datetime, timedelta
 
 from .errors import CdxError
+from .session_ranking import rank_sessions
 from .status_view import (
     PRIORITY_EMPTY_AVAILABLE_THRESHOLD,
     _parse_reset_timestamp,
     _priority_reset_timestamp,
-    _recommend_priority_sessions,
 )
 
 NOTIFY_USAGE = "Usage: cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] | cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh]"
@@ -103,10 +103,16 @@ def resolve_notify_event(rows, parsed, now_ts=None):
     now_ts = time.time() if now_ts is None else now_ts
     if parsed["mode"] == "next-ready":
         active_rows = [row for row in rows if row.get("enabled", True) is not False]
-        priority = _recommend_priority_sessions([
-            row for row in active_rows
-            if not _is_usable_now(row) and _priority_reset_timestamp(row) is not None
-        ])
+        # Same ranking every other selector uses; the pre-filter is what makes
+        # this "next to come back" rather than "best right now".
+        priority, _decision = rank_sessions(
+            [
+                row for row in active_rows
+                if not _is_usable_now(row) and _priority_reset_timestamp(row) is not None
+            ],
+            now_ts,
+            _priority_reset_timestamp,
+        )
         if not priority:
             return _event(False, "cdx", "No upcoming session reset available", None)
         first = priority[0]

package/src/provider_background.py

@@ -0,0 +1,263 @@
+"""Delegating detached runs to a provider's own background agents.
+
+cdx has always detached runs itself: fork the child into its own session, keep
+its pid, sweep the record when that pid dies. Claude Code now ships the same
+thing natively - `--bg` starts a background agent and `claude agents --json`
+lists them - so on that provider cdx can stop owning the mechanism and own the
+routing instead, which is the part no provider will do.
+
+Two deliberate limits:
+
+Claude only. codex-cli exposes `cloud` and `exec-server`, both marked
+EXPERIMENTAL in its own --help. Trading a working in-house path for a surface
+the provider may change without notice is a bad trade, so Codex keeps the
+in-house launcher until that surface settles.
+
+Capability, never version. The installed CLI is asked what it supports, the
+same way `cdx doctor --check-provider-flags` already does, because a version
+comparison goes stale the moment either side ships.
+"""
+
+import json
+import os
+import re
+import subprocess
+
+from .config import PROVIDER_CLAUDE
+
+BACKGROUND_PATH_PROVIDER = "provider_native"
+BACKGROUND_PATH_CDX = "cdx_detached"
+
+_CAPABILITY_PROBE_TIMEOUT_SECONDS = 10
+
+# Observed on Claude Code 2.1.226 by watching one agent from launch to finish:
+# completion is carried by `state`, not by `status`. `status` alternates
+# idle/busy - it describes activity, not outcome - and an agent waiting on
+# something sits at `state: "blocked"` with `status: "idle"`, which reads
+# exactly like a finished one if you look at `status`.
+_TERMINAL_STATES = {"done", "failed", "cancelled", "canceled", "error", "stopped"}
+_SUCCESS_STATE = "done"
+
+# `claude --bg` prints `backgrounded · <id>` on stdout. That is the authoritative
+# handle: the provider assigns the id itself and ignores --session-id, so this
+# line is the only thing that reliably names the agent just started.
+_BACKGROUNDED = re.compile(r"backgrounded\s*[^\w]?\s*([0-9a-fA-F]{6,})")
+
+
+def parse_backgrounded_id(output):
+    """The agent id `claude --bg` reported, or None."""
+    if not output:
+        return None
+    match = _BACKGROUNDED.search(output)
+    return match.group(1) if match else None
+
+
+EXPERIMENTAL_ENV = "CDX_EXPERIMENTAL_NATIVE_BG"
+
+
+def supports_native_background(provider, env=None, spawn_sync=None):
+    """Whether the installed provider CLI can run and report background agents.
+
+    Off unless `CDX_EXPERIMENTAL_NATIVE_BG=1`. Two live trials against Claude
+    Code 2.1.226 fixed the identification problems and exposed a deeper one.
+
+    Fixed: the provider assigns its own id and ignores `--session-id`, so the
+    agent is now named from the `backgrounded - <id>` line `--bg` prints, and
+    completion is read from `state` rather than `status` (which alternates
+    idle/busy and says nothing about outcome).
+
+    Not fixed, and the reason this stays off:
+
+    1. A delegated run cannot honour the `cdx run --json` contract. The
+       in-house path runs `claude --print --output-format json` and gets a
+       structured result, token usage, and a final payload. `--bg` runs the
+       interactive TUI; `claude logs <id>` returns an ANSI screen dump. So
+       usage accounting, the final payload, and the rate-limit classification
+       that `--failover` depends on all have no source.
+    2. Nothing yet drives a delegated run to a terminal status. `agent_terminal_status`
+       exists but no caller consults the provider, so the record relies on pid
+       liveness and a blocked agent reads as running indefinitely.
+    3. cdx's own launch spec makes the agent block. A hand-run
+       `claude --bg --permission-mode bypassPermissions "..."` reaches
+       `state: done`; the same task launched through cdx sits at
+       `state: blocked`, most likely because the spec passes a `--session-id`
+       that already exists.
+
+    Delegation therefore needs its own request, not a flag flip.
+    """
+    if provider != PROVIDER_CLAUDE:
+        return False
+    environment = env if env is not None else os.environ
+    if str(environment.get(EXPERIMENTAL_ENV, "")).strip() not in ("1", "true", "on", "yes"):
+        return False
+    runner = spawn_sync or _default_spawn_sync
+    try:
+        help_text = runner(["claude", "--help"], env=env)
+        agents_help = runner(["claude", "agents", "--help"], env=env)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    if help_text is None or agents_help is None:
+        return False
+    return "--bg" in help_text and "--json" in agents_help
+
+
+def _default_spawn_sync(argv, env=None):
+    try:
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=_CAPABILITY_PROBE_TIMEOUT_SECONDS,
+            env=env,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return f"{completed.stdout or ''}{completed.stderr or ''}"
+
+
+def list_background_agents(env=None, cwd=None, spawn_sync=None):
+    """Every background agent the provider knows about, completed ones included.
+
+    Returns [] rather than raising for any failure: this feeds a status refresh
+    that must never take down the command that asked for it.
+    """
+    runner = spawn_sync or _default_spawn_sync
+    argv = ["claude", "agents", "--json", "--all"]
+    if cwd:
+        argv += ["--cwd", cwd]
+    output = runner(argv, env=env)
+    if not output:
+        return []
+    start = output.find("[")
+    if start < 0:
+        return []
+    try:
+        agents = json.loads(output[start:])
+    except ValueError:
+        return []
+    return agents if isinstance(agents, list) else []
+
+
+def find_agent(agents, identifier):
+    """The agent with this id, matching either the short id or the session id."""
+    for agent in agents:
+        if not isinstance(agent, dict):
+            continue
+        if identifier in (agent.get("id"), agent.get("sessionId")):
+            return agent
+    return None
+
+
+def stop_background_agent(identifier, env=None, spawn_sync=None):
+    """Release a parked session once its task is done.
+
+    `--bg` starts an interactive session that outlives the turn it was given,
+    so a one-shot run leaves it alive unless cdx stops it. Six were leaked
+    during development before this existed.
+    """
+    if not identifier:
+        return False
+    runner = spawn_sync or _default_spawn_sync
+    return runner(["claude", "stop", str(identifier)], env=env) is not None
+
+
+def turn_is_complete(outcome):
+    """Whether the provider recorded an answer for the prompt cdx submitted.
+
+    This, not the agent's state, is what says a one-shot delegated task
+    finished. A `--bg` session parks at `state: blocked, status: idle` after
+    answering and stays there indefinitely, waiting for a next prompt that a
+    one-shot run will never send - indistinguishable, by state alone, from an
+    agent still thinking.
+    """
+    return bool(outcome and outcome.get("result") is not None and outcome.get("usage"))
+
+
+def agent_terminal_status(agent):
+    """The cdx run status a provider agent maps to, or None while it runs.
+
+    An agent the provider no longer lists has finished in a way cdx cannot
+    name, so it reports `failed` rather than `succeeded`: claiming success for
+    a run whose outcome was never observed is the one answer that must not be
+    guessed.
+    """
+    if agent is None:
+        return "failed"
+    state = str(agent.get("state") or "").strip().lower()
+    if state not in _TERMINAL_STATES:
+        return None
+    return "succeeded" if state == _SUCCESS_STATE else "failed"
+
+
+def find_session_transcript(auth_home, session_id):
+    """The provider's own JSONL transcript for a background session, or None.
+
+    Claude Code writes one file per session under `.claude/projects/<cwd>/`,
+    named by session id. Located by walking rather than by reconstructing the
+    encoded cwd directory, because that encoding is the provider's and is not
+    part of any contract cdx should depend on.
+    """
+    if not auth_home or not session_id:
+        return None
+    root = os.path.join(auth_home, ".claude", "projects")
+    if not os.path.isdir(root):
+        return None
+    target = f"{session_id}.jsonl"
+    for dirpath, _dirnames, filenames in os.walk(root):
+        if target in filenames:
+            return os.path.join(dirpath, target)
+    return None
+
+
+def read_transcript_outcome(path):
+    """The final assistant text and summed token usage from a session transcript.
+
+    This is what makes a delegated run able to honour the `cdx run --json`
+    contract at all: `--bg` produces no structured stdout, but the provider
+    records the same facts here. Usage is summed across assistant messages
+    because a session can hold several turns.
+    """
+    outcome = {"result": None, "usage": None}
+    if not path:
+        return outcome
+    totals = {"input_tokens": 0, "output_tokens": 0, "reasoning_tokens": 0, "total_tokens": 0}
+    seen = False
+    try:
+        with open(path, encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line.startswith("{"):
+                    continue
+                try:
+                    record = json.loads(line)
+                except ValueError:
+                    continue
+                if record.get("type") != "assistant":
+                    continue
+                message = record.get("message")
+                if not isinstance(message, dict):
+                    continue
+                content = message.get("content")
+                if isinstance(content, list):
+                    text = " ".join(
+                        block.get("text", "") for block in content
+                        if isinstance(block, dict) and block.get("type") == "text"
+                    ).strip()
+                    if text:
+                        outcome["result"] = text
+                usage = message.get("usage")
+                if isinstance(usage, dict):
+                    seen = True
+                    inp = (usage.get("input_tokens") or 0) + (usage.get("cache_creation_input_tokens") or 0) \
+                        + (usage.get("cache_read_input_tokens") or 0)
+                    out = usage.get("output_tokens") or 0
+                    totals["input_tokens"] += inp
+                    totals["output_tokens"] += out
+                    totals["total_tokens"] += inp + out
+    except OSError:
+        return outcome
+    if seen:
+        totals["reasoning_tokens"] = None
+        outcome["usage"] = totals
+    return outcome