@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/phase.md

@@ -0,0 +1,150 @@
+# Phases — phase / open / add / abort / delegate / verify
+<!-- also: phase_open, phase_add_step, phase_abort_step, delegate_steps, phase_complete, phases, steps -->
+<!-- group: Sessions -->
+
+A task's work is split into **phases**, worked in order: alpha, beta, gamma and
+on. Only one is current. A phase is a contract:
+
+- a **design document** — the feature spec the phase is verified against, kept
+  in the task's folder as `phases/<name>/plan.md`;
+- the **files** that came with it (images, mockups), copied into
+  `phases/<name>/files/` — open them by path;
+- a **lead**, the task's lead unless it says otherwise;
+- a list of **steps**: one or two sentences each, numbered within the phase.
+  A step is never a spec. The document is.
+
+The user watches all of it in the task's **Overview** tab, and the steps you
+are on sit on a dial over your chat box.
+
+## Your todos are your steps
+
+While a phase is open, the todo list you keep — TaskCreate/TaskUpdate,
+TodoWrite, or [`todo_write`](todo_write.md) — **is** the list of steps assigned
+to you:
+
+| Todo | Step |
+|---|---|
+| a new item | a new step, assigned to you |
+| `in_progress` / `completed` | started / marked off |
+| deleted, or dropped from a `todo_write` | aborted |
+
+Steps can be marked off in any order — finish step 4 before step 3 if that is
+how the work lands. Moving a step that is not yours, or one that was aborted,
+is refused, and nothing in that call is applied. A step a person
+added from the Overview tab joins your list as soon as you write it there.
+
+## How a phase opens
+
+If you lead the task, **an approved plan opens the phase**: the plan you wrote
+in plan mode becomes the document. Write your steps as todos straight after.
+Re-planning an open phase replaces its document and keeps its steps.
+
+Outside plan mode:
+
+```python
+await api.phase_open(
+    "Drafts autosave",
+    doc=open("docs/autosave.md").read(),
+    files=["design/autosave-states.png"],   # copied into the task's folder
+)
+```
+
+## Reading it
+
+```python
+p = await api.phase()
+p["phase"]["plan_path"]       # read this — it is the spec
+p["phase"]["files"]           # absolute paths to the copies
+p["phase"]["your_steps"]      # [1, 2, 5]
+p["phase"]["your_next_step"]  # 2
+```
+
+`phase` is `None` when the current phase has not been opened yet.
+
+## Steps without a todo list
+
+```python
+await api.phase_add_step("Show a saved indicator under the title")
+await api.phase_abort_step(6, reason="covered by step 4")
+```
+
+Only a step's assignee or the phase lead can abort it.
+
+## Delegating (lead only)
+
+```python
+await api.delegate_steps([3, 4])                       # a new agent in this task
+await api.delegate_steps([5], to="drafts/session2")    # one already here
+await api.delegate_steps([5], to="drafts/session1")    # naming yourself takes it back
+```
+
+The delegate is sent the phase document, the paths of its files, and its steps,
+and works them as its own todos. On your side it is a **background task**: keep
+working, and you are woken when its last step is done — or if it fails or is
+closed with steps still open, in which case they stay assigned to it for you to
+hand on.
+
+## Finishing a phase (lead only)
+
+Two calls, for two different questions. Both need every step done or aborted.
+
+### "I have finished it" — `phase_complete`
+
+When you are done implementing and want a person to review the phase:
+
+```python
+await api.phase_complete(
+    "Drafts now save on their own and come back after a reload.",
+    checks=["Type in a new draft, wait a second, reload: the text is still there"],
+)
+return "Phase beta is up for review."   # end the turn here
+```
+
+First it puts a **review gate** in your chat: should an adversarial review run
+before the phase is approved? **Allow** or **Skip**, and it is the person's
+call, not yours — do not run a review of your own before calling this.
+
+- **Skip** puts the approval card up at once and does not wake you.
+- **Allow**, or words typed instead (what the review should look at), opens
+  the phase again and wakes you with a brief: spawn 2–3 read-only reviewers
+  told to find where the phase's claims do not hold, add what must be fixed
+  as steps, fix it, and call `phase_complete` again. That second call goes
+  straight to the approval card; say in its summary what the review found.
+
+The approval card is a **question card in your own chat** — the phase, your
+summary, the checks, and two answers: **Approve** or **Needs changes**. After
+Needs changes, the next `phase_complete` asks the gate again. Nothing to attach
+first: the person reading your conversation is who reviews it. They can also
+type instead of choosing, which counts as changes, with what they typed as the
+notes.
+
+It **does not wait**, and the card does not expire. It is stored like an inbox
+row: it stays in your chat until somebody answers, comes back after a reload,
+and can be answered from the inbox too. So end your turn straight afterwards —
+it returns `{"status": "queued", "id", ...}` — and the answer wakes you with
+what was decided:
+
+- **Approve** closes the phase and moves the task to the next letter.
+- **Needs changes**, or words typed instead, opens it again with what they
+  wrote. Add steps for what needs doing and call it once more when they are
+  done.
+
+More work while a card is up — a step added, or a todo taken up — opens the
+phase again by itself and withdraws the gate or approval card: neither
+describes the phase any more. Call `phase_complete` again when that work is
+done, and the person is asked about all of it.
+
+When the phase changed something visible, attach the app and drive it to where
+the checks can be tried *before* calling this, so the reviewer has it in front
+of them. The review card is the one way a phase is closed: there is no separate
+in-app "does this work?" card.
+
+## Returns
+
+```python
+api.phase()          -> {"task", "you", "current", "phase": {...} | None, "done": [...]}
+api.phase_open(...)  -> the phase, as api.phase() describes it
+api.phase_add_step   -> {"n", "phase", "assignee", "reopened"?: True, "note"?}
+api.delegate_steps   -> {"delegation", "steps", "to", "spawned", "background": True}
+api.phase_complete   -> {"status": "queued", "id", "phase", "note", "gate"?: True}
+```

package/python/xactor/man/powershell.md

@@ -0,0 +1,74 @@
+# api.powershell(script, timeout=120, background=False) -> dict
+<!-- group: Coding -->
+<!-- also: pwsh, ps1, Get-CimInstance, Start-Sleep, Stop-Process, windows -->
+
+Run a PowerShell script exactly as written. **Gated** (it asks as `bash`).
+**Never raises — read `exit_code`.**
+
+## Why this exists
+
+Through `api.bash`, PowerShell sat inside bash double quotes, and bash spoke
+first. `$_` is bash's own variable — the last argument of the previous command —
+so `ForEach-Object { $_.Name }` reached PowerShell as
+`ForEach-Object { /usr/bin/bash.Name }`. `$p`, `$s` and `$PSItem` became
+nothing at all. And `powershell -Command` exits **0** after most errors, so a
+`Stop-Process` that stopped nothing came back looking like success, and the
+next step ran against the process it had meant to kill.
+
+`powershell` never puts the script on a command line, so nothing interprets it
+but PowerShell; and any error ends the script with exit code 1 and the error on
+stderr.
+
+## Examples
+
+```python
+r = await api.powershell(r'''
+Get-CimInstance Win32_Process -Filter "Name='node.exe'" |
+  Where-Object { $_.CommandLine -like '*vite*' } |
+  ForEach-Object { Stop-Process -Id $_.ProcessId -Force; $_.ProcessId }
+''')
+if r["exit_code"] != 0:
+    return r["stderr"]
+```
+
+Use a raw string, `r'''…'''`: a Windows path or a regex in a normal string has
+its backslashes consumed by your own Python before PowerShell gets it.
+
+## What it sets up
+
+Before your script, on one line:
+
+- every cmdlet defaulting to `-ErrorAction Stop`, and a `trap` that writes the
+  error to stderr and exits 1. A failing cmdlet stops the script rather than
+  printing and carrying on. Native programs are not affected: `git fetch 2>&1`
+  printing progress to stderr does not stop anything.
+- UTF-8 output, so non-ASCII text is not mangled by the console code page.
+
+Because that is one line, a position PowerShell reports — `ps1:4 char:9` — is
+your script's line plus one.
+
+If the script's **last** statement is a program that fails (`git`, `cmd /c`),
+`exit_code` is that program's code. A program failing earlier does not raise in
+PowerShell and does not stop the script; check `$LASTEXITCODE` after it, or
+call it with `api.run` instead.
+
+The script is written to a temporary `.ps1` exactly as given, line endings
+included, and deleted as soon as the process ends — background runs too.
+
+## Returns
+
+```python
+{"stdout": str, "stderr": str, "exit_code": int, "program": str}
+```
+
+Windows PowerShell 5.1 on Windows; `pwsh` elsewhere, if installed. A missing
+PowerShell is `exit_code` 127.
+
+## Waiting
+
+To wait, do not shell out to `Start-Sleep`: `await asyncio.sleep(seconds)` does
+it in place.
+
+## See also
+
+`run`, `bash`, `sandbox`

package/python/xactor/man/profiles.md

@@ -0,0 +1,60 @@
+# api.profiles() -> dict
+<!-- group: Working on a website -->
+
+The browser identities on this machine, and which one you are using.
+
+Ungated: listing opens nothing, starts nothing and acts as nobody.
+`api.use_profile` is the one that has consequences.
+
+## Returns
+
+```python
+{
+  "profiles": [{"id": str, "name": str, "active": bool, "running": bool}],
+  "current": str | None,
+}
+```
+
+- **`active`** — the profile the *picker* is set to. A per-window setting a
+  human chose.
+- **`current`** — the profile *this session* is browsing as, and therefore what
+  your next `drive` will use.
+- **`running`** — whether that profile's browser is up. `False` is ordinary;
+  `use_profile` starts it.
+
+**`active` and `current` are allowed to differ, and often should.** Two sessions
+can hold two identities at once, so there is no single answer to "which profile
+is WidgeX using" — only "which one is *this* session using", which is `current`.
+If you want to know who you are about to act as, read `current`, never `active`.
+
+## Examples
+
+```python
+state = await api.profiles()
+if state["current"] is None:
+    await api.use_profile("personal")
+```
+
+Picking the one that is already warm, when either would do:
+
+```python
+state = await api.profiles()
+warm = next((p for p in state["profiles"] if p["running"]), None)
+if warm:
+    await api.use_profile(warm["name"])
+```
+
+## Getting it wrong
+
+**Reading `active` to decide what you are driving.** That is the human's picker
+setting, not your session's identity. `current` is yours.
+
+**Treating an empty list as broken.** A machine with no profiles yet is a normal
+first run. One is created from the browser widget.
+
+**Calling it in a loop to wait for `running`.** `use_profile` does not return
+until the browser is up, so there is nothing to poll for.
+
+## See also
+
+`use_profile`, `drive`, `request_operator_action`

package/python/xactor/man/project_drive.md

@@ -0,0 +1,49 @@
+# api.project_drive / project_drive_suggest — the project's WidgeX Drive
+<!-- also: project_drive_suggest, widgex_drive, team_drive, documents, team_documents -->
+<!-- group: Coding -->
+
+Every project has a **Drive**: the team's documents, kept like code in git.
+Every approved version of every document is in it, and teammates get it
+through the project's own sync. A Google Drive or OneDrive folder may be linked
+as a remote, but the Drive works without one.
+
+Not the same thing as a drive space (`man('drive_space')`), which opens a
+drive folder *as the workspace*. The project Drive sits beside any workspace.
+
+## Where the documents are
+
+`api.project_drive()` returns `folder`: a real folder on this machine holding
+a copy of every document. It is the same copy the person edits — they open
+Word, PowerPoint and Excel files in Google's editor inside WidgeX, and what
+they write there comes back into these files. Read and edit the files there
+with your ordinary file tools; there is no special read or write call.
+
+```python
+d = await api.project_drive()
+d['folder']    # '/Users/…/.widgex/project-drives/widgex-1a2b3c4d/files'
+d['files']     # what is in the Drive
+d['changed']   # what differs in the copy: added, modified or deleted
+d['changes']   # changes open or sent back, with their comments
+```
+
+`drive_moved_on` on a changed file means a teammate's change to it landed
+after the copy was taken. Suggesting yours would replace theirs; say so in the
+title, or ask the person first.
+
+## Getting an edit into the Drive
+
+Nothing you write reaches the Drive by itself. When the documents are ready:
+
+```python
+await api.project_drive_suggest(['Pitch deck.pptx'], 'Tighten slides 3–5')
+```
+
+That makes a **change**. It appears on the Drive page, where a person looks
+at each document before and after, then approves it or sends it back with a
+note. Approved, it lands for everyone and, if a remote is linked, is pushed
+there in place. Sent back, the note is in the change's `comments`; edit the
+files again, and the person presses Suggest again.
+
+Only files listed under `changed` can be suggested. A `.pptx`, `.docx` or
+`.xlsx` you edit should stay in that format — a Google document in a linked
+folder is written back from it.

package/python/xactor/man/read_bulletin.md

@@ -0,0 +1,89 @@
+# api.read_bulletin() -> str
+<!-- group: Talking to other agents -->
+
+Read what every other agent in this codebase is working on. Not gated.
+
+The bulletin is a board this machine keeps for this repository. Every agent
+that has published a task list is on it, and each agent's list is exactly what
+it last sent to `todo_write` — or to the native `TodoWrite` tool, which posts to
+the same place.
+
+It is a **hint, not a lock**. Nothing on it reserves a file or blocks a write.
+It exists so you can notice a collision before it happens rather than after.
+
+## Returns
+
+A string. One block per agent:
+
+```
+LOCAL BULLETIN — 2 other agents have an active task list in this codebase.
+Positions are 1-based and are what api.wait_for_task(node, n) refers to.
+
+AGENT N1 ACTIVE WORK:
+  1. [x] Read XylonMountConfig for the file-watch shape
+  2. [~] Wire the bulletin store into setSessionTodos
+  3. [ ] Add api.read_bulletin and api.wait_for_task
+
+AGENT N2/E1 ACTIVE WORK:   (fork, running in a clone)
+  1. [~] Bisect the crash
+```
+
+`[x]` is completed, `[~]` is in progress, `[ ]` is pending. The number is the
+`n` for `wait_for_task`.
+
+An empty board comes back as a **single sentence** saying so, never as an empty
+string — a call that returns nothing reads as a broken call.
+
+The header line for your own entry is annotated `(this is you)`. Other
+annotations you may see: `(harness)`, `(fork, running in a clone)`, and
+`(last seen 4m ago)` for an agent that has not touched its list in a while.
+
+## How agents get on and off it
+
+You go **on** the board the first time you call `todo_write` with anything
+unfinished. You come **off** it when every task on your list is `completed`, or
+when your session ends.
+
+That means an agent with nothing on the board is not necessarily idle — it may
+simply never have published a list. Absence is not evidence.
+
+## Examples
+
+Before starting something that sounds like it might already be underway:
+
+```python
+board = await api.read_bulletin()
+if "provider catalog" in board:
+    return f"Someone is already on this:\n\n{board}"
+```
+
+After noticing a file changed under you:
+
+```python
+return await api.read_bulletin()
+```
+
+## Getting it wrong
+
+**Treating it as a lock.** Nothing stops two agents editing one file, and
+nobody is waiting on you. Reading the board tells you a collision is likely; it
+does not prevent one, and there is no way to claim anything.
+
+**Polling it in a loop.** If you actually need to wait for someone, that is
+`wait_for_task`, which blocks properly. A loop around `read_bulletin` burns
+turns and finds out no sooner.
+
+**Assuming your own list is on it.** You appear once you have called
+`todo_write`, not before. If you have not published a list, other agents cannot
+see what you are doing either — which is the more important half.
+
+**Reading an absent agent as an idle one.** A session that never published a
+list never appears, however busy it is.
+
+**Leaving finished work marked `in_progress`.** You only leave the board when
+every task is complete. Until then everyone else is reading a list that says
+you are still inside work you finished an hour ago.
+
+## See also
+
+`wait_for_task`, `todo_write`, `bulletin`, `relay`, `sessions`

package/python/xactor/man/read_file.md

@@ -0,0 +1,90 @@
+# api.read_file(path, offset=0, limit=None, raw=False) -> str
+<!-- group: Coding -->
+
+Read a file. Returns text with line numbers prepended — or, with `raw=True`,
+exactly what is on disk. Not gated.
+
+## Options
+
+- **`path`** — absolute, or relative to the shell's cwd. `/c/Users/...`, `/tmp`
+  and `~` mean what they mean in `api.bash`.
+- **`offset`** — first line to return, **0-based**. `offset=0` starts at the
+  top; `offset=100` skips the first 100 lines.
+- **`limit`** — how many lines to return. `None` (default) means the rest of
+  the file.
+- **`raw`** — return the text itself: no numbers, trailing whitespace kept,
+  `\r\n` kept. This is the form to parse (`json.loads`), to search with `re`,
+  or to change and hand back to `write_file`. It is what `cat` through
+  `api.bash` was being used for.
+
+```python
+import json
+pkg = json.loads(await api.read_file("package.json", raw=True))
+```
+
+Decoded as UTF-8 with `errors="replace"`, so a binary or mis-encoded file comes
+back full of `\ufffd` rather than raising.
+
+## Returns
+
+One string. Each line is formatted as:
+
+```
+{line_number:>6}\t{line_content}
+```
+
+— the number right-aligned in six columns, then a **tab**, then the line with
+trailing whitespace stripped. Numbering is 1-based and accounts for `offset`,
+so `offset=100` starts the display at 101.
+
+An empty file, or an `offset` past the end, returns `""`.
+
+## Examples
+
+```python
+return await api.read_file("src/index.ts")
+```
+
+A window in the middle of a large file:
+
+```python
+return await api.read_file("src/index.ts", offset=400, limit=80)
+```
+
+Getting the file's *actual* text, unnumbered, to build an `edit_file` anchor:
+
+```python
+raw = (await api.bash("sed -n '40,60p' src/index.ts"))["stdout"]
+return raw
+```
+
+## Getting it wrong
+
+**Feeding the output back into `edit_file`.** This is the most common mistake
+with this call.
+
+```python
+chunk = await api.read_file("a.py", offset=10, limit=3)
+# chunk is "    11\tdef go():\n    12\t    return 1"
+# Wrong — that string does not occur anywhere in a.py.
+await api.edit_file("a.py", chunk, "...")
+```
+
+The numbers and tabs are display formatting. So is the stripped trailing
+whitespace. Use `read_file` to *locate* an edit and to understand the code;
+write `old_string` as the file actually contains it, or pull raw text with
+`api.bash("cat ...")` / `sed -n`.
+
+**Off-by-one on `offset`.** `offset` is 0-based but the displayed numbers are
+1-based. To start at the line displayed as 250, pass `offset=249`.
+
+**Reading a whole large file to find one thing.** `api.grep` gives you file,
+line and text without spending the context. Grep first, then read the region
+around the hit.
+
+**Using it to test existence.** A missing file raises `FileNotFoundError`,
+which kills the exec. `await api.glob(path)` returns `[]` instead.
+
+## See also
+
+`edit_file`, `write_file`, `grep`, `glob`, `bash`