aether-rsi 0.1.0__py3-none-any.whl

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/__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/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

aether/fallback/agent/claude-code/README.md

@@ -0,0 +1,109 @@
+# Claude Code agent (built in) ― Vertex AI only
+
+The agent that comes with the core (`aether/fallback/agent/claude-code/`). It puts the Claude Code CLI behind the agent protocol
+([spec/agent.md](../../../../spec/agent.md)). A workspace that has its own `claude-code` in `extensions/` uses that one instead.
+
+**It is for Claude on Google Cloud Vertex AI only.** The core switches Claude Code to Vertex (`CLAUDE_CODE_USE_VERTEX=1` and the project,
+region and key) only from `settings.json` `vertex`. Without it Claude Code falls back to whatever sign-in it has of its own, which this
+agent does not support. So before the first message:
+
+1. `claude` on this machine (below)
+2. a Google Cloud project that may call Claude on Vertex AI
+3. a service-account key file, its **path** in `settings.json` `vertex.credentials`
+
+## 1. Claude Code
+
+Install the Claude Code CLI (https://docs.claude.com/en/docs/claude-code/setup) so that `claude --version` works in a terminal.
+The agent looks for `AETHER_CLAUDE` (a path), then `claude` on the PATH, then (macOS) the copy inside the Claude desktop app.
+You do not need to sign in to Claude Code itself: Vertex is the sign-in.
+
+## 2. The project: Vertex AI and the Claude models
+
+With the gcloud CLI (https://cloud.google.com/sdk/docs/install), signed in as someone who may administer the project:
+
+```bash
+gcloud auth login
+PROJECT=your-project-id
+gcloud config set project $PROJECT
+gcloud services enable aiplatform.googleapis.com          # the Vertex AI API (the project needs billing)
+```
+
+Then turn on the Claude models in the Cloud console: **Vertex AI → Model Garden**, search “Claude”, open the model you want
+(e.g. Claude Opus) and press **Enable** (accept Anthropic's terms). Do it for each model you will use. Vertex serves Claude in the
+`global` region and in some single regions; `global` is the default here.
+
+## 3. A key that can only call the model
+
+A service account with the **Vertex AI User** role (`roles/aiplatform.user`) and nothing else: the agent process holds the key, so give
+it no more than calling the model.
+
+```bash
+gcloud iam service-accounts create aether-agent --display-name "AetherRSI agents"
+gcloud projects add-iam-policy-binding $PROJECT \
+  --member "serviceAccount:aether-agent@$PROJECT.iam.gserviceaccount.com" --role roles/aiplatform.user
+mkdir -p ~/.config/aether && chmod 700 ~/.config/aether
+gcloud iam service-accounts keys create ~/.config/aether/vertex-key.json \
+  --iam-account aether-agent@$PROJECT.iam.gserviceaccount.com
+chmod 600 ~/.config/aether/vertex-key.json
+```
+
+Keep the key **outside the workspace and outside any git repository** (`settings.json` itself is git-ignored, the key file is not).
+The core passes only the key's path, never its contents; it never shows or serves the file, and this agent denies Claude Code's own
+Read/Edit/Write on it (`AETHER_SECRETS`). A shell command run by the agent could still read it, which is why the role is the narrow one.
+
+If key creation is refused (`iam.disableServiceAccountKeyCreation`, an organisation policy), ask the project's admin for a key, or use
+your own sign-in instead (step 4, `--adc`).
+
+## 4. Put the path in settings.json
+
+From a terminal (the page shows what is set, it never sets it):
+
+```bash
+aether setup vertex --project $PROJECT --region global --key ~/.config/aether/vertex-key.json
+aether setup vertex          # no options: shows what is set (project, region, key file or own sign-in)
+```
+
+From a clone it is `python3 -m aether setup vertex …`. It writes `settings.json` beside the clone (a pip install:
+`~/.aether-rsi/settings.json`; `AETHER_SETTINGS` points elsewhere). Or write it by hand from `settings.example.json`:
+
+```json
+{
+  "vertex": {
+    "credentials": "/abs/path/to/.config/aether/vertex-key.json",
+    "project": "your-project-id",
+    "region": "global"
+  }
+}
+```
+
+The path must be absolute (`~/` works) and the file must exist, or the entry is skipped and shown as an error (`/api/info` `errors`).
+A running core reads the file again by itself: no restart. The agent then gets `GOOGLE_APPLICATION_CREDENTIALS`,
+`ANTHROPIC_VERTEX_PROJECT_ID`, `CLOUD_ML_REGION` and `CLAUDE_CODE_USE_VERTEX=1` ([spec/agent.md §4.1](../../../../spec/agent.md#41-environment)).
+
+Your own sign-in instead of a key (Cloud Shell, or after `gcloud auth application-default login` with an account that may call
+Vertex): `aether setup vertex --project $PROJECT --adc`. No key file is kept anywhere; `--key` switches back.
+
+## 5. Try it
+
+Pick **Claude Code** in the shell and send “say hello”. If it fails, the job's error says why:
+
+| Error | What to do |
+|:--|:--|
+| `claude not found` | Step 1, or set `AETHER_CLAUDE` to the path of `claude` (`settings.json` `env`) |
+| `vertex.credentials: no such file …` (in errors) | The path in step 4 is wrong or not absolute |
+| `403` / `PERMISSION_DENIED` | The service account lacks `roles/aiplatform.user`, or the Vertex AI API is off (step 2, 3) |
+| `404` / model not found | The model is not enabled in Model Garden for this project, or not in this region: enable it, or pick one that is with `AETHER_CLAUDE_MODEL` |
+| It answers, but bills your Claude account | `settings.json` has no `vertex`: Claude Code used its own sign-in (step 4) |
+
+## Options
+
+Set in `settings.json` `env` (or the core's environment):
+
+| Variable | What it does |
+|:--|:--|
+| `AETHER_CLAUDE` | The path of `claude` |
+| `AETHER_CLAUDE_MODEL` | The model (`--model`), e.g. one your project has enabled |
+| `AETHER_CLAUDE_PERMISSION` | Claude Code's permission mode (default `acceptEdits`: edits without asking, no shell without asking) |
+
+In a workspace the person trusts (`aether trust`), Claude Code also loads the folder's own settings, hooks and MCP servers; elsewhere it
+starts with `--setting-sources user --strict-mcp-config` ([spec/custom.md](../../../../spec/custom.md#safe-by-default)).

aether/fallback/agent/claude-code/aether.json

@@ -0,0 +1,9 @@
+{
+  "aether": "0.1",
+  "kind": "agent",
+  "id": "claude-code",
+  "label": "Claude Code",
+  "command": ["{python}", "{dir}/agent.py"],
+  "inject": true,
+  "guard": true
+}