@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/seals.py

@@ -0,0 +1,438 @@
+"""Offline WidgeX marker enforcement for Python-only file operations.
+
+The shell owns this implementation because reads and searches never cross the
+TypeScript bridge. A bridge lookup would both add an RPC per read and disappear
+when permissions are bypassed, precisely where an absolute organisational rule
+must remain present.
+
+Three layers live here: `check_call` judges an api call by its arguments (the
+file tools, plus `drive`/`navigate`/`browser_open_tab` URLs and `aux_context`);
+`check_event` is the audit hook's backstop for every file any other api body
+opens; and the index remembers every seal it has seen, so a rewrite that drops
+one does not unseal the file. Shell *commands* are judged in TypeScript
+(`sealGate.ts`), which is where the permission request for them goes, and
+their output is screened there too (`sealScreen.ts`).
+"""
+
+import contextlib
+import contextvars
+import hashlib
+import os
+import re
+import time
+from dataclasses import dataclass
+from typing import Any, Iterator
+
+_PREFIX = "WGX" + "SEAL"
+SEAL_DOC_DIRECTIVE = _PREFIX + "-DOC"
+SEAL_OP_ORDER = "RWXCM"
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_CHUNK_DOMAIN = _PREFIX + "/v1/model\n"
+_CHUNK_BYTES = 5
+_CHUNK_SYMBOLS = 8
+_MAX_SEAL_BYTES = 7 + 1 + 5 + 1 + (64 * 8) + 63
+_SCAN_CHUNK_BYTES = 256 * 1024
+_OVERLAP_BYTES = _MAX_SEAL_BYTES
+_HUGE_FILE_BYTES = 64 * 1024 * 1024
+_HUGE_HEAD_BYTES = 8 * 1024 * 1024
+_HUGE_TAIL_BYTES = 1 * 1024 * 1024
+_RECENT_WRITE_SECONDS = 2
+_MAX_ENTRIES = 5000
+_CROCKFORD_CLASS = "[0-9A-HJKMNP-TV-Z]"
+
+# Assembly keeps this engine's grammar from becoming a live marker if the
+# quarantine directive is ever damaged. The scanner must not make its own
+# enforcement source uneditable merely because it explains the syntax.
+_SEAL_RE = re.compile(
+    rf"(?<![0-9A-Za-z]){_PREFIX}-([{SEAL_OP_ORDER}]{{1,5}})"
+    rf"(?:-({_CROCKFORD_CLASS}{{{_CHUNK_SYMBOLS}}}(?:-{_CROCKFORD_CLASS}{{{_CHUNK_SYMBOLS}}}){{0,63}}))?"
+    rf"(?![-0-9A-Za-z])"
+)
+_DOC_RE = re.compile(rf"(?<![0-9A-Za-z]){SEAL_DOC_DIRECTIVE}(?![-0-9A-Za-z])")
+
+
+@dataclass(frozen=True)
+class ParsedSeal:
+    raw: str
+    source: str
+    index: int
+    denied_ops: frozenset[str]
+    chunks: tuple[str, ...]
+
+
+def has_seal_doc_directive(text: str) -> bool:
+    return bool(_DOC_RE.search(text))
+
+
+def normalize(ops: Any) -> list[str]:
+    seen: set[str] = set()
+    for raw in ops:
+        for char in str(raw).upper():
+            if char in SEAL_OP_ORDER:
+                seen.add(char)
+    return [op for op in SEAL_OP_ORDER if op in seen]
+
+
+def model_chunk(key: str) -> str:
+    digest = hashlib.sha256((_CHUNK_DOMAIN + key).encode("utf-8")).digest()[:_CHUNK_BYTES]
+    value = 0
+    bits = 0
+    out: list[str] = []
+    for byte in digest:
+        value = (value << 8) | byte
+        bits += 8
+        while bits >= 5:
+            out.append(_CROCKFORD[(value >> (bits - 5)) & 31])
+            bits -= 5
+    if bits:
+        out.append(_CROCKFORD[(value << (5 - bits)) & 31])
+    return "".join(out)
+
+
+def _find(text: str, source: str) -> list[ParsedSeal]:
+    if not text or _PREFIX not in text or has_seal_doc_directive(text):
+        return []
+    return [ParsedSeal(match.group(0), source, match.start(), frozenset(normalize([match.group(1)])),
+                       tuple(match.group(2).split("-")) if match.group(2) else ())
+            for match in _SEAL_RE.finditer(text)]
+
+
+def find_seals_in_text(text: str) -> list[ParsedSeal]:
+    return _find(text, "text")
+
+
+def find_seals_in_path(file_path: str) -> list[ParsedSeal]:
+    return _find(str(file_path).replace("\\", "/"), "path")
+
+
+def seal_candidate_keys(model: Any) -> list[str]:
+    if isinstance(model, dict):
+        provider, model_id = str(model.get("providerId", "")), str(model.get("modelId", ""))
+    elif isinstance(model, (tuple, list)) and len(model) == 2:
+        provider, model_id = str(model[0]), str(model[1])
+    else:
+        value = str(model)
+        provider, sep, model_id = value.partition("/")
+        if not sep:
+            provider, model_id = "", value
+    bare = re.sub(r"-(?:\d{4}-\d{2}-\d{2}|\d{8})$", "", model_id)
+    return list(dict.fromkeys([f"{provider}/{model_id}", model_id, f"{provider}/{bare}", bare, f"{provider}/*"]))
+
+
+def seal_applies_to(seal: ParsedSeal, model: Any) -> bool:
+    return not seal.chunks or bool(set(seal.chunks) & {model_chunk(key) for key in seal_candidate_keys(model)})
+
+
+def denied_ops_for(seals: list[ParsedSeal], model: Any) -> set[str]:
+    denied: set[str] = set()
+    for seal in seals:
+        if seal_applies_to(seal, model):
+            denied.update(seal.denied_ops)
+    return denied
+
+
+def _true_case(path: str) -> str:
+    """`path` with each existing component spelled as the filesystem spells it.
+
+    Only matters where names are case-insensitive: there a lowercased spelling
+    of a sealed folder's name lands inside that folder, and only the real,
+    uppercase spelling parses as a seal. `realpath` does not correct case on
+    macOS, so each component is matched against its directory there. Windows'
+    realpath already answers with the real spelling of the longest existing
+    prefix, and elsewhere names are case-sensitive.
+    """
+    if os.sys.platform != "darwin":
+        return path
+    drive, rest = os.path.splitdrive(path)
+    parts = [p for p in re.split(r"[\\/]+", rest) if p]
+    current = drive + os.sep if (drive or rest.startswith(("/", "\\"))) else ""
+    for i, part in enumerate(parts):
+        try:
+            names = os.listdir(current or ".")
+        except OSError:
+            return os.path.join(current, *parts[i:]) if current else path
+        match = next((n for n in names if n.lower() == part.lower()), None)
+        current = os.path.join(current, match if match is not None else part)
+        if match is None:
+            return os.path.join(current, *parts[i + 1:])
+    return current or path
+
+
+@dataclass
+class _CacheEntry:
+    mtime_ns: int
+    ctime_ns: int
+    size: int
+    marks: list[ParsedSeal]
+    truncated: bool
+
+
+class _Index:
+    def __init__(self) -> None:
+        self.cache: dict[str, _CacheEntry] = {}
+        # Every body seal ever seen on a path. A rescan that finds fewer keeps
+        # the missing ones: `sed -i` on the marker line, or appending the DOC
+        # directive, must not unseal a file. Mirrors `SealIndex.seen` in TS.
+        self.seen: dict[str, list[ParsedSeal]] = {}
+
+    def _remember(self, key: str, marks: list[ParsedSeal]) -> list[ParsedSeal]:
+        before = self.seen.get(key, [])
+        if not before and not marks:
+            return marks
+        now = {mark.raw for mark in marks}
+        kept = [mark for mark in before if mark.raw not in now]
+        merged = [*marks, *kept]
+        self.seen[key] = merged
+        return merged
+
+    def forget(self, file_path: str | None = None) -> None:
+        if file_path is None:
+            self.cache.clear()
+            self.seen.clear()
+            return
+        resolved = os.path.abspath(file_path)
+        key = os.path.normcase(resolved) if os.name == "nt" or os.sys.platform == "darwin" else resolved
+        self.cache.pop(key, None)
+        self.seen.pop(key, None)
+
+    def _path_marks(self, path: str) -> list[ParsedSeal]:
+        marks = find_seals_in_path(path)
+        try:
+            real = _true_case(os.path.realpath(path))
+        except OSError:
+            real = path
+        if real == path:
+            return marks
+        seen = {mark.raw for mark in marks}
+        marks.extend(mark for mark in find_seals_in_path(real) if mark.raw not in seen)
+        return marks
+
+    def _scan(self, path: str, size: int) -> tuple[list[ParsedSeal], bool]:
+        huge = size > _HUGE_FILE_BYTES
+        marks: list[ParsedSeal] = []
+        seen: set[str] = set()
+        quarantined = False
+        try:
+            with open(path, "rb") as file:
+                def scan_span(start: int, end: int) -> None:
+                    nonlocal quarantined
+                    file.seek(start)
+                    carry = b""
+                    while file.tell() < end:
+                        data = file.read(min(_SCAN_CHUNK_BYTES, end - file.tell()))
+                        if not data:
+                            break
+                        text = (carry + data).decode("latin1")
+                        quarantined = quarantined or has_seal_doc_directive(text)
+                        for mark in find_seals_in_text(text):
+                            if mark.raw not in seen:
+                                seen.add(mark.raw)
+                                marks.append(mark)
+                        carry = (carry + data)[-_OVERLAP_BYTES:]
+                if huge:
+                    scan_span(0, _HUGE_HEAD_BYTES)
+                    scan_span(max(_HUGE_HEAD_BYTES, size - _HUGE_TAIL_BYTES), size)
+                else:
+                    scan_span(0, size)
+        except OSError:
+            return [], False
+        return ([] if quarantined else marks), huge
+
+    def marks_for_path(self, file_path: str) -> tuple[list[ParsedSeal], list[ParsedSeal], bool]:
+        resolved = os.path.abspath(file_path)
+        path_marks = self._path_marks(resolved)
+        try:
+            stat = os.stat(resolved)
+        except OSError:
+            return path_marks, [], False
+        if not os.path.isfile(resolved):
+            return path_marks, [], False
+        key = os.path.normcase(resolved) if os.name == "nt" or os.sys.platform == "darwin" else resolved
+        hit = self.cache.get(key)
+        if (hit and hit.mtime_ns == stat.st_mtime_ns and hit.ctime_ns == stat.st_ctime_ns
+                and hit.size == stat.st_size and time.time() - stat.st_mtime > _RECENT_WRITE_SECONDS):
+            return path_marks, hit.marks, hit.truncated
+        marks, truncated = self._scan(resolved, stat.st_size)
+        marks = self._remember(key, marks)
+        self.cache.pop(key, None)
+        self.cache[key] = _CacheEntry(stat.st_mtime_ns, stat.st_ctime_ns, stat.st_size, marks, truncated)
+        while len(self.cache) > _MAX_ENTRIES:
+            self.cache.pop(next(iter(self.cache)))
+        return path_marks, marks, truncated
+
+    def all_marks(self, file_path: str) -> list[ParsedSeal]:
+        path, content, _ = self.marks_for_path(file_path)
+        return [*path, *content]
+
+
+_INDEX = _Index()
+
+
+class SealDenied(PermissionError):
+    pass
+
+
+def _model_name(model_id: Any) -> str:
+    if isinstance(model_id, dict):
+        return f"{model_id.get('providerId', '')}/{model_id.get('modelId', '')}"
+    return str(model_id) if model_id else "an unidentified model"
+
+
+def check_path(op: str, path: str, model_id: Any) -> None:
+    marks = _INDEX.all_marks(path)
+    if not marks:
+        return
+    denied = denied_ops_for(marks, model_id) if model_id else {op for mark in marks for op in mark.denied_ops}
+    if op in denied:
+        culprit = next((mark for mark in marks if op in mark.denied_ops), marks[0])
+        raise SealDenied(f"WidgeX Seal — `{culprit.raw}` on `{path}` forbids {op} for `{_model_name(model_id)}`. "
+                         "This is absolute: no permission mode bypasses it and no approval unlocks it.")
+
+
+def forget(file_path: str | None = None) -> None:
+    """Drop what is remembered about one path, or all of them. Re-scan seals."""
+    _INDEX.forget(file_path)
+
+
+# ── The backstop: every file an api body opens ──────────────────────────
+#
+# `check_call` judges a call by its arguments, which works for the four calls
+# whose arguments *are* the file. Everything else that reads a file on the
+# caller's behalf — an aux_context loader, an importer, a capture — named its
+# path in some other argument or none at all, and was never checked. So the
+# audit hook asks here about every `open`, `os.remove`, `os.rename` and
+# `shutil.copyfile` an api body performs, judged against the model the exec
+# was stamped with.
+#
+# The four that check themselves are exempt, because they legitimately open
+# files the seal forbids *returning*: `write_file` reads the old bytes to judge
+# integrity, `edit_file` has to read what it edits, and `grep` skips sealed
+# files after looking at them. Their own checks are the stricter ones.
+
+SELF_CHECKED = frozenset({"read_file", "write_file", "edit_file", "grep", "glob", "ls"})
+
+_acting_model: contextvars.ContextVar[Any] = contextvars.ContextVar("seal_acting_model", default=None)
+_backstop: contextvars.ContextVar[bool] = contextvars.ContextVar("seal_backstop", default=False)
+
+
+@contextlib.contextmanager
+def acting(model_id: Any, backstop: bool) -> Iterator[None]:
+    """Run an api body as `model_id`, with or without the open() backstop."""
+    model_token = _acting_model.set(model_id)
+    backstop_token = _backstop.set(backstop)
+    try:
+        yield
+    finally:
+        _backstop.reset(backstop_token)
+        _acting_model.reset(model_token)
+
+
+@contextlib.contextmanager
+def internal() -> Iterator[None]:
+    """Opens the shell makes for itself, not for the caller — exempt."""
+    token = _backstop.set(False)
+    try:
+        yield
+    finally:
+        _backstop.reset(token)
+
+
+def backstop_active() -> bool:
+    return _backstop.get()
+
+
+def check_event(op: str, path: str) -> None:
+    """The audit hook's question: may this api body do `op` to `path`?
+
+    Raises `SealDenied`. Called from inside the hook with its re-entrancy guard
+    held, so the scan's own `open` calls are not audited back into here.
+    """
+    if not _backstop.get():
+        return
+    check_path(op, path, _acting_model.get())
+
+
+def _integrity(before: str, after: str) -> ParsedSeal | None:
+    had = find_seals_in_text(before)
+    kept = {seal.raw for seal in find_seals_in_text(after)}
+    return next((seal for seal in had if seal.raw not in kept), None)
+
+
+def local_path_of_url(url: Any) -> str | None:
+    """The file a `file://` URL or a bare absolute path names, or None.
+
+    `api.drive` accepts both, and a browser opened on a sealed file renders its
+    bytes into a page every page verb can read back.
+    """
+    if not isinstance(url, str) or not url.strip():
+        return None
+    text = url.strip()
+    # Every spelling Chromium accepts: file:///x, file:/x, and view-source: of either.
+    if text.lower().startswith("view-source:"):
+        text = text[len("view-source:"):]
+    if text.lower().startswith("file:"):
+        from urllib.parse import unquote, urlparse
+        parsed = urlparse(text)
+        path = unquote(parsed.path)
+        if parsed.netloc and parsed.netloc.lower() != "localhost":
+            path = f"//{parsed.netloc}{path}"  # a UNC share
+        if re.match(r"^/[A-Za-z]:", path):
+            path = path[1:]
+        return path or None
+    if os.path.isabs(text):
+        return text
+    return None
+
+
+# Calls that hand a file to something that will show it to a model, under an
+# argument that is not `path`. Each is a read of that file.
+_URL_ARGS = {"drive": "url", "browser_open_tab": "url", "navigate": "url"}
+_AUX_CALLS = frozenset({"session_fork", "agent"})
+
+
+def check_call(name: str, args: dict[str, Any], model_id: Any) -> None:
+    if name in _URL_ARGS:
+        local = local_path_of_url(args.get(_URL_ARGS[name]))
+        if local:
+            check_path("R", local, model_id)
+        return
+    if name in _AUX_CALLS:
+        aux = args.get("aux_context")
+        if isinstance(aux, str) and aux.strip():
+            check_path("R", aux, model_id)
+        return
+    op = {"read_file": "R", "write_file": "W", "edit_file": "W"}.get(name)
+    if not op:
+        return
+    path = next((args[key] for key in ("file_path", "path", "notebook_path", "filePath")
+                 if isinstance(args.get(key), str) and args[key]), None)
+    if not path:
+        return
+    check_path(op, path, model_id)
+    # An edit is also a read: finding `old_string`, and saying whether it was
+    # found, is an oracle on the file. A read seal refuses it (as `sealGate`).
+    if name == "edit_file":
+        check_path("R", path, model_id)
+    if op != "W":
+        return
+    # Integrity is model-independent: a second, unsealed model must not be able
+    # to remove a marker for the model it serves, or scoped seals are theatre.
+    try:
+        with internal(), open(path, "r", encoding="utf-8", errors="replace") as file:
+            before = file.read()
+    except OSError:
+        return
+    after = args.get("content") if name == "write_file" else None
+    # Bytes are judged as the text they decode to. `write_file` accepts bytes
+    # now, and a marker removed through bytes is removed all the same — left
+    # undecoded, this check would simply have been skipped.
+    if isinstance(after, (bytes, bytearray)):
+        after = bytes(after).decode("utf-8", errors="replace")
+    if name == "edit_file" and isinstance(args.get("old_string"), str) and isinstance(args.get("new_string"), str):
+        old, new = args["old_string"], args["new_string"]
+        after = before.replace(old, new) if args.get("replace_all") else before.replace(old, new, 1)
+    if isinstance(after, str):
+        lost = _integrity(before, after)
+        if lost:
+            raise SealDenied(f"WidgeX Seal — this edit would remove `{lost.raw}` from `{path}`. "
+                             "A seal cannot delete itself, whatever operations it lists.")

package/python/xactor/shell_hints.py

@@ -0,0 +1,210 @@
+"""What went wrong between the layers, said at the layer that did it.
+
+A command on its way to a program crosses the agent's Python string, then
+`bash -c`, then often a second interpreter. Each failure below was read out of
+real transcripts, where it cost a round trip or more because the agent could
+see neither what bash received nor that bash was the one who changed it. The
+error it did see always came from the last layer, and named the symptom.
+
+Two kinds of rule:
+
+* **Definite** — the command is wrong whatever happened when it ran. bash
+  *will* expand `$_` inside double quotes; an unquoted `C:\\Users` *will* lose
+  its backslashes. These are noted every time, because the run that exits 0 is
+  exactly the one that does damage quietly: a `Stop-Process` that stopped
+  nothing, a `type` that read nothing.
+* **On failure** — worth saying only once something has gone wrong, because
+  the same construct is often right: a missing tool, a backslash Python
+  consumed on purpose.
+
+Pure functions over strings, so they can be tested without a shell.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# ── Definite ───────────────────────────────────────────────────────────
+
+_POWERSHELL = re.compile(r"\b(?:powershell|pwsh)(?:\.exe)?\b", re.IGNORECASE)
+_PS_VAR = re.compile(r"(?<!\\)\$(?:_|[A-Za-z][\w:]*|\{|\()")
+
+
+def _double_quoted_after(command: str, start: int) -> str | None:
+    """The first bash double-quoted string after `start`, or None.
+
+    Tracks single quotes, inside which a double quote means nothing, and `\\"`
+    inside double quotes, which does not close them.
+    """
+    i, n = start, len(command)
+    in_single = False
+    while i < n:
+        c = command[i]
+        if in_single:
+            if c == "'":
+                in_single = False
+        elif c == "'":
+            in_single = True
+        elif c in ";|&\n":
+            return None  # the invocation ended without a double-quoted argument
+        elif c == '"':
+            j = i + 1
+            while j < n:
+                if command[j] == "\\":
+                    j += 2
+                    continue
+                if command[j] == '"':
+                    return command[i + 1:j]
+                j += 1
+            return command[i + 1:]
+        i += 1
+    return None
+
+
+def powershell_dollar(command: str) -> str | None:
+    """`$` meant for PowerShell, sitting where bash expands it first."""
+    for m in _POWERSHELL.finditer(command):
+        body = _double_quoted_after(command, m.end())
+        if body is None:
+            continue
+        names = sorted({v.group(0) for v in _PS_VAR.finditer(body)})
+        if names:
+            shown = ", ".join(f"`{n}`" for n in names[:4])
+            return (
+                f"bash expanded {shown} inside the double quotes before PowerShell "
+                "ran — `$_` becomes bash's last argument and other names become "
+                "empty — so PowerShell did not get the script you wrote. Use "
+                "api.powershell(script), which passes it untouched."
+            )
+    return None
+
+
+_DRIVE_BACKSLASH = re.compile(r"[A-Za-z]:\\[^\s'\"]")
+
+
+def unquoted_windows_path(command: str) -> str | None:
+    """A `C:\\...` path outside quotes, whose backslashes bash removes."""
+    in_single = in_double = False
+    i, n = 0, len(command)
+    while i < n:
+        c = command[i]
+        if in_single:
+            if c == "'":
+                in_single = False
+        elif in_double:
+            if c == "\\":
+                i += 2
+                continue
+            if c == '"':
+                in_double = False
+        elif c == "'":
+            in_single = True
+        elif c == '"':
+            in_double = True
+        elif c == "\\":
+            i += 2
+            continue
+        else:
+            m = _DRIVE_BACKSLASH.match(command, i)
+            if m and (i == 0 or not command[i - 1].isalnum()):
+                end = i
+                while end < n and not command[end].isspace() and command[end] not in ";|&":
+                    end += 1
+                path = command[i:end]
+                mangled = path.replace("\\", "")
+                return (
+                    f"bash removes unquoted backslashes, so `{path}` reached the "
+                    f"program as `{mangled}`. Write `{path.replace(chr(92), '/')}`, "
+                    "or quote it."
+                )
+        i += 1
+    return None
+
+
+# ── On failure ─────────────────────────────────────────────────────────
+
+_NOT_FOUND = re.compile(r"(?:^|\n)(?:[^\n:]*: )?(?:line \d+: )?([\w.+-]+): command not found")
+
+# Tools an agent expects and Git Bash on Windows does not have, with the way
+# to get the same thing. Only names seen missing in transcripts.
+_MISSING_TOOLS = {
+    "pkill": "stop processes with api.powershell(\"Stop-Process -Name <name>\")",
+    "pgrep": "list processes with api.powershell(\"Get-Process <name>\")",
+    "killall": "stop processes with api.powershell(\"Stop-Process -Name <name>\")",
+    "python3": "on Windows the interpreter is `python`",
+    "pwsh": "Windows PowerShell is `powershell`, or call api.powershell(script)",
+    "dig": "use `nslookup`, or api.powershell(\"Resolve-DnsName <name>\")",
+}
+
+
+def missing_tool(stderr: str) -> str | None:
+    for m in _NOT_FOUND.finditer(stderr or ""):
+        advice = _MISSING_TOOLS.get(m.group(1))
+        if advice:
+            return f"`{m.group(1)}` is not available in this shell: {advice}."
+    return None
+
+
+_FAILURE_TEXT = re.compile(
+    r"SyntaxError|syntax error|unexpected (?:token|EOF|end of file)|unterminated|"
+    r"is not recognized|No such file|not found|ParserError|Missing (?:expression|closing)",
+)
+
+
+def looks_failed(result: dict[str, Any]) -> bool:
+    """Whether a shell result shows any sign of having gone wrong."""
+    code = result.get("exit_code")
+    if isinstance(code, int) and code != 0:
+        return True
+    return bool(_FAILURE_TEXT.search(result.get("stderr") or ""))
+
+
+def hints_for(command: str, result: dict[str, Any], literal_note: str | None = None) -> list[str]:
+    """Every note this command and its result call for, most specific first."""
+    notes = [h for h in (powershell_dollar(command), unquoted_windows_path(command)) if h]
+    if "background_id" in result:
+        return notes
+    if looks_failed(result):
+        if literal_note:
+            notes.append(literal_note)
+        tool = missing_tool(result.get("stderr") or "")
+        if tool:
+            notes.append(tool)
+    return notes
+
+
+# ── The literal lint, computed when the exec is compiled ───────────────
+
+_ESCAPE = re.compile(r"\\(\\|'|\"|n|t)")
+_SHOWN = {"\\": "`\\\\` became `\\`", "'": "`\\'` became `'`", '"': '`\\"` became `"`',
+          "n": "`\\n` became a line break", "t": "`\\t` became a tab"}
+
+
+def literal_note(segment: str, value: str | None, line: int, call: str) -> str | None:
+    """The note for one non-raw string literal passed to a shell call.
+
+    `segment` is the literal's source text, prefix and quotes included; `value`
+    is what Python made of it, when it is a plain constant.
+    """
+    prefix = re.match(r"[A-Za-z]*", segment).group(0).lower()
+    if "r" in prefix:
+        return None
+    escapes = []
+    for m in _ESCAPE.finditer(segment):
+        shown = _SHOWN[m.group(1)]
+        if shown not in escapes:
+            escapes.append(shown)
+    if not escapes:
+        return None
+    target = "PowerShell" if call == "powershell" else ("the program" if call == "run" else "bash")
+    note = (
+        f"line {line}: the string passed to api.{call} is not raw, so Python "
+        f"processed it before {target} saw it — {', '.join(escapes[:3])}."
+    )
+    if value is not None:
+        received = value.replace("\n", "⏎")
+        if len(received) > 160:
+            received = received[:157] + "…"
+        note += f" {target[0].upper() + target[1:]} received: {received}"
+    return note + ' Write it as r"…" to pass backslashes through as written.'

package/python/xactor/states/__init__.py

@@ -0,0 +1,13 @@
+"""Layer 2 — State machine infrastructure for browser automation."""
+
+from .base import PageState, LoadingState, Observation, Transition, Step
+from .registry import StateRegistry
+
+__all__ = [
+    "PageState",
+    "LoadingState",
+    "Observation",
+    "Transition",
+    "Step",
+    "StateRegistry",
+]