@widgex/wgx 0.0.0-stage → 0.4.1

package/python/xactor/man/session_rest.md

@@ -0,0 +1,73 @@
+# api.session_rest(reason=None) -> dict
+<!-- group: Sessions -->
+
+Stop a harness re-serving its prompt. Not gated.
+
+A harnessized session is handed the same prompt again at the start of every turn.
+This is how that stops. The session stays alive and the harness binding stays
+configured — a human can re-arm it from the Harness Manager without setting it up
+again.
+
+## Options
+
+- **`reason`** — a short line saying why you stopped. It is shown to the user in
+  the Harness Manager, and it is the only explanation they get. `"done"` tells
+  them nothing; `"the migration is merged, so there is nothing left to poll
+  for"` tells them whether to re-arm.
+
+## Returns
+
+```python
+{"rested": True, "reason": str | None}
+```
+
+**`{"rested": False}`** when the session is not a harness. It does not raise —
+calling it from a normal session is a no-op that reports itself as one.
+
+## Examples
+
+Ending the loop when the work is actually finished:
+
+```python
+if not remaining:
+    await api.session_rest("all flaky tests are quarantined; nothing left to triage")
+    return "Done — I've stopped the harness."
+```
+
+Stopping on a condition you cannot fix unattended:
+
+```python
+if migration_needs_a_decision:
+    await api.session_rest(
+        "the schema change needs a call on whether to drop the legacy column; "
+        "I can't ask while unattended"
+    )
+    return "Rested — this needs a human decision before it can continue."
+```
+
+## Getting it wrong
+
+**Using `session_terminate` instead.** Terminating destroys the session: the
+transcript stops being a live thing you can re-arm, and the user has to build
+the harness again from scratch. Resting is the reversible version, and it is
+almost always the one you want.
+
+**Never calling it.** A harness with no exit condition runs until it hits its
+token or cycle limit and stops there, unfinished, waiting for a person. If your
+prompt has a notion of "finished" that its machine cannot see, you are the only
+thing that can notice.
+
+**Resting because one turn had nothing to do.** A poll that finds no work is a
+normal turn, not a reason to stop. Rest when the *task* is over, not when this
+pass was quiet.
+
+**Expecting it to end the turn.** It does not. Code after this call still runs
+and your reply is still delivered. It changes what happens *next* turn.
+
+**Calling it from a normal session and not checking the result.** You get
+`{"rested": False}` and no error. If you thought you were a harness, you were
+wrong, and nothing told you but the return value.
+
+## See also
+
+`session_harness`, `harness`, `session_terminate`, `sessions`

package/python/xactor/man/session_scope.md

@@ -0,0 +1,84 @@
+# api.session_scope(scope) -> dict
+<!-- also: scope, rename, session_name, what-am-i-working-on -->
+<!-- group: Talking to the user -->
+
+Say what part of the project this session is working on. Not gated.
+
+One short phrase, in the words somebody **managing** the work would use — "the
+sign-in flow", "release notarisation", "the kanban board". It becomes the top
+line of this session's card on the board, its row in the sidebar, its editor tab,
+and any queue row it raises.
+
+## You usually do not need to call this
+
+A session is already named from whatever it was first asked for, and that is
+almost always right — a person wrote it, so it is in their language by
+construction.
+
+Call this when the work turned out to be about something else. A request to
+"have a look at the build" that became notarisation is still shown as *"Have a
+look at the build"* until you say otherwise, and somebody scanning six agents
+will pick the wrong one. That is the whole use: one call, when the name has
+stopped being true.
+
+There is nothing to call at the start of a task, and nothing to repeat each turn.
+
+## What this is not
+
+**Not what you are doing right now.** That comes from the task list you already
+keep with `todo_write` — the `activeForm` of whatever is `in_progress`. The two
+are different questions with different lifetimes, which is why they are two lines
+and not one string, and why only one of them needs a call.
+
+**Not a file, a directory, a branch or a symbol.** `panel/board` and
+`ClaudeSessionService.ts` are accurate and useless here: whoever reads this is
+deciding which agent to look at next, not editing it. A branch is worse than
+useless — every session in a worktree shares one, so it names the checkout and
+tells you nothing about the agent.
+
+**Not a rename over the user's head.** If they have renamed this session, theirs
+is shown. Yours is kept and appears if they clear it.
+
+## Options
+
+- **`scope`** — the phrase. Long ones are cut at the first clause and then at 44
+  characters, so lead with the subject rather than the reason: "Release
+  notarisation" beats "Looking into why notarisation fails, which seems to be
+  about the keychain".
+
+## Returns
+
+```python
+{"scope": str | None}      # what was recorded
+```
+
+## Examples
+
+The case it exists for — the request and the work turned out to be different
+things:
+
+```python
+# Started as "have a look at the build please".
+await api.session_scope("Release notarisation")
+```
+
+Correcting a scope that has drifted, mid-session:
+
+```python
+await api.session_scope("Keychain access under launchd")
+```
+
+## Getting it wrong
+
+**Calling it every turn.** It is a standing claim, not a status. It persists
+across a window reload precisely so it does not need restating.
+
+**Naming the code.** "src/ide-widgets/panel" is the register this exists to
+avoid. If the phrase contains a slash or a file extension, it is wrong.
+
+**Using it to report progress.** "Finished the parser, now on tests" is two
+statements and neither is a scope. Progress is `todo_write`.
+
+## See also
+
+`todo_write`, `request_review`, `agent`, `bulletin`

package/python/xactor/man/session_terminate.md

@@ -0,0 +1,58 @@
+# api.session_terminate(session_id) -> dict
+<!-- group: Sessions -->
+
+Stop this session or one of its descendants. Gated.
+
+## Options
+
+- **`session_id`** — the session to stop. Yourself, or something you spawned
+  (or something *it* spawned, to any depth).
+
+Anything outside your own subtree is refused. You cannot terminate your parent,
+a sibling, or an unrelated session.
+
+## Returns
+
+```python
+{"success": True}
+```
+
+## Examples
+
+Cleaning up a child that is no longer needed:
+
+```python
+r = await api.session_join(child_id, timeout=600)
+if r["status"] == "timeout":
+    await api.session_terminate(child_id)
+    return "That was taking too long; I stopped it."
+return r["lastMessage"]
+```
+
+Abandoning a fork after reading its answer:
+
+```python
+r = await api.session_join(fork_id, timeout=1800)
+await api.session_terminate(fork_id)
+return r.get("lastMessage")
+```
+
+## Getting it wrong
+
+**Terminating yourself to "finish".** Ending your turn is how you finish. This
+call destroys the session, so anything the user says next has nowhere to go. If
+you are a harness and want to stop looping, that is `api.session_rest`, which
+leaves the session alive and re-armable.
+
+**Terminating a child you have not joined.** Whatever it was going to report is
+lost. Join first, read the result, then terminate.
+
+**Expecting it to undo the child's work.** Files it wrote stay written.
+Termination stops the conversation, not its effects. To see what it changed,
+read its node with `xylon_get_diff`.
+
+**Using it on a sibling.** Refused. The subtree rule has no override.
+
+## See also
+
+`session_rest`, `session_join`, `sessions`, `xylon_read`, `permissions`

package/python/xactor/man/session_token.md

@@ -0,0 +1,78 @@
+# Session tokens: who is calling a tool
+
+<!-- group: Concepts -->
+<!-- also: WIDGEX_SESSION_TOKEN, harness identity, identity token, actor, segregation of duties, verify session -->
+
+Every command a session runs through `api.run`, `api.bash` or `api.powershell`
+has `WIDGEX_SESSION_TOKEN` in its environment. A tool you write — a ledger CLI,
+a deploy script, a check — can hand that token back to WidgeX and be told which
+session is calling, and which harness and state it is in **right now**.
+
+It is optional at both ends. A tool that never looks at it is unaffected.
+
+## Why it exists
+
+A tool that enforces who may do what used to learn who was calling from flags
+like `--actor` and `--role`, which the agent writes itself. That catches
+mistakes, not an agent that claims to be someone else. A token is not
+something an agent can type for another session: it is signed with a key that
+exists only in the WidgeX window's memory, and each session only ever sees its
+own.
+
+## Checking one
+
+Each WidgeX window writes where to ask into
+`~/.widgex/harness-identity/<issuer>.json`. The issuer is the token's second
+dot-separated field. Post the token to that file's `url`:
+
+```python
+import json, os, pathlib, urllib.request
+
+def who_is_calling():
+    token = os.environ.get("WIDGEX_SESSION_TOKEN")
+    if not token:
+        return None                      # not run from a WidgeX session
+    issuer = token.split(".")[1]
+    info = json.loads((pathlib.Path.home() / ".widgex" / "harness-identity" / f"{issuer}.json").read_text())
+    req = urllib.request.Request(info["url"], data=json.dumps({"token": token}).encode(),
+                                 headers={"content-type": "application/json"})
+    with urllib.request.urlopen(req, timeout=5) as r:
+        return json.load(r)
+```
+
+A valid token answers:
+
+```json
+{"valid": true, "verified_at": 1792890000000,
+ "session_id": "95791dee-…", "node": "proj/repo/issue/session4", "label": "architect",
+ "harness": "revenue-desk", "harness_kind": "overlay", "state": "propose",
+ "parent_session_id": "b3588d9d-…"}
+```
+
+`harness`, `harness_kind` and `state` are `null` for a session not running one.
+Anything else answers `{"valid": false, "reason": "..."}`. A tool enforcing a
+rule should refuse on that, not fall back to a flag.
+
+Read the url from the file, never from an environment variable: the agent
+chooses its commands' environment, and a url it set could point anywhere.
+
+## What it proves
+
+- **Which session's commands the call came from.** Session A cannot pass
+  itself off as session B.
+- **Its harness and state when you asked**, not when the command started.
+
+What it does not prove:
+
+- That the session *should* be doing this. Your tool's rules still decide that.
+- Anything against code that sets out to subvert WidgeX on the same account,
+  for instance by rewriting the discovery file. The token makes lying mean
+  doing that, instead of typing a different `--actor`.
+
+## Lifetime
+
+A token is valid for as long as its session exists and the window that issued
+it is open. After a window reload the old tokens stop verifying
+(`"issued by another WidgeX window, or by this one before it reloaded"`), and
+every shell started from then on carries a new one. Sessions running on a
+remote host carry no token.

package/python/xactor/man/sessions.md

@@ -0,0 +1,93 @@
+# Sessions
+<!-- group: Concepts -->
+
+What a session is, how children relate to parents, and which call makes which.
+
+A session is one conversation with one model, running in one working directory,
+occupying one node in a xylon tree. You are a session. Everything you can spawn
+is either a *child session* — its own conversation, its own node, running
+independently — or a *subagent*, which is neither.
+
+## The shapes
+
+| Call | Repo | Conversation | Node | Runs |
+|---|---|---|---|---|
+| `agent` | **same** working dir | fresh, briefed by `summary` | child of yours | independently |
+| `session_fork` | **cloned** copy | **copy of yours** | child of yours | independently |
+| `agent` | same | fresh, briefed by `prompt` | none | **blocks you** |
+| `session_harness` | this session | this one | this one | re-serves you |
+
+Only `agent` blocks. `extend` and `fork` return as soon as the child exists;
+you wait for one with `session_join` or you do not wait at all.
+
+## Talking to a child
+
+At birth a child gets exactly three things:
+
+1. its `prompt`,
+2. whatever `aux_context` file you attached, inlined into that prompt,
+3. `summary`, if you passed one (`agent` only).
+
+It can also read your side of the tree with `xylon_read_messages('..')` — that
+is the fallback a child is told about when you give it no `summary` — and you
+can read its result with `session_join`.
+
+After that, there is a channel: see `relay`. `api.relay_connect(node)` asks any
+session for one and it may decline; `force=True` takes one on a **direct child**
+without asking, and turns your `relay_send` into that child's prompt, blocking
+until it answers. That is how you steer a child that has misread the job,
+instead of waiting for it to finish being wrong.
+
+What every agent in this codebase is *currently* working on is a separate
+thing, and is on the `bulletin`.
+
+## Waiting, and not waiting
+
+```python
+child = await api.agent(
+    "Port the auth tests to the new fixture API and report what broke.",
+    summary="I'm mid-refactor of src/auth; the fixture API changed shape today.",
+)
+r = await api.session_join(child["sessionId"], timeout=600)
+if r["status"] != "done":
+    return {"child": child["sessionId"], "status": r["status"], "why": r.get("error")}
+return r["lastMessage"]
+```
+
+Fire and forget is legitimate — a child that will take an hour should not hold
+your turn open. Report the session id and move on.
+
+## Terminating
+
+`session_terminate` works on **yourself or a descendant only**. A parent, a
+sibling, or an unrelated session is refused. There is no way to kill something
+that did not come from you.
+
+## Permission
+
+`session_fork`, `agent`, `session_terminate` and `session_harness` all prompt
+the user. `session_join` and `session_rest` never
+do — waiting and stopping need no approval.
+
+## Getting it wrong
+
+**Spawning a child to do something you could just do.** A child costs a whole
+new context, and the answer has to travel back through `session_join` as a
+single string. For work you want the answer from, `agent` is cheaper and
+returns directly.
+
+**Forking when you meant to extend.** A fork clones the repository. Two
+sessions then edit two different copies of the same files, and nothing merges
+them. Fork when the work is speculative or must not touch the user's tree;
+extend when it is the same tree at a different scope.
+
+**Assuming a child inherits the conversation.** Only `session_fork` copies the
+history. `agent` gives the child nothing but what you wrote.
+
+**Reading `lastMessage` without checking `status`.** A failed child returns an
+empty `lastMessage`, which reads exactly like a child that had nothing to say.
+
+## See also
+
+`agent-vs-fork`, `agent`, `session_fork`, `session_join`,
+`session_terminate`, `agent`, `xylon`, `harness`

package/python/xactor/man/set_harness.md

@@ -0,0 +1,15 @@
+# api.set_harness(agent, harness, brief=None) -> dict
+
+<!-- group: Sessions -->
+
+Put an agent under a harness — a state machine that drives it state by state.
+
+`agent` is an id from `api.tasks()`. `harness` is a harness name from
+`.widgex/harnesses/`. `brief` is the standing instruction the harness re-serves
+above every state; it defaults to what the agent was first asked.
+
+If the agent is busy, the harness arms and starts when its current turn ends.
+
+## Returns
+
+`{"agent": str, "harness": str, "started": bool}`

package/python/xactor/man/spawn_swarm.md

@@ -0,0 +1,80 @@
+# api.spawn_swarm(shared_prompt, given, model=None, workflow=None, browser=False) -> dict
+
+<!-- also: swarm, agent_swarm -->
+<!-- group: Sessions -->
+
+Start an agent swarm: one autonomous agent per prompt in `given`, all working on
+the same kind of problem at once. **Always asks the user**, in every mode —
+Autonomous included — because the card is the only moment a person sees how
+many agents are about to start.
+
+Each agent:
+
+- is sent your `shared_prompt` first, then a divider, then its own `given` prompt;
+- gets a worktree and a branch of its own, cut from **your task's branch** — the
+  worktrees are made in parallel, so twenty cost little more than one;
+- runs Autonomous, on `model` (or yours), under `workflow` if you name a harness.
+
+Together they are one **Agent Swarm** row under your task, with counters for
+idle, blocked, running and finished. The user opens the row to read every
+agent's briefs in one stream, message all of them at once, and answer their
+permission requests and questions; and merges, halts, wakes or aborts them from
+the row's menu. When the task is shelved or done, every agent's work is
+committed and its worktree removed.
+
+Returns at once once approved; nothing waits on the agents. The approval itself
+waits on a person, so give the exec a generous `timeout_seconds` (600 or more).
+Calling again with the same prompts while that swarm is live hands back the one
+already running (`already: True`) rather than starting it twice.
+
+## Arguments
+
+- **`shared_prompt`** — a path to a file, relative to the cwd, or the prompt
+  text itself. A single word with an extension that names no file is refused,
+  rather than sent to twenty agents as their brief.
+- **`given`** — a list, one entry per agent, each a path or text like
+  `shared_prompt`. At most 50.
+- **`model`** — e.g. `'claude-sonnet-5-5'`. `'Claude-Sonnet-5.5'` is accepted as
+  the same id. An unknown one is refused with the list, and nothing is made.
+- **`workflow`** — a harness name or a path to its `.json`. It must have a
+  terminal state, or the agents could never stop.
+- **`browser`** — whether the agents may use the browser. `False` refuses
+  `drive`, `use_widget` and the `browser_*` calls to them.
+
+## Returns
+
+```python
+{"swarm": "swarm-…", "task": "issue-12", "branch": "widgex/…",
+ "members": [{"index": 1, "session": "session-40", "node": "…",
+              "branch": "widgex/…", "label": "#1 …"}],
+ "failed": [{"index": 3, "label": "#3 …", "error": "…"}]}
+```
+
+A member whose worktree could not be made is in `failed`; the rest still start.
+
+## What the agents are told
+
+That they are one of N, that the others are on other branches, to report with
+`api.swarm_brief(text)` as they go, and to commit and call `api.request_review`
+when done — which marks them finished on the row instead of filing an inbox row.
+
+## Examples
+
+```python
+files = [f"tasks/{n}.md" for n in range(1, 9)]
+r = await api.spawn_swarm("tasks/shared.md", files, model="claude-sonnet-5-5")
+return f"{len(r['members'])} agents started, {len(r['failed'])} failed"
+```
+
+Prompts as text:
+
+```python
+modules = ["parser", "lexer", "printer"]
+await api.spawn_swarm(
+    "Add property-based tests to one module. Keep the public API unchanged.",
+    [f"The module is src/{m}.ts." for m in modules],
+)
+```
+
+Run it from an agent in a task, not from the main checkout — the agents are cut
+from the task's branch, and the Coordinator has none.

package/python/xactor/man/submit_evidence.md

@@ -0,0 +1,54 @@
+# api.submit_evidence(id, note, files=None) -> dict
+<!-- group: Sessions -->
+
+Attach one required artifact to the harness state you are in. Not gated.
+
+Some harness states are **evidence gates**: they cannot be left until every
+required artifact has been submitted, no matter what you answer in the
+transition block. The prompt for such a state lists what is still owed, by id.
+This is how you hand it over.
+
+Answering the transition questions does not move a harness that still owes
+evidence. That is deliberate — an agent that believes it has finished is exactly
+the one whose word is worth least, and the gate exists so that belief is not the
+thing being tested.
+
+## Options
+
+- **`id`** — the artifact id as written in the state's prompt: lowercase, and
+  one of the ids that state actually requires. Anything else raises, and the
+  message names the ids that were expected. You cannot invent one.
+- **`note`** — the evidence itself. The command you ran and what it printed, not
+  a claim that you ran it. An empty note is refused, because a submission that
+  says nothing is indistinguishable from not having done the work.
+- **`files`** — optional paths backing the claim.
+
+Re-submitting the same id during the same visit to a state **replaces** your
+earlier note rather than adding to it, so re-running a failing test and
+submitting again is the normal way to correct the record.
+
+## Returns
+
+```python
+{"submitted": True, "still_missing": ["diff", "visual"], "state": "evidence"}
+```
+
+`still_missing` is what the gate is *now* waiting for. An empty list means the
+gate is satisfied and the next transition you answer true can move.
+
+## Raises
+
+`ValueError` when the session is not running under a harness, when the state
+collects no evidence, or when `id` is not one of that state's artifacts.
+
+## Freshness
+
+Submissions are scoped to the current **visit** to the state. If a review sends
+work back and the run later re-enters the gate, last round's proof does not
+count and every required artifact must be submitted again — which is the whole
+point of sending it back.
+
+## See also
+
+- `request_review` — say a whole piece of work is ready for a person to look at.
+- `session_rest` — stop, when another cycle would add nothing.

package/python/xactor/man/swarm_brief.md

@@ -0,0 +1,30 @@
+# api.swarm_brief(text) -> dict
+
+<!-- group: Sessions -->
+
+Report progress to your agent swarm's stream. Never asks. Only for an agent
+started by `api.spawn_swarm`; anyone else is refused.
+
+The user reads every agent's briefs side by side in one stream, so a brief is
+one or two sentences about **what changed** — not what you are about to try,
+and not a log. Write one when you have started, at each milestone, and before
+you stop. A turn that ends without one has its last message posted in its
+place, which is rarely as clear as one you wrote.
+
+Finishing is not a brief: commit your work and call `api.request_review(claim)`.
+That marks you finished on the swarm's row.
+
+Messages the user sends to the whole swarm arrive in your tool results or as a
+prompt. Answer them in your reply — the reply is shown in the stream.
+
+## Returns
+
+```python
+{"ok": True, "swarm": "swarm-…"}
+```
+
+## Example
+
+```python
+await api.swarm_brief("Parser tests in: 14 properties, 2 found real bugs (fixed, see commit).")
+```

package/python/xactor/man/task_status.md

@@ -0,0 +1,82 @@
+# api.task_status(status, detail=None) -> dict
+
+<!-- group: Sessions -->
+
+Say where your task has got to. Only the task's lead may.
+
+The one thing on the user's board that is **told** rather than read.
+
+Everything else a card shows is derived from your session: which lane it is in
+comes from your permission mode and whether you have asked anybody to look at
+something, the badge comes from your status, the branch comes from your Issue.
+That works for every question a session can be *observed* to answer.
+
+"How is this going" is not one of them. A session three files into a refactor
+and a session stuck on the second look identical from outside — same status,
+same lane, same branch — and you are the only thing in the system that knows
+which one you are.
+
+## Who may call it
+
+The task's **lead**: the first agent spun up in it, which is the one answerable
+for the task and whose state the task already shows. `api.tasks()` reports
+`lead` on every task, so you can check rather than assume.
+
+An aux agent is refused, and the refusal names the lead. That is not a
+formality — a task is one working copy with one agent answerable for it and any
+number of agents helping, so a status any of them could write would be the group
+talking over the one that answers for it. Report to your lead with
+`api.relay_send` and let it speak for the task.
+
+Outside a task it is refused too. The main checkout is the folder the user has
+open; nobody is answerable for it, so a status there would describe the window
+rather than any piece of work. Work that wants a status wants a task:
+`api.agent(raise_=True, title=...)`.
+
+## Options
+
+- **`status`** — where the work is, in a few words. *"reading the importer"*,
+  *"blocked on the schema"*, *"landing it"*. One line, up to 60 characters,
+  because it is drawn on a card about 200px wide. Longer is refused rather than
+  silently cut, so you choose the words instead of a slice choosing them.
+- **`detail`** — one sentence more, when the label cannot carry it. Shown when
+  somebody hovers the card. Up to 400 characters.
+
+## Returns
+
+```python
+{"task": str, "status": str, "detail": str | None, "at": int}
+```
+
+`task` is the id it was recorded against, and `status` is what was stored after
+being collapsed to a single line.
+
+## When to call it
+
+When the answer changes. You have understood the problem; you have started
+building; you are blocked on something; you are landing.
+
+It is a **position, not a log**. A line that changes every thirty seconds is a
+line nobody reads, and nothing here is a progress feed — the transcript already
+holds what happened, and `api.todo_write` already holds your own checklist.
+
+## Getting it wrong
+
+**Using it to hand work back.** It is not `api.phase_complete`. This says
+where the work is; that says the work is done and asks a human to judge it.
+Writing "finished" here hands nothing back, files nothing on anybody's queue,
+and nobody is asked to look.
+
+**Writing it per tool call.** See above: a position, not a log.
+
+**Calling it as an aux agent and treating the refusal as a bug.** It names your
+lead because relaying to the lead is the thing to do instead.
+
+**Expecting it to move a card between lanes.** Lanes are claims about the world
+and are derived — see `update_card` for the one call that places a card, and
+note that it is for an orchestrator pointing a card at a subagent, which is a
+different job from this.
+
+## See also
+
+`tasks`, `update_card`, `phase_complete`, `relay`