witbitz-code 1.2.0__py3-none-any.whl

witbitz_code/seen.py

@@ -0,0 +1,49 @@
+"""What the person has seen in the Code session list, shared by their devices — spaces/public/codeUnread.js, in Python.
+
+The owner: "When I switch devices I get green dots". The page kept the record per device, so a session read on the phone
+was news on the laptop. The computer keeps one too: the connector answers SEEN_ROUTE (GET: its record; POST a device's
+record: merged, and the merge back), and every device merges with it. The rules are codeUnread.js's normSeen/mergeSeen;
+tests/test_connector_e2e.py runs the same sequence against both connectors.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any
+
+SEEN_ROUTE = "/witbitz/seen"
+_SEEN_ID = re.compile(r"[A-Za-z0-9_-]{1,128}")
+SEEN_MAX = 5000
+
+
+def _num(v: Any) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v) and v > 0
+
+
+def _plain(v: float | int) -> float | int:
+    return int(v) if isinstance(v, float) and v.is_integer() else v  # 9000.0 → 9000, as JSON.stringify writes it
+
+
+def norm_seen(o: Any) -> dict:
+    """A record from the wire or the disk, checked: session ids, positive numbers, at most SEEN_MAX (the latest looks kept)."""
+    if not isinstance(o, dict):
+        return {"since": 0, "at": {}}
+    raw = o.get("at")
+    entries = [(k, _plain(v)) for k, v in (raw.items() if isinstance(raw, dict) else []) if isinstance(k, str) and _SEEN_ID.fullmatch(k) and _num(v)]
+    if len(entries) > SEEN_MAX:
+        entries = sorted(entries, key=lambda e: -e[1])[:SEEN_MAX]
+    since = o.get("since")
+    return {"since": _plain(since) if _num(since) else 0, "at": dict(entries)}
+
+
+def merge_seen(a: dict, b: dict) -> dict:
+    """Two records → one: each session's LATER look, the EARLIER first look. The same `a` back when `b` adds nothing."""
+    since = min(a["since"], b["since"]) if a["since"] and b["since"] else (a["since"] or b["since"])
+    at = a["at"]
+    for sid, v in b["at"].items():
+        if not (sid in a["at"] and a["at"][sid] >= v):
+            if at is a["at"]:
+                at = dict(a["at"])
+            at[sid] = v
+    return a if since == a["since"] and at is a["at"] else {"since": since, "at": at}

witbitz_code/tools_probe.py

@@ -0,0 +1,67 @@
+"""Which suggested tools this computer has — tools/code-tools-probe.mjs, in Python ("Set up this computer").
+
+A PATH lookup, nothing else: no process is started, no model is asked, nothing is installed. The connector answers the
+page's nonce-checked `{t:'tools'}` with this. The catalog is spaces/public/codeTools.js; tests/test_tools_probe.py holds
+this copy of the binary names and the answers to the JavaScript ones.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+# (tool id, binaries — any one on PATH means installed), in the catalog's order.
+TOOL_BINS: list[tuple[str, list[str]]] = [
+    ("git", ["git"]), ("ripgrep", ["rg"]), ("jq", ["jq"]), ("python", ["python3", "python"]), ("uv", ["uv"]),
+    ("ffmpeg", ["ffmpeg"]), ("whisper", ["whisper-cli", "whisper-cpp", "whisper"]), ("poppler", ["pdftotext"]),
+    ("qpdf", ["qpdf"]), ("tesseract", ["tesseract"]), ("pandoc", ["pandoc"]), ("imagemagick", ["magick", "convert"]),
+]
+# Package managers, most preferred first per OS: (id the page knows, binary).
+PACKAGE_MANAGERS: dict[str, list[tuple[str, str]]] = {
+    "darwin": [("brew", "brew"), ("port", "port")],
+    "linux": [("apt", "apt-get"), ("dnf", "dnf"), ("pacman", "pacman"), ("zypper", "zypper"), ("apk", "apk"), ("brew", "brew")],
+    "win32": [("winget", "winget"), ("choco", "choco"), ("scoop", "scoop")],
+}
+_EXTRA_POSIX = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/snap/bin", "/home/linuxbrew/.linuxbrew/bin"]
+_EXTRA_HOME = [".local/bin", ".cargo/bin", "bin"]
+
+
+def _is_executable(path: str) -> bool:
+    try:
+        st = os.stat(path)
+    except OSError:
+        return False
+    return stat.S_ISREG(st.st_mode) and os.access(path, os.X_OK)
+
+
+def search_dirs(*, env: Mapping[str, str], platform: str, home: str) -> list[str]:
+    """The folders searched, in order, without repeats."""
+    win = platform == "win32"
+    raw = env.get("PATH") or env.get("Path") or ""
+    from_path = [d for d in raw.split(";" if win else ":") if d]
+    extra = [] if win else _EXTRA_POSIX + ([f"{home.rstrip('/')}/{d}" for d in _EXTRA_HOME] if home else [])
+    return list(dict.fromkeys(from_path + extra))
+
+
+def probe_tools(*, env: Mapping[str, str] | None = None, platform: str | None = None, home: str | None = None,
+                is_executable: Callable[[str], bool] = _is_executable) -> dict:
+    env = os.environ if env is None else env
+    platform = sys.platform if platform is None else platform
+    home = str(Path.home()) if home is None else home
+    win = platform == "win32"
+    dirs = search_dirs(env=env, platform=platform, home=home)
+    exts = [""] + [e.lower() for e in (env.get("PATHEXT") or ".COM;.EXE;.BAT;.CMD").split(";") if e] if win else [""]
+
+    def join(d: str, b: str) -> str:
+        return f"{d.rstrip(chr(92) + '/')}\\{b}" if win else f"{d.rstrip('/')}/{b}"
+
+    def has(b: str) -> bool:
+        return any(is_executable(join(d, b + e)) for d in dirs for e in exts)
+
+    tools = {tid: any(has(b) for b in bins if not (win and b == "convert")) for tid, bins in TOOL_BINS}  # Windows' convert.exe is not ImageMagick
+    os_id = platform if platform in PACKAGE_MANAGERS else ""
+    pm = next((pid for pid, b in PACKAGE_MANAGERS[os_id] if has(b)), "") if os_id else ""
+    return {"tools": tools, "platform": {"os": os_id, "pm": pm}}

witbitz_code-1.2.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: witbitz-code
+Version: 1.2.0
+Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
+Author: Witbitz
+License-Expression: MIT
+Project-URL: Documentation, https://witbitz.chat/docs/opencode.md
+Project-URL: Repository, https://github.com/witbitzchat/witbitz-code
+Keywords: witbitz,opencode,relay,e2ee
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Requires-Dist: websockets>=13
+Requires-Dist: httpx>=0.25
+Requires-Dist: segno>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# witbitz-code
+
+Use the **Code** section of Witbitz Spaces, on any device you're signed in on, to reach
+[OpenCode](https://opencode.ai) running on your computer. It's end-to-end encrypted, needs no open port, and doesn't need
+Tailscale.
+
+This is the Python build of the `witbitz-code` tool. It speaks the same wire protocol, uses the same pairing file and the
+same account registry as the single-file Node download (`node witbitz-code.mjs`), so either one can pair a computer and
+the other can serve or unpair it.
+
+## Install
+
+```sh
+pipx install witbitz-code          # or: pip install witbitz-code
+```
+
+Python 3.10 or newer. Dependencies: `cryptography`, `websockets`, `httpx`, `segno`.
+
+You also need OpenCode itself: `npm install -g opencode-ai` or `curl -fsSL https://opencode.ai/install | bash`.
+
+## Use
+
+```sh
+witbitz-code pair                 # shows a QR code: scan it in Spaces → Settings → Back up & recovery → Add a device
+witbitz-code serve                # starts OpenCode on 127.0.0.1:4096 (unless it is running) and the connector
+```
+
+Then open Code in Spaces. Leave `serve` running (Ctrl-C stops it).
+
+| command | what it does |
+|---|---|
+| `pair [--name <name>] [--port <n> \| --opencode-url <url>]` | Show the QR code. The account that scans it gets this computer. `--name` sets the label your devices show (default: the hostname). |
+| `serve [--port <n>] [--no-opencode]` | Start OpenCode on `127.0.0.1:<n>` (default 4096) if nothing is listening there, then connect the pairings whose OpenCode is on that port. One OpenCode per port, one `serve` per OpenCode. |
+| `status` | List this computer's pairings: name, account, OpenCode address and relay. Secrets are never printed. |
+| `rotate [--account <email>]` | Replace the pairing secret(s) without scanning again, then restart `serve`. Devices pick up the new secret on their next sync. |
+| `unpair [--account <email>]` | Remove this computer from an account. Every device drops it on its next sync. |
+| `version`, `--help` | |
+
+`pair`, `rotate` and `unpair` also accept `--dry-run`.
+
+**More than one account.** Each account that scans the QR code gets its own pairing, with its own secret and relay
+channel. OpenCode has no users, so every paired account reaches the same sessions, files and shell. That's fine when
+all the accounts are yours. If a second account belongs to **another person**, run a separate OpenCode for them
+(another port, ideally another OS user) and pair that account with `--port`.
+
+## How it works
+
+```
+ phone / desktop (Code page)                               this computer
+ seal ▸ frames ◂ open  ── wss ─▶ code-relay.witbitz.chat ◀─ wss ──  witbitz-code serve ──▶ opencode (127.0.0.1)
+```
+
+- **Both ends dial out** to `wss://code-relay.witbitz.chat`. Nothing listens on your network, and OpenCode never leaves
+  `127.0.0.1`.
+- **Pairing** uses a device link: the QR code holds only an ephemeral public key. Your signed-in device seals the account
+  pointer to that key. The computer then mints a random 32-byte **secret** for this pairing and does two things with it:
+  - stores it in `~/.witbitz/code/pairings.json` (mode 0600);
+  - publishes it into the account's sealed `computers` registry, which every signed-in device reads.
+- **Keys:** the relay channel id and two direction keys (page→computer and computer→page, AES-256-GCM) are derived from
+  the secret with HKDF-SHA256. A frame reflected back at its sender doesn't decrypt.
+- **Every frame is sealed.** The relay forwards ciphertext it can't read, and the clear header (sender id, sequence
+  number) is authenticated. Receivers drop replays. Large bodies are split into parts below the relay's message size cap.
+- **Replays across restarts:** each time the connector's socket opens, it announces a fresh random nonce inside its
+  sealed hello. Every request and subscription must carry that nonce, so a request recorded before a restart or
+  reconnect is refused (409) and never reaches OpenCode.
+- **The connector only forwards what the Code page itself calls:** list and read sessions, send a message, abort, answer
+  a permission prompt, rename and delete. Every other request gets a 403 without touching OpenCode. OpenCode can run shell
+  commands, so a leaked secret must not unlock more than the page can do. The live event stream is forwarded only while
+  a device is watching.
+- **The OpenCode password** lives in `~/.opencode-server.env` (created 0600 on first pair). The connector adds it to local
+  calls, and it never leaves the computer.
+
+**Auto mode** (Manual · Accept edits · Plan · **Auto** in the Code composer's mode chip, per session) lets this computer answer OpenCode's permission
+prompts while you are away:
+- **Refused at once:** what is never safe, like `rm -rf ~`, `mkfs` or `dd` onto a disk. The agent is told why.
+- **Allowed at once:** read-only commands that stay inside the project, and edits to ordinary files in it.
+- **Everything else** goes to the session's own model, in a throw-away session that can use no tools. Only a clear,
+  low-severity allow runs. A refusal, "ask", an unclear answer or a timeout leaves the prompt for you.
+- **Never "always":** each answer covers that one call.
+
+Each decision is logged to `~/.witbitz/code/auto-log.jsonl` as a digest, never the command. The rules are shared with the
+Node connector and tested against the same cases, so both decide alike.
+
+**What is encrypted, and what isn't.** Requests, responses and events travel end to end. The relay operator sees a
+pseudonymous channel id, IP addresses, connection times, and frame sizes and timing. That's the same class of metadata
+the Spaces room store sees. Anyone holding a pairing secret can drive OpenCode within the allowlist until you run
+`rotate`.
+
+Design: `docs/opencode-relay.md` in the Witbitz repository.
+
+## Files and environment
+
+| | default | override |
+|---|---|---|
+| pairings | `~/.witbitz/code/pairings.json` | `WITBITZ_CODE_PAIRINGS` |
+| OpenCode password | `~/.opencode-server.env` (`OPENCODE_SERVER_PASSWORD=`) | `OPENCODE_ENV_FILE` |
+| pairing QR, as SVG | `~/.witbitz-rc.link.svg` | |
+| Auto mode state + decision log | `~/.witbitz/code/auto-<computer>.json`, `auto-log.jsonl` | `WITBITZ_CODE_AUTO_DIR` |
+| account API | `https://api.witbitz.chat/v1/space` | `RC_BASE`, `RC_ORIGIN` |
+| device-link origins | `https://spaces.witbitz.chat,https://witbitz-spaces.pages.dev` | `RC_LINK_ORIGIN` |
+
+## Development
+
+```sh
+pip install -e '.[test]'
+python -m pytest tests -q
+```
+
+The tests hold this package to the JavaScript reference implementation. They run the modules in `spaces/public/` and
+`tools/` under `node` (22 or newer), and they cover:
+
+- the pinned HKDF vectors;
+- frames sealed on either side opening on the other;
+- chunking through surrogate pairs;
+- the device-link reply and the backup keys;
+- the registry merge rules, compared byte for byte;
+- the pairing file in both directions;
+- the gzip wrap of account docs;
+- a connector of each language driven by a client of the other, through a local fake relay and a fake OpenCode.
+
+Without the repository checkout (`WITBITZ_REPO`) or `node`, the cross-implementation tests are skipped.

witbitz_code-1.2.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+witbitz_code/__init__.py,sha256=Ip38w5d2nF2_LLuLFtZyq9dkyXe6n-bXbAHfcpedcFg,290
+witbitz_code/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+witbitz_code/_js.py,sha256=56cKC97SfM1UZAcOGzGnL-SgIB4SfdAlqVDXX3Vi-N0,11458
+witbitz_code/account.py,sha256=JoCbG1H-qK0hrh2PyNTFYoPpaHukuB8zfD_xaE6lsjA,6133
+witbitz_code/asks.py,sha256=PuuM_WItEim4gKyn4tY9uEo3u_ejmcmwcJAYk2cziYs,5703
+witbitz_code/attachments.py,sha256=1IxpI0YOTl-8x8AtPXwmXYMuxU5qip0ggoBo1I7rAS4,12409
+witbitz_code/auto.py,sha256=lHwCzGOgQd42WUQTCCF4a-otEXaGQ9H4QDdPOJh1wtI,27609
+witbitz_code/auto_runner.py,sha256=mvjlstcHetr-tmJttht4r9rEJ9Qps9VXangBxbGPCKA,26067
+witbitz_code/cli.py,sha256=NCg0Cv3NscYcXHZrEtZKVbly44GNsYFWA6bJL-umHxM,9806
+witbitz_code/codetools.py,sha256=MAZ3CkeHhHgaNa1Mi_nmL7eIC-uOroskdnSSVgomkCI,6758
+witbitz_code/compress.py,sha256=ghZf_HTmYyHOwJDxDgJumr-7hIeohwio_SIMrzs1jtM,759
+witbitz_code/computers.py,sha256=CJccZsL2Km4anrAbwKdhkENe1ZGXqOd_ou05k-gITDU,8280
+witbitz_code/connector.py,sha256=JiK7m4qmH5pu7rgncQWhzfswAD5YghlNASri0ynJLSY,43313
+witbitz_code/devicelink.py,sha256=v_xW6OkrdCJkkyvBtwuzmgc46uSngi7MiGeamiDN00g,7043
+witbitz_code/folders.py,sha256=wi_WYJWNg6bhMfd9258BNsRH23hHwwoCTpFmqBbpSyc,10153
+witbitz_code/link.py,sha256=UgLYh86NBX4m-FseRqo6Y90fpuKrz8AljxpJPN7njAI,8759
+witbitz_code/net.py,sha256=YnqhwZPer4RADTtNIGdp02NXzI5v45fq9XsWOr-yLns,2062
+witbitz_code/outputs.py,sha256=Sibj4Gb6yNEgBQdM7DDlOXbZS93Wo0CxHz7Llzgmyvs,5808
+witbitz_code/pair.py,sha256=OD-Kmy-UBSVUAHvmRH2ApP4H6mpPxUJ3GzNp8MRWN5M,9681
+witbitz_code/pairings.py,sha256=tb9A3jfa4AHmJUsuApJGUPNlI4T8oX7oQry17BP0xcQ,9808
+witbitz_code/plugins.py,sha256=c4soyUM-VSwcLSmvey2aEYNfuu8J6jrsZtAAv4YzS6I,6679
+witbitz_code/policy.py,sha256=kuvtkdKRTE-wf7_nBdwCs9PQvq_n2m-BCVqG6B7Iz1Y,2014
+witbitz_code/qr.py,sha256=Rd5sitzrdGNktHsn7ISGBs-OURtPHmEPbwqPNRXbTTs,2776
+witbitz_code/relay.py,sha256=9pHVrqQj0c4kGGPmckHZLsIchdLtexC5zGUjm3IwWWg,34626
+witbitz_code/seen.py,sha256=ltMM6RgOu9b2mdpGOgTKWGWME_gLHUs1UxJiY7n_AyI,2182
+witbitz_code/tools_probe.py,sha256=fELe69rzJwpB0omek9twRHN3OOolky3wrKVXFk28VFg,3404
+witbitz_code/opencode_plugins/notes-init.md,sha256=7SkhvxSFhKY0W1EZv4DIk34RzbpxoQbqub3f7DJs9c0,768
+witbitz_code/opencode_plugins/witbitz-media-server.mjs,sha256=M-wEUBlDASM89txnCyYLMUYci6Ss5du14fmEx27TZvo,75529
+witbitz_code/opencode_plugins/witbitz-notes.js,sha256=M8V0WZiJdPE78hcjHT3oo1aybbD513rMWlxbcDBOdzg,26661
+witbitz_code/opencode_plugins/witbitz-progress.js,sha256=6J9B71eZqhXpWoCLm-hSBSrlTfflCmHnWHp9yhEItbQ,10349
+witbitz_code-1.2.0.dist-info/licenses/LICENSE,sha256=tAdpEnopN3C7_Mtwt4FpOt54tdJcytanMIPmfjWQyX8,1064
+witbitz_code-1.2.0.dist-info/METADATA,sha256=1x4pzOpJjfPv8FMBcS3IMs_y6IPyAobaPmwjA5uqX5Y,8041
+witbitz_code-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+witbitz_code-1.2.0.dist-info/entry_points.txt,sha256=rjZTJptXZoB2fSJowQBgbsNiiTfsmJGXEwJNIYJHbu4,55
+witbitz_code-1.2.0.dist-info/top_level.txt,sha256=_Q9iBQXeIhv110W9Do9iSt_V4RRTbWIFBIjEhN_hq94,13
+witbitz_code-1.2.0.dist-info/RECORD,,

witbitz_code-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

witbitz_code-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+witbitz-code = witbitz_code.cli:main

witbitz_code-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Witbitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

witbitz_code-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+witbitz_code