@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/request_merge_decisions.md

@@ -0,0 +1,121 @@
+# api.request_merge_decisions(source_branch, target_ref, ambiguities, resolved=None, timeout_seconds=3600) -> dict
+
+<!-- also: merge_decisions, merge_board, resolve_merge, merge_conflicts, conflicts -->
+<!-- group: Talking to the user -->
+
+Ask the user which features to keep, where a merge is genuinely ambiguous.
+
+You are standing in a working copy with a conflicted rebase in it. Most of what
+git stopped on, you can settle: an import both sides added, a rename on one side
+against an edit on the other, two formattings of the same block. Some of it you
+cannot, because both sides implemented the same thing differently and keeping
+the wrong one silently loses somebody's work.
+
+This is for that second kind. The user gets a board — your branch's features
+down the left, the target's down the right, and an **include** column in the
+middle they drag into.
+
+**It blocks**, and the default timeout is an hour. They are reading a diff's
+worth of consequence, not dismissing a dialog.
+
+## The shape that matters
+
+```python
+r = await api.request_merge_decisions(
+    source_branch="widgex/merge_flow_fix",
+    target_ref="origin/main",
+    resolved=[
+        {"path": "src/config.ts",
+         "summary": "Both added an unrelated field; kept both."},
+    ],
+    ambiguities=[{
+        "id": "discovery",
+        "question": "How model discovery decides a runtime is reachable.",
+        "choices": [
+            {"id": "discovery-branch", "side": "branch",
+             "title": "Ollama discovery over fetch",
+             "detail": "Probes with a fetch stub, so the suite needs no socket. "
+                       "Loses the shared timeout the target side applies.",
+             "paths": ["src/providers/ollamaDiscovery.ts"]},
+            {"id": "discovery-target", "side": "target",
+             "title": "Discovery through the shared probe",
+             "detail": "Routes every runtime through one prober, so timeouts are "
+                       "uniform. Opens a real socket, which CI has no route for.",
+             "paths": ["src/providers/ollamaDiscovery.ts", "src/providers/probe.ts"]},
+        ],
+    }],
+    timeout_seconds=3600,
+)
+
+if r["outcome"] == "submitted":
+    print(r["instructions"])   # ← act on this
+```
+
+Run it with `widgex_terminal(code=..., timeout_seconds=3900)`. The tool's clock
+and the exec's are separate, and both have to outlast the person.
+
+## Ask about as little as possible
+
+A card is a **fork in the road**, not a conflict marker. If you can work out the
+right answer, that is not an ambiguity — resolve it, list it under `resolved`,
+and do not put it on the board.
+
+Calling this with an empty `ambiguities` is refused, and the refusal says to
+continue rather than to retry, because at that point you are finished.
+
+The counter-failure is worse, though, and it is the one to watch for: settling
+something you should have asked about. Two implementations of one feature, a
+behaviour the user chose deliberately on one side, anything where you find
+yourself reasoning about what they *probably* wanted — that is a card.
+
+## They can include both, and usually will
+
+Two cards in the middle is not a contradiction for you to resolve by picking
+one. It is an instruction to **weave both features together** in the resolved
+file. Order in the middle column is precedence, for wherever they genuinely
+collide on the same lines.
+
+`instructions` says this in words. Read it rather than inferring from
+`decisions`, which carries the same answer as bare choice ids.
+
+## Options
+
+- **`source_branch`** — the branch being replayed. `"widgex/merge_flow_fix"`.
+- **`target_ref`** — what it is being replayed onto. `"origin/main"`.
+- **`ambiguities`** — one per fork in the road:
+  - **`id`** — unique across the board.
+  - **`question`** — one line on what is actually in doubt.
+  - **`choices`** — at least two. One choice is not a question.
+    - **`id`** — unique within its ambiguity. This is what a drop carries.
+    - **`side`** — `"branch"` or `"target"`, which column it starts in.
+    - **`title`** — the feature, named. "Ollama model discovery".
+    - **`detail`** — what this side does here **and how it differs from the
+      other side**. This is the entire reason a card beats a merge editor.
+      "Keeps the old behaviour" tells them nothing.
+    - **`paths`** — files it touches. Never empty.
+- **`resolved`** — `[{"path", "summary"}]` for what you settled alone. Shown
+  read-only at the bottom of the board. A merge that silently decided seven
+  things and displayed none of them is one nobody can audit.
+- **`timeout_seconds`** — how long to wait.
+
+## What comes back
+
+- **`submitted`** — they answered. `instructions` is prose naming each feature
+  they included, which branch it came from, its files, and the precedence order.
+  `decisions` is the same as raw ids.
+- **`asked`** — they want something from you before they can decide, in `note`.
+  Answer it and ask again.
+- **`declined`** — they would rather do it by hand. Leave the conflict markers
+  alone and say so.
+
+`ValueError` means the board was malformed and the message says what to fix.
+Repair it and call again — do **not** fall back to resolving the ambiguity
+yourself, which is the one thing the user asked to decide.
+
+`RuntimeError` means nobody answered in time. The markers are untouched.
+
+## Related
+
+`phase_complete` hands over a judgement about work already done;
+`request_user_action` hands over work you cannot do. This hands over a
+**choice**, and is the only one of the three that comes back with a payload.

package/python/xactor/man/request_operator_action.md

@@ -0,0 +1,152 @@
+# api.request_operator_action(action, detail=None, timeout_seconds=600) -> dict
+<!-- also: operator, operator-action, handoff, hand-over, verification, verify, does-it-work -->
+<!-- group: Talking to the user -->
+
+Hand the user a step on the page you are already on. **Does not block. Not
+gated.**
+
+`request_user_action` points at a `url` and trusts the user to go there. This is
+about the page **your session is driving** — an app window or a browser tab
+alike, with your cookies and your login state, and the step is one they take in
+place.
+
+## It does not block, and that changed what "in place" means
+
+Your turn finishes; the request waits as a row in the user's inbox.
+
+It used to draw the card into the driven tab at the moment you asked, which was
+only possible because you were standing there holding the page open. You are
+not any more — so the card moves to where the user is, and **opening the row
+wakes you** to bring the page back up and walk them through it with
+`api.instruct` / `api.await_user`.
+
+**When you are driving a browser tab, the card links to it.** The tab you are on
+is handed to the user: its Open button brings that page up exactly as you left
+it — a form you filled in stays filled in — and opening it wakes nobody, because
+there is nothing for you to do until they press Done. You will not navigate that
+tab again, and it stays open after you finish. So fill in everything you can
+first, and hand over only the step that is theirs: Submit, a sign-in, a CAPTCHA.
+
+With no tab — an attached app, say — the old behaviour holds, below.
+
+That wake is now the whole difference between this verb and
+`request_user_action`. A user action carries a url and is worth answering with
+you long gone; this one is worth nothing without you, so opening it fetches you.
+Pick accordingly: the wrong one here costs the user either a turn they did not
+need or a row nobody can act on.
+
+Say everything the next you will need in `detail`, and end the turn:
+
+```python
+await api.drive("https://console.example.com/login", why="sign in to read the keys")
+await api.request_operator_action(
+    "Sign In",
+    detail="Sign in with your own account. I'll read the API key names once "
+           "you're in — I won't see your password. Say so if you'd rather not.",
+)
+return "Handed you the console sign-in; nothing else needs doing until it's done."
+```
+
+Writing the rest of the turn as though the step were already taken is the way
+this goes wrong. **Look at the page** when you are woken — `done` means they
+pressed Done, not that the thing you wanted happened.
+
+## When to use it
+
+For what you cannot do and should not try to:
+
+- signing in, including 2FA and passkeys
+- clearing a CAPTCHA or a bot check
+- choosing between accounts or organisations
+- anything at all involving the user's own credentials
+
+**Never type a password yourself.** Not from an env var, not from something you
+found on disk. Hand the page over and let the person type it.
+
+### Asking whether something you built works
+
+Outside a phase, this is also how to hand back a change somebody can see. Drive
+to where it can be tried, then make `action` the thing to try and `detail` what
+they should see:
+
+```python
+await api.request_operator_action(
+    "Type a draft, reload, check it is still there",
+    detail="Drafts should now save on their own. Done if the text survives the "
+           "reload; Can't do this, with what you saw, if it does not.",
+)
+```
+
+**declined** with a note is the answer you asked for, not a failure: read it,
+fix what it says, and ask again. Inside a phase, the lead asks with
+[`phase_complete`](phase.md) instead — one review card for the whole phase.
+
+## Options
+
+- **`action`** — the label on the button. Imperative and short: `"Sign In"`.
+  Over 60 characters is rejected; the explanation goes in `detail`.
+- **`detail`** — one line on what to do and what happens next. The user is
+  choosing between finishing, giving up and asking you something, so say what
+  each will mean — and say it for a reader who was not here, because this is all
+  the next you will have.
+- **`timeout_seconds`** — **accepted and ignored.** A row that outlives the turn
+  that made it has nothing to time out of. Still accepted, and still validated
+  as a positive integer, so existing callers keep working.
+
+There is no `url`: the page is the one your browser is already on, so navigate
+there *before* handing over. That absence is not an oversight — it is why this
+row needs you back and the other one does not.
+
+## Returns
+
+```python
+{"status": "queued", "id": "inbox-1757280000000-a1b2c3"}
+```
+
+A **receipt, not an answer**. `id` is the row it left behind.
+
+The answer arrives later, as a prompt:
+
+- **done** — they finished. Look at the page before assuming what state it is
+  in; they may have landed somewhere you did not expect.
+- **declined** — they aborted. An answer to route around, not an error.
+- **asked** — they want something from you before they can finish. Answer it,
+  then ask again.
+
+## Getting it wrong
+
+**Branching on the return value.** `{"status": "queued"}` means the row was
+filed. There is no `outcome` key, and `r["outcome"]` raises `KeyError`.
+
+**Treating `done` as "the thing I wanted happened".** It means they pressed
+Done. Check the page.
+
+**Treating `declined` as an error.** It is an answer. Route around it and say
+what you are doing instead.
+
+**Handing over a page you have not navigated to.** There is no `url`. Whatever
+your session's browser is on is what they get — and it is what you will be
+brought back to when they open the row.
+
+**Drawing a step blind when you are woken.** The app may be gone by then. If you
+cannot attach, say so plainly rather than instructing them about a screen you
+cannot see; the inbox draws "getting ready…" until you have actually put
+something up, and silence is what that state is for.
+
+**Using it for a question.** If you only need words, that is `request_answer`,
+or `ask_user` when it has to be answered now. This costs the user a page to work
+through.
+
+**Typing the password yourself.** The reason this tool exists.
+
+**Raising the exec's timeout to cover it.** There is nothing to cover — the call
+returns at once. This used to be the mistake that wasted the most of the user's
+time on this page, and it no longer exists.
+
+## See also
+
+`request_user_action` — the same handoff for a page the user can reach alone,
+which wakes nobody.
+
+`request_answer`, `ask_user`, `drive`, `use_widget`, `browser_tabs`,
+`permissions`

package/python/xactor/man/request_review.md

@@ -0,0 +1,122 @@
+<!-- also: review, ready, done, hand back, finished, call for review -->
+<!-- group: Talking to the user -->
+
+# api.request_review(claim, demo=None, covers=None, missing=None) -> dict
+
+Say this is ready to be looked at, and carry on. **Does not block. Not gated.**
+
+## Why this exists
+
+Every way of reaching the user used to hold your turn open until they answered.
+`walkthrough` blocked. `request_user_action` blocked. So there was no way to say *"I have finished and built you a demo"*
+that was not also the way to say *"I am stuck and cannot proceed"* — and the
+second one is louder. An agent that finished cleanly was **less** visible than
+one that got stuck, because the stuck one held a row in the queue and the
+finished one dropped into a list of git diffs at the bottom of the board.
+
+This was the first call to do it the other way, and the argument it won has
+since been applied to the handoffs themselves: `request_user_action`,
+`request_operator_action` and `request_answer` all file
+a row and return now. `walkthrough` and `ask_user` are what still block, and
+they block because somebody is watching.
+
+It leaves a row behind, bound to your branch, and returns immediately. Nothing
+expires and nothing is waiting on you. End your turn straight afterwards; end
+the session. The request waits.
+
+**This is how a parallel agent hands work back.** Eight sessions finishing
+overnight cannot each block a turn on a human who is asleep.
+
+## The shape
+
+```python
+await api.attach_app(surface="panel", env="fresh", reach="install-and-sign-in")
+# ... build it, drive it, save a walkthrough of it ...
+
+await api.request_review(
+    claim="The provider picker opens from the row and remembers your choice.",
+    demo="provider-setup",
+    covers=["opens-from-row", "survives-restart"],
+    missing=["useful message when no CLI is installed"],
+)
+return "Done — raised for review."
+```
+
+## Options
+
+- **`claim`** — one sentence on what is now true, **in the user's terms**. This
+  is the headline of a row read at a glance beside seven others, so it has to
+  survive being skimmed by somebody who has not read your transcript and is not
+  going to. "Drafts now save automatically", not "added a debounced `useEffect`
+  to `NoteEditor`". Under 200 characters. If the sentence names a file or a
+  function, rewrite it.
+
+- **`demo`** — the **name of a saved notebook** (`api.notebook(title, cells,
+  save=True)`, kept under `.widgex/notebooks/`), never the demo text itself.
+  Walkthrough scripts are retired. It becomes the row's **Watch** button, the
+  shortest path from "an agent claims X" to a human seeing X happen. No file to
+  name? Leave `demo` out.
+
+  A name that does not exist is refused **now**, with the list of ones that do.
+  That is deliberate — this row outlives you, so a typo discovered at reading
+  time is discovered by somebody with no agent left to ask.
+
+- **`covers`** — the obligations you are claiming to have met.
+
+- **`missing`** — the obligations you did **not** meet. **Say them.** They are
+  shown plainly, with no alarm styling, and they sort your row *up* rather than
+  down. An agent that did three of four things and reports the fourth is worth
+  more than one that reports four, and this field is designed to cost you
+  nothing for saying so: a queue that punished honesty would stop receiving it.
+
+## Returns
+
+```python
+{"raised": True, "id": "9f2c1a0b3e44", "branch": "feat/provider-picker",
+ "demo": "provider-setup", "covers": [...], "missing": [...]}
+```
+
+`id` is stable for one claim on one branch. Raising the same claim again after a
+fix **updates** that row rather than adding a second one saying almost the same
+thing — eight agents each leaving three near-duplicates is how a queue stops
+being read.
+
+## Choosing between this and asking for a verdict
+
+| | |
+|---|---|
+| `request_review` | "Here is what I built. Look when you like." One row, no single claim to judge. |
+| `phase_complete` | "I have finished the phase." A review card in your chat — Approve or Needs changes — and the answer prompts you back. Task leads, inside a phase. |
+| `walkthrough` | "Let me show you, step by step, while you use it." **Blocks** for as long as a person takes. |
+
+Neither is replaced and neither is discouraged. Both of the first two return at
+once now, so the choice between them is no longer about your turn — it is about
+whether you lead a task with a phase to close. Use `walkthrough`
+when you want to sit with somebody while they try it, which is the one of the
+three that genuinely needs you present.
+
+## Getting it wrong
+
+**Raising one with no demo and no claim worth reading.** A row saying "finished
+the task" is a row that gets skipped, and the work behind it waits longer than
+if you had said nothing. If there is genuinely nothing to look at — a refactor,
+a type fix, a build script — say what you did in your reply and do not raise
+one; a queue padded with rows nobody can act on is worse than a short queue.
+
+**Asking twice.** Calling `phase_complete` and then this, for the same
+change, puts two rows in front of somebody for one piece of work.
+
+**Omitting `missing` because it looks bad.** It is the field a manager most
+wants and the one you are least inclined to write. Nothing in the row punishes
+it.
+
+## See also
+
+- `api.instruct(...)` / `api.await_user(...)` — giving the demo itself.
+  There is no file to save: a tour is decided as it is given, so `demo=`
+  names a notebook or nothing.
+- `api.man('attach_app')` — `reach=`, and getting the app to the state a demo starts from
+- `api.phase_complete(...)` — when you lead a task and its phase is done. It does
+  not block either; the review prompts you back.
+- `api.request_operator_action(...)` — when you need somebody's hand on the page
+  you are driving rather than an opinion on a branch.

package/python/xactor/man/request_user_action.md

@@ -0,0 +1,126 @@
+# api.request_user_action(action, detail=None, url=None, timeout_seconds=600) -> dict
+<!-- group: Talking to the user -->
+
+Hand a GUI task to the human, to do when they get to it. **Does not block. Not
+gated.**
+
+For the things you cannot do yourself: signing in, clearing a CAPTCHA,
+completing 2FA, approving something in a vendor's own dashboard. The request
+appears as a row in the user's inbox carrying the `url`, and they go and do it
+whenever they reach it.
+
+## It does not block
+
+Your turn finishes. The row waits, and nothing expires. When they answer, you
+are prompted with what they said and carry on from there.
+
+So the call is the **end** of a turn, not a pause in the middle of one. Say what
+you are waiting on and stop:
+
+```python
+await api.request_user_action(
+    "Log in to Vercel",
+    detail="I need an authenticated session to create the deploy token. "
+           "If you decline I'll write the steps out for you to run by hand.",
+    url="https://vercel.com/login",
+)
+return "Asked for a Vercel login — everything that does not need one is done."
+```
+
+Writing the rest of the turn as though the answer were in hand is the way this
+goes wrong. There is no outcome in the return value and there will not be one
+before your turn ends.
+
+## It wakes nobody, and `url` is what pays for that
+
+Opening this row starts no turn. It does not have to: the row says where the
+work is, so it is still worth answering days later, with this session long gone.
+
+That is the whole difference from `request_operator_action`, which is about the
+page **your** browser is on and therefore has no url to give — opening one of
+those wakes you to bring the page back up and walk them through it. Neither
+draws a card at send time any more, so this is the distinction between them,
+and picking the wrong verb costs the user either a turn they did not need or a
+row they cannot act on.
+
+## Options
+
+- **`action`** — the label on a button. Imperative and **under 60 characters**:
+  `"Log In"`, `"Approve the deploy"`. Longer is rejected with a `ValueError`
+  telling you to move the explanation into `detail`.
+- **`detail`** — one line on why it is needed and what happens next. Say what
+  each outcome will mean, because the user is choosing between them. This is
+  **the whole of what the next you will know**, so write it for somebody who was
+  not here — it will be read after a compaction, quite possibly by a session
+  that has no memory of asking.
+- **`url`** — `http`/`https` only. Where the work happens. Defaults to the page
+  this session's browser is already on.
+- **`timeout_seconds`** — **accepted and ignored.** A row that outlives the turn
+  that made it has nothing to time out of; it sits in the inbox until it is
+  answered or deleted. Still accepted, and still validated as a positive
+  integer, so existing callers keep working.
+
+## Returns
+
+```python
+{"status": "queued", "id": "inbox-1757280000000-a1b2c3"}
+```
+
+A **receipt, not an answer**. `id` is the row it left behind. Nothing in this
+dict says what the user did, because at the moment it returns they have not seen
+it.
+
+Declining is an ordinary answer, not an error. It arrives as a prompt like any
+other, which is why `detail` has to say what you will do with each outcome.
+
+## Getting it wrong
+
+**Branching on the return value.** `{"status": "queued"}` means the request was
+filed, not done. There is no `outcome` key to read.
+
+```python
+# Wrong — `outcome` is not in this dict, and would not be true if it were.
+r = await api.request_user_action("Log In")
+if r["outcome"] == "done":
+    ...
+
+# Right — file it and end the turn. You are prompted when they answer.
+await api.request_user_action("Log In", detail="I'll read the API key names once you're in.")
+return "Waiting on the Vercel login."
+```
+
+**Putting the explanation in `action`.** Anything over 60 characters is
+rejected outright. The button says `"Log In"`; `detail` says why.
+
+**Writing `detail` for yourself.** You will not read it. The next session will,
+with none of your context, possibly next week.
+
+**Using it for a decision.** If you want the user to *choose*, that is
+`request_answer` — or `ask_user` when you need the answer before the next line
+of code runs. This call is for work only they can perform.
+
+**Using it while you are driving something.** This points at a page and trusts
+the user to go there, which is right when the work is on a site you are not
+attached to and wrong the moment you have a surface open — they get a link and
+have to work out for themselves which of the things on their screen you meant.
+Use `request_operator_action`, which brings you back to show them.
+
+```python
+await api.attach_app(surface='chat', env='fresh')
+# Not this: the user gets a link, and nobody to show them anything.
+#   await api.request_user_action("Sign in")
+await api.request_operator_action("Sign in")
+```
+
+**Raising the exec's timeout to cover it.** There is nothing to cover. The call
+returns at once, so the tool call's own `timeout_seconds` is irrelevant here —
+this used to be the commonest mistake on this page and it no longer exists.
+
+## See also
+
+`request_operator_action` — the same handoff for the page you are driving, which
+wakes you to guide them when they open it.
+
+`request_answer` — a decision rather than a task, on the same non-blocking shape.
+
+`ask_user`, `use_widget`, `drive`, `browser_screenshot`, `harness`

package/python/xactor/man/return_card.md

@@ -0,0 +1,71 @@
+# api.return_card(card_id, finding) -> dict
+
+<!-- also: reject_card, send_back, adjudicate, refuse_submission, bounce_card -->
+<!-- group: Talking to the user -->
+
+Send a submission back, saying what is missing. Refused in Plan mode.
+
+## Why a submission is adjudicated at all
+
+An agent asking for review is making a claim about its own work. The
+claimant is not the judge, so a claim reaches a human only once something else
+has looked at it — and that something is you.
+
+This is how you refuse one. The card goes back to **Doing**, your finding is
+recorded on it, and the agent is woken with it.
+
+```python
+await api.return_card(card.id, "The empty-list case has no test, and the claim says it does.")
+```
+
+## The same path a human's rejection takes
+
+A human asking for changes on a review does exactly this: the note joins the
+card's findings, the card returns to Doing, and the next turn reads it back.
+Deliberately one mechanism. Two would teach an agent that one of them is the
+softer one, and it would be right.
+
+## Say what is missing, not that something is
+
+> "No test covers the empty case" is a finding.
+> "Not done yet" is a delay.
+
+The agent reads this on its next turn and acts on it. A finding it cannot act on
+costs it a turn to discover that, and costs the task's budget the same as a real
+one.
+
+## Findings accumulate, and that is the specification
+
+Nothing is written in advance. There is no checklist, and a card carries only
+the text a human wrote on it — so the standard for "done" is built out of what
+adjudication has actually found wanting, in order.
+
+That list does three things at once:
+
+- the **agent** is told what is still outstanding, specifically,
+- **you** can see what you have already demanded, which is what stops you
+  contradicting yourself on the next pass,
+- a **human** reading the card sees why it is on its third attempt.
+
+## Not gated, unlike `session_nudge`
+
+Both wake somebody else and spend their tokens, so the difference is worth
+knowing. `session_nudge` can wake any descendant at any moment. This can only
+wake a session that has already asked to be judged and is sitting in Verify
+waiting for an answer — the consequence is bounded by the thing that invited it,
+and the task's budget ceiling bounds it again.
+
+## Arguments
+
+- **`card_id`** — the card, as `tasks()` and `add_card` report it.
+- **`finding`** — what is missing. Required, and refused when empty: a card sent
+  back with nothing to act on is a turn spent for nothing.
+
+## Returns
+
+`{ id, lane, returned }`
+
+## See also
+
+`api.man('update_card')` for moving a card between the lanes a human may set,
+and `api.man('add_card')` for putting one on the board.