@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/xylon_blame.md

@@ -0,0 +1,80 @@
+# api.xylon_blame(path, line, end_line=None, tree_name=None) -> dict
+<!-- also: blame, who-wrote-this, line_origin, git_blame -->
+<!-- group: Xylon -->
+
+Which task, agent and tool call wrote a line of code. Not gated; writes nothing.
+
+`git blame` says which commit last changed a line. This carries on from there
+through WidgeX's own record:
+
+1. **Commit to task.** Each task records the commits it made, and that record
+   outlives its branch. A commit newer than the record is found through the open
+   tasks' working copies. A merge commit names the branch it merged.
+2. **Task to agent.** Every session that worked in the task is in its folder.
+3. **Agent to tool call.** The transcripts keep every tool call with its input.
+   An edit whose new text contains the line is the one that wrote it.
+
+Use it when you need to know *why* a line is the way it is: the conversation
+around the edit usually says.
+
+## Result
+
+```python
+{"tree": "widgex", "file": "widgex-ide/extension/src/services/handoff.ts",
+ "lines": [
+   {"from": 41, "to": 41, "text": "export const HANDOFF_TAIL_MAX = 20_000;",
+    "commit": {"sha": "3f2a…", "subject": "Hand-offs keep the tail…",
+               "author": "…", "at": "2026-10-09T…"},
+    "task": {"title": "Switch models mid-conversation", "ref": "widgex/switch-models-1a2b3c4d",
+             "branch": "widgex/switch-models", "via": "task-record"},
+    "agent": {"node": "widgex/switch-models-1a2b3c4d/session2", "model": "claude-opus-5"},
+    "edit": {"tool": "Edit", "tool_use_id": "toolu_…", "at": "2026-10-09T…",
+             "turn": 14, "match": "exact", "excerpt": "…HANDOFF_TAIL_MAX = 20_000…"}}]}
+```
+
+- Consecutive lines with the same commit and the same edit come back as one
+  entry, `from` to `to`.
+- **`task.via`** says how the task was found: `task-record`, `worktree`,
+  `merge-subject`, or `uncommitted` for a line you or your task wrote and nobody
+  has committed yet.
+- **`edit.match`**: `exact` means the edit's new text contains the line.
+  `file` means the call touched the file but the text is not in it. That is
+  usually a `sed` or a script run through the shell, and the attribution is a
+  best guess.
+- **`commit: None`**: not committed yet. **`task: None`**: no task made that
+  commit, because a person did, or it predates WidgeX. **`edit: None`**: the
+  task is known but no tool call in its sessions touched the file.
+
+## Examples
+
+Why is this line here?
+
+```python
+b = await api.xylon_blame("src/services/handoff.ts", 41)
+hit = b["lines"][0]
+if hit["edit"]:
+    return await api.xylon_read_turns(hit["agent"]["node"], around=hit["edit"]["turn"])
+return hit
+```
+
+Who wrote this function?
+
+```python
+b = await api.xylon_blame("src/services/handoff.ts", 68, end_line=80)
+return [(l["from"], l["to"], l["task"] and l["task"]["title"]) for l in b["lines"]]
+```
+
+## Getting it wrong
+
+**Reading `match: 'file'` as certain.** It names the last call that touched the
+file before the commit, not one known to have written the line.
+
+**Blaming a whole file.** At most 50 lines per call. For a file's history,
+`git log --follow` through `api.bash` is the better tool.
+
+**Passing another worktree's path without `tree_name`.** The tasks searched are
+your own project's.
+
+## See also
+
+`xylon_search`, `xylon_read`, `compact`

package/python/xactor/man/xylon_read.md

@@ -0,0 +1,131 @@
+# api.xylon_list_trees() / xylon_get_tree / xylon_get_node / xylon_read_messages
+<!-- also: xylon_list_trees, xylon_get_tree, xylon_get_node, xylon_read_messages -->
+<!-- group: Xylon -->
+
+The four read calls on the session tree. None is gated; none writes.
+
+The path grammar is shared by three of the four, and it is most of what there is
+to know, so they live on one page.
+
+## Session paths
+
+A path is `{repo}/{issue}/{session}` under a project. Sessions are **files** in
+an issue's directory and are always siblings — nothing nests.
+
+- **`.`** — this session.
+- **`..`** — the session yours came from, read off `parent` on your header.
+- **a bare `sessionN`** — a sibling in your own issue.
+- **anything with slashes** — absolute: `widgex-ide/fix-relay/session3`.
+
+`tree_name` defaults to this session's own project.
+
+**A relative path cannot be combined with a different `tree_name`.** You get
+`Cannot use a relative node_path ('..') with a different tree_name ('other')` —
+`..` has no meaning over there. Other refusals: an empty `node_path`, a session
+that has no address yet ("nothing to be relative to"), and `..` on the first
+session in an issue, which came from nothing.
+
+## The calls
+
+### `xylon_list_trees() -> dict`
+
+```python
+{"working": [{"name", "sourceName", "path", "createdAt"}],
+ "saved":   [{"name", "sizeBytes", "modifiedAt"}]}
+```
+
+**Two lists, not one.** `working` trees are unpacked and live. `saved` trees are
+`.wxylon` archives. A name can appear in both.
+
+### `xylon_get_tree(tree_name=None) -> dict`
+
+The whole project, three levels deep: repos, the issues in each, and the
+sessions in each issue. Headers only — no transcripts.
+
+### `xylon_get_node(node_path, tree_name=None) -> dict`
+
+```python
+{"name": str, "path": str, "tree": str,
+ "hasCosm": bool, "cosmData": dict | None, "children": [...]}
+```
+
+`path` and `tree` are **what your arguments resolved to** — the whole point of
+them is that `.`, `..` and an omitted `tree_name` are otherwise opaque. `name`
+is only the last segment, and on its own it identifies nothing: the first
+session in every issue is called `session1`.
+
+To find out what *you* are called, prefer the name in your system prompt. It is
+`issue/session`, which is the form other agents address you by.
+
+`children` is always empty: a session is a leaf, and its siblings are found by
+listing the issue rather than by descending into it.
+
+`hasCosm` false means there is no file at that path. `cosmData` is the header:
+`summary`, `summaryKind` (`'handoff'` or `'final'`), `parent`, `branch`,
+`files` — the repo-relative paths the session wrote, in the order it first
+touched them — and `usage`, tokens and cost per `<provider>/<model>`.
+
+### `xylon_read_messages(node_path, tree_name=None) -> list[dict]`
+
+The transcript, as a list of message objects. **This is large.** A full session
+transcript can be a substantial fraction of your context. If what you want is
+what was *said* — not what tools printed — `xylon_read_turns` returns only that,
+a page at a time.
+
+A sealed session's transcript is gzipped on disk and inflated here, so this
+costs more than the header read above it whatever the file size suggests.
+
+## Examples
+
+What did the session that spawned me do?
+
+```python
+msgs = await api.xylon_read_messages("..")
+return f"parent said {len(msgs)} things"
+```
+
+What files have *I* written to so far?
+
+```python
+me = await api.xylon_get_node(".")
+return me["cosmData"].get("files") or "nothing yet"
+```
+
+Reading a child's work after joining it:
+
+```python
+r = await api.session_join(child_id, timeout=900)
+if r["status"] == "done":
+    return await api.xylon_get_node(r["xylonNodePath"])
+return r
+```
+
+Finding a tree by name:
+
+```python
+trees = await api.xylon_list_trees()
+return [t["name"] for t in trees["working"]]
+```
+
+## Getting it wrong
+
+**Expecting bash edits in `files`.** They are not there, and nothing warns you.
+
+**Reading `..` as a matter of course.** A three-sentence `summary` on
+`agent` costs a fraction of a transcript. The parent read is the
+fallback for when the brief was not enough.
+
+**Reading `files` as a diff.** It is a list of paths and says nothing about what
+changed in them. `git diff` on the Issue's branch is what answers that.
+
+**Passing `tree_name` alongside `..`.** Refused.
+
+**Treating `xylon_list_trees` as a list.** It is a dict of two lists. Iterating
+it gives you the strings `"working"` and `"saved"`.
+
+**Expecting a write call.** There is none. Summaries and the file list are the
+IDE's job.
+
+## See also
+
+`xylon`, `xylon_search`, `agent`, `session_join`, `bash`

package/python/xactor/man/xylon_search.md

@@ -0,0 +1,125 @@
+# api.xylon_search(query=None, who=None, tree_name=None, limit=20) / xylon_read_turns
+<!-- also: xylon_read_turns -->
+<!-- group: Xylon -->
+
+Find past work by what was said in it, then read just the part that matters.
+Neither is gated; neither writes.
+
+Every conversation in a project is kept. These two calls search and read the
+**prose** of them — what the user typed and what agents answered — and leave out
+tool calls and their output, which is most of a transcript and almost never what
+you are looking for.
+
+## `xylon_search(query=None, who=None, tree_name=None, limit=20) -> dict`
+
+```python
+{"query": "notarize",
+ "total": 3,                      # tasks that matched, before limit
+ "tasks": [
+   {"tree": "widgex", "task": "widgex/release-signing",
+    "title": "Release signing on CI", "open": False,
+    "branch": "ci-signing", "updatedAt": "2026-10-09T…",
+    "bullets": ["CI signs from a keychain it creates for each job", …],
+    "mentions": 4,
+    "hits": [{"node": "widgex/release-signing/3f2a…", "turn": 12,
+              "who": "user", "at": "2026-10-09T…",
+              "text": "…why does notarize hang on the runner"}]}]}
+```
+
+- **`query`** — every word must be in the same turn. Case is ignored and a word
+  matches inside a longer one, so `notariz` finds *notarize* and *notarization*.
+  `"a quoted phrase"` is matched whole. There is no stemming and nothing fuzzy:
+  a miss means it was not said in those words, so try another word before
+  concluding it never came up.
+- **No query** lists the most recent tasks with what each built and its
+  conversations (`conversations: [{node, turns, brief?}]`) — the answer to "what
+  has been done here".
+- **`who='user'`** keeps only what a person typed. That is the strongest signal
+  for what was *asked for* and *decided*; agents repeat a term across a dozen
+  replies for every once it was asked about. A prompt another agent relayed
+  carries `from` and counts as neither side.
+- **`tree_name`** defaults to your own project. `'*'` searches every project on
+  this machine.
+
+Tasks come best first: one named for the query, then by the best hit, the
+user's own words ahead of an agent's, newer ahead of older. `hits` holds up to
+three per task; `mentions` is how many turns matched in all.
+
+`bullets` is what the task built, a line each. It is empty for a task nobody has
+summarised yet — that says nothing about whether work was done.
+
+**`reading` means the answer is partial.** The first search on a machine reads
+every conversation once (seconds for hundreds of megabytes). If that is still
+going after twenty seconds the call returns what it has with
+`"reading": {"done": 120, "total": 271}`. Ask again.
+
+## `xylon_read_turns(node_path, tree_name=None, around=None, before=3, after=3, who=None, offset=0, limit=40, max_chars=4000) -> dict`
+
+```python
+{"tree": "widgex", "node": "widgex/release-signing/3f2a…", "total": 58,
+ "turns": [{"n": 11, "who": "agent", "at": "…", "text": "…"},
+           {"n": 12, "who": "user",  "at": "…", "text": "why does notarize hang…"}],
+ "more": True}
+```
+
+`node_path` is a hit's `node`, or `.` / `..` as for `xylon_get_node`.
+
+- **`around=turn`** returns that turn with `before` ahead of it and `after`
+  behind. This is how a hit is opened up.
+- Without `around`, a page: `limit` turns from `offset`. `more` says whether
+  there are turns after the last one returned; `total` is how many there are.
+- A turn longer than `max_chars` is cut and carries `clipped`. Raise `max_chars`
+  for the one turn you need whole rather than for a page.
+
+Turn numbers are stable: a turn keeps its `n` as the conversation goes on.
+
+## Examples
+
+Has this been dealt with before?
+
+```python
+found = await api.xylon_search("notarize hang")
+return [(t["title"], t["mentions"], t["hits"][:1]) for t in found["tasks"]]
+```
+
+Open the best hit:
+
+```python
+hit = found["tasks"][0]["hits"][0]
+return await api.xylon_read_turns(hit["node"], around=hit["turn"])
+```
+
+What did the user actually ask for in that conversation?
+
+```python
+return await api.xylon_read_turns(hit["node"], who="user", limit=100)
+```
+
+What has been done in this project lately?
+
+```python
+recent = await api.xylon_search(limit=10)
+return [(t["title"], t["bullets"]) for t in recent["tasks"]]
+```
+
+## Getting it wrong
+
+**Reaching for `xylon_read_messages` to find something.** It returns one whole
+transcript, tool output included, and you would have to know which one. Search,
+then read turns.
+
+**Searching for a sentence.** Every word has to be in one turn. Two or three
+distinctive words find more than a description does.
+
+**Treating no hits as "never discussed".** It is keyword search. The same thing
+may have been called something else — and tool output is not searched at all, so
+a string that only ever appeared in a log will not be found.
+
+**Ignoring `reading`.** A partial answer with no hits is not a "no".
+
+**Passing a hit's `node` with another project's `tree_name` omitted.** After a
+`tree_name='*'` search, pass the task's `tree` along with the node.
+
+## See also
+
+`xylon`, `xylon_list_trees`, `ask_reference`

package/python/xactor/manual.py

@@ -0,0 +1,195 @@
+"""The bundled manual — one markdown page per api call and per WidgeX feature.
+
+Pages live in ``man/`` beside this module and are read straight off disk. No
+bridge call, no permission, and it works in every sandbox mode: the shell's
+Python process runs with ``<extension>/python`` as its cwd, which puts that
+directory on ``sys.path``, and ``sandbox._python_prefixes`` always allows reads
+under a ``sys.path`` prefix. The read happens inside ``api_scope`` — the same
+thing that lets ``read_file`` call a bare ``open()``.
+
+Named ``manual.py`` rather than ``man.py`` so the module never sits ambiguously
+beside the ``man/`` directory it reads, and so ``man/*.md`` means exactly "every
+page" with no ``__init__.py`` to exclude from the glob.
+
+A page's names are its filename stem plus anything in an ``also:`` comment, so
+adding ``foo.md`` for a new ``api.foo`` is complete on its own. Only pages that
+cover a family of calls need the comment. The alternative — a registry mapping
+names to files — costs two edits per method and makes "the page exists but
+nothing resolves to it" the *default* failure rather than an unusual one.
+"""
+
+import difflib
+import functools
+from pathlib import Path
+from typing import Any
+
+# .resolve() because sandbox.py canonicalises both its allowed prefixes and the
+# path being opened; an unresolved path here would be compared against resolved
+# prefixes and could miss on a symlinked or short-name install path.
+MAN_DIR = Path(__file__).resolve().parent / "man"
+
+_ALSO = "<!-- also:"
+_GROUP = "<!-- group:"
+
+# How the index orders its sections. Anything with a group not named here is
+# sorted alphabetically after these, so a new group appears rather than vanishes.
+GROUP_ORDER = (
+    "Coding",
+    "Talking to the user",
+    "Subagents",
+    "Talking to other agents",
+    "Sessions",
+    "Xylon",
+    "Working on a website",
+    "Reporting a WidgeX problem",
+    "Documentation",
+    "Concepts",
+)
+
+# Front matter is only ever at the top; scanning the whole file would let a
+# fenced code block containing an `also:` line hijack a page's names.
+_FRONT_MATTER_LINES = 6
+
+
+def _normalize(topic: str) -> str:
+    """Reduce a topic to its lookup key.
+
+    Agents reach for this call precisely when they are unsure, so the spellings
+    that arrive are the ones a model would guess: ``api.bash``, ``bash()``,
+    ``await api.session_join``, ``session join``. All of them should land.
+    """
+    text = topic.strip().lower()
+    for prefix in ("await ", "api.", "widgex_terminal.", "man "):
+        if text.startswith(prefix):
+            text = text[len(prefix):].strip()
+    text = text.rstrip("()").strip()
+    return text.replace(" ", "-").replace("_", "-")
+
+
+def _strip_comment(line: str, marker: str) -> str:
+    """Pull the payload out of a ``<!-- marker: payload -->`` line."""
+    body = line[len(marker):].strip()
+    if body.endswith("-->"):
+        body = body[:-3]
+    return body.strip()
+
+
+def _parse(path: Path) -> dict[str, Any]:
+    """Read one page and pull out its title, blurb, names and group."""
+    # utf-8-sig, never the default: Path.read_text() falls back to the locale
+    # encoding, which is cp1252 on a stock Windows box and mangles every em-dash
+    # in these pages. The -sig also drops a BOM that would otherwise end up
+    # glued to the leading '#' and break the title parse.
+    text = path.read_text(encoding="utf-8-sig")
+    lines = text.splitlines()
+
+    title = lines[0].lstrip("#").strip() if lines else path.stem
+    also: list[str] = []
+    group = "Other"
+    blurb = ""
+
+    for line in lines[1:_FRONT_MATTER_LINES]:
+        stripped = line.strip()
+        if stripped.startswith(_ALSO):
+            also = [n.strip() for n in _strip_comment(stripped, _ALSO).split(",") if n.strip()]
+        elif stripped.startswith(_GROUP):
+            group = _strip_comment(stripped, _GROUP) or "Other"
+        elif stripped and not stripped.startswith("<!--") and not blurb:
+            blurb = stripped
+
+    return {
+        "stem": path.stem,
+        "title": title,
+        "blurb": blurb,
+        "group": group,
+        "names": [path.stem, *also],
+        "text": text,
+    }
+
+
+@functools.lru_cache(maxsize=1)
+def _index() -> tuple[dict[str, dict[str, Any]], tuple[dict[str, Any], ...]]:
+    """Build ``({normalized name: page}, all pages)``. Cached; pages ship read-only."""
+    pages = [_parse(p) for p in sorted(MAN_DIR.glob("*.md"))]
+    by_name: dict[str, dict[str, Any]] = {}
+    for page in pages:
+        for name in page["names"]:
+            by_name.setdefault(_normalize(name), page)
+    return by_name, tuple(pages)
+
+
+def _index_page(pages: tuple[dict[str, Any], ...]) -> str:
+    """The contents listing, generated so it cannot fall behind the pages."""
+    out = [
+        "# The WidgeX api manual",
+        "",
+        "`await api.man(name)` returns any page below. Names are forgiving —",
+        "`'bash'`, `'api.bash'` and `'bash()'` all reach the same page.",
+        "",
+    ]
+
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for page in pages:
+        grouped.setdefault(page["group"], []).append(page)
+
+    ordered = [g for g in GROUP_ORDER if g in grouped]
+    ordered += sorted(g for g in grouped if g not in GROUP_ORDER)
+
+    for group in ordered:
+        out.append(f"## {group}")
+        for page in sorted(grouped[group], key=lambda p: p["stem"]):
+            out.append(f"  {page['stem']:<26}  {page['blurb']}".rstrip())
+        out.append("")
+
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _miss(topic: str, key: str, by_name: dict[str, dict[str, Any]],
+          partial: list[dict[str, Any]]) -> str:
+    """What to say when nothing matched.
+
+    Returned, never raised — see ``lookup``.
+    """
+    out = [f"No manual page for {topic!r}."]
+
+    if partial:
+        stems = sorted({p["stem"] for p in partial})
+        out += ["", "Did you mean: " + ", ".join(stems) + "?"]
+    else:
+        close = difflib.get_close_matches(key, sorted(by_name), n=3, cutoff=0.6)
+        stems = list(dict.fromkeys(by_name[c]["stem"] for c in close))
+        if stems:
+            out += ["", "Closest matches: " + ", ".join(stems)]
+
+    out += ["", "`await api.man()` lists every topic."]
+    return "\n".join(out)
+
+
+def lookup(topic: str | None = None) -> str:
+    """The page for ``topic``, or the index when it is omitted.
+
+    Never raises. An unknown topic comes back as prose suggesting near misses,
+    because this is the call an agent makes when it does *not* know something —
+    if getting the name wrong could abort the exec, the surrounding work dies
+    with it and guessing becomes the cheaper strategy. That is the exact
+    incentive this call exists to reverse.
+    """
+    by_name, pages = _index()
+
+    if not isinstance(topic, str) or not topic.strip():
+        return _index_page(pages)
+
+    key = _normalize(topic)
+    page = by_name.get(key)
+    if page is not None:
+        return page["text"]
+
+    # A prefix that reaches exactly one page is an answer, not a miss:
+    # 'session_ext' can only mean session_extend. Several pages means the agent
+    # is browsing a family ('browser'), so name them instead of guessing.
+    partial = [by_name[n] for n in sorted(by_name) if n.startswith(key)]
+    unique = {p["stem"]: p for p in partial}
+    if len(unique) == 1:
+        return next(iter(unique.values()))["text"]
+
+    return _miss(topic, key, by_name, partial)

package/python/xactor/parent_watch.py

@@ -0,0 +1,115 @@
+"""Leave when the process that started this daemon is gone.
+
+The daemon's normal way out is EOF on stdin: the host closes the pipe, the read
+loop stops, the interpreter exits. That depends on the pipe closing reaching
+*this* process, and on Windows it often does not. `python3` there is commonly a
+launcher — the Python install manager's, a venv redirector — that starts the
+real `python.exe` as a child and relays stdio to it, and a host that dies or
+calls `process.exit()` closes the launcher's pipe without the child ever seeing
+EOF. Both processes then live on with nothing to read, naming their worktree on
+the command line, and with their background commands standing in it: a closed
+task's folder that can never be deleted. 138 of them were found on one machine,
+almost all left behind by test runs in task worktrees.
+
+So the host passes its own pid in `WIDGEX_PARENT_PID`, and this watches that
+process directly. On Windows it holds a handle opened at startup, while the
+parent was certainly alive, so a later process given the same pid cannot be
+mistaken for it. Elsewhere it watches `getppid()` and, when a launcher sits in
+between, polls the pid.
+
+The variable is removed from the environment once read: commands this daemon
+starts inherit its environment, and one of them starting a daemon of its own
+must watch *its* parent, not ours.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Callable
+
+ENV = "WIDGEX_PARENT_PID"
+
+_POLL_S = 2.0
+_SYNCHRONIZE = 0x00100000
+_INFINITE = 0xFFFFFFFF
+
+
+def _parent_pid() -> int | None:
+    raw = os.environ.pop(ENV, None)
+    if not raw:
+        return None
+    try:
+        pid = int(raw)
+    except ValueError:
+        return None
+    return pid if pid > 0 else None
+
+
+def watch(on_gone: Callable[[], None]) -> bool:
+    """Call `on_gone` from a background thread once the host process exits.
+
+    Returns whether a watch was started. Started before the sandbox is
+    installed, so the handle is opened while nothing refuses it.
+    """
+    pid = _parent_pid()
+    if pid is None or pid == os.getpid():
+        return False
+
+    if sys.platform == "win32":
+        import _winapi
+
+        try:
+            handle = _winapi.OpenProcess(_SYNCHRONIZE, False, pid)
+        except OSError:
+            # Gone already, or not ours to open. The first is worth acting on;
+            # the second cannot be told apart from it here, and a daemon that
+            # leaves because it could not watch is worse than one that does
+            # not watch — EOF still works wherever it reaches us.
+            return False
+
+        def wait() -> None:
+            _winapi.WaitForSingleObject(handle, _INFINITE)
+            on_gone()
+    else:
+        direct = os.getppid() == pid
+
+        def alive() -> bool:
+            if direct:
+                return os.getppid() == pid
+            try:
+                os.kill(pid, 0)
+            except ProcessLookupError:
+                return False
+            except PermissionError:
+                return True
+            return True
+
+        def wait() -> None:
+            while alive():
+                time.sleep(_POLL_S)
+            on_gone()
+
+    threading.Thread(target=wait, name="xactor-parent-watch", daemon=True).start()
+    return True
+
+
+def leave() -> None:
+    """Stop what this daemon started, then exit without waiting on anything.
+
+    `os._exit` rather than a normal shutdown: a normal one is exactly what has
+    already failed to happen, and it waits on threads that may never finish.
+    Background commands are stopped first, since they are what actually stands
+    in the worktree.
+    """
+    # Only if it is loaded: the browser backend never imports it, and importing
+    # it here would run its module setup on the way out.
+    stdlib_api = sys.modules.get(f"{__package__}.stdlib_api")
+    try:
+        if stdlib_api is not None:
+            stdlib_api._stop_background_commands()
+    except BaseException:  # noqa: BLE001 — leaving regardless
+        pass
+    os._exit(0)