aether-rsi 0.1.0__tar.gz

aether_rsi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AetherRSI contributors
+
+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.

aether_rsi-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: aether-rsi
+Version: 0.1.0
+Summary: A small, local workbench for coding agents: a message queue, a task list and a file tree. Everything else is an extension.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AetherRSI
+
+A small local workbench for coding agents: **send a message → it queues → an agent runs it → you watch, inject, or stop.**
+The core does three things ― 💬 Messages, 📋 Tasks, 📂 Files. Everything else is an extension that speaks one protocol ([spec/custom.md](spec/custom.md)).
+Python 3.9+ standard library only. No build step, no dependencies.
+
+## Start
+
+```bash
+pip install aether-rsi    # or from a clone: pip install .
+aether                    # http://127.0.0.1:8030/ ― offers a SampleProject on the first run
+```
+
+Python 3.9+ on macOS, Linux or Windows (WSL). From a clone, `python3 -m aether` works too (`--workspace DIR`, `--port N`, `--reload`).
+
+### The built-in Claude Code agent needs Vertex AI
+
+The agent that comes with the core, **Claude Code, is for Claude on Google Cloud Vertex AI only**. Before the first message, put the
+**path of a service-account key** in `settings.json` (beside the clone, or `~/.aether-rsi/settings.json` for a pip install):
+
+```bash
+aether setup vertex --project your-project-id --region global --key /abs/path/to/vertex-key.json
+```
+
+How to get the key and enable the models, step by step: [aether/fallback/agent/claude-code/README.md](aether/fallback/agent/claude-code/README.md).
+Without `vertex` in `settings.json`, Claude Code is not switched to Vertex. The **Echo** agent of the SampleProject runs without any of this.
+
+## Extensions
+
+A folder with `aether.json`, put in `<workspace>/extensions/` or listed in `settings.json`. Check one with `aether check <folder>`.
+
+| Kind | What it is | Guide |
+|:--|:--|:--|
+| 👁 Preview | a page that shows a file type | [spec/preview.md](spec/preview.md) |
+| 🤖 Agent | a program that reads and writes JSON lines | [spec/agent.md](spec/agent.md) |
+| 🧩 App | a folder with a page and rules for the agent | [spec/app.md](spec/app.md) |
+
+## Safe by default
+
+Binds to 127.0.0.1, keeps agents out of the core and its data, and runs extension pages in sandboxed iframes.
+
+## More
+
+- [spec/custom.md](spec/custom.md) ― customizing in general: the screen, start and workspace, settings.json, the manifest, pages and the bar, safety and the lock, the HTTP API, tests, releases
+- [spec/preview.md](spec/preview.md) · [spec/agent.md](spec/agent.md) (voice, dispatch, the screen) · [spec/app.md](spec/app.md) ― each kind of extension, protocol v0.1 included
+- `conformance/` ― the tests (`python3 -m unittest discover -s conformance -t .`)
+
+Status: v0.1 draft. License: MIT ([LICENSE](LICENSE)).

aether_rsi-0.1.0/README.md

@@ -0,0 +1,48 @@
+# AetherRSI
+
+A small local workbench for coding agents: **send a message → it queues → an agent runs it → you watch, inject, or stop.**
+The core does three things ― 💬 Messages, 📋 Tasks, 📂 Files. Everything else is an extension that speaks one protocol ([spec/custom.md](spec/custom.md)).
+Python 3.9+ standard library only. No build step, no dependencies.
+
+## Start
+
+```bash
+pip install aether-rsi    # or from a clone: pip install .
+aether                    # http://127.0.0.1:8030/ ― offers a SampleProject on the first run
+```
+
+Python 3.9+ on macOS, Linux or Windows (WSL). From a clone, `python3 -m aether` works too (`--workspace DIR`, `--port N`, `--reload`).
+
+### The built-in Claude Code agent needs Vertex AI
+
+The agent that comes with the core, **Claude Code, is for Claude on Google Cloud Vertex AI only**. Before the first message, put the
+**path of a service-account key** in `settings.json` (beside the clone, or `~/.aether-rsi/settings.json` for a pip install):
+
+```bash
+aether setup vertex --project your-project-id --region global --key /abs/path/to/vertex-key.json
+```
+
+How to get the key and enable the models, step by step: [aether/fallback/agent/claude-code/README.md](aether/fallback/agent/claude-code/README.md).
+Without `vertex` in `settings.json`, Claude Code is not switched to Vertex. The **Echo** agent of the SampleProject runs without any of this.
+
+## Extensions
+
+A folder with `aether.json`, put in `<workspace>/extensions/` or listed in `settings.json`. Check one with `aether check <folder>`.
+
+| Kind | What it is | Guide |
+|:--|:--|:--|
+| 👁 Preview | a page that shows a file type | [spec/preview.md](spec/preview.md) |
+| 🤖 Agent | a program that reads and writes JSON lines | [spec/agent.md](spec/agent.md) |
+| 🧩 App | a folder with a page and rules for the agent | [spec/app.md](spec/app.md) |
+
+## Safe by default
+
+Binds to 127.0.0.1, keeps agents out of the core and its data, and runs extension pages in sandboxed iframes.
+
+## More
+
+- [spec/custom.md](spec/custom.md) ― customizing in general: the screen, start and workspace, settings.json, the manifest, pages and the bar, safety and the lock, the HTTP API, tests, releases
+- [spec/preview.md](spec/preview.md) · [spec/agent.md](spec/agent.md) (voice, dispatch, the screen) · [spec/app.md](spec/app.md) ― each kind of extension, protocol v0.1 included
+- `conformance/` ― the tests (`python3 -m unittest discover -s conformance -t .`)
+
+Status: v0.1 draft. License: MIT ([LICENSE](LICENSE)).

aether_rsi-0.1.0/aether/__init__.py

@@ -0,0 +1,5 @@
+"""AetherRSI core: a message queue for coding agents, a task list and a file tree.
+Everything else (previews, agents, apps) is an extension that speaks the protocol in spec/ (custom.md, preview.md, agent.md, app.md)."""
+
+VERSION = "0.1.0"
+PROTOCOL = "0.1"

aether_rsi-0.1.0/aether/__main__.py

@@ -0,0 +1,272 @@
+"""python3 -m aether [--workspace DIR] [--port N] [--reload] [--no-init]   |   python3 -m aether check <extension folder>   |   python3 -m aether init [DIR]
+|   python3 -m aether trust [DIR] [--remove]   |   python3 -m aether setup vertex [--project ID] [--region R] [--key FILE | --adc]
+(installed with pip, the command is `aether`). Without --workspace the core uses the folder saved from the page; a fresh install asks
+in the terminal whether to make a SampleProject (else the page asks for a folder)."""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from . import VERSION, extensions
+from . import settings as settings_mod
+from .server import REPO, RECENT, check_workspace, serve, source_checkout
+
+SAMPLE = Path(__file__).resolve().parent / "sample_project"   # shipped in the wheel: what `aether init` copies out
+
+
+def default_workspace() -> str:
+    """AETHER_WORKSPACE, else "" ―― the folder saved in config.json, or (a fresh install) the shell asks for one."""
+    return os.environ.get("AETHER_WORKSPACE") or ""
+
+
+def default_data() -> str:
+    return os.environ.get("AETHER_DATA") or str(Path.home() / ".aether-rsi")
+
+
+def saved_workspace(data) -> str:
+    """config.json `workspace` ("" when none, or the file is unreadable)."""
+    try:
+        return json.loads((Path(data).expanduser() / "config.json").read_text()).get("workspace") or ""
+    except (OSError, ValueError, AttributeError):
+        return ""
+
+
+def save_workspace(data, ws: Path):
+    """Keep ws as the workspace for the next start, the way the page's form does (workspace + recent)."""
+    d = Path(data).expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    cfg = d / "config.json"
+    try:
+        conf = json.loads(cfg.read_text()) if cfg.is_file() else {}
+    except ValueError:
+        conf = {}
+    conf["recent"] = list(dict.fromkeys(p for p in [str(ws), conf.get("workspace") or "", *(conf.get("recent") or [])] if isinstance(p, str) and p))[:RECENT]
+    conf["workspace"] = str(ws)
+    tmp = cfg.with_suffix(".tmp")
+    tmp.write_text(json.dumps(conf, ensure_ascii=False, indent=2))
+    tmp.replace(cfg)
+
+
+def set_trusted(data, folder: Path, on: bool = True) -> list:
+    """config.json `trusted`: the folders whose own code the person trusts (their extensions/ may run commands; agents load their
+    settings, hooks and MCP servers). Returns the list as saved."""
+    d = Path(data).expanduser()
+    d.mkdir(parents=True, exist_ok=True)
+    cfg = d / "config.json"
+    try:
+        conf = json.loads(cfg.read_text()) if cfg.is_file() else {}
+    except ValueError:
+        conf = {}
+    have = [t for t in (conf.get("trusted") or []) if isinstance(t, str) and t != str(folder)]
+    conf["trusted"] = [*have, str(folder)] if on else have
+    tmp = cfg.with_suffix(".tmp")
+    tmp.write_text(json.dumps(conf, ensure_ascii=False, indent=2))
+    tmp.replace(cfg)
+    return conf["trusted"]
+
+
+def trust(argv) -> int:
+    ap = argparse.ArgumentParser(prog="aether trust", description="Trust a folder's own code: its extensions/ may run commands and agents "
+                                 "load its settings, hooks and MCP servers. For the person: it refuses to run inside an agent's job")
+    ap.add_argument("dir", nargs="?", default=".")
+    ap.add_argument("--remove", action="store_true", help="stop trusting it")
+    ap.add_argument("--data", default=default_data())
+    a = ap.parse_args(argv)
+    if os.environ.get("AETHER_AGENT") == "1":
+        print("aether trust: refused inside an agent's job (only the person trusts a folder)", file=sys.stderr)
+        return 2
+    folder = Path(a.dir).expanduser().resolve()
+    if not folder.is_dir():
+        print(f"aether trust: no such folder: {folder}", file=sys.stderr)
+        return 2
+    now = set_trusted(a.data, folder, not a.remove)
+    print(f"{'no longer trusted' if a.remove else 'trusted'}: {folder}  (trusted now: {len(now)})")
+    return 0
+
+
+KEY_TYPES = {"service_account", "authorized_user", "external_account", "impersonated_service_account"}
+
+
+def setup(argv) -> int:
+    """`aether setup vertex`: how agents reach the models, written to settings.json from a terminal (the page only shows it).
+    No --key: the person's own sign-in (ADC: Cloud Shell, or `gcloud auth application-default login`), no key file anywhere."""
+    ap = argparse.ArgumentParser(prog="aether setup vertex", description="Set how agents reach Vertex AI (written to settings.json). "
+                                 "Without --key they use your own sign-in (ADC); refused inside an agent's job")
+    ap.add_argument("what", choices=["vertex"])
+    ap.add_argument("--project", help="the Google Cloud project that runs the models")
+    ap.add_argument("--region", help="the Vertex AI region (default: global)")
+    g = ap.add_mutually_exclusive_group()
+    g.add_argument("--key", help="a service-account key file, for a project your own sign-in cannot use")
+    g.add_argument("--adc", action="store_true", help="drop the key file: use your own sign-in")
+    ap.add_argument("--data", default=default_data())
+    a = ap.parse_args(argv)
+    if os.environ.get("AETHER_AGENT") == "1":
+        print("aether setup: refused inside an agent's job (only the person sets how agents reach the models)", file=sys.stderr)
+        return 2
+    path = settings_mod.where(REPO, Path(a.data).expanduser(), source_checkout())
+    try:
+        raw = json.loads(path.read_text()) if path.is_file() else {}
+    except ValueError as e:
+        print(f"aether setup: {path} is not JSON ({e}); fix or remove it first", file=sys.stderr)
+        return 2
+    v = dict(raw.get("vertex") or {})
+    if not (a.project or a.region or a.key or a.adc):   # no change asked: say what is set (never the key's contents)
+        how = f"key file {v['credentials']}" if v.get("credentials") else ("your own sign-in (ADC)" if v.get("project") else "not set")
+        print(f"settings: {path}\nvertex: project={v.get('project') or '-'}  region={v.get('region') or '-'}  sign-in={how}")
+        return 0
+    if a.key:
+        key = Path(a.key).expanduser().resolve()
+        try:
+            kind = json.loads(key.read_text()).get("type")
+        except (OSError, ValueError, AttributeError) as e:
+            print(f"aether setup: cannot use {key} as a key file ({type(e).__name__})", file=sys.stderr)
+            return 2
+        if kind not in KEY_TYPES:
+            print(f"aether setup: {key} is not a Google credentials file (type {kind!r})", file=sys.stderr)
+            return 2
+        v["credentials"] = str(key)
+        ws = saved_workspace(a.data)
+        if ws and (Path(ws).resolve() == key or Path(ws).resolve() in key.parents):
+            print(f"note: the key sits inside the workspace {ws}. The core never shows or serves it, but outside is safer", file=sys.stderr)
+    if a.adc:
+        v.pop("credentials", None)
+    if a.project:
+        v["project"] = a.project
+    v["region"] = a.region or v.get("region") or "global"
+    if not v.get("project"):
+        print("aether setup: --project is needed the first time", file=sys.stderr)
+        return 2
+    raw["vertex"] = v
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(raw, ensure_ascii=False, indent=2) + "\n")
+    tmp.replace(path)
+    print(f"saved {path}: project={v['project']} region={v['region']} sign-in={'key file' if v.get('credentials') else 'your own (ADC)'}"
+          "  (a running aether reads it again by itself)")
+    return 0
+
+
+def make_project(where=None) -> Path:
+    """Copy the SampleProject to where (default ./SampleProject). A taken name becomes name-2, name-3 …: nothing is replaced."""
+    if not SAMPLE.is_dir():
+        raise ValueError(f"this install has no sample project ({SAMPLE})")
+    want = Path(where or "SampleProject").expanduser().resolve()
+    dest, n = want, 1
+    while dest.exists():
+        n += 1
+        dest = want.with_name(f"{want.name}-{n}")
+    if not dest.parent.is_dir():
+        raise ValueError(f"no such folder: {dest.parent}")
+    shutil.copytree(SAMPLE, dest, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"))
+    return check_workspace(str(dest))   # the copy is never home or a disk root, but the rule lives in one place
+
+
+def init(argv) -> int:
+    ap = argparse.ArgumentParser(prog="aether init", description="Make a SampleProject (apps/hello-app and sample extensions) without asking")
+    ap.add_argument("dir", nargs="?", default="SampleProject", help="where to make it (default ./SampleProject; a taken name gets -2, -3 …)")
+    ap.add_argument("--data", default=default_data())
+    a = ap.parse_args(argv)
+    try:
+        ws = make_project(a.dir)
+    except (ValueError, OSError) as e:
+        print(f"aether init: {e}", file=sys.stderr)
+        return 2
+    print(f"made {ws}")
+    set_trusted(a.data, ws)   # the person asked for it and its code ships with the core
+    if saved_workspace(a.data):
+        print(f"start it with:  aether --workspace {ws}   (your saved workspace stays as it is)")
+    else:
+        save_workspace(a.data, ws)
+        print("saved as the workspace. start with:  aether")
+    return 0
+
+
+def ask_init(data) -> str:
+    """A fresh install started from a terminal: make ./SampleProject? "" = no (the page asks for a folder, as before)."""
+    try:
+        ans = input("AetherRSI: no workspace yet. Make a sample project at ./SampleProject? [Y/n] ").strip().lower()
+    except EOFError:
+        return ""
+    if ans not in ("", "y", "yes"):
+        return ""
+    try:
+        ws = make_project()
+    except (ValueError, OSError) as e:
+        print(f"could not make it ({e}); enter a folder in the page instead", file=sys.stderr)
+        return ""
+    save_workspace(data, ws)
+    set_trusted(data, ws)
+    print(f"made {ws} (saved as the workspace)")
+    return str(ws)
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    if argv[:1] == ["check"]:
+        bad_total = 0
+        for d in argv[1:] or ["."]:
+            m, bad = extensions.check(d)
+            print(f"{'ok ' if not bad else 'NG '} {d}" + (f"  ({m['kind']} {m['id']})" if m and not bad else ""))
+            for b in bad:
+                print(f"     - {b}")
+            bad_total += len(bad)
+        return 1 if bad_total else 0
+    if argv[:1] == ["init"]:
+        return init(argv[1:])
+    if argv[:1] == ["trust"]:
+        return trust(argv[1:])
+    if argv[:1] == ["setup"]:
+        return setup(argv[1:])
+    ap = argparse.ArgumentParser(prog="aether", description=f"AetherRSI {VERSION}")
+    ap.add_argument("--workspace", default=default_workspace())
+    ap.add_argument("--data", default=default_data())
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=int(os.environ.get("AETHER_PORT") or 8030))
+    ap.add_argument("--reload", action="store_true", help="swap in changed core code without a restart (after the running jobs end)")
+    ap.add_argument("--no-init", action="store_true", help="never ask to make a sample project (the page asks for a folder)")
+    a = ap.parse_args(argv)
+    ws = ""
+    if a.workspace:
+        try:
+            ws = str(check_workspace(str(Path(a.workspace).expanduser().resolve())))   # a relative --workspace is from where you start
+        except ValueError as e:
+            print(f"{e}. Pass another --workspace, or none and set it in the page", file=sys.stderr)
+            return 2
+    elif not a.no_init and not saved_workspace(a.data) and sys.stdin.isatty() and sys.stdout.isatty():
+        ask_init(a.data)   # saved, not passed: the page's form stays free to change it (a passed one locks it)
+    try:
+        srv = serve(ws, a.data, a.host, a.port)
+    except OSError as e:
+        if e.errno not in (errno.EADDRINUSE, errno.EACCES):
+            raise
+        why = "is in use (another aether, or another program: open it, or stop it)" if e.errno == errno.EADDRINUSE else "is not allowed here"
+        print(f"aether: port {a.port} on {a.host} {why}. Start on another one with --port {a.port + 1}", file=sys.stderr)
+        return 2
+    c = srv.core
+    where = c.ws or f"(not set: enter it in the page{' ― ' + c.ws_error if c.ws_error else ''})"
+    print(f"AetherRSI {VERSION}  http://{a.host}:{a.port}/  workspace={where}  core {'locked 🔒' if c.locked else 'UNLOCKED 🔓'} ({c.lock_reason})", flush=True)
+    for e in c.info()["errors"]:
+        print(f"  extension skipped: {e}", flush=True)
+    if a.reload:
+        from .reload import Reloader
+        Reloader(c, argv, log=lambda m: print(m, flush=True)).start()
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def cli():
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    cli()

aether_rsi-0.1.0/aether/extensions.py

@@ -0,0 +1,174 @@
+"""Extensions: a folder with an `aether.json` manifest (spec/custom.md). The core only reads manifests; it never imports extension code."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+from pathlib import Path
+
+from . import PROTOCOL
+
+MANIFEST = "aether.json"
+KINDS = ("preview", "agent", "app")
+ID = re.compile(r"^[a-z0-9][a-z0-9-]{0,39}(\.[a-z0-9][a-z0-9-]{0,39})?$")   # "name" or "author.name" (share with the author part)
+ICON = {".svg": "image/svg+xml", ".png": "image/png"}   # an icon goes to the UI as a data: URL in an <img> (no route into the folder, no script runs)
+ICON_MAX = 64 * 1024
+
+
+def compatible(v) -> bool:
+    """0.x: the minor must match exactly. From 1.0: same major, minor not newer than the core."""
+    try:
+        major, minor = (int(x) for x in str(v).split(".")[:2])
+        cmaj, cmin = (int(x) for x in PROTOCOL.split(".")[:2])
+    except ValueError:
+        return False
+    return (major, minor) == (cmaj, cmin) if cmaj == 0 else major == cmaj and minor <= cmin
+
+
+def _inside(base: Path, rel) -> bool:
+    if not isinstance(rel, str) or not rel or rel.startswith("/") or "\\" in rel:
+        return False
+    p = (base / rel).resolve()
+    return p.is_file() and base.resolve() in p.parents
+
+
+def _rel(rel) -> bool:
+    """A path inside the folder, written relative to it (it need not exist yet: runs/ appears with the first run)."""
+    if not isinstance(rel, str) or not rel.strip() or rel.startswith("/") or "\\" in rel or "\x00" in rel:
+        return False
+    parts = [x for x in rel.split("/") if x not in ("", ".")]
+    return bool(parts) and ".." not in parts
+
+
+LOOPBACK = re.compile(r"^https?://(127\.0\.0\.1|localhost|\[::1\])(:\d{1,5})?(/\S*)?$")
+
+
+def check(folder) -> tuple:
+    """Returns (manifest, problems). An empty list of problems means the extension conforms to the protocol."""
+    folder = Path(folder)
+    f = folder / MANIFEST
+    try:
+        m = json.loads(f.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None, [f"no {MANIFEST}"]
+    except ValueError as e:
+        return None, [f"{MANIFEST} is not JSON: {e}"]
+    if not isinstance(m, dict):
+        return None, [f"{MANIFEST} must be an object"]
+    bad = []
+    if not compatible(m.get("aether")):
+        bad.append(f"protocol {m.get('aether')!r} is not supported (core speaks {PROTOCOL})")
+    if m.get("kind") not in KINDS:
+        bad.append(f"kind must be one of {', '.join(KINDS)}")
+    if not ID.match(str(m.get("id") or "")):
+        bad.append("id must be lowercase letters, digits and '-' (max 40), optionally prefixed by the author: author.name")
+    if not isinstance(m.get("label"), str) or not m["label"].strip():
+        bad.append("label is required")
+    kind = m.get("kind")
+    if kind == "preview" and not _inside(folder, m.get("entry")):
+        bad.append("entry must be a file inside the folder")
+    if kind == "app":
+        if "url" in m:   # a page served by a program on this machine (e.g. a live viewer), not a file of the folder
+            if not (isinstance(m["url"], str) and LOOPBACK.match(m["url"])):
+                bad.append("url must be a page of a server on this machine: http://127.0.0.1:<port>/… (or localhost)")
+        elif not _inside(folder, m.get("entry")):
+            bad.append("entry must be a file inside the folder (or url: a page of a server on this machine)")
+    if kind == "preview":
+        if "binary" in m and not isinstance(m["binary"], bool):
+            bad.append("binary must be true or false")
+        if "render" in m and not (isinstance(m["render"], list) and m["render"] and all(isinstance(x, str) for x in m["render"])):
+            bad.append("render must be a list of strings (the command that draws the pages)")
+        match = m.get("match")
+        if not (isinstance(match, list) and match and all(isinstance(x, str) and (x.startswith(".") or x == "*") for x in match)):
+            bad.append('match must be a list of extensions like [".md"] ("*" = any file no other preview takes)')
+    if kind == "agent":
+        cmd = m.get("command")
+        if not (isinstance(cmd, list) and cmd and all(isinstance(x, str) for x in cmd)):
+            bad.append("command must be a list of strings")
+        for k in ("inject", "guard", "audio", "dispatch"):
+            if k in m and not isinstance(m[k], bool):
+                bad.append(f"{k} must be true or false")
+    if kind == "app" and "ports" in m and not (isinstance(m["ports"], list) and all(isinstance(x, int) and not isinstance(x, bool) and 0 < x < 65536 for x in m["ports"])):
+        bad.append("ports must be a list of port numbers (1-65535)")
+    if kind == "app" and "agent_rules" in m and not _inside(folder, m["agent_rules"]):
+        bad.append("agent_rules must be a file inside the folder")
+    if kind == "app" and "history" in m and not (isinstance(m["history"], list) and all(_rel(x) for x in m["history"])):
+        bad.append("history must be a list of paths inside the folder (its past data: runs, results, logs)")
+    if "icon" in m and not (_inside(folder, m["icon"]) and Path(m["icon"]).suffix.lower() in ICON and (folder / m["icon"]).stat().st_size <= ICON_MAX):
+        bad.append(f"icon must be an .svg or .png file inside the folder, up to {ICON_MAX // 1024} KB")
+    return m, bad
+
+
+def icon_url(m: dict) -> str:
+    """The manifest's icon as a data: URL ("" without one)."""
+    if not m.get("icon"):
+        return ""
+    f = Path(m["dir"]) / m["icon"]
+    try:
+        return f"data:{ICON[f.suffix.lower()]};base64,{base64.b64encode(f.read_bytes()).decode()}"
+    except OSError:   # removed since the scan: the label alone
+        return ""
+
+
+def folders(d: Path):
+    """<d>/<folder>/ and, one level down, <d>/<group>/<folder>/ (group = a folder without a manifest, e.g. preview/ or agent/)."""
+    for f in sorted(p for p in d.iterdir() if p.is_dir() and not p.name.startswith(".")):
+        if (f / MANIFEST).is_file():
+            yield f, None
+        else:
+            for g in sorted(p for p in f.iterdir() if p.is_dir() and not p.name.startswith(".")):
+                yield g, f.name
+
+
+def stamp(dirs) -> tuple:
+    """Changes when an extension folder is added or removed, at either level, or the folder moves under a symlink, or a manifest
+    or its icon is edited (the core rescans then ―― 2026-10-18 an "icon" added to claude-code's aether.json never reached the page)."""
+    out = []
+    for d in map(Path, dirs):
+        out.append(str(d.resolve()))   # scan() keeps resolved dirs: a link swapped for its target keeps every mtime but not the path
+        out.append(d.stat().st_mtime_ns if d.is_dir() else 0)
+        if d.is_dir():
+            out += [f.stat().st_mtime_ns for f in sorted(d.iterdir()) if f.is_dir() and not (f / MANIFEST).is_file()]
+            for folder, _ in folders(d):
+                out += [x.stat().st_mtime_ns if x.is_file() else 0 for x in (folder / MANIFEST, *(folder / n for n in sorted(os.listdir(folder)) if Path(n).suffix.lower() in ICON))]
+    return tuple(out)
+
+
+def scan(dirs, locked: bool, spare=()) -> dict:
+    """Reads every extension folder (see folders). First id wins. Apps are not registered here (they live in the file tree).
+    spare: folders read last that only fill in ids nobody else has (marked "spare"); one the workspace already has is skipped quietly."""
+    out, seen = {"preview": {}, "agent": {}, "errors": []}, {}
+    for d, is_spare in [*((d, False) for d in dirs), *((d, True) for d in spare)]:
+        d = Path(d)
+        if not d.is_dir():
+            continue
+        for folder, group in folders(d):
+            m, bad = check(folder)
+            if m is None and bad == [f"no {MANIFEST}"]:
+                continue
+            name = str(folder.relative_to(d.parent))   # projects/extensions/preview/x vs .aether-rsi/extensions/x
+            if m and group in KINDS and m.get("kind") != group:
+                bad = [*bad, f"kind {m.get('kind')!r} sits in the {group}/ folder"]
+            if bad:
+                out["errors"].append(f"{name}: {'; '.join(bad)}")
+                continue
+            if m["kind"] == "app":
+                continue
+            if m["id"] in seen:
+                if not is_spare:
+                    out["errors"].append(f"{name}: id {m['id']!r} is already taken by {seen[m['id']]} (rename one to author.name)")
+                continue
+            seen[m["id"]] = name
+            m = dict(m, dir=str(folder.resolve()), **({"spare": True} if is_spare else {}))
+            if m["kind"] == "agent" and locked and not m.get("guard"):
+                m["disabled"] = 'the core is locked and this agent does not declare "guard": true'
+            out[m["kind"]][m["id"]] = m
+    return out
+
+
+def app_of(folder: Path):
+    """The app manifest of a folder in the file tree, or None."""
+    m, bad = check(folder)
+    return m if m and not bad and m["kind"] == "app" else None