@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/instruct.md

@@ -0,0 +1,111 @@
+<!-- also: card, coach -->
+<!-- group: Talking to the user -->
+
+# api.instruct(text, target=None, expect=None, title="", step=None, total=None) -> dict
+
+Put a sentence in the app, beside a control when you name one.
+
+With a `target` the card is placed against that control with a pointer, and the
+control is ringed for you. Without one it takes a corner, which is right for
+"watch what happens next" and wrong for anything naming a button.
+
+Pass `text=None` to take it down.
+
+**Taking it down can hand you a question.** The card holds one typed while no
+wait was armed, so `{"status": "cleared", "asked": "…"}` means somebody asked
+while you were not listening and the demo ended before you answered. Say
+something rather than letting the tour be their answer.
+
+## Options
+
+- **`text`** — the instruction. Short and imperative: it sits beside a live app
+  and is skimmed, not read. **Name the control in the words as well as ringing
+  it** — the ring is dropped whenever the geometry cannot be proven, and a
+  sentence that leans on it breaks at exactly the moment the safety net fires.
+- **`target`** — what the card is about. Ringed, and the card is anchored to it.
+- **`expect`** — what they should see. Prose you are showing them; nothing
+  checks it.
+- **`title`** — the eyebrow above the instruction. Say "detour" here when a
+  question has taken you off the route you were on.
+- **`step`, `total`** — optional counter. Omit for a single instruction; pass
+  them when walking somebody through several and they will want to know how far
+  along they are.
+
+## Returns
+
+`{"status": "shown", "box": {...}}`, or `{"status": "shown", "unmarked": ...}`
+when the target could not be ringed — the card is still shown, and says why
+nothing is marked, because an instruction naming a control with nothing marked
+otherwise reads as the product being broken.
+
+**`unmarked` takes any previous ring down with it.** A card saying nothing could
+be marked, over a ring still framing the last step's control, is read as the
+ring. A step naming no target at all leaves the ring alone, so `highlight` then
+`instruct` still works.
+
+**`{"unraised": ...}` means they may not be looking at it.** The first step of a
+tour brings the app's window to the front, since a preview opens in its own
+window and that window is usually *behind* the one the chat is in. Where it
+cannot — a mirror has no window, and raising another process's is macOS-only —
+this field carries the sentence to pass on. Say it: an unraised window is a step
+running its whole timeout in front of nobody, reported afterwards as if they had
+ignored you.
+
+`{"error": ...}` means the step was **not drawn**, or was drawn where nobody can
+see it — under a modal, or off the edge of the viewport. Either way nobody is
+looking at anything. Do not carry on to the next step.
+
+A target that is scrolled out of view comes back as `unmarked` rather than an
+error: the words are still worth showing, the ring is not a claim that can be
+made, and the fix is yours — scroll it into view and instruct again.
+
+## Examples
+
+**A question is not answered with this call.** `reply` is, and the difference is
+the whole of why it exists: `instruct` *is* a new step — it moves the ring,
+resets the counter and replaces the words — so answering with it takes away the
+very sentence somebody was asking you to explain.
+
+```python
+r = await api.await_user(target)
+if q := r.get("asked"):
+    await api.reply("Claude Code advertises named methods, so we show them.")
+    r = await api.await_user(target)      # the same step, handed back
+```
+
+Use `instruct` when the answer really is somewhere else — a question is allowed
+to take the tour off course, and that is what `title="detour"` is for:
+
+```python
+    await api.instruct(
+        "That one installs the CLI — here it is.",
+        api.find(role="button", text_exact="Install"),
+        title="detour",
+    )
+```
+
+Say the words rather than moving the ring whenever both would do. A step that
+survives the question is a tour; a step replaced by its own answer is a script
+starting again.
+
+## Getting it wrong
+
+**Writing documentation.** The card clamps to two lines. Over about 140
+characters is not read, it is cropped.
+
+**An opening step that does nothing.** "Press Next to begin" is a step somebody
+has to dismiss. Start on the first real action.
+
+**Describing a screen you have not looked at.** Look at the app before you write
+each step. A step written ahead of time is a prediction, and the tour is guided
+live precisely so that it does not have to be one.
+
+**Demoing the mechanism.** Narrating how tours work, over an app doing something
+unrelated, demonstrates nothing. Point at the thing you changed.
+
+**Leaving it up.** `instruct(None)` and `highlight()` when you are done. A card
+outliving what it was about is how a finished tour reads as a broken one.
+
+## See also
+
+`reply`, `highlight`, `await_user`, `phase_complete`

package/python/xactor/man/ls.md

@@ -0,0 +1,63 @@
+# api.ls(path=None) -> list[dict]
+<!-- group: Coding -->
+
+List one directory. Not recursive. Not gated.
+
+## Options
+
+- **`path`** — directory to list. Absolute, or relative to the shell's cwd.
+  Defaults to the cwd.
+
+## Returns
+
+```python
+[{"name": str, "type": "dir" | "file", "size": int | None}, ...]
+```
+
+sorted by name. `name` is the bare entry name, not a path — join it to `path`
+yourself. `size` is bytes for files and **`None` for directories**.
+
+One degenerate shape: an unreadable directory returns
+`[{"error": "Permission denied: <path>"}]`, a normal return rather than a
+raise. A path that does not exist *does* raise `FileNotFoundError`, and a path
+that is a file raises `NotADirectoryError`.
+
+## Examples
+
+```python
+return await api.ls("src")
+```
+
+Just the subdirectories:
+
+```python
+entries = await api.ls()
+return [e["name"] for e in entries if e.get("type") == "dir"]
+```
+
+Finding the largest files in a directory:
+
+```python
+entries = await api.ls("dist")
+files = [e for e in entries if e["type"] == "file"]
+files.sort(key=lambda e: e["size"], reverse=True)
+return files[:5]
+```
+
+## Getting it wrong
+
+**Expecting recursion.** `ls` sees one level. Use `api.glob("**/*")` to walk a
+tree.
+
+**Sorting on `size` without filtering.** Directories carry `size: None`, and
+`None` in a numeric sort raises `TypeError`. Filter to `type == "file"` first.
+
+**Treating `name` as a path.** `api.read_file(e["name"])` resolves against the
+shell's cwd, not against the directory you listed. Join them, or `api.cd` first.
+
+**Using it to check existence.** It raises for a missing path. `api.glob` is
+the non-raising way to ask.
+
+## See also
+
+`glob`, `grep`, `cd`, `read_file`

package/python/xactor/man/man.md

@@ -0,0 +1,86 @@
+# api.man(topic=None) -> str
+<!-- group: Documentation -->
+
+The manual page for an api call or a WidgeX feature. Not gated.
+
+The tool description is an index of one-line glosses. This is where the options,
+the return shapes, and the ways each call is usually got wrong actually live.
+
+Reading a page costs one round trip. Guessing a return shape costs everything
+built on top of the guess.
+
+## Options
+
+- **`topic`** — an api call or feature name. Spelling is forgiving: `'bash'`,
+  `'api.bash'`, `'bash()'` and `'await api.bash'` all land on the same page, as
+  do `'session join'` and `'session_join'`. An unambiguous prefix resolves too,
+  so `'session_ext'` reaches `agent`. Omit it for the index of every
+  page.
+
+## Returns
+
+The page, as markdown, in a `str`. Not a dict — there is no `['text']` to index
+into.
+
+**A topic that matches nothing does not raise.** It comes back as prose naming
+the near misses:
+
+```
+No manual page for 'sesion_join'.
+Closest matches: session_join, session_rest, session_fork
+All topics: api.man() lists them.
+```
+
+This is deliberate. An exception would abort the whole exec and take the
+surrounding work with it, which would make guessing the cheaper strategy.
+
+## Examples
+
+Before the first use of a call:
+
+```python
+return await api.man("edit_file")
+```
+
+The full index:
+
+```python
+return await api.man()
+```
+
+Reading a page and carrying on in the same exec — safe, because a miss is a
+string:
+
+```python
+doc = await api.man("session_dae")      # resolves by prefix
+files = await api.glob("src/**/*.ts")
+return {"doc_len": len(doc), "files": len(files)}
+```
+
+A feature rather than a call:
+
+```python
+return await api.man("agent-vs-fork")
+```
+
+## Getting it wrong
+
+**Not calling it.** The tool description is one line per call. It is enough to
+know a call exists and roughly nothing else. The pages exist because the
+signature is not the contract.
+
+**Calling it after the mistake.** The page for `edit_file` is worth reading
+before the edit, not while explaining why the edit did not land.
+
+**Indexing the result.** It is a string. `(await api.man('bash'))['text']` is a
+`TypeError`.
+
+**Assuming a topic must be exact.** Prefixes and loose spellings resolve. If
+something genuinely does not exist, you get suggestions, not a failure.
+
+**Reading every page.** They are documentation, not context. Read the one you
+are about to use.
+
+## See also
+
+`overview`, `sandbox`, `permissions`

package/python/xactor/man/merge_wiz.md

@@ -0,0 +1,40 @@
+<!-- group: Talking to the user -->
+# api.merge_wiz(sources, target, pr) -> dict
+
+Propose a merge. A card asks the person, and **Proceed** opens the Merge Wizard already set up.
+
+```python
+r = await api.merge_wiz(["widgex/auth-tokens", "widgex/ui-theme"], target="main")
+if r["proceeded"]:
+    ...   # the wizard is open and theirs; carry on with something else
+elif r.get("denied"):
+    ...   # they pressed Abort: do not merge these any other way
+```
+
+The card is headed **Merge these branches?** It draws every source branch as a
+square name tag on the left, with arrows to the target's tag on the right:
+solid for a direct merge, dashed for a pull request. Two buttons, and an Ask.
+
+| Answer | Returns |
+|---|---|
+| Proceed | `{"proceeded": True}` |
+| Abort | `{"proceeded": False, "denied": True}` |
+| Ask | `{"proceeded": False, "asked": "<what they want to know>"}` |
+
+**Proceed starts nothing.** It opens the wizard with `sources[0]` on the left
+card, the rest under it, `target` on the right and the arrow on merge or pull
+request, with the plan drawn: for more than one source, the conflict groups.
+The person presses Start there, after reading it. So `proceeded` means "they
+took it from here", not "it is merged".
+
+**Abort is a no.** Do not merge those branches some other way, and do not ask
+again unless something has changed.
+
+- `sources` is a non-empty list of branch names, none repeated and none equal
+  to `target`. The host checks each one resolves to a commit and says which
+  does not, as a `ValueError` to fix and call again.
+- `target` defaults to `"main"`. `pr=True` sets the arrow to a pull request.
+- **It blocks** until they answer: raise the exec's `timeout_seconds` past a
+  few minutes. A card nobody answers expires, raising `RuntimeError`.
+- Refused in Plan mode. A merge proposed from a plan nobody has approved is a
+  merge nobody has approved.

package/python/xactor/man/notebook.md

@@ -0,0 +1,98 @@
+<!-- also: worked examples, refactor demo, non-visual, cells, show a function -->
+<!-- group: Talking to the user -->
+
+# api.notebook(title, cells, save=None) -> dict
+
+Worked examples, for a change with nothing to look at. **Requires permission.**
+
+## Why
+
+A walkthrough shows a feature by having somebody use it. A refactor, a type fix,
+a new pure function, a build script — none of them has a surface to mirror, and
+the standing advice for those is *"say what you did and stop"*. So the entire
+confirmation apparatus was missing exactly where the diff is hardest to read.
+
+This is the same idea through the terminal: a few concrete inputs, the real
+output each produced, in reading order. It writes `.widgex/notebooks/<slug>.md`,
+which is readable in the editor, in a pull request, and by somebody who has never
+heard of WidgeX. There is no viewer to open.
+
+## It is not a test run
+
+Writing it as one wastes it. *"31 tests passed"* tells a reader nothing about
+whether the thing does what they meant — it tells them the assertions somebody
+already wrote still hold.
+
+`flattenPrelude` called on a two-step route, with its actual output printed
+underneath, tells them whether the idea is right. That is the job: the same one a
+walkthrough does for a feature, and just as far from being a test suite. A
+walkthrough is not 100% coverage either; it is somebody being shown the point.
+
+Pick examples that would make a reviewer say *"ah, that's what it does"*.
+
+```python
+await api.notebook(
+    "How a prelude resolves a use: reference",
+    cells=[
+        {"note": "A route with two clickable steps, referenced by a feature "
+                 "walkthrough. The reference expands to both of its clicks.",
+         "run": "node -e \"...\""},
+        {"note": "Its third step is `advance: manual` — an instruction, not an "
+                 "action. Using it whole is refused, by name and with the "
+                 "`upto` to write instead.",
+         "run": "node -e \"...\""},
+    ],
+    save="prelude-resolution",
+)
+```
+
+## The commands run here
+
+That is why this call exists rather than you writing the markdown yourself. An
+agent can type `$ pnpm test` above the words "31 passed" without either having
+happened. Here the command line and the exit code are recorded by the host, the
+prose between them is yours, and the rendering keeps them apart — fenced,
+labelled output; unfenced commentary.
+
+A cell that exits non-zero is **kept and shown**. A worked example that fails is
+still a worked example, and a notebook that dropped them would be a highlight
+reel — the one shape this must not have, because a reader trusts it exactly as
+far as it shows what really happened.
+
+**Keep the command short.** A reader's eye has to get past it to reach the
+output, so a 400-character `node -e "..."` one-liner buries the thing you are
+trying to show. If the setup is long, put it in a small script and run that —
+the command line is there to make the output checkable, not to be the content.
+
+Each cell gets 120 seconds and its output is trimmed middle-out if it is very
+long, so the tail — the result, the last row, the traceback — survives.
+
+## Options
+
+- **`title`** — what these examples are showing, in one line.
+- **`cells`** — in order. Each is `{"run": "<command>", "note": "<why>"}`. The
+  `note` is the prose above the output: say what to look at, not what the command
+  is. A reader can see the command.
+- **`save`** — the slug to write. Defaults to a slug of the title.
+
+## Returns
+
+```python
+{"saved_to": ".../.widgex/notebooks/prelude-resolution.md",
+ "name": "prelude-resolution", "cells": 2, "failed": 0}
+```
+
+`failed` counts non-zero exits. They are in the document, not hidden.
+
+## Permission
+
+Gated, because it runs commands straight out of a model's output — which is what
+`api.bash` is gated for. That the commands are being recorded into a document a
+human will read does not make them safer to run.
+
+## See also
+
+- `api.request_review(claim, demo=…)` — hand it over when it is written
+- `api.instruct(...)` / `api.await_user(...)` — the equivalent for something
+  with a surface: a tour given live, decided step by step
+- `api.man('request_review')` — deciding what to raise for review at all

package/python/xactor/man/overview.md

@@ -0,0 +1,89 @@
+# The WidgeX api
+<!-- also: index, help, api, getting-started -->
+<!-- group: Concepts -->
+
+Everything is an `api.*` call inside one Python shell. Start here.
+
+There is one tool. Reading a file, running a command, asking the user a
+question, driving a website, spawning a session — all of it is a coroutine on
+`api`, awaited, in code you write. The tool description lists the calls in one
+line each; every one of them has a page.
+
+```python
+return await api.man("edit_file")
+```
+
+## The groups
+
+**Coding** — `read_file` `write_file` `edit_file` `bash` `glob` `grep` `ls` `cd`.
+The file calls are journalled and appear in the xylon diff; `bash` is not.
+
+**Talking to the user** — `ask_user` (a multiple-choice question, blocking),
+`request_user_action` (ask a human to do something you cannot), `todo_write`
+(the task list shown in chat).
+
+**Subagents** — `agent`. Blocks, returns a string, no session, no prompt.
+Underused.
+
+**Talking to other agents** — `read_bulletin` and `wait_for_task` for the shared
+task board; `relay_connect` `relay_send` `relay_inbox` `relay_accept`
+`relay_decline` `relay_close` for direct messaging. `force=True` on a connect is
+orchestration of a direct child and nothing else.
+
+**Sessions** — `agent` and `session_fork` create children;
+`session_join` waits; `session_terminate` stops one; `session_harness` and
+`session_rest` control unattended running.
+
+**Xylon** — `xylon_list_trees` `xylon_get_tree` `xylon_get_node`
+`xylon_read_messages` `xylon_get_diff`. Reads of the context tree.
+`xylon_search` finds past tasks by what was said in them and `xylon_read_turns`
+reads the turns around a hit — start there rather than with a whole transcript.
+
+**Working on a website** — `widgets` first, then `use_widget` or `drive`, and
+then act with the verbs on `api`: `outline` / `search` / `find` / `one` to
+locate, `click` / `type_text` / `select` to act, `drain` for one report of the
+whole chain. Actions queue — load a chain rather than awaiting each step. A
+widget's machine is `registry`, bound here too. See `driving`, then
+`finding`, `widget-model`, and `browser-driver` for handing a long session to a
+smaller model.
+
+**Reporting a WidgeX problem** — `report_bug`. For the IDE, not the project you
+are editing.
+
+**Documentation** — `man`.
+
+## Three rules
+
+1. **`await` everything.** Every api call is a coroutine.
+2. **`return` sends a value back.** Printing is not returning.
+3. **Only `api` reaches outside.** Imports, `open()` and direct `os.*` calls are
+   refused by the sandbox — see `sandbox`.
+
+## Gated calls
+
+Some calls interrupt the user for approval: `bash`, `write_file`, `edit_file`,
+`browser_exec`, `browser_screenshot`, `browser_snapshot`, `drive`, `use_widget`,
+`agent`, `session_fork`, `session_terminate`, `session_harness`. Which ones prompt, and what happens under a harness, is on
+the `permissions` page.
+
+## Getting it wrong
+
+**Treating the tool description as the documentation.** It is one line per call.
+The options, the return shapes and the failure modes are on the pages, and
+several calls fail *silently* if you guess — `edit_file` returns an error string
+rather than raising, `session_join` reports a crashed child as an empty answer,
+`todo_write` replaces the whole list.
+
+**Assuming an error will announce itself.** Several calls return a shape rather
+than raising. Read the "Returns" section before building on a result.
+
+**Reaching for `bash` for file work.** It is not journalled, so its changes are
+invisible to the tree and cannot be reverted. Use the file calls.
+
+**Spawning a session for something `agent` would answer.** See
+`agent-vs-fork`.
+
+## See also
+
+`man`, `sandbox`, `permissions`, `sessions`, `bulletin`, `relay`, `xylon`,
+`widget-model`, `agent-vs-fork`, `harness`

package/python/xactor/man/permissions.md

@@ -0,0 +1,137 @@
+# Permissions
+<!-- group: Concepts -->
+
+Which calls interrupt the user, and how a refusal reaches you.
+
+Permission is enforced per api call, not per exec. The user approves *this
+write to this path*, not "a block of Python that could do anything". That is
+the reason there is one tool and everything is an `api.*` call.
+
+## The gated calls
+
+```
+write_file  edit_file  bash
+session_fork  session_terminate  session_harness
+use_widget  drive  use_profile  notebook
+browser_open_tab  browser_exec  browser_snapshot  browser_screenshot
+attach_app  attach_ide_surface
+```
+
+Everything else runs without asking, including all reads (`read_file`, `glob`,
+`grep`, `ls`), all of `xylon_*`, `widgets`, `todo_write`, `session_join`,
+`session_rest`, `report_bug` and `man`.
+
+**`agent` is the one call that is gated or not depending on how you call it.**
+A waited subagent in your own tree — `api.agent(prompt)` — is bounded, runs in
+your shell and is gone when it returns, and does not ask. Every other shape
+leaves something running that acts on its own, and each of those asks:
+
+```
+api.agent(prompt)                  # no prompt — waited, shared tree
+api.agent(prompt, wait=False)      # asks — outlives this call
+api.agent(prompt, isolate=True)    # asks — its own worktree
+api.agent(prompt, raise_=True)     # asks — an Issue is durable by design
+```
+
+Two of the gated calls deserve a note on *why*:
+
+- **`use_widget` / `drive`** gate reaching a site at all, not just running
+  code on it. Which of the two you call is itself the declaration — a named
+  automation, or an admission that there is none.
+- **`browser_snapshot` / `browser_screenshot`** are gated because a snapshot
+  carries the page's cookies and a screenshot captures whatever the human left
+  signed in.
+
+`widgets()` is deliberately *not* gated: listing what is installed opens
+nothing and reveals nothing.
+
+## Plan mode
+
+Plan mode is read-only, and it does not ask — it **refuses**. Nothing you do
+while planning raises a card except `ExitPlanMode` itself.
+
+So the gated list above is not the list that matters here. A different and
+smaller set runs: reads (`read_file`, `glob`, `grep`, `ls`, `man`), the
+page-reading verbs (`search`, `outline`, `one`, `snapshot`, `digest`), the
+`xylon_*` tree, relay and the bulletin, `ask_user`, `ask_model`, `todo_write`,
+`report_bug`, `add_card`, and a waited `api.agent(...)` — which is itself
+plan-constrained, so research subagents work and writing ones do not.
+
+Everything else refuses, including calls that are ungated in every other mode:
+`bash_kill`, `cd`, `evaluate`, `screenshot`, the `request_*` family, and the
+browser action verbs (`click`, `type_text`, `press`, `navigate`, …).
+
+A refusal is not a decision you can change by asking again — it is the mode,
+and every alternative spelling of the same action gets the same answer. Write
+the plan and call `ExitPlanMode`; the user approves it, the mode changes, and
+the call runs.
+
+Because a refusal raises, it aborts the exec like any other — so batching a
+read and an action together loses the read. While planning, keep the reads in
+their own exec.
+
+## How a refusal arrives
+
+A declined call raises `PermissionError`:
+
+```
+Permission denied for bash(): the user declined this operation
+```
+
+Because it raises, **it aborts the whole exec**. Everything after that line in
+the same block does not run. That is the main practical consequence: a long
+script with a gated call in the middle loses the work below it if the user says
+no.
+
+The validator for a call runs *before* the prompt, so the user is never asked
+to approve something that could not have worked. A bad argument gives you a
+`ValueError` naming the fix, with no interruption to anyone.
+
+## Examples
+
+Keep the ungated work out of the gated exec's blast radius:
+
+```python
+# One exec: gather everything first, cheaply and without prompting.
+hits = await api.grep(r"TODO", path="src", glob_filter="*.ts")
+return hits
+```
+
+```python
+# A second exec: now spend the user's attention, once, on the change itself.
+r = await api.edit_file("src/app.ts", "// TODO: cache", "const cache = new Map();")
+return r
+```
+
+Treating a refusal as an instruction rather than an error:
+
+```python
+try:
+    out = await api.bash("pnpm test")
+except PermissionError:
+    return "You declined the test run — tell me if you'd rather run it yourself."
+return out["stdout"][-2000:]
+```
+
+## Getting it wrong
+
+**Batching ten gated calls into one exec.** Each one prompts separately, so the
+user gets ten dialogs, and a refusal on the third throws away the seven below
+it. Group ungated reads together; keep gated writes deliberate.
+
+**Retrying a declined call.** A decline is the user's decision, not a transient
+failure. Take the refusal, and any note attached to it, as an instruction.
+
+**Assuming permission was the failure.** `edit_file` returns `Error:` strings
+for its own failures and only raises for a decline — see `man('edit_file')`. A
+`PermissionError` means the user said no; an `Error:` return means the edit did
+not match.
+
+**Expecting a prompt in a harness.** A harness runs unattended and never
+prompts. Gated calls there are decided by its grants: auto-allowed or
+auto-denied, with no human in the loop. `ask_user` is refused outright. See
+`man('harness')`.
+
+## See also
+
+`sandbox`, `edit_file`, `bash`, `harness`, `ask_user`