raidlock 0.1.0__py3-none-any.whl

raidlock/bench.py

@@ -0,0 +1,286 @@
+"""Offline overhead measurements using disposable board state and fresh hook processes."""
+
+import argparse
+import importlib
+import json
+import math
+import os
+import platform
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+CHARS_PER_TOKEN = 4
+
+
+def size(text):
+    return {
+        "bytes": len(text.encode("utf-8")),
+        "chars": len(text),
+        "estimated_tokens": math.ceil(len(text) / CHARS_PER_TOKEN),
+    }
+
+
+def percentile(values, fraction):
+    return sorted(values)[max(0, math.ceil(len(values) * fraction) - 1)]
+
+
+def listing(path):
+    text = path.read_text(encoding="utf-8").split("\n---", 1)[0]
+    fields = dict(line.split(": ", 1) for line in text.splitlines() if ": " in line)
+    return fields["name"] + ": " + fields["description"]
+
+
+def check_budget(metrics, budget):
+    if not isinstance(budget, dict) or not budget:
+        raise ValueError("budget must be a nonempty object of metric names and numeric upper limits")
+    failures = []
+    for name, limit in budget.items():
+        if isinstance(limit, bool) or not isinstance(limit, (int, float)) or not math.isfinite(limit) or limit < 0:
+            raise ValueError(f"invalid budget for {name}")
+        if name not in metrics:
+            raise ValueError(f"unknown budget metric: {name}")
+        if metrics[name] > limit:
+            failures.append({"metric": name, "actual": metrics[name], "budget": limit})
+    return failures
+
+
+def summary(report):
+    m = report["metrics"]
+    return (
+        f"Idle overhead: {m['idle.estimated_tokens']} estimated tokens per session "
+        f"(skill and agent listings {m['idle.estimated_tokens'] - m['idle.hooks.estimated_tokens']}, "
+        f"idle hook output {m['idle.hooks.estimated_tokens']}); with MCP tool schemas: "
+        f"{m['idle.with_mcp.estimated_tokens']}. Tokenizer: {report['tokenizer']}, "
+        f"{report['chars_per_token']} characters per estimated token."
+    )
+
+
+def markdown(report):
+    lines = [summary(report), "", "| Metric | Value |", "| --- | ---: |"]
+    lines.extend(f"| {name} | {value} |" for name, value in sorted(report["metrics"].items()))
+    lines.append(f"\nBudget: {'FAIL' if report['failures'] else 'PASS'}")
+    return "\n".join(lines)
+
+
+def _invoke(args, env, cwd, payload=None):
+    start = time.perf_counter_ns()
+    result = subprocess.run(
+        [sys.executable, "-m", "raidlock", *args],
+        input=payload,
+        text=True,
+        encoding="utf-8",
+        capture_output=True,
+        cwd=cwd,
+        env=env,
+        timeout=30,
+        check=True,
+    )
+    elapsed = (time.perf_counter_ns() - start) / 1_000_000
+    if result.stderr:
+        raise RuntimeError(result.stderr)
+    return result.stdout, elapsed
+
+
+def _fixture(root, runs):
+    from . import hooks
+    from .core import Board, db
+    from .core.identity import token_path
+    from .mcp.server import Server, compact
+
+    root = Path(root)
+    workspace = root / "workspace"
+    workspace.mkdir()
+    board, secret = Board.init(workspace, lead="bench-lead")
+    lead = board.caller(agent=board.lead, lead_secret=secret)
+    board.new_card(lead, "Benchmark card", card_id="bench-card")
+    texts, metrics = {}, {}
+    env = dict(os.environ)
+    base = {"cwd": str(workspace), "session_id": "bench-session", "tool_input": {}}
+    cases = {f"{event}.allow": dict(base) for event in hooks.HANDLERS}
+    cases["pre-write.allow"] = {**base, "tool_name": "Write", "tool_input": {"file_path": str(workspace / "free.txt")}}
+    cases["pre-bash.allow"] = {**base, "tool_name": "Bash", "tool_input": {"command": "printf hello"}}
+    cases["session-start.unbound"] = {**base, "session_id": "bench-other-session", "source": "startup"}
+    cases["pre-write.deny"] = {
+        **base,
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(workspace / ".board/board.json")},
+    }
+    cases["pre-bash.deny"] = {**base, "tool_name": "Bash", "tool_input": {"command": "echo x > .board/board.json"}}
+    cases["pre-read.deny"] = {
+        **base,
+        "agent_id": "bench-worker",
+        "tool_name": "Read",
+        "tool_input": {"file_path": token_path(board.home, board.uid, board.lead)},
+    }
+    for name, payload in cases.items():
+        samples = []
+        outputs = []
+        _invoke(["hook", name.split(".")[0]], env, workspace, json.dumps(payload))
+        for _ in range(runs):
+            out, elapsed = _invoke(["hook", name.split(".")[0]], env, workspace, json.dumps(payload))
+            if name.endswith(".deny"):
+                decision = json.loads(out)["hookSpecificOutput"]["permissionDecision"]
+                if decision != "deny" or "hook error" in out:
+                    raise RuntimeError(f"invalid deny fixture: {name}: {out}")
+            elif out:
+                raise RuntimeError(f"allow fixture was not silent: {name}: {out}")
+            samples.append(elapsed)
+            outputs.append(out)
+        texts[f"hook.{name}"] = max(outputs, key=len)
+        metrics[f"hook.{name}.p50_ms"] = round(percentile(samples, 0.5), 3)
+        metrics[f"hook.{name}.p95_ms"] = round(percentile(samples, 0.95), 3)
+    commands = {
+        "show": ["show"],
+        "show_card": ["show", "bench-card"],
+        "who": ["who"],
+        "claimable": ["claimable"],
+        "brief": ["brief", "bench-card"],
+        "tokens": ["tokens"],
+    }
+    for name, args in commands.items():
+        out, _ = _invoke([*args, "--json", "--board", str(workspace)], env, workspace)
+        data = json.loads(out)
+        if not data.get("ok"):
+            raise RuntimeError(f"CLI fixture failed: {name}")
+        texts[f"cli.{name}"] = out
+    joined = board.join(lead, agent="bench-worker", runtime="claude-code")
+    worker_args = ["--agent", "bench-worker", "--token", joined["token"]]
+    for name, args in (
+        ("claim", ["claim", "bench-card"]),
+        ("note", ["note", "bench-card", "Benchmark evidence"]),
+        ("move", ["move", "bench-card", "review", "--note", "Benchmark complete"]),
+    ):
+        out, _ = _invoke([*args, *worker_args, "--json", "--board", str(workspace)], env, workspace)
+        data = json.loads(out)
+        if not data.get("ok"):
+            raise RuntimeError(f"CLI fixture failed: {name}")
+        texts[f"cli.{name}"] = out
+        if name == "claim":
+            worker_args.extend(["--fence", str(data["fence"])])
+    brief = board.brief("bench-card")
+    texts["brief"] = brief["text"]
+    metrics["brief.cap_tokens"] = brief["max_tokens"]
+    metrics["brief.cap_ratio"] = brief["tokens"] / brief["max_tokens"]
+    server = Server()
+    server.handle({"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {"protocolVersion": "2025-11-25"}})
+    texts["mcp.tools_list"] = compact(server.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/list"})) + "\n"
+    db.close_all()
+    return {"texts": texts, "metrics": metrics}
+
+
+def measure(runs=20, plugin_root=None, tokenizer="auto"):
+    if runs < 1:
+        raise ValueError("runs must be positive")
+    root = Path(plugin_root) if plugin_root else Path(__file__).resolve().parents[2]
+    texts = {}
+    for kind, pattern in (("skill", "skills/*/SKILL.md"), ("agent", "agents/*.md")):
+        paths = sorted(root.glob(pattern))
+        if not paths:
+            raise ValueError(f"no {kind} listings under {root}; pass --plugin-root with a raidlock checkout")
+        texts[f"listing.{kind}"] = "\n".join(listing(path) for path in paths)
+    with tempfile.TemporaryDirectory(prefix="raid-bench-") as temporary:
+        scratch = os.path.realpath(temporary)
+        env = {key: os.environ[key] for key in ("PATH", "SYSTEMROOT", "WINDIR", "TMPDIR") if key in os.environ}
+        env.update(
+            {
+                "PYTHONPATH": str(Path(__file__).resolve().parents[1]),
+                "PYTHONUTF8": "1",
+                "RAIDLOCK_HOME": str(Path(scratch) / "state"),
+                "CLAUDE_PLUGIN_DATA": str(Path(scratch) / "plugin"),
+                "CLAUDE_CODE_SESSION_ID": "bench-session",
+            }
+        )
+        code = (
+            "import json,sys; from raidlock.bench import _fixture; "
+            "print(json.dumps(_fixture(sys.argv[1], int(sys.argv[2]))))"
+        )
+        result = subprocess.run(
+            [sys.executable, "-c", code, scratch, str(runs)],
+            env=env,
+            cwd=scratch,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=60 + runs * 30,
+            check=True,
+        )
+        fixture = json.loads(result.stdout)
+    texts.update(fixture["texts"])
+    metrics = fixture["metrics"]
+    encoding = None
+    if tokenizer == "auto":
+        from unittest.mock import patch
+
+        try:
+            tiktoken = importlib.import_module("tiktoken")
+
+            with patch("tiktoken.load.read_file", side_effect=OSError("benchmark is offline")):
+                encoding = tiktoken.get_encoding("cl100k_base")
+        except (ImportError, OSError):
+            pass
+    for name, text in texts.items():
+        metrics.update({f"{name}.{unit}": value for unit, value in size(text).items()})
+        if encoding:
+            metrics[f"{name}.tiktoken_tokens"] = len(encoding.encode(text, disallowed_special=()))
+    listings = sum(metrics[f"listing.{kind}.estimated_tokens"] for kind in ("skill", "agent"))
+    idle_hooks = sum(
+        metrics[f"{name}.estimated_tokens"] for name in texts if name.startswith("hook.") and not name.endswith(".deny")
+    )
+    metrics["idle.hooks.estimated_tokens"] = idle_hooks
+    metrics["idle.estimated_tokens"] = listings + idle_hooks
+    metrics["idle.with_mcp.estimated_tokens"] = listings + idle_hooks + metrics["mcp.tools_list.estimated_tokens"]
+    return {
+        "schema_version": 1,
+        "runs": runs,
+        "chars_per_token": CHARS_PER_TOKEN,
+        "tokenizer": "cl100k_base" if encoding else "estimate",
+        "python": platform.python_version(),
+        "platform": platform.system(),
+        "metrics": metrics,
+        "failures": [],
+    }
+
+
+def setup(parser):
+    parser.add_argument("--runs", type=int, default=20)
+    parser.add_argument("--budget", type=Path)
+    parser.add_argument("--plugin-root", type=Path)
+    parser.add_argument("--tokenizer", choices=("estimate", "auto"), default="auto")
+
+
+def execute(args):
+    report = measure(args.runs, args.plugin_root, args.tokenizer)
+    if args.budget:
+        report["failures"] = check_budget(report["metrics"], json.loads(args.budget.read_text(encoding="utf-8")))
+    return report
+
+
+def register_cli(add_command):
+    def handler(ctx, args):
+        from .core.errors import Precondition
+
+        try:
+            report = execute(args)
+        except (ValueError, OSError) as exc:
+            raise Precondition(str(exc)) from exc
+        return {**report, "_exit": 1 if report["failures"] else 0}, json.dumps(report, indent=2) + "\n\n" + markdown(
+            report
+        )
+
+    add_command("bench", "measure idle and per-action overhead offline", setup, handler)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    setup(parser)
+    args = parser.parse_args(argv)
+    try:
+        report = execute(args)
+    except (ValueError, OSError) as exc:
+        parser.error(str(exc))
+    print(json.dumps(report, indent=2))
+    print(markdown(report), file=sys.stderr)
+    return 1 if report["failures"] else 0

raidlock/bridge/__init__.py

@@ -0,0 +1,186 @@
+"""Native host bridges: Agent Teams teammates and Codex sessions under raidlock leases."""
+
+import contextlib
+import json
+import os
+import re
+import time
+
+from ..core import identity, leases, store
+from ..core.errors import Precondition
+from ..core.lock import FileLock
+
+CONFIG = "bridge.json"
+NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+STALE_SECONDS = 12 * 3600
+PATCH_LINE = re.compile(r"^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+?)\s*$", re.M)
+
+
+def config_path(board):
+    return os.path.join(board.dir, CONFIG)
+
+
+def load(board):
+    data = store.read_json(config_path(board)) or {}
+    pool = [n for n in data.get("pool", []) if isinstance(n, str) and NAME.match(n)]
+    return {"pool": pool}
+
+
+def validate_pool(board, names):
+    agents = board.agents()
+    out = []
+    for name in names:
+        name = name.strip()
+        if not name:
+            continue
+        if not NAME.match(name):
+            raise Precondition(f"invalid agent name {name!r}")
+        if name == board.lead:
+            raise Precondition("the lead cannot be in the auto-join pool")
+        if name not in agents:
+            raise Precondition(f"{name} has not joined this board", hint=f"raidlock join --agent {name} --team <team>")
+        if name not in out:
+            out.append(name)
+    return out
+
+
+def set_pool(board, caller, names):
+    """Lead-only. Record which joined workers new unbound host sessions may take on start."""
+    pool = validate_pool(board, names)
+    with board.lead_write(caller, "configure the auto-join pool"):
+        store.write_json(config_path(board), {"pool": pool})
+    return load(board)
+
+
+def patch_paths(text):
+    """Every file an apply_patch body adds, updates, deletes or moves to."""
+    if not isinstance(text, str):
+        return []
+    return [m.strip() for m in PATCH_LINE.findall(text) if m.strip()]
+
+
+def _pool_dir(state, uid):
+    return os.path.join(state, "pool", re.sub(r"[^A-Za-z0-9_.-]", "_", uid))
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def pool_lock(state, uid):
+    return FileLock(os.path.join(_pool_dir(state, uid), ".lock"))
+
+
+def allocated(state, uid, session):
+    with pool_lock(state, uid):
+        return _allocated(state, uid, session)
+
+
+def _allocated(state, uid, session):
+    folder = _pool_dir(state, uid)
+    try:
+        names = sorted(os.listdir(folder))
+    except OSError:
+        return ""
+    for entry in names:
+        if entry.endswith(".json") and _read(os.path.join(folder, entry)).get("session") == session:
+            return entry[:-5]
+    return ""
+
+
+def _stale(board, path, name, now):
+    try:
+        age = now - os.path.getmtime(path)
+    except OSError:
+        return True
+    if age < STALE_SECONDS:
+        return False
+    return not live_worker(board, name)
+
+
+def live_worker(board, name):
+    return any(v.get("agent") == name and leases.is_live(v) for v in board.leases().values())
+
+
+def allocate(board, state, session, now=None):
+    with pool_lock(state, board.uid), board.lock():
+        return _allocate(board, state, session, now)
+
+
+def _allocate(board, state, session, now=None):
+    """Give `session` a pool identity it alone holds. Returns the name or ""."""
+    if not session:
+        return ""
+    now = time.time() if now is None else now
+    pool = load(board)["pool"]
+    held = allocated(state, board.uid, session)
+    if held in pool:
+        return held
+    if held:
+        free(state, board.uid, session)
+    folder = _pool_dir(state, board.uid)
+    os.makedirs(folder, mode=0o700, exist_ok=True)
+    os.chmod(folder, 0o700)
+    for name in pool:
+        if live_worker(board, name):
+            continue
+        path = os.path.join(folder, name + ".json")
+        if os.path.exists(path):
+            if not _stale(board, path, name, now):
+                continue
+            try:
+                os.unlink(path)
+            except OSError:
+                continue
+        try:
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+        except OSError:
+            continue
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            identity.issue_token(board.home, board.uid, name)
+            json.dump({"session": session, "at": now}, f, sort_keys=True)
+        return name
+    return ""
+
+
+def free(state, uid, session):
+    with pool_lock(state, uid):
+        return _free(state, uid, session)
+
+
+def _free(state, uid, session):
+    name = allocated(state, uid, session)
+    if name:
+        with contextlib.suppress(OSError):
+            os.unlink(os.path.join(_pool_dir(state, uid), name + ".json"))
+    return name
+
+
+def _setup(parser):
+    parser.add_argument(
+        "action",
+        nargs="?",
+        default="show",
+        choices=("show", "pool"),
+        help="show the bridge config, or set the auto-join pool",
+    )
+    parser.add_argument("names", nargs="?", default=None, help="comma-separated joined worker names; empty clears")
+
+
+def _handler(ctx, args):
+    board = ctx.board
+    if args.action == "show":
+        cfg = load(board)
+        return cfg, "auto-join pool: " + (", ".join(cfg["pool"]) or "(empty)")
+    names = (args.names or "").split(",")
+    cfg = set_pool(board, ctx.caller(), names)
+    return cfg, "auto-join pool: " + (", ".join(cfg["pool"]) or "(empty)")
+
+
+def register_cli(add_command):
+    add_command("bridge", "native host bridge: show, or set the auto-join pool (lead)", _setup, _handler, mutating=True)

raidlock/budgets.py

@@ -0,0 +1,178 @@
+"""Delegation budget checks, using UTC days and calendar months.
+
+The core config API must accept budget.* keys before set_budget can persist
+limits. Register the CLI with register_cli(raidlock.cli.add_command).
+Checks inspect recorded usage; they do not reserve funds or stop active runs.
+"""
+
+import datetime
+import json
+from decimal import Decimal, InvalidOperation
+
+from .core import clock
+from .core.errors import Precondition
+from .core.model import card_id
+
+DAILY = "budget.workspace.daily_usd"
+MONTHLY = "budget.workspace.monthly_usd"
+TOKENS = "budget.tokens_per_card"
+COUNT_PLAN = "budget.count_plan_usage"
+
+
+def _number(value, key, integer=False):
+    try:
+        if isinstance(value, bool):
+            raise ValueError
+        number = Decimal(str(value))
+        if not number.is_finite() or number < 0 or (integer and number != number.to_integral_value()):
+            raise ValueError
+        result = int(number) if integer else float(number)
+        if not integer and not Decimal(str(result)).is_finite():
+            raise ValueError
+        return result
+    except (InvalidOperation, ValueError, TypeError, OverflowError):
+        raise Precondition(f"{key} must be a finite nonnegative {'integer' if integer else 'number'}") from None
+
+
+def _boolean(value):
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str) and value.lower() in ("true", "false"):
+        return value.lower() == "true"
+    raise Precondition(f"{COUNT_PLAN} must be true or false")
+
+
+def _value(key, value):
+    if value is None:
+        return None
+    if key in (DAILY, MONTHLY):
+        return _number(value, key)
+    if key == TOKENS:
+        return _number(value, key, integer=True)
+    if key == COUNT_PLAN:
+        return _boolean(value)
+    if key.startswith("budget.card."):
+        card_id(key[len("budget.card.") :])
+        if not isinstance(value, dict) or not value or set(value) - {"usd", "tokens"}:
+            raise Precondition(f"{key} must be an object with usd and/or tokens")
+        return {
+            unit: None if cap is None else _number(cap, key + "." + unit, integer=unit == "tokens")
+            for unit, cap in value.items()
+        }
+    raise Precondition(f"unknown budget key {key}")
+
+
+def set_budget(board, caller, key, value):
+    """Persist a validated cap through core's lead-only config API; null clears it."""
+    if key not in (DAILY, MONTHLY, TOKENS, COUNT_PLAN) and not key.startswith("budget.card."):
+        raise Precondition(f"unknown budget key {key}")
+    if key.startswith("budget.card."):
+        board.card(card_id(key[len("budget.card.") :]))
+    value = _value(key, value)
+    board.set_setting(caller, key, value)
+    return {"key": key, "value": value}
+
+
+def _settings(board):
+    settings = board.get_setting()
+    return {key: _value(key, value) for key, value in settings.items() if key.startswith("budget.")}
+
+
+def _remaining(cap, used):
+    if cap is None:
+        return None
+    return max(0, float(Decimal(str(cap)) - Decimal(str(used))))
+
+
+def _workspace_usd(board, since, until, count_plan):
+    rows = board.spend(by="billing", since=clock.iso(since), until=clock.iso(until))["rows"]
+    return float(
+        sum(
+            (Decimal(str(row.get("usd_equiv" if row["key"] == "plan" and count_plan else "usd") or 0)) for row in rows),
+            Decimal(0),
+        )
+    )
+
+
+def check_before_delegate(board, card):
+    """Return allowed, reasons, limits, used and remaining; None means uncapped.
+
+    Accept a card id or a card dict. All token usage counts, even when plan USD
+    equivalents are disabled. A card token cap overrides tokens_per_card.
+    Call before runner preparation, joining, claiming or cloning, for either role.
+    """
+    with board.lock():
+        card = board.card(card["id"] if isinstance(card, dict) else card)
+        settings = _settings(board)
+        count_plan = settings.get(COUNT_PLAN)
+        count_plan = True if count_plan is None else count_plan
+        caps = settings.get("budget.card." + card["id"]) or {}
+        limits = {
+            "card_usd": caps.get("usd"),
+            "card_tokens": caps.get("tokens", settings.get(TOKENS)),
+            "daily_usd": settings.get(DAILY),
+            "monthly_usd": settings.get(MONTHLY),
+        }
+        row = next((r for r in board.spend(by="card")["rows"] if r["key"] == card["id"]), {})
+        usd = Decimal(str(row.get("usd") or 0))
+        if count_plan:
+            usd += sum(
+                (Decimal(str(r.get("usd_equiv") or 0)) for r in card.get("costs", []) if r.get("billing") == "plan"),
+                Decimal(0),
+            )
+        now = clock.now()
+        day = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        month = day.replace(day=1)
+        next_month = (month.replace(day=28) + datetime.timedelta(days=4)).replace(day=1)
+        used = {
+            "card_usd": float(usd),
+            "card_tokens": row.get("tokens") or 0,
+            "daily_usd": _workspace_usd(board, day, day + datetime.timedelta(days=1), count_plan),
+            "monthly_usd": _workspace_usd(board, month, next_month, count_plan),
+        }
+        remaining = {key: _remaining(cap, used[key]) for key, cap in limits.items()}
+        if remaining["card_tokens"] is not None:
+            remaining["card_tokens"] = max(0, limits["card_tokens"] - used["card_tokens"])
+        reasons = [f"{key} budget exhausted" for key, cap in limits.items() if cap is not None and used[key] >= cap]
+        return {
+            "card": card["id"],
+            "allowed": not reasons,
+            "reasons": reasons,
+            "limits": limits,
+            "used": used,
+            "remaining": remaining,
+            "count_plan_usage": count_plan,
+        }
+
+
+def _setup(parser):
+    parser.add_argument("budget_action", nargs="?", default="show", choices=("set", "show"))
+    parser.add_argument("key", nargs="?", help="budget config key for set, optional card id for show")
+    parser.add_argument(
+        "value", nargs="?", help='JSON value, e.g. 10, true, or {"usd":10,"tokens":50000}; null clears a cap'
+    )
+
+
+def _handler(ctx, args):
+    if args.budget_action == "set":
+        if args.key is None or args.value is None:
+            raise Precondition("budget set requires a config key and JSON value")
+        try:
+            value = json.loads(args.value)
+        except ValueError:
+            raise Precondition("budget value must be valid JSON") from None
+        result = set_budget(ctx.board, ctx.caller(), args.key, value)
+    elif args.value is not None:
+        raise Precondition("budget show accepts at most one card id")
+    elif args.key:
+        result = check_before_delegate(ctx.board, args.key)
+    else:
+        settings = _settings(ctx.board)
+        if settings.get(COUNT_PLAN) is None:
+            settings[COUNT_PLAN] = True
+        result = {"settings": settings}
+    return result, json.dumps(result, indent=2, sort_keys=True)
+
+
+def register_cli(add_command):
+    add_command("budget", "set or show delegation budgets", _setup, _handler, mutating=True)