@widgex/wgx 0.0.0-stage → 0.4.1

package/python/xactor/plan_mode.py

@@ -0,0 +1,350 @@
+"""What Plan mode permits, and the refusal for everything else.
+
+Plan mode is read-only, and the enforcement is here rather than at the
+shell-exec boundary for the reason the whole permission model is per-call:
+gating the enclosing exec cannot tell `api.read_file` from `api.write_file`,
+so it asked about both. That made planning an approval loop, which is the
+complaint this module exists to answer.
+
+**An allowlist, not a denylist**, for a reason the codebase already
+demonstrates. `_gate_api_methods` iterates `vars(cls)` at class-definition
+time and therefore silently omits the 34 verbs `_graft_browser_l1` attaches
+later — a denylist would inherit exactly that shape of bug, where a new verb
+is dangerous by default and safe only if someone remembers. Inverted, a new
+verb is *broken in Plan mode* until someone opts it in: loud, immediate, and
+caught by the coverage sweep in `test/planModeApiSurface.test.mjs` rather
+than by a user discovering their plan edited something.
+
+The cost is real and worth naming: a genuinely read-only api method added
+later is refused in Plan mode until it is listed here. That sweep test fails
+with the unclassified name printed, so the fix is one line and obvious.
+
+The membership criterion, stated so future entries are decided rather than
+argued: **a call is Plan-safe when it changes nothing that survives the plan
+being rejected.** Session-scoped UI state dies with the session and is fine.
+Anything durable, anything outside this process, and anything that acts on a
+page, a process, another session or the human's screen is not.
+
+Deliberately *not* "does it read secrets". Plan mode permits `read_file`, so
+confinement is the sandbox's job — see `sandbox.guarded_os`.
+"""
+
+import functools
+import inspect
+from typing import Any, Callable
+
+from . import bridge
+
+#: Calls Plan mode runs without asking. Everything else is refused.
+#:
+#: Grouped by why, because every group was a judgment call:
+PLAN_SAFE = frozenset({
+    # ── Reads. The reason this module exists. ──────────────────────────
+    "read_file", "glob", "grep", "ls", "man",
+    # Checking a harness file reads it and says what is wrong. A plan that
+    # proposes a harness is better for having been checked first.
+    "harness_check",
+    # Reading what an *already approved* background command is doing. The
+    # command was gated when it started; watching it is not a second act.
+    "bash_output", "bash_list",
+
+    # ── Session and tree reads ─────────────────────────────────────────
+    "children", "tasks", "session_join", "wait_for_task",
+    # Asking a conversation the person attached as a reference. It starts an
+    # agent, which nothing else here does — but that agent is handed the
+    # asker's own mode, so under a plan it can read and answer and no more,
+    # and what an earlier task decided is exactly what a plan should rest on.
+    "ask_reference",
+    # Saying where your *own* task has got to. Not a read, and admitted
+    # anyway: it writes one line of workspace state and nothing in the
+    # project, and a planning agent is exactly the one whose progress is
+    # worth seeing — it is reading code for minutes with nothing else to
+    # show for it. Refusing it would make Plan mode the one mode whose
+    # cards never say anything.
+    "task_status",
+    # A swarm member's progress report, on the same terms: one line into the
+    # swarm's stream and nothing in the project. `spawn_swarm` is not here —
+    # it starts agents that write, which is what planning is not.
+    "swarm_brief",
+    # The user's `/chess` game: a move on a board in wgx's memory, and a read
+    # of it. Nothing in the project, and the person started the game.
+    "chess_move", "chess_state",
+    # Clearing your own context. It writes nothing in the project, and a
+    # long planning session is as likely as any to need it.
+    "compact",
+    "xylon_list_trees", "xylon_get_tree", "xylon_get_node", "xylon_read_messages",
+    "xylon_search", "xylon_read_turns", "xylon_blame",
+    # A drive space's listing, and where a review stands. Both read; neither
+    # fetches a file or opens anything.
+    "drive_tree", "drive_review_status",
+    # The project Drive's documents and what differs in this machine's copy.
+    # It brings the copy up to date with what teammates landed, which writes
+    # under ~/.widgex and nothing in the project; suggesting is not here.
+    "project_drive",
+    # `widgets` and `profiles` are absent from PERMISSION_REQUIRED for the
+    # reason given there — listing what is installed opens nothing and
+    # reveals nothing. The same reasoning admits them here.
+    "widgets", "profiles",
+    # Reads of a browser someone already attached. Reaching a *new* site
+    # still needs `drive` / `use_widget` / `browser_open_tab`, all gated.
+    "browser_tabs", "browser_hybrid",
+
+    # ── Talking ────────────────────────────────────────────────────────
+    # Exactly the set `COMMUNICATION_CALLS` (src/providers/tools.ts) admits
+    # in Read-only, which is the stricter mode. Plan must not be stricter
+    # than Read-only about answering a question.
+    #
+    # Known escape hatch, accepted knowingly: `relay_send` can ask another
+    # agent to do the work. That is pre-existing and deliberate — it is the
+    # same hatch Read-only has — not something Plan mode opens.
+    "read_bulletin",
+    "relay_connect", "relay_accept", "relay_decline",
+    "relay_send", "relay_inbox", "relay_close",
+    # Asking the human, and asking another model for text. `ask_user` is the
+    # single most valuable call a planner has when the requirements are
+    # ambiguous; refusing it would make Plan mode worse at planning than any
+    # other mode is. `ask_model` is the sanctioned alternative to `agent`
+    # for a second opinion — no tools, no subagent, no session.
+    "ask_user", "ask_model",
+
+    # ── Session-scoped UI. Dies with the session. ──────────────────────
+    # `todo_write` is how the user watches the plan being built.
+    "todo_write", "session_scope",
+    # `phase` only reads: where the plan being written will land, and what came before.
+    "phase",
+
+    # ── Durable, and permitted anyway, by explicit decision ────────────
+    # Both write something that outlives the plan, so the criterion above
+    # argues against them. Allowed because the alternative is worse: an
+    # agent that hits a WidgeX defect while planning and cannot report it,
+    # or notices follow-up work and has to hold it in prose until the plan
+    # is approved.
+    "report_bug", "add_card",
+
+    # ── Argument-dependent. See StdlibAPI._plan_safe_agent. ────────────
+    "agent",
+
+    # ── Grafted browser verbs: the ones that only read the page ────────
+    "find", "search", "one", "outline", "snapshot", "digest",
+    "get_state", "here", "wait_for", "wait_stable",
+
+    # ── Grafted: withdrawn stubs that only raise a redirect ────────────
+    # `api.query()` and friends do nothing but raise "use api.search(...)".
+    # Refusing them would replace a genuinely helpful hint with a mode
+    # refusal, for a call that could not have done anything either way.
+    "query", "query_one", "hybrid_snapshot",
+})
+
+
+#: What the Support Sprite may do *beyond* reading: drive the IDE it is
+#: attached to.
+#:
+#: Support mode is Plan mode's reads plus these. The sprite answers by pointing
+#: at things in the user's own window — ringing a control, captioning a step,
+#: clicking through a menu with them watching — so the page verbs are the job,
+#: not an escape from it. What stays refused is everything that acts *off*
+#: screen: files, shell, other sessions, other sites.
+#:
+#: Deliberately absent: `evaluate` (arbitrary script in the workbench, which can
+#: reach far more than the screen shows), `navigate` (moving a webview away from
+#: the IDE's own page breaks it), and every `request_*` handoff.
+SUPPORT_DRIVE = frozenset({
+    "click", "double_click", "type_text", "clear_and_type", "hover",
+    "scroll_to", "select", "focus", "press", "dom_click", "dom_fill", "drain",
+    "screenshot",
+    # The guide verbs: the reason the sprite exists.
+    "highlight", "instruct", "reply", "await_user",
+    # Re-pointing at another part of its own window.
+    "attach_ide",
+})
+
+#: Everything a support session may call without being refused.
+SUPPORT_SAFE = PLAN_SAFE | SUPPORT_DRIVE
+
+#: The most a grant can ever add to support mode, whatever the exec meta says.
+#: Mirrors SUPPORT_GRANT_CALLS in src/ide-widgets/supportSprite/supportGrant.ts.
+#: Three of the four ask permission, and the host checks their arguments.
+SUPPORT_GRANTABLE = frozenset({
+    "drive", "request_operator_action", "write_file", "edit_file",
+})
+
+#: The permission mode the Support Sprite runs in. See ClaudeSessionService.
+SUPPORT_MODE = "support"
+
+#: A read-only copy's mode: a conversation copied to answer one question about
+#: it, which is how an @-mentioned agent answers in a channel. See
+#: ClaudeSessionService.READONLY_MODE.
+COPY_MODE = "readonly"
+
+#: Everything a read-only copy may call. Narrower than Plan on purpose: Plan
+#: is somebody planning their own work, and admits asking the user, starting
+#: an agent, filing a card and writing todos. A copy answers somebody else's
+#: question about somebody else's work; it reads, and that is all. The
+#: criterion is stricter than Plan's too: **a call is copy-safe when it
+#: changes nothing at all**, durable or not, here or anywhere.
+#:
+#: The page-reading verbs are here only because `guard` hands Plan-safe
+#: grafted verbs back unwrapped, so a copy could not be refused them anyway;
+#: listing them says so rather than leaving it implicit. They read a page
+#: someone already attached, and a copy attaches nothing.
+COPY_SAFE = frozenset({
+    "read_file", "glob", "grep", "ls", "man",
+    "tasks", "read_bulletin",
+    "xylon_list_trees", "xylon_get_tree", "xylon_get_node", "xylon_read_messages",
+    "xylon_search", "xylon_read_turns", "xylon_blame",
+    "drive_tree", "drive_review_status",
+    "harness_check",
+    "find", "search", "one", "outline", "snapshot", "digest",
+    "get_state", "here", "wait_for", "wait_stable",
+    "query", "query_one", "hybrid_snapshot",
+})
+
+
+def _message(name: str) -> str:
+    """The refusal an agent reads.
+
+    Written against the two things a model does when a call is refused, both
+    of which cost turns and neither of which can work here:
+
+    1. It retries, on the theory that the user might answer differently.
+    2. It looks for another spelling — `click` refused, so `dom_click`, then
+       `evaluate("...click()")`, then `bash("osascript ...")`. That instinct
+       is real enough that `_browser_intent_hint` exists to catch it.
+
+    So the message says outright that it is the mode and not the user, that
+    no other call does this, and what *does* still work — a refusal that only
+    says no is a refusal the model argues with.
+    """
+    return (
+        f"Plan mode does not permit api.{name}().\n"
+        "\n"
+        "It is the mode refusing, not the user — there is nothing to retry, "
+        "and no other call does this without the same refusal. What still "
+        "works: reads (read_file, glob, grep, ls), the page-reading verbs "
+        "(search, outline, one), the xylon tree, relay and the bulletin, "
+        "ask_user, ask_model, todo_write, man.\n"
+        "\n"
+        "Write the plan, then call ExitPlanMode. The user approves it, the "
+        "mode changes, and this call runs. If ExitPlanMode answers \"You are "
+        "not in plan mode\", WidgeX and the harness disagree about the mode: "
+        "call EnterPlanMode and then ExitPlanMode, so both see a fresh approval."
+    )
+
+
+def _support_message(name: str) -> str:
+    """The refusal the Support Sprite reads.
+
+    **Duplicated in ClaudeSessionService.SUPPORT_DENIAL**, which refuses the
+    same calls from the other side of the bridge.
+    """
+    return (
+        f"Support mode does not permit api.{name}().\n"
+        "\n"
+        "You are read-only: you can read, look things up, and drive the IDE on "
+        "screen, but not edit files or run commands yourself. It is the mode "
+        "refusing, not the user — nothing will make this call succeed. Show the "
+        "user how to do it instead: point at the control with api.highlight or "
+        "api.instruct, and let them press it."
+    )
+
+
+def _copy_message(name: str) -> str:
+    """The refusal a read-only copy reads.
+
+    **Duplicated in ClaudeSessionService.READONLY_DENIAL**, which refuses the
+    same calls from the other side of the bridge.
+    """
+    return (
+        f"A read-only copy does not permit api.{name}().\n"
+        "\n"
+        "You are a copy of a conversation, made to answer a question about it. "
+        "You can read files, search them and read the project, and nothing "
+        "else. It is the mode refusing, not the user, and nothing will make "
+        "this call succeed. Answer from what you can read."
+    )
+
+
+def refuse_if_planning(name: str, allowed: bool | None = None) -> None:
+    """Raise when `name` is not something Plan mode permits. No-op otherwise.
+
+    `allowed` is the verdict of a `_plan_safe_<name>` sibling, for the calls
+    whose answer depends on their arguments. It **overrides** membership in
+    both directions, and it has to: `agent` is listed in `PLAN_SAFE` — the
+    coverage sweep reads that list to know the call has been classified at all
+    — while only one of its shapes is actually safe. Reading membership first
+    and returning would have made every `agent(wait=False)` plan-safe, which
+    is precisely the escape this module exists to close.
+
+    The hot path — a loop of `read_file`, which is what planning is — costs one
+    contextvar read and one frozenset lookup. The mode is read first because
+    support mode has its own list: it refuses `agent`, which Plan admits.
+
+    **A missing mode means unrestricted, deliberately.** Tests that spawn a
+    bare daemon and headless use send no `permissionMode`, and this mirrors
+    `_require_permission`'s own "no bridge means nobody to ask, so proceed".
+    The *allowlist* fails closed within Plan mode; the *mode* fails open when
+    unstated, and what makes that acceptable is that exactly one place stamps
+    it — `StdlibShell.exec` — rather than each of the four call sites that
+    assemble exec meta.
+    """
+    meta = bridge.exec_meta.get()
+    mode = meta.get("permissionMode")
+    # First, because a copy is narrower than Plan in both directions: the
+    # Plan-safe verdict (`agent` with wait=True, say) does not admit anything
+    # here, and nothing outside COPY_SAFE runs whatever its arguments.
+    if mode == COPY_MODE:
+        if name in COPY_SAFE:
+            return
+        raise PermissionError(_copy_message(name))
+    if mode != SUPPORT_MODE and (allowed if allowed is not None else (name in PLAN_SAFE)):
+        return
+    if mode == SUPPORT_MODE:
+        # The sprite's own allowlist. `allowed` is a planning verdict and is
+        # not consulted: support mode is narrower than Plan about subagents.
+        if name in SUPPORT_SAFE and name != "agent":
+            return
+        # A Walter opened for one job (drive setup) may also make the calls
+        # that job needs. Names only, stamped by StdlibShell.exec; which url
+        # and which file are checked by the host when the call asks.
+        if name in SUPPORT_GRANTABLE and name in (meta.get("supportGrants") or ()):
+            return
+        raise PermissionError(_support_message(name))
+    if mode != "plan":
+        return
+    raise PermissionError(_message(name))
+
+
+def guard(name: str, fn: Callable) -> Callable:
+    """Wrap a grafted browser verb so Plan mode can refuse it.
+
+    `_graft_browser_l1` attaches these with `setattr` *after* the class body
+    has run, so `_gate_api_methods` never sees them and `_api_method` never
+    wraps them. This is the second of the two call sites enforcing PLAN_SAFE.
+
+    **The sync branch is load-bearing, not tidiness.** Ten of these verbs —
+    `click`, `type_text`, `press`, `hover`, `select`, … — are plain `def`.
+    They call `bridge.call(...)` eagerly and hand the coroutine to `_enqueue`,
+    which does `asyncio.ensure_future`, so *the request goes out on the next
+    tick whether or not the agent awaits it*. An `async def` wrapper on one of
+    those would return a coroutine nobody awaits: the guard would never run,
+    the agent would see no error, and the only trace would be a RuntimeWarning
+    on a stderr nobody reads. The refusal has to happen at the call site.
+
+    Allowlisted verbs are returned unwrapped rather than wrapped-and-allowed,
+    so `outline()` and `search()` are byte-identical to before this existed.
+    """
+    if name in PLAN_SAFE:
+        return fn
+
+    if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            refuse_if_planning(name)
+            return await fn(*args, **kwargs)
+    else:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:  # type: ignore[misc]
+            refuse_if_planning(name)
+            return fn(*args, **kwargs)
+
+    return wrapper