@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/relay.md

@@ -0,0 +1,216 @@
+# Relay — send / inbox / connect / close
+<!-- also: relay_connect, relay_send, relay_inbox, relay_accept, relay_decline, relay_close -->
+<!-- group: Talking to other agents -->
+
+Message another session, on this machine or another one. None is gated.
+
+## Two kinds of relay
+
+**A message** — `relay_send(node, subject, body)` to any session. There is no
+channel to open and nothing for the other side to accept: it is in their inbox
+as soon as their machine has read it, they are told once, and they read it and
+answer — or not — when they choose to.
+
+**Delivered is not read, and does not start a turn.** If the recipient is busy it
+sees the notice at its next tool result. If it is **idle**, a person at its
+machine is asked whether to wake it (a session running Autonomous is woken
+without asking, unless the message came from another account). Until someone
+answers, or opens that chat, it stays idle with the message sitting in its
+inbox — `relay_inbox()["sent"]` still says `delivered`, and for a session on
+another machine a message can sit at `waiting` for the same reason. Neither
+status says anyone is working on it. If you need an answer from an idle session
+on someone else's machine, tell its person out of band to look for the wake
+prompt.
+
+**Forced** — orchestration, and nothing else. A parent may take a channel on a
+**direct child** without asking it, one at a time, with
+`relay_connect(node, force=True)`. The child does not consent and never reads an
+inbox: your message arrives as its prompt, and your `relay_send` **blocks** until
+its turn ends and returns what it said. You are its user, until you close it.
+
+Reach for `force=True` when you spawned a session to do a job and you are the
+one deciding what it does next. For anything else, send a message.
+
+## How a message travels
+
+It is a line in **your own transcript**. That is the whole of sending: the call
+writes it and returns. Whichever machine is running the other session delivers
+it — by appending it to *their* transcript — once it has read yours:
+
+- **In this window** — delivered before `relay_send` returns: `status: 'delivered'`.
+- **Another window here, or a machine the sync is linked to** — a few seconds.
+- **A machine that is offline** — when it next syncs. Nothing has to be online
+  at the same time; the message waits in your transcript.
+- **A session that is not running anywhere** — when it next runs.
+
+You find out it arrived the same way: their transcript comes back with it in.
+`relay_inbox()["sent"]` marks each of your messages `delivered` or `waiting`.
+**Do not send it again** because it says `waiting` — it is already on its way,
+and a second send is a second message.
+
+A private task's transcript never leaves this machine, so a message from one
+reaches only sessions here. The return says so when that is the case.
+
+## Naming the other session
+
+Every call takes a session the way notices and the bulletin print it:
+`"fix-auth/session3"`. A session on another machine is named the same way, once
+its transcript has synced here. `"."` is you and `".."` is your parent. A full
+`repo/issue/session` and a bare session id also work. The older
+`"@machine/issue/session"` form still resolves — the machine part is ignored,
+because a session is the same session wherever it runs.
+
+If the session id at the end of a name is one this machine holds, it resolves
+even when the issue folder in front of it is spelled differently here (`-2`
+suffixes appear when two folders collide). A task that has synced without any
+session transcript in it has nothing to address — ask its owner for the session id.
+
+A name that matches nothing, or more than one session, **raises** with who you
+could have meant.
+
+## `relay_send(node, subject, body, timeout=None) -> dict`
+
+**The same call behaves differently for the two kinds.** This is the part that
+gets missed.
+
+A **message** returns at once:
+
+```python
+{"status": "delivered", "node": "fix-auth/session3", "id": "…"}
+{"status": "sent", "node": "fix-auth/session3", "id": "…", "delivery": "…"}
+```
+
+`delivered` is in their inbox now. `sent` waits for their machine, and
+`delivery` says how it will get there.
+
+On a **forced** relay it blocks for the child's whole turn and returns its
+answer:
+
+```python
+{"status": "done" | "timeout" | "error" | "gone" | "closed", "node": ..., "reply": str}
+```
+
+**Check `status` before reading `reply`.** It is empty on `error`, where the
+reason is in `error` instead — a crashed child otherwise reads exactly like one
+that had nothing to say. `timeout` leaves the relay open and the child running,
+so you can send again or close.
+
+`subject` is one line, at most 120 characters: it rides in the tail of the other
+agent's tool result, where a paragraph is noise. `timeout` applies to forced
+sends only, defaults to 300 seconds — and, as with `session_join`, the exec's
+own `timeout_seconds` must be higher or your code is killed mid-wait.
+
+## `relay_inbox(msg=None) -> dict`
+
+Everything by default:
+
+```python
+{"messages": [...], "count": int, "unread": int, "sent": [...], "forced": [...]}
+```
+
+Each message is `{msg, from, reply_to, subject, body, at, sent_at}`. `from` is
+the name to answer with. `sent` is what you have sent, each with `status`
+`delivered` or `waiting`. `forced` lists any forced relay you are part of and
+your role in it.
+
+With `msg=n`, just that one. **A number that does not exist returns
+`{"message": None, "available": [...]}`** rather than raising — the number came
+out of a notice you may have half-remembered, and killing the exec over a typo
+would destroy the work around it.
+
+Message numbers are a message's position in your transcript, so they are never
+reused and never renumbered.
+
+## `relay_connect(node, force=True, reason=None) -> dict`
+
+Takes a forced relay on a direct child. Returns `{status: 'open' |
+'already-open', node, connection_id, forced}`. Without `force` it returns
+`{status: 'not-needed'}` — just send.
+
+**Raises** for an unresolvable node, and for forcing anything that is not a
+direct child running here, a child its state machine is driving, or a second
+child while one is open.
+
+## `relay_close(node) -> dict`
+
+Ends a forced relay. Returns `{status: 'closed' | 'not-open', node}`. It does
+**not** terminate anything — the child keeps running and keeps its work. Only the
+parent may close one. A plain message has nothing to close.
+
+## `relay_accept` / `relay_decline`
+
+Kept so older scripts run; both return `{status: 'not-needed'}`. There is no
+request to answer any more. To say no, reply saying so, or do not reply.
+
+## How a message reaches you
+
+You are told **once**, in the tail of a tool result, that mail arrived:
+
+```
+──
+Relay: 1 new message is in your inbox.
+  msg 7  from fix-auth/session3 — "schema for the auth tables"
+Read them with `await api.relay_inbox()`, or one with `api.relay_inbox(msg=N)`.
+```
+
+That notice is not repeated and nothing is waiting on you. Finish what you are
+doing and read it at a natural break.
+
+If you were idle, the person running you is asked whether to wake you for it —
+or, in Autonomous mode, you are woken without asking, unless the message came
+from somebody else's account.
+
+## Examples
+
+Messaging a peer:
+
+```python
+await api.relay_send("fix-auth/session3", "schema", "Which columns does users gain?")
+# ... carry on working; the answer arrives in your inbox ...
+return await api.relay_inbox()
+```
+
+Orchestrating a child:
+
+```python
+await api.relay_connect("fix-auth/session4", force=True)
+r = await api.relay_send("fix-auth/session4", "scope", "Do the reads first, leave writes to me.",
+                         timeout=600)
+if r["status"] != "done":
+    return {"child": r["status"], "why": r.get("error")}
+verdict = r["reply"]
+await api.relay_close("fix-auth/session4")
+return verdict
+```
+
+## Getting it wrong
+
+**Reading `reply` without checking `status`.** The `session_join` failure,
+exactly: a child that crashed comes back with an empty `reply` and looks like a
+child that succeeded quietly.
+
+**Sending again because it says `waiting`.** It is in your transcript and will
+be delivered when their machine reads it. A second send is a second message.
+
+**Leaving the exec timeout at its default on a forced send.** `timeout=600`
+inside a tool call capped at 120 seconds means your code dies at 120 and the
+child is left mid-turn.
+
+**Forcing a grandchild, or a session you did not spawn.** It raises. Forcing
+goes around whoever is actually orchestrating that session, which is the one
+thing it must never do.
+
+**Treating `relay_close` as terminate.** It ends the forced relay. The child
+carries on. `session_terminate` is the other thing, and it is not this.
+
+**Treating the tail notice as an interrupt.** It is announced once and then
+waits. Abandoning a half-finished edit to read it is worse than reading it two
+minutes later.
+
+**Expecting a subagent to have an inbox.** `agent` runs a subagent, not a
+session — it has no transcript of its own, so it cannot be an endpoint.
+
+## See also
+
+`session_join`, `agent`, `session_fork`, `sessions`, `read_bulletin`,
+`bulletin`, `agent-vs-fork`

package/python/xactor/man/reply.md

@@ -0,0 +1,72 @@
+<!-- also: answer -->
+<!-- group: Talking to the user -->
+
+# api.reply(text) -> dict
+
+Answer a question without taking the step away.
+
+For what comes back as `asked`. The instruction, the ring and the step counter
+all stay exactly as they were, and the answer appears on its own line
+underneath — a word with somebody about the step they are on, rather than a new
+step.
+
+## Do not answer with `instruct`
+
+`instruct` **is** a new step. It moves the ring, resets the counter and replaces
+the words — so answering a question with it takes away the very sentence the
+question was about, which is the thing somebody was asking you to explain.
+
+That was the original behaviour and it was reported as exactly what it looked
+like: asking cost you your place. A question is a side conversation about the
+step, not a reason to leave it.
+
+## Options
+
+- **`text`** — the answer, in a sentence or two. It sits on a live card beside
+  the app, so it is skimmed rather than read; if the real answer is long, say
+  the short version here and the rest in the chat.
+
+## Returns
+
+`{"status": "answered"}`, or `{"error": ...}` when there is no card up to answer
+on — which means the tour already ended, and the reply has nowhere to go.
+
+## Examples
+
+The loop, with the answer folded in:
+
+```python
+while True:
+    r = await api.await_user(target)
+    if r.get("clicked") or r.get("advanced"):
+        break
+    if q := r.get("asked"):
+        await api.reply(answer_for(q))
+        continue          # same step, still ringed, handed back to them
+    if r.get("stopped"):
+        break
+```
+
+A question that deserves to move the tour instead:
+
+```python
+    if q := r.get("asked"):
+        await api.reply("That one installs the CLI — let me show you.")
+        target = api.find(role="button", text_exact="Install")
+        await api.instruct("Here it is.", target, title="detour")
+```
+
+## Getting it wrong
+
+**Replying when nothing asked.** There is no card to write on once a tour has
+ended, and the error says so rather than drawing one from nowhere.
+
+**Answering in the chat and carrying on.** The tour is in its own window. An
+answer typed into this conversation is in a window they are not looking at.
+
+**Treating a question as an interruption.** It is the tour working. Answer it,
+and go wherever it points — you are a guide, not a script.
+
+## See also
+
+`await_user`, `instruct`, `highlight`

package/python/xactor/man/reply_message.md

@@ -0,0 +1,78 @@
+<!-- also: reply, answer-back, inbox-reply -->
+<!-- group: Talking to the user -->
+
+# api.reply_message(id, text) -> dict
+
+Answer back, in the inbox row you are being asked about.
+
+When somebody answers one of your requests you are woken with what they said.
+Often what they said is a question — and until this existed there was nowhere to
+put the answer, so it went into the transcript.
+
+**That is the same as not answering.** They asked in the row; they are watching
+the row; your transcript is a different surface they are not looking at. This is
+the failure that produced this call: an agent asked about a file, the reply was
+*"what's the context of this?"*, and the explanation went somewhere the person
+who asked never saw.
+
+## The row comes back to them, to read
+
+Replying puts the message back to unread — the dot comes back and the reply box
+is theirs again — but it does **not** put it back to waiting on them. They
+answered it once; that settled it. The task is not held in Blocked by your
+reply, and it is not counted on the badge.
+
+So if you still need something from them before you can go on — a verdict, a
+decision, an action — file it as its own request after replying
+(`request_verification`, `request_answer`, `request_operator_action`). That one
+waits until it is answered, and it is drawn on the task's Card tab where they
+can answer it.
+
+That is also the reason not to reply with nothing. Every reply costs them a
+second look at a row they had finished with.
+
+## Options
+
+- **`id`** — the message you are answering. It came back from the request you
+  sent, and the prompt that woke you names it. You may only reply to your own
+  messages; anything else is refused.
+- **`text`** — what you want to say. Plain text; blank lines are paragraphs.
+
+## Say it the way they asked it
+
+The register rule from `api.man('request_answer')` applies here and matters
+more, because they have already told you once that they could not follow you.
+
+Answer the question they actually asked. If they asked what something is about,
+that is a question about *their* work and their reasons — not about your call
+stack. Do not explain the mechanism unless the mechanism is what they asked
+about.
+
+```python
+# they asked: "what's the context of this?"
+
+# no
+await api.reply_message(id, "It's the CSV parser refactor in legacy/csv.ts — "
+                            "the shared implementation lacks the quoted-newline "
+                            "handling that the local one has.")
+
+# yes
+await api.reply_message(id, "Sorry — it came out of the import work you asked "
+                            "for last week. Two of the files read data in an "
+                            "older way than the rest, and I wanted to know "
+                            "whether to bring them in line now or leave them.")
+```
+
+## It does not block
+
+Your turn finishes here. Their next answer wakes you again, the same way the
+first one did.
+
+## Returns
+
+`{'status': 'queued', 'id': ...}` — a receipt, not an answer.
+
+## See also
+
+- `api.man('request_answer')` — asking in the first place, and the register rule
+- `api.man('request_user_action')` — handing over work rather than a question

package/python/xactor/man/report_bug.md

@@ -0,0 +1,118 @@
+# api.report_bug(attempted, expected, actual, severity, kind='defect', surface=None, blocked=False, workaround=None, reproduction=None, citations=None) -> dict
+<!-- group: Reporting a WidgeX problem -->
+
+File a bug against **WidgeX** — the environment you are running in. Not gated.
+
+This has nothing to do with the project you are editing. You are almost
+certainly working on someone's codebase; a limitation you hit *while* doing that
+is exactly the report that is wanted.
+
+File when an api call misbehaves, a capability does not exist, the sandbox
+refuses something legitimate, a permission prompt hangs, a browser will not
+attach, or a fork or harness fails.
+
+## Options
+
+- **`attempted`** — what you were trying to accomplish, in your own terms.
+- **`expected`** — what you expected the environment to let you do.
+- **`actual`** — what happened instead.
+- **`severity`** — impact **on your ability to work**, not code severity:
+  `'critical'` (blocked, no workaround), `'major'`, `'minor'`, `'cosmetic'`.
+- **`kind`** — `'defect'` when something misbehaved, `'missing_capability'`
+  when there was simply no way to do it, `'unclear'` when you cannot tell.
+  Default `'defect'`. **`'unclear'` is a real answer** and better than a
+  confident guess.
+- **`surface`** — where you hit it: `files`, `shell`, `search`, `sessions`,
+  `harness`, `browser`, `xylon`, `permissions`, `ui`, `other`.
+- **`blocked`** — `True` only if it stopped the work. If you got there another
+  way, this is `False` and the way is `workaround`.
+- **`workaround`** — what you did instead.
+- **`reproduction`** — minimal steps, if you know them.
+- **`citations`** — WidgeX source lines, e.g. `["StdlibShell.ts:301"]`. Normally
+  omitted; you are not expected to know its internals.
+
+**Write prose in every field.** Session state, environment, a transcript
+excerpt, this turn's diff and recent logs are attached automatically. Pasting a
+stack trace in `actual` displaces the sentence that would have been useful.
+
+## Returns
+
+```python
+{"report_id": str, "path": str, "similar": [...]}
+```
+
+`similar` lists earlier reports with the same signature. **Check it before
+filing the same thing twice.**
+
+## Examples
+
+A call that did not do what its signature says:
+
+```python
+return await api.report_bug(
+    attempted="load the github widget by name so I could drive the PR page",
+    expected="browser_load(name='github') to register that widget's states",
+    actual="it was accepted but the registry stayed empty, and browser_context "
+           "reported no widget loaded",
+    severity="major",
+    kind="defect",
+    surface="browser",
+    blocked=False,
+    workaround="passed the state definitions as code= instead",
+)
+```
+
+Something that simply does not exist:
+
+```python
+return await api.report_bug(
+    attempted="unbind the state machine from this harness while re-arming it",
+    expected="some way to clear the binding from the api",
+    actual="omitting machine= keeps the existing binding, and there is no value "
+           "that clears it — the only route is the Harness Manager UI",
+    severity="minor",
+    kind="missing_capability",
+    surface="harness",
+)
+```
+
+Not knowing what went wrong is fine:
+
+```python
+return await api.report_bug(
+    attempted="join a child session I had just extended",
+    expected="status done or timeout",
+    actual="status error with an empty reason; the child's node looks complete",
+    severity="major",
+    kind="unclear",
+    surface="sessions",
+    blocked=True,
+)
+```
+
+## Getting it wrong
+
+**Not filing because it is probably your fault.** Partial ownership is enough.
+"I may have called it wrong" and "the environment is plausibly involved" are
+both true at once, and only one of them is a reason to file.
+
+**Not filing because you are not working on WidgeX.** You are never working on
+WidgeX. That is the normal case.
+
+**Treating "there is no way to do X" as a dead end.** It is a report —
+`kind='missing_capability'` — and then you find another route. File and keep
+going.
+
+**Pasting logs, diffs or stack traces.** They are attached already, and the
+fields cap out. Describe what happened.
+
+**Filing once per retry.** One report per distinct limitation. Check `similar`.
+
+**Telling the user you are blocked when you are not.** If you worked around it,
+`blocked=False` and put the workaround in the report — not in an apology.
+
+**Using it for a bug in the user's code.** That is not this. This is the IDE.
+
+## See also
+
+`sandbox`, `permissions`, `overview`

package/python/xactor/man/request_answer.md

@@ -0,0 +1,142 @@
+<!-- also: ask, question, decide, decision, which one -->
+<!-- group: Talking to the user -->
+
+# api.request_answer(question, detail=None, choices=None) -> dict
+
+Ask the user to decide something you cannot decide yourself. **Does not block.
+Not gated.**
+
+The other three handoffs give away *work* — a GUI task, a judgement.
+`request_answer` gives away a **decision**: two defensible options and no way
+for you to pick between them from inside the code.
+
+## It does not block
+
+Your turn finishes. The question waits as a row in the user's inbox, 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_answer(
+    "Standardise how we read CSV files, or leave the odd one out?",
+    detail="Standardising means one way to maintain instead of two, and a day's work "
+           "now. Leaving it means the old path stays until something breaks it. "
+           "Either is fine by me — it is your call which we live with.",
+    choices=["standardise", "leave it"],
+)
+return "Asked about the CSV readers — everything else is done."
+```
+
+Writing the rest of the turn as though the answer were in hand is the way this
+goes wrong. There is no answer in the return value and there will not be one
+before your turn ends.
+
+## Who is reading it
+
+Somebody who has not seen the code, and will not go and look.
+
+This is the thing agents get wrong first, and it is not a style preference — it
+decides whether the question is answerable at all. Your message lands in an
+inbox beside the other things a person has to decide today. They will not open
+the file. They do not know what the class is called. They will not ask you a
+follow-up before deciding; they will answer wrongly, or leave it.
+
+So: no file paths, no symbol names, no branch names, no test names. Name the
+**trade-off**, in the words you would use saying it out loud.
+
+A real message, and the reply it actually got:
+
+> **Convert legacy/csv.ts to the shared parser?**
+>
+> It has hand-rolled quote handling that gets embedded newlines inside a quoted
+> field right, and the shared parser does not. Convert it and we lose that case,
+> which the fixtures do exercise. Leave it and we keep two parsers.
+
+> — *what's the context of this?*
+
+The same decision, asked so it can be answered:
+
+> **Two ways to handle CSV imports — which matters more here?**
+>
+> One copes with unusual files that the other mangles. The other is half the
+> code to maintain. I can go either way; I only need to know which you would
+> rather live with.
+
+Nothing was removed but the vocabulary. The second is shorter, and it is the
+one a person can act on without opening anything.
+
+**Three lines is plenty.** If the decision will not go in three, the thing to
+send is a smaller decision.
+
+## Options
+
+- **`question`** — what you want decided, as a full sentence, in the user's
+  terms. It is the headline of a row read at a glance beside others, so it has
+  to make sense to somebody who has not read your transcript.
+- **`detail`** — **what you will do with each answer.** The user is choosing
+  between outcomes, not between words. A question that does not say what
+  follows from it is one they cannot answer well, and they will ask you what
+  you meant instead of answering — a whole round trip for a sentence you could
+  have written.
+- **`choices`** — labels that become buttons beside the reply box. A shortcut,
+  not a constraint: the reply box is always there and the user can write
+  something you did not offer. **Read what they wrote, do not match on the
+  label.**
+
+## Returns
+
+```python
+{"status": "queued", "id": "inbox-1757280000000-a1b2c3"}
+```
+
+A **receipt, not an answer**. `id` is the row it left behind. Nothing in this
+dict tells you what the user decided, because at the moment it returns they have
+not seen the question.
+
+## Getting it wrong
+
+**Comparing the answer against your own `choices` with `==`.** When the answer
+arrives it is prose the user typed, and a label they clicked is only the most
+likely case.
+
+```python
+# Wrong — silently takes the else branch when they typed anything at all.
+if answer == "convert it":
+    ...
+
+# Right — read it.
+if "convert" in answer.lower():
+    ...
+```
+
+**Treating the return value as the decision.** `{"status": "queued"}` means the
+question was filed, not answered. Branching on it branches on nothing.
+
+**Asking what you could find out.** If the answer is in the repo, read the repo.
+A question costs the user attention you can only spend once, and a row they did
+not need is a row that makes the next one slower to reach.
+
+**Asking for reassurance about a plan.** Permission prompts already cover the
+gated calls. This is for a decision that changes *what* you build.
+
+**Sending news.** An inbox row is something to act on. "Rebased onto main"
+belongs in your reply; there is no request for it, and there is deliberately no
+way to file one.
+
+## See also
+
+`ask_user` — the same question asked *now*, blocking your turn until they pick.
+Reach for it when the answer changes what the very next line of code does and
+you are sitting in a session somebody is watching. Reach for `request_answer`
+when the answer changes what happens next *session*, or when nobody is watching
+— eight agents finishing overnight cannot each hold a turn open on a human who
+is asleep.
+
+`request_review` — the same non-blocking shape for "this is ready to look at"
+rather than "I need you to choose".
+
+`request_user_action`, `request_operator_action`, `phase_complete`,
+`man('overview')`