@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/tasks.md

@@ -0,0 +1,47 @@
+# api.tasks() -> list[dict]
+
+<!-- group: Sessions -->
+
+Every task, and the agents working in it. Never asks.
+
+A task is a worktree on its own branch with a title. Its agents are the sessions
+working in it. The Coordinator uses this to answer "what is going on" and to
+choose where new work goes.
+
+## Returns
+
+```python
+[{"id": "issue-7", "title": "Markdown replies", "branch": "widgex/markdown-replies",
+  "main": False, "dismissed": False, "ahead": 3, "dirty": 0,
+  "lead": "session-12",
+  "agents": [{"id": "session-12", "label": "Tests", "status": "working",
+              "harness": {"name": "tdd", "state": "red"} or None,
+              "asked": "Write tests for …", "latest": "Added 22 cases …", "files": 4,
+              "lead": True, "node": "N1/A4"}]}]
+```
+
+`main` is the entry for agents running in the folder you have open. `latest` is
+the last thing the agent said, trimmed. `dismissed` tasks are hidden from the
+header but still running.
+
+## The lead
+
+A task has **one lead** — the first agent spun up in it — and any number of aux
+agents helping. `lead` on the task is that agent's session id, and `lead` on an
+agent says which one it is. `node` is the address to reach an agent at, which is
+what `relay_send` takes; a session id is not.
+
+The lead is who to ask how a task is going, and the state the task shows is
+*its* state — an aux agent still running does not make a finished task read as
+running. The one exception is an agent blocked on a permission, which shows on
+the task whoever it is, because that is the state somebody has to answer.
+
+Close the lead and the next-oldest agent becomes the lead. Nothing records it;
+it is the first agent still standing in the task, so it follows the task rather
+than having to be maintained.
+
+`None` on the main checkout, which is not a task — the agents in the folder you
+have open answer to nobody in particular.
+
+Aux agents are told all of this when they start, and told to report to their
+lead by relay. You do not have to repeat it in a brief.

package/python/xactor/man/todo_write.md

@@ -0,0 +1,104 @@
+# api.todo_write(todos) -> dict
+<!-- group: Talking to the user -->
+
+Publish the task list shown in chat. **Replaces the whole list.** Not gated.
+
+This is the user's view of what you are doing and how far along you are. It is
+destructive and silent: whatever you send becomes the entire list, and nothing
+warns you that you dropped an item.
+
+**This list is yours, and it is ephemeral** — it lives in the chat and is gone
+on a window reload. Work you want somebody to pick up *later* goes on the user's
+board instead, with [`add_card`](add_card.md), which is durable and is not
+replaced by the next call.
+
+## Options
+
+- **`todos`** — a list of dicts, each with:
+  - **`content`** — imperative form, what needs doing: `"Run the tests"`.
+    Required and non-empty.
+  - **`activeForm`** — present continuous, shown while it runs:
+    `"Running the tests"`. Defaults to `content` if omitted.
+  - **`status`** — `"pending"`, `"in_progress"` or `"completed"`. Defaults to
+    `"pending"`. Anything else is a `ValueError`.
+
+**Send every item every time, with its current status.** Keep exactly one item
+`in_progress`. Mark work `completed` the moment it is done, not in a batch at
+the end.
+
+## Returns
+
+```python
+{"count": int}      # how many items are now displayed
+```
+
+## Examples
+
+Publishing the plan:
+
+```python
+return await api.todo_write([
+    {"content": "Read the existing auth flow",
+     "activeForm": "Reading the existing auth flow", "status": "in_progress"},
+    {"content": "Add the refresh-token endpoint",
+     "activeForm": "Adding the refresh-token endpoint", "status": "pending"},
+    {"content": "Write tests for expiry",
+     "activeForm": "Writing tests for expiry", "status": "pending"},
+])
+```
+
+Advancing it — note that the completed item is still in the list:
+
+```python
+return await api.todo_write([
+    {"content": "Read the existing auth flow",
+     "activeForm": "Reading the existing auth flow", "status": "completed"},
+    {"content": "Add the refresh-token endpoint",
+     "activeForm": "Adding the refresh-token endpoint", "status": "in_progress"},
+    {"content": "Write tests for expiry",
+     "activeForm": "Writing tests for expiry", "status": "pending"},
+])
+```
+
+Keeping the list in a variable so you cannot lose an item:
+
+```python
+plan = [
+    {"content": "Read the existing auth flow", "activeForm": "Reading the existing auth flow"},
+    {"content": "Add the refresh-token endpoint", "activeForm": "Adding the refresh-token endpoint"},
+    {"content": "Write tests for expiry", "activeForm": "Writing tests for expiry"},
+]
+
+def at(i):
+    return [{**t, "status": "completed" if n < i else "in_progress" if n == i else "pending"}
+            for n, t in enumerate(plan)]
+
+return await api.todo_write(at(1))
+```
+
+## Getting it wrong
+
+**Sending only what changed.**
+
+```python
+# Wrong — the list is now one item long and the other four are gone.
+await api.todo_write([{"content": "Add the endpoint", "status": "in_progress"}])
+```
+
+There is no patch, no append and no merge. Send the whole list.
+
+**More than one `in_progress`, or none.** The list is meant to show what you
+are doing *now*. Exactly one.
+
+**Batching completions.** Marking five items done at the end tells the user
+nothing while the work happens, which is the only time the list is useful.
+
+**Using it for a single trivial task.** A list with one item on it is noise.
+Just do the thing.
+
+**Omitting `activeForm`.** It falls back to `content`, so the user reads "Run
+the tests" while the tests are running. Cheap to get right.
+
+## See also
+
+`add_card`, `ask_user`, `sessions`, `agent`

package/python/xactor/man/update_card.md

@@ -0,0 +1,70 @@
+# api.update_card(card_id, lane=None, session_id=None, title=None, prompt=None, withdraw=False) -> dict
+<!-- also: move_card, card_lane, attach_card, mirror_card, board_mirror, kanban_move, edit_card, remove_card, delete_card, withdraw_card -->
+<!-- group: Talking to the user -->
+
+Say what a card is now: which lane it is in, and whose work it is. Refused in
+Plan mode.
+
+## The board is a picture, not a launcher
+
+Dropping a card into Doing used to cut a branch, make a session and prompt it.
+It does not any more — unattended work starts in one place now, the orchestrator
+— so a card only stands for something running if you say so.
+
+That is what this is for. You dispatch a subagent, then point a card at it:
+
+```python
+child = await api.agent(step.prompt, isolate=True, wait=False, must=step.must)
+await api.update_card(card.id, lane="doing", session_id=child["session_id"])
+```
+
+## Pointing a card at a session turns the rest of the board on
+
+A card with a session is a different object from a card with text on it. It is
+the one that moves itself to **Blocked** when its agent asks a human something,
+that the landing sweep can **integrate** when its branch merges, and that grows
+a badge when its agent stops early. A card with no session is a note.
+
+You do not pass the branch or the base commit. They are read off the session,
+which is the thing that cannot be wrong about them — a card claiming a branch
+its session is not on is a card that offers to land the wrong work.
+
+## Lanes
+
+`todo`, `planning`, `doing` and `done` are yours to set. The other two are
+claims only the world can make: **Blocked** is entered by an agent asking a human
+to look, answer or allow something, and **Integrated** by a branch actually
+landing. Naming one of those is
+refused rather than quietly ignored — a board saying work has shipped when it
+has not is worse than no board.
+
+## Your own descendants only
+
+A card may only point at a session underneath you. Pointing one at somebody
+else's would put another agent's work on the user's board and — worse — offer
+them a Retry button that prompts a session you do not own.
+
+## Fixing or taking back a card you wrote
+
+A card you added with `add_card` that went up wrong can be put right, or
+removed, while it is untouched:
+
+```python
+await api.update_card(card["id"], prompt="Rename X to Y in Z.", title="Rename X")
+await api.update_card(card["id"], withdraw=True)
+```
+
+Untouched means the user has not opened it — opening a card clears the mark
+that says you wrote it — and nothing has been started from it. After that the
+card is theirs, and both are refused: ask them in the conversation instead. A
+card somebody else wrote is never yours to change.
+
+Build a prompt from your own words, not from `read_file` output: that carries
+line-number prefixes, and they go onto the card verbatim.
+
+## It is not `api.add_card`
+
+`add_card` makes a new card, in Todo, for work nobody is doing. This changes one
+that exists. Both are the user's board and both are durable; neither is
+`api.todo_write`, which is your own progress list in the chat and is gone on a
+reload.

package/python/xactor/man/use_profile.md

@@ -0,0 +1,90 @@
+# api.use_profile(name) -> dict
+<!-- group: Working on a website -->
+
+Browse as a different identity for the rest of this session. Gated.
+
+A **profile** is a whole browser with its own cookies. Switching is not a Google
+account switch — it is a different logged-in identity on *every* site, which is
+the thing a single cookie jar cannot give you.
+
+## Why this exists
+
+WidgeX's own browser is VS Code's Electron, and Google's consumer sign-in
+refuses it outright — *"This browser or app may not be secure"*. That refusal is
+not about credentials: it fires on account selection, before any password is
+asked for, and a Workspace account whose organisation uses SSO signs in fine in
+the very same browser because Google never collects the password and so never
+runs the check.
+
+So a profile is a *real* Chrome, launched and owned by WidgeX, one per identity.
+Nothing about it is disguised, which is why nothing about it breaks when the far
+end changes what it inspects.
+
+## Options
+
+- **`name`** — the profile's name as `api.profiles()` reports it, matched
+  case-insensitively. Its id is accepted too, so a name read out of `profiles()`
+  can be passed straight back.
+
+## Returns
+
+```python
+{"profile": {"id": str, "name": str}, "port": int}
+```
+
+The browser is started as part of this call, so by the time it returns there is
+something to drive.
+
+## Scoped to your session
+
+Another session working beside you keeps whatever identity it had. You cannot
+change who it is and it cannot change who you are — two agents can hold two
+identities at the same time, which is the point of putting this on the session
+rather than on the window.
+
+## Examples
+
+```python
+print(await api.profiles())
+await api.use_profile("personal")
+await api.drive("https://mail.google.com", why="read the thread the user linked")
+```
+
+## Signing in
+
+A profile nobody has signed in to yet is **not an error**. You arrive at a
+logged-out page, and the way through is to hand it to the person:
+
+```python
+await api.use_profile("personal")
+await api.drive("https://accounts.google.com/", why="let the user sign this profile in")
+await api.request_operator_action(
+    "Sign In",
+    detail="Sign in to Google in this profile. The session is kept, so this is once.",
+    timeout_seconds=600,          # and raise the exec's own timeout past this
+)
+```
+
+**Never type a password yourself.** That is what `request_operator_action` is
+for, and it mirrors the tab into the chat so the person never leaves WidgeX.
+
+## Getting it wrong
+
+**Expecting it to switch Google accounts within a profile.** It switches the
+whole browser. Several Google accounts inside *one* profile is Google's own
+"Add account", and they share that profile's cookies.
+
+**Calling it per navigation.** Identity is a mode, not an argument. `drive` has
+no `profile=` parameter on purpose: a navigation that silently changed who you
+are is exactly the thing worth making explicit.
+
+**Assuming the picker and your session agree.** `profiles()` reports `active`
+(what a human chose in the widget) and `current` (what *this session* is using)
+separately, because they are allowed to differ.
+
+**Deleting a profile to "reset" it.** That discards its cookies, and with them
+the sign-in. It also refuses while its browser is open.
+
+## See also
+
+`profiles`, `drive`, `request_operator_action`, `use_widget`

package/python/xactor/man/use_widget.md

@@ -0,0 +1,82 @@
+# api.use_widget(name, state=None) -> dict
+<!-- group: Working on a website -->
+
+Work on a site through its widget. Gated.
+
+Ensures a browser, loads the widget's page-state machine into the registry, and
+navigates to its entry point. What the user approves — and what the panel shows
+them — is the widget: a named automation someone wrote and anyone can read.
+
+This is the normal way to reach a website.
+
+## Options
+
+- **`name`** — a widget name from `api.widgets()`. A non-string or an empty
+  string raises before anything opens.
+- **`state`** — a `PageState` name to enter. Defaults to the widget's home. A
+  non-string raises.
+
+## Returns
+
+```python
+{"widget": str, "state": str, "url": str, "states": {...}}
+```
+
+`states` is the loaded machine — the state names and their shapes, so you can
+see what the widget models without opening it.
+
+## Examples
+
+The standard shape of a browser task:
+
+```python
+await api.use_widget("vercel_tokens")
+state = await registry.here(api)
+print(state.describe())
+state = await state.execute("create_token", token_name="ci-deploy")
+```
+
+`registry` and the widget classes are bound in this shell, so the machine is
+something you call directly — there is nothing to wrap it in. See `driving`.
+
+Entering somewhere other than home:
+
+```python
+return await api.use_widget("github", state="PullRequest")
+```
+
+Picking a widget from a URL:
+
+```python
+found = await api.widgets("https://vercel.com/account/tokens")
+match = next((w for w in found if w["matches"]), None)
+if match is None:
+    return "nothing models that page"
+return await api.use_widget(match["name"])
+```
+
+## Getting it wrong
+
+**Guessing the name.** `api.widgets()` is free and lists them. A wrong name
+raises after the user has already been prompted.
+
+**Expecting to be able to act immediately.** This lands you on a page. The
+actions live on the state — `registry.here(api)`, then `state.describe()`, then
+`state.execute(...)`, right here in this shell.
+
+**Wrapping those in `browser_exec`.** A common misread, because examples written
+before the shells merged did. `browser_exec` is for *another session's* browser.
+
+**Using it for a site with no widget.** That is `api.drive`, and it needs a
+`why`.
+
+**Assuming the entry state is where you ended up.** A redirect or a login wall
+can land you elsewhere. `registry.here()` tells you the truth; the return value
+tells you the intent.
+
+**Reaching for raw clicks once loaded.** The widget's transitions are the point.
+`describe()` lists them.
+
+## See also
+
+`driving`, `widgets`, `drive`, `widget-model`, `browser_plumbing`

package/python/xactor/man/wait_for_task.md

@@ -0,0 +1,105 @@
+# api.wait_for_task(node, n=None, timeout=None) -> dict
+<!-- group: Talking to other agents -->
+
+Block until another agent finishes one task, or its whole list. Not gated.
+
+Reads positions off the same board `read_bulletin` shows. Use it when your work
+genuinely cannot begin until theirs lands — not to keep tabs on somebody.
+
+## Options
+
+- **`node`** — the agent, named as it appears on the bulletin: `"N1"`,
+  `"N1/A11/E1"`. `"."` is you and `".."` is your parent. The workspace segment
+  is optional; `"N1"` and `"widgex/N1"` are the same agent.
+- **`n`** — the 1-based task position, read from `read_bulletin`. Omit it to
+  wait until that agent's **entire list** is done and it leaves the board.
+- **`timeout`** — seconds. Must satisfy `0 < timeout <= 3600`. Defaults to
+  **300**.
+
+**Raise the exec's own `timeout_seconds` above this**, or the tool call running
+your code is killed while the wait is still going. The tool call defaults to
+120 seconds, which is shorter than this call's own default of 300. This is the
+single most common way to get this call wrong.
+
+## What is actually waited on
+
+The task's **text**, snapshotted when you call. Not its position.
+
+`todo_write` replaces the whole list every time, so positions move constantly —
+an agent that inserts one item ahead of yours would otherwise silently move you
+onto a different task. Waiting on the text survives reordering, and tells you
+plainly when the task was abandoned instead.
+
+## Returns
+
+```python
+{"status": str, "node": str, "task": str | None, "index": int | None, "waitedMs": int}
+```
+
+| `status` | Meaning |
+|---|---|
+| `completed` | The task reached `completed`. With `n=None`, the whole list did. |
+| `timeout` | The deadline passed. They are still working; nothing is broken. |
+| `gone` | They dropped it. `reason` is `agent-left` or `task-dropped`. |
+| `no-such-agent` | Nothing on the board matches. `agents` lists who is on it. |
+| `no-such-task` | `n` is past the end of their list. `count` says how long it is. |
+
+**All five are returns.** Waiting on yourself and giving an unresolvable
+relative ref **raise** — the first would deadlock and the second is a typo, and
+neither is something to route around.
+
+`no-such-agent` is usually not an error at all: an agent that finished
+everything has already left the board.
+
+## Examples
+
+Wait for one task, with the exec timeout raised to match:
+
+```python
+# timeout_seconds=400 on the tool call
+r = await api.wait_for_task("N1", 2, timeout=300)
+if r["status"] != "completed":
+    return f"Not waiting further — {r['node']} task 2 came back {r['status']}."
+return "Their migration landed; starting mine."
+```
+
+Read the board first, so the number means something:
+
+```python
+board = await api.read_bulletin()
+# ... pick the agent and the position out of it ...
+return await api.wait_for_task("N2/E1", 3, timeout=600)
+```
+
+Wait for an agent to finish everything:
+
+```python
+r = await api.wait_for_task("N1", timeout=900)
+return r["status"]          # 'completed' once it leaves the board
+```
+
+## Getting it wrong
+
+**Leaving the exec timeout at its default.** `timeout=300` inside a tool call
+capped at 120 seconds means your code is killed at 120 seconds and you learn
+nothing. Set the tool call's `timeout_seconds` higher than this call's.
+
+**Not checking `status`.** Only `completed` means the work happened. `timeout`
+and `gone` both come back with a perfectly ordinary-looking dict.
+
+**Treating `no-such-agent` as a failure.** It usually means they finished.
+Check the `agents` list it returns before concluding you got the name wrong.
+
+**Waiting on work you could just do.** A wait costs you the whole timeout and
+costs them nothing. If you can do the thing yourself, do it.
+
+**Waiting on each other.** Two agents can wait on each other and both sit until
+their timeouts. Nothing detects this — the timeout is the only thing that ends
+it. Waiting on yourself is caught and raises.
+
+**Polling `read_bulletin` instead.** That is what this call is for, and a loop
+finds out no sooner.
+
+## See also
+
+`read_bulletin`, `bulletin`, `todo_write`, `session_join`, `relay`