Python
OPE-153: a question card can be skipped — one question, or the whole card
Devika Vermaf0f59ff9770e
diff --git a/coworker/engine.py b/coworker/engine.pyindex a915fc2a..b2a3b1f3 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -2651,7 +2651,17 @@ class TurnEngine:"error": "no response",}- status = "ok" if (result.get("answer") or result.get("answers")) else "denied"+ # A skipped question answers None (OPE-153), so an all-skipped card is "denied" like an+ # unanswered one — `answers` being non-empty isn't enough on its own.+ replies = result.get("answers")+ status = (+ "ok"+ if (+ result.get("answer")+ or (isinstance(replies, dict) and any(v is not None for v in replies.values()))+ )+ else "denied"+ )if status == "ok":self._note_ask_replies(result, question)self.messages.append(self._timed_result(tool_call, result))@@ -2686,8 +2696,10 @@ class TurnEngine:self._reviewer_denials = 0anchor = sum(1 for m in self.messages if m.get("role") == "user" and not m.get("source"))answers = result.get("answers")+ # Skipped questions answer None (OPE-153) — dropped here, else str(None) files "None"+ # as something the user actually said.values = (- [str(v) for v in answers.values()]+ [str(v) for v in answers.values() if v is not None]if isinstance(answers, dict)else [str(result.get("answer") or "")])diff --git a/coworker/tools/ask.py b/coworker/tools/ask.pyindex a426232d..7c7a3ac7 100644--- a/coworker/tools/ask.py+++ b/coworker/tools/ask.py@@ -22,6 +22,24 @@ from aisuite.agents import ToolMetadata, tool# How many questions one grouped call may carry (stepper chips get unreadable past this).MAX_GROUPED_QUESTIONS = 4+# OPE-153 — the resolution string a card sends when the user declines to answer. The resolution+# field otherwise carries the answer verbatim, so "skipped" needs a value no answer can collide+# with; the GUI writes the same constant (see SKIP in InboxItemCard.tsx — keep the two in step).+# A grouped card marks a per-question skip by using it as that question's value in the answer map,+# and a whole-card skip by filling every unanswered question with it.+SKIP_SENTINEL = "__ocw_skip__"++# Told to the agent alongside a skipped answer. Only the no-re-ask half is absolute — it's the+# anti-loop guarantee the skip exists for. "Pick a default" is deliberately conditional: the same+# note fires for "you choose the chart colour" and for "Staging or Production?", and a model that+# follows instructions literally would deploy off a shrug. Proceeding without deciding is offered+# as a third path so that judgment is asked for, not left to whichever model happens to be driving.+SKIP_NOTE = (+ "The user chose not to answer. Do not put this question back to them. If you can proceed "+ "safely, pick a sensible default and say which way you went. If the choice is consequential "+ "or hard to undo, don't guess — say what you'd need and let them come back to it."+)+# An option is a plain string OR a rich object. `label` is what the user picks (and what comes# back as the answer); `description` renders under it; `recommended` adds the green tag (put the# recommended option first); `preview` is monospace text shown in the side pane (code, config,@@ -143,6 +161,12 @@ def ask_user_tool() -> object:Grouped form (`questions`) returns `{"answers": {"<header or question>": "..."}}` — oneentry per question. Don't ask what you can reasonably decide yourself; reserve this forchoices that are actually the user's to make.++ The user may SKIP any question. A skipped answer comes back as `null` (never ""), with+ `skipped` naming what was declined. Treat it as "you decide" where the choice is safe:+ pick a sensible default, continue, and say which way you went. Where it isn't — anything+ consequential or hard to undo — don't guess; say what you'd need instead. Either way,+ never re-ask a skipped question."""# Real handling lives in the engine (it needs the out-of-band Inbox round-trip). This body# only runs if no question_asker is wired (e.g. a headless surface).@@ -242,22 +266,56 @@ def question_item_fields(args: dict) -> dict | None:}+def question_key(entry) -> str:+ """The answer-map key for one grouped question — its header, else the question text. The+ same key the card writes when it resolves, so the two halves agree."""+ if not isinstance(entry, dict):+ return "answer"+ return str(entry.get("header") or entry.get("question") or "answer")++def answer_result(item_questions: list, resolution: str | None) -> dict:"""Shape the ask_user tool result from an Inbox item's resolution string. Grouped itemsresolve with a JSON object string keyed by header-or-question → `{"answers": {...}}`;- everything else returns the plain `{"answer": str}` shape."""+ everything else returns the plain `{"answer": str}` shape.++ A skipped question (OPE-153) answers `None` rather than "", so the agent can tell "the user+ declined" from "the answer came back empty" — the two used to be the same value. Skips also+ carry `skipped` (the question keys, or True for a lone question) and `SKIP_NOTE`."""if item_questions:+ # A text-only surface (mirrored channel) can only send the bare sentinel: that skips the+ # whole card, so every question answers None.+ if resolution == SKIP_SENTINEL:+ keys = [question_key(q) for q in item_questions]+ return {+ "answers": dict.fromkeys(keys),+ "skipped": keys,+ "note": SKIP_NOTE,+ }try:parsed = json.loads(resolution or "")except (ValueError, TypeError):parsed = Noneif isinstance(parsed, dict):- return {"answers": {str(k): str(v) for k, v in parsed.items()}}+ answers: dict[str, str | None] = {}+ skipped: list[str] = []+ for k, v in parsed.items():+ key = str(k)+ if v is None or str(v) == SKIP_SENTINEL:+ answers[key] = None+ skipped.append(key)+ else:+ answers[key] = str(v)+ result: dict = {"answers": answers}+ if skipped:+ result["skipped"] = skipped+ result["note"] = SKIP_NOTE+ return resultif resolution:# Answered from a text-only surface (e.g. a mirrored channel): attribute the lone# answer to the first question rather than losing it.- first = item_questions[0] if isinstance(item_questions[0], dict) else {}- key = str(first.get("header") or first.get("question") or "answer")- return {"answers": {key: str(resolution)}}+ return {"answers": {question_key(item_questions[0]): str(resolution)}}return {"answer": ""}+ if resolution == SKIP_SENTINEL:+ return {"answer": None, "skipped": True, "note": SKIP_NOTE}return {"answer": resolution or ""}diff --git a/surfaces/gui/e2e/ask-skip.spec.ts b/surfaces/gui/e2e/ask-skip.spec.tsnew file mode 100644index 00000000..51678925--- /dev/null+++ b/surfaces/gui/e2e/ask-skip.spec.ts@@ -0,0 +1,163 @@+import type { Page } from "@playwright/test";+import { test, expect } from "./fixtures";++// OPE-153 — skipping a question. A question card used to have no exit: the only ways out were+// picking an option or typing an answer, so a user who couldn't answer had to invent one or+// abandon the session. Now every card carries Skip, and grouped cards carry both "Skip question"+// (this one, advance) and "Skip all" (resolve the rest). Seeded via a per-test inbox route+// override so the base fixtures' counts stay untouched.++// Mirrors SKIP in InboxItemCard.tsx / SKIP_SENTINEL in coworker/tools/ask.py.+const SKIP = "__ocw_skip__";++const BASE = {+ body: "",+ state: "pending",+ resolution: null as string | null,+ inbox: "default",+ created_at: "2026-08-31 08:00:00",+ resolved_at: null as string | null,+ session_title: "Investigate alerts",+ session_agent: "ops",+ session_workspace: "",+ session_exists: true,+};++const SINGLE_ITEM = {+ ...BASE,+ id: "inb-question-single",+ session_id: "ops-1",+ kind: "question",+ title: "Which environment should I deploy to?",+ header: "Environment",+ options: ["Staging", "Production"],+ allow_text: true,+ multi: false,+ questions: [],+};++// The card a user could previously get stuck on: exhaustive options, no free-text escape.+const NO_TEXT_ITEM = {+ ...SINGLE_ITEM,+ id: "inb-question-notext",+ allow_text: false,+};++const GROUPED_ITEM = {+ ...BASE,+ id: "inb-question-grouped",+ session_id: "ops-1",+ kind: "question",+ title: "Chart style?",+ header: "Chart style",+ options: ["Bar", "Line"],+ allow_text: false,+ multi: false,+ questions: [+ { question: "Chart style?", header: "Chart style", options: ["Bar", "Line"], allow_text: false, multi: false },+ { question: "Which distribution?", header: "Distribution", options: ["Stacked", "Grouped"], allow_text: false, multi: false },+ { question: "Which palette?", header: "Palette", options: ["Warm", "Cool"], allow_text: false, multi: false },+ ],+};++/** Replace the Inbox's seeded items for this test (resolve mutates the local copy). */+async function seedInbox(page: Page, items: Record<string, unknown>[]) {+ const inbox = items.map((i) => ({ ...i }));+ const json = (body: unknown) => ({+ status: 200,+ contentType: "application/json",+ body: JSON.stringify(body),+ });+ await page.route(/\/v1\/inbox\/[^/]+\/resolve$/, (route) => {+ const path = new URL(route.request().url()).pathname;+ const id = decodeURIComponent(path.split("/").slice(-2)[0]);+ const it = inbox.find((x) => x.id === id);+ if (it) {+ it.state = "resolved";+ it.resolution = route.request().postDataJSON().resolution;+ }+ return route.fulfill(json({ ok: true }));+ });+ await page.route(/\/v1\/inbox(\?.*)?$/, (route) =>+ route.fulfill(json({ items: inbox.filter((i) => i.state === "pending") })),+ );+ return inbox;+}++async function openInbox(page: Page, expectTitle: string) {+ await page.goto("/");+ await page.getByTestId("inbox-chip").click();+ await expect(page.getByText(expectTitle)).toBeVisible();+}++test("a single question can be skipped, and resolves as skipped rather than blank", async ({+ page,+}) => {+ await seedInbox(page, [SINGLE_ITEM]);+ await openInbox(page, "Which environment should I deploy to?");++ // One control, labelled plainly — no stepper, so nothing to say "question" about.+ const skip = page.getByTestId("question-skip");+ await expect(skip.getByRole("button", { name: "Skip", exact: true })).toBeVisible();+ await expect(skip.getByRole("button", { name: "Skip all" })).toHaveCount(0);++ const resolved = page.waitForRequest((r) => r.url().includes("/resolve") && r.method() === "POST");+ await skip.getByRole("button", { name: "Skip", exact: true }).click();+ expect((await resolved).postDataJSON().resolution).toBe(SKIP);+ await expect(page.getByText("Nothing pending.")).toBeVisible();+});++test("Skip is offered even when the card has no free-text escape", async ({ page }) => {+ await seedInbox(page, [NO_TEXT_ITEM]);+ await openInbox(page, "Which environment should I deploy to?");++ // Exhaustive options and no "Or type your own answer…" — Skip is the ONLY way out.+ await expect(page.getByPlaceholder("Or type your own answer…")).toHaveCount(0);+ const resolved = page.waitForRequest((r) => r.url().includes("/resolve") && r.method() === "POST");+ await page.getByTestId("question-skip").getByRole("button", { name: "Skip", exact: true }).click();+ expect((await resolved).postDataJSON().resolution).toBe(SKIP);+});++test("one step of a grouped card can be skipped while the others are answered", async ({+ page,+}) => {+ await seedInbox(page, [GROUPED_ITEM]);+ await openInbox(page, "Chart style?");++ const stepper = page.getByTestId("question-stepper");+ const skip = page.getByTestId("question-skip");++ // Skipping step 1 advances exactly as answering would.+ await skip.getByRole("button", { name: "Skip question" }).click();+ await expect(stepper).toContainText("2 of 3");++ await page.getByRole("button", { name: "Stacked", exact: true }).click();+ await expect(stepper).toContainText("3 of 3");++ // Last step: nothing left to "skip all", so only the per-question control remains.+ await expect(skip.getByRole("button", { name: "Skip all" })).toHaveCount(0);++ const resolved = page.waitForRequest((r) => r.url().includes("/resolve") && r.method() === "POST");+ await page.getByRole("button", { name: "Warm", exact: true }).click();+ expect((await resolved).postDataJSON().resolution).toBe(+ JSON.stringify({ "Chart style": SKIP, Distribution: "Stacked", Palette: "Warm" }),+ );+});++test("Skip all resolves the rest of a grouped card but keeps answers already given", async ({+ page,+}) => {+ await seedInbox(page, [GROUPED_ITEM]);+ await openInbox(page, "Chart style?");++ await page.getByRole("button", { name: "Bar", exact: true }).click();+ await expect(page.getByTestId("question-stepper")).toContainText("2 of 3");++ const resolved = page.waitForRequest((r) => r.url().includes("/resolve") && r.method() === "POST");+ await page.getByTestId("question-skip").getByRole("button", { name: "Skip all" }).click();+ // Step 1's real answer survives; only the two the user never reached are skipped.+ expect((await resolved).postDataJSON().resolution).toBe(+ JSON.stringify({ "Chart style": "Bar", Distribution: SKIP, Palette: SKIP }),+ );+ await expect(page.getByText("Nothing pending.")).toBeVisible();+});diff --git a/surfaces/gui/src/components/InboxItemCard.tsx b/surfaces/gui/src/components/InboxItemCard.tsxindex 82ef7aa8..ddcb9c08 100644--- a/surfaces/gui/src/components/InboxItemCard.tsx+++ b/surfaces/gui/src/components/InboxItemCard.tsx@@ -40,6 +40,10 @@ const BTN_BORDERED =const BTN_ACCENT ="px-3 py-1.5 rounded-lg border border-accent text-accent text-ui font-semibold hover:bg-accentSoft";const BTN_QUIET = "px-3 py-1.5 text-ui text-faint hover:text-danger";+// Skip (OPE-153) is an escape, not a rejection — quiet like Deny, without the danger red. Uses+// `muted` rather than Deny's `faint`: a borderless text button is already secondary next to the+// option pills, and this one has to be FOUND (faint is only ~3:1 on the dark panel).+const BTN_SKIP = "px-3 py-1.5 text-ui text-muted hover:text-ink";const OPT_BASE ="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-full border text-ui transition-colors";const OPT_OFF = "border-line bg-paper text-ink hover:border-accent hover:bg-accentSoft/50";@@ -79,6 +83,11 @@ export function approvalItemFromParked(item: InboxItem): Extract<Item, { kind: "};}+// The resolution a card sends when the user declines to answer (OPE-153). Mirrors+// SKIP_SENTINEL in coworker/tools/ask.py, which turns it back into a null answer —+// keep the two constants in step.+const SKIP = "__ocw_skip__";+// -- question normalization ---------------------------------------------------interface NormOption {@@ -288,6 +297,25 @@ function QuestionCard({else onResolve(item.id, JSON.stringify(all));};+ // Skipping ONE question is just answering it with the sentinel — the stepper advances (or the+ // card resolves on the last step) exactly as a real answer would.+ const skipStep = () => submit(SKIP);++ // Skipping the WHOLE card resolves it now, marking every question the user never got to.+ // Answers already given are kept: "skip all" means "don't ask me the rest", not "discard".+ const skipAll = () => {+ if (!grouped) {+ onResolve(item.id, SKIP);+ return;+ }+ const all = { ...answers };+ for (let i = step; i < specs.length; i++) {+ const k = keyFor(specs[i]);+ if (!(k in all)) all[k] = SKIP;+ }+ onResolve(item.id, JSON.stringify(all));+ };+return (<>{/* Stepper chips (grouped): "Chart style · 1 of 2 · Distribution ›" — ‹ steps back. */}@@ -326,6 +354,18 @@ function QuestionCard({{chip}{/* key={step} resets selection/text/hover state when the stepper advances */}<QuestionBlock key={step} spec={spec} onAnswer={submit} />+ {/* OPE-153: the way out. Always present — a card with exhaustive options and+ allow_text:false is exactly where the user would otherwise be stuck. */}+ <div className="flex items-center gap-1 mt-1.5" data-testid="question-skip">+ <button className={BTN_SKIP} onClick={skipStep}>+ {grouped ? t("inbox.skip_question") : t("inbox.skip")}+ </button>+ {grouped && step + 1 < specs.length && (+ <button className={BTN_SKIP} onClick={skipAll}>+ {t("inbox.skip_all")}+ </button>+ )}+ </div></>);}diff --git a/surfaces/gui/src/locales/en.json b/surfaces/gui/src/locales/en.jsonindex d7c3ca52..56a2caa4 100644--- a/surfaces/gui/src/locales/en.json+++ b/surfaces/gui/src/locales/en.json@@ -879,6 +879,9 @@"send_count": "Send ({{count}})","or_type_answer": "Or type your own answer…","your_answer": "Your answer…",+ "skip": "Skip",+ "skip_question": "Skip question",+ "skip_all": "Skip all","grant": "Grant","grant_no_folder": "Grant (no folder)","no_folder_suggested": "No folder was suggested",diff --git a/surfaces/gui/src/locales/zh.json b/surfaces/gui/src/locales/zh.jsonindex 0d2000fe..4c932360 100644--- a/surfaces/gui/src/locales/zh.json+++ b/surfaces/gui/src/locales/zh.json@@ -867,6 +867,9 @@"send_count": "发送 ({{count}})","or_type_answer": "或输入你自己的回答…","your_answer": "你的回答…",+ "skip": "跳过",+ "skip_question": "跳过此问题",+ "skip_all": "全部跳过","grant": "授权","grant_no_folder": "授权(无文件夹)","no_folder_suggested": "未建议文件夹",diff --git a/tests/test_ask_user_upgrades.py b/tests/test_ask_user_upgrades.pyindex f5a19b85..ba18808a 100644--- a/tests/test_ask_user_upgrades.py+++ b/tests/test_ask_user_upgrades.py@@ -11,6 +11,8 @@ from coworker.interactions import buttons_for, decodefrom coworker.server.manager import SessionManagerfrom coworker.tools.ask import (MAX_GROUPED_QUESTIONS,+ SKIP_NOTE,+ SKIP_SENTINEL,answer_result,ask_user_tool,normalize_option,@@ -112,6 +114,50 @@ def test_answer_result_shapes():assert answer_result(grouped, "") == {"answer": ""} # engine reads this as denied+# -- skipping (OPE-153) -------------------------------------------------------+++def test_skipped_single_question_answers_null_not_empty():+ """The whole point of the sentinel: "" (no answer came back) and a skip must not+ look alike to the agent."""+ res = answer_result([], SKIP_SENTINEL)+ assert res["answer"] is None+ assert res["skipped"] is True+ assert res["note"] == SKIP_NOTE+ assert answer_result([], "") == {"answer": ""} # unchanged, still not a skip+++def test_skipped_grouped_questions_name_what_was_declined():+ grouped = [{"question": "Chart style?", "header": "Chart"}, {"question": "Colors?"}]+ # one step skipped, one answered+ res = answer_result(grouped, json.dumps({"Chart": SKIP_SENTINEL, "Colors?": "Blue"}))+ assert res["answers"] == {"Chart": None, "Colors?": "Blue"}+ assert res["skipped"] == ["Chart"]+ assert res["note"] == SKIP_NOTE+ # whole card skipped from the card: every question carries the sentinel+ res = answer_result(grouped, json.dumps({"Chart": SKIP_SENTINEL, "Colors?": SKIP_SENTINEL}))+ assert res["answers"] == {"Chart": None, "Colors?": None}+ assert res["skipped"] == ["Chart", "Colors?"]+ # a JSON null means the same thing (defensive — a surface may serialize it that way)+ assert answer_result(grouped, json.dumps({"Chart": None}))["skipped"] == ["Chart"]+++def test_bare_sentinel_skips_a_whole_grouped_card():+ """A text-only surface can't send the answer map — the bare sentinel skips everything+ rather than being filed as the first question's answer."""+ grouped = [{"question": "Chart style?", "header": "Chart"}, {"question": "Colors?"}]+ res = answer_result(grouped, SKIP_SENTINEL)+ assert res["answers"] == {"Chart": None, "Colors?": None}+ assert res["skipped"] == ["Chart", "Colors?"]+++def test_fully_answered_card_carries_no_skip_keys():+ """No skip → no `skipped`/`note` noise in the agent's tool result."""+ grouped = [{"question": "Chart style?", "header": "Chart"}]+ assert answer_result(grouped, json.dumps({"Chart": "Bar"})) == {"answers": {"Chart": "Bar"}}+ assert answer_result([], "staging") == {"answer": "staging"}++# -- inbox persistence + back-compat ------------------------------------------