@tealbrick/kit 0.2.7 → 0.3.0-rc.10

package/assets/buzz/buzz-backend-provider.py

@@ -0,0 +1,99 @@
+#!/usr/bin/python3
+# tealbrick-buzz-provider: generated by `tealbrick buzz provider install`; safe to overwrite with --force.
+"""Buzz Desktop managed-agent provider: runs a Desktop-managed agent on a Mac host as buzz-acp + Teal Brick
+kit `native acp` (the owner's kit profile, expert contracts and Portal grants stay the authority).
+Protocol v1: one JSON request on stdin, one JSON response on stdout. The agent key travels only over
+stdin -> ssh stdin -> host helper stdin; never argv, env or logs."""
+import hashlib, json, os, re, subprocess, sys
+PROVIDER_ID = '__TB_PROVIDER_ID__'; VERSION = '__TB_KIT_VERSION__'
+# Test-only override (a fake ssh); Desktop never sets it. Real deployments always use the system ssh.
+SSH = os.environ.get('TEALBRICK_BUZZ_PROVIDER_TEST_SSH') or '/usr/bin/ssh'
+HELPER = 'agents/buzz/bin/tb-provider-apply.py'  # relative to the remote HOME (ssh starts there)
+HEX = re.compile(r'^[0-9a-f]{64}$')
+# --- bech32 (NIP-19 nsec) + secp256k1 x-only pubkey, stdlib only ---------------------------------
+CS = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
+def nsec_hex(s):
+    s = s.strip().lower()
+    if HEX.match(s): return s
+    if not s.startswith('nsec1') or any(c not in CS for c in s[5:]): raise ValueError('private key is not nsec/hex')
+    data = [CS.index(c) for c in s[5:-6]]; acc = bits = 0; out = []
+    for v in data:
+        acc = (acc << 5) | v; bits += 5
+        while bits >= 8: bits -= 8; out.append((acc >> bits) & 0xff)
+    if len(out) != 32: raise ValueError('bad nsec length')
+    return bytes(out).hex()
+P = 2**256 - 2**32 - 977; N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+G = (0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798, 0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8)
+def add(a, b):
+    if a is None: return b
+    if b is None: return a
+    if a[0] == b[0] and (a[1] + b[1]) % P == 0: return None
+    l = (3 * a[0] * a[0] * pow(2 * a[1], -1, P)) % P if a == b else ((b[1] - a[1]) * pow(b[0] - a[0], -1, P)) % P
+    x = (l * l - a[0] - b[0]) % P; return (x, (l * (a[0] - x) - a[1]) % P)
+def pubkey(sk_hex):
+    k = int(sk_hex, 16)
+    if not 0 < k < N: raise ValueError('bad key')
+    r, q = None, G
+    while k:
+        if k & 1: r = add(r, q)
+        q = add(q, q); k >>= 1
+    return format(r[0], '064x')
+# -------------------------------------------------------------------------------------------------
+CONFIG_SCHEMA = {'type': 'object', 'required': ['owner', 'host'], 'additionalProperties': False, 'properties': {
+    'owner': {'type': 'string', 'title': 'Teal Brick kit owner on the host',
+              'description': 'Kit owner directory name under the host owners directory (set up with tealbrick native setup + native enroll), e.g. owner-a'},
+    'host': {'type': 'string', 'title': 'SSH host',
+             'description': 'SSH host alias or user@host of the agent host Mac (key-based, non-interactive), e.g. agent-host'}}}
+def rules_toml():
+    # One rule: an agent wakes only when its own pubkey is p-tagged (an explicit @mention), by anyone.
+    # Desktop DMs p-tag the agent, so DMs still work; untagged channel and thread messages are ignored.
+    kinds = '[9, 40003, 46010, 40007]'
+    return (f'# Generated by buzz-backend-{PROVIDER_ID}: wake only on an explicit @mention (p-tag) from anyone.\n'
+            f'[[rules]]\nname = "mentions"\nchannels = "all"\nkinds = {kinds}\nrequire_mention = true\n')
+def deploy(req):
+    agent = req.get('agent') or {}; cfg = req.get('provider_config') or {}
+    owner = str(cfg.get('owner') or '').strip().lower(); host = str(cfg.get('host') or '').strip()
+    if not re.fullmatch(r'[a-z0-9-]{2,32}', owner): raise ValueError('provider_config.owner is required (e.g. owner-a)')
+    # A leading letter/digit keeps the host from ever being parsed as an ssh option.
+    if not re.fullmatch(r'([A-Za-z0-9][A-Za-z0-9._-]{0,31}@)?[A-Za-z0-9][A-Za-z0-9._-]{0,63}', host):
+        raise ValueError('provider_config.host is required (an ssh alias or user@host, e.g. agent-host)')
+    sk = nsec_hex(agent.get('private_key_nsec') or ''); apub = pubkey(sk)
+    launch = agent.get('launch') or {}; owner_pub = (launch.get('owner_pubkey') or '').lower()
+    tag = agent.get('auth_tag')
+    if not HEX.match(owner_pub): raise ValueError('payload has no owner_pubkey')
+    if not tag: raise ValueError('agent has no NIP-OA auth_tag (recreate it in Desktop)')
+    t = json.loads(tag) if isinstance(tag, str) else tag
+    if not (isinstance(t, list) and len(t) == 4 and t[0] == 'auth' and t[1] == owner_pub): raise ValueError('auth_tag owner does not match the Desktop owner')
+    relay = (agent.get('relay_url') or '').rstrip('/')
+    m = re.fullmatch(r'wss?://([A-Za-z0-9-]+)[A-Za-z0-9.-]*(:\d+)?', relay)
+    if not m: raise ValueError('payload relay_url is not a ws(s) URL')
+    slug = m.group(1).lower()[:20] + '-' + hashlib.sha256(relay.encode()).hexdigest()[:4]
+    label = f'{owner}-{apub[:8]}-{slug}'
+    remote = {'label': label, 'owner': owner, 'relay_url': relay, 'agent_pubkey': apub, 'owner_pubkey': owner_pub,
+              'private_key': sk, 'auth_tag': json.dumps(t), 'respond_to': agent.get('respond_to'),
+              'respond_to_allowlist': agent.get('respond_to_allowlist') or [], 'name': agent.get('name'),
+              'policy_env': launch.get('policy_env') or {}, 'rules_toml': rules_toml()}
+    p = subprocess.run([SSH, '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=15', '--', host, '/usr/bin/python3', HELPER],
+                       input=json.dumps(remote), capture_output=True, text=True, timeout=180)
+    lines = [l for l in p.stdout.splitlines() if l.strip().startswith('{')]
+    try: res = json.loads(lines[-1]) if lines else None
+    except ValueError: res = None
+    if not isinstance(res, dict): res = {'ok': False, 'error': (p.stderr or 'no response from host')[-300:]}
+    if not res.get('ok'): raise RuntimeError(f"{host}: {res.get('error')}")
+    return {'ok': True, 'agent_id': f'{PROVIDER_ID}:{host}:{label}'}
+def redact(text):
+    return re.sub(r'nsec1[0-9a-z]+|[0-9a-fA-F]{64}', '<redacted>', text)
+def main():
+    try:
+        req = json.loads(sys.stdin.read() or '{}'); op = req.get('op')
+        if op == 'info':
+            res = {'ok': True, 'name': f'Teal Brick · {PROVIDER_ID}', 'version': VERSION, 'protocol_version': 1,
+                   'description': 'Runs the agent on a Mac host over ssh as buzz-acp + Teal Brick kit native acp for a kit owner; Portal grants and kit contracts stay the authority.',
+                   'config_schema': CONFIG_SCHEMA}
+        elif op == 'deploy': res = deploy(req)
+        else: raise ValueError(f'unsupported op {op!r}')
+        print(json.dumps(res)); return 0
+    except Exception as e:
+        msg = redact(f'{type(e).__name__}: {e}')[:400]
+        print(json.dumps({'ok': False, 'error': msg})); print(msg, file=sys.stderr); return 1
+if __name__ == '__main__': sys.exit(main())

package/assets/buzz/buzz-plist.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+# tealbrick-buzz-host: installed by `tealbrick buzz host setup`; rewritten on every setup run.
+"""Writes ~/Library/LaunchAgents/com.tealbrick.buzz-acp.<label>.plist for one provider-managed agent.
+The unit runs ~/agents/buzz/bin/buzz-run.sh <label>; logs stay in the agent directory (0700)."""
+import os, plistlib, re, sys
+def main():
+    if len(sys.argv) != 2 or not re.fullmatch(r'[a-z0-9][a-z0-9-]{2,62}', sys.argv[1]):
+        print('usage: buzz-plist.py <label>', file=sys.stderr); return 2
+    label = sys.argv[1]; H = os.path.expanduser('~'); BUZZ = os.path.join(H, 'agents', 'buzz')
+    D = os.path.join(BUZZ, label); logs = os.path.join(D, 'logs')
+    os.makedirs(logs, mode=0o700, exist_ok=True); os.chmod(logs, 0o700)
+    agents = os.path.join(H, 'Library', 'LaunchAgents'); os.makedirs(agents, exist_ok=True)
+    unit = f'com.tealbrick.buzz-acp.{label}'
+    body = {'Label': unit, 'ProgramArguments': ['/bin/bash', os.path.join(BUZZ, 'bin', 'buzz-run.sh'), label],
+            'WorkingDirectory': D, 'RunAtLoad': True, 'KeepAlive': {'SuccessfulExit': False},
+            'ThrottleInterval': 30, 'ProcessType': 'Background', 'Umask': 63,
+            'StandardOutPath': os.path.join(logs, 'buzz-acp.out.log'), 'StandardErrorPath': os.path.join(logs, 'buzz-acp.err.log')}
+    path = os.path.join(agents, unit + '.plist'); tmp = path + '.tmp'
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, 'wb') as f: plistlib.dump(body, f)
+    os.chmod(tmp, 0o600); os.replace(tmp, path); print(path); return 0
+if __name__ == '__main__': sys.exit(main())

package/assets/buzz/buzz-run.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# tealbrick-buzz-host: installed by `tealbrick buzz host setup`; rewritten on every setup run.
+# Runs one provider-managed agent: buzz-acp with Teal Brick kit `native acp` as its ACP agent.
+# Usage (from its launchd unit): buzz-run.sh <label>
+# Each agent gets an isolated environment (env -i): nothing from the login session leaks into the
+# agent, and one agent's keys never reach another (block/buzz#3142). The key and auth tag are read
+# from their files by the final shell and never appear in any process argv (only their paths do).
+# A missing precondition logs one line and exits 0: the unit uses KeepAlive SuccessfulExit=false, so
+# launchd does not restart-loop an agent that cannot start. Fix the cause, then
+# `launchctl kickstart -k gui/$(id -u)/com.tealbrick.buzz-acp.<label>`.
+set -euo pipefail
+NODE=@@NODE@@
+KIT_CLI=@@KIT_CLI@@
+OWNERS_DIR=@@OWNERS_DIR@@
+BUZZ=@@BUZZ_BIN@@
+BUZZ_ACP=@@BUZZ_ACP_BIN@@
+a=${1:-}
+stop() { echo "buzz-run: ${a:-<no label>}: $1; not starting (exit 0, launchd will not restart it)" >&2; exit 0; }
+[[ "$a" =~ ^[a-z0-9][a-z0-9-]{2,62}$ ]] || stop "bad or missing label"
+D="$HOME/agents/buzz/$a"
+[ -d "$D" ] || stop "agent directory $D is missing"
+O=$(cat "$D/owner" 2>/dev/null || echo "$a")
+[[ "$O" =~ ^[a-z0-9-]{2,32}$ ]] || stop "bad owner in $D/owner"
+R="$OWNERS_DIR/$O"
+[ -f "$R/.tealbrick/native-serve.json" ] || stop "kit owner '$O' is not set up under $OWNERS_DIR"
+RELAY=$(cat "$D/relay-url" 2>/dev/null || cat "$HOME/agents/buzz/relay-url" 2>/dev/null || true)
+[ -n "$RELAY" ] || stop "no relay URL ($D/relay-url)"
+[ -s "$D/auth-tag.json" ] || stop "no auth tag ($D/auth-tag.json)"
+[ -s "$D/nostr.key" ] || stop "no agent key ($D/nostr.key)"
+exec /usr/bin/env -i HOME="$HOME" USER="${USER:-$(id -un)}" LOGNAME="${LOGNAME:-$(id -un)}" \
+  PATH="$(dirname "$NODE"):/usr/bin:/bin:/usr/sbin:/sbin" LANG=en_US.UTF-8 \
+  BUZZ_RELAY_URL="$RELAY" \
+  BUZZ_ACP_AGENT_COMMAND="$NODE" BUZZ_ACP_AGENT_ARGS="$KIT_CLI,native,acp,--root,$R,--buzz-cli,$BUZZ" \
+  BUZZ_ACP_RESPOND_TO=owner-only BUZZ_ACP_SESSION_POLICY=thread BUZZ_ACP_PERMISSION_MODE=default \
+  BUZZ_ACP_MULTIPLE_EVENT_HANDLING=queue BUZZ_ACP_IDLE_TIMEOUT=1800 BUZZ_ACP_NO_BASE_PROMPT=true \
+  BUZZ_ACP_NO_MEMORY=true BUZZ_ACP_CONFIG="$D/buzz-acp.toml" RUST_LOG=info \
+  $(grep -E "^BUZZ_ACP_(SUBSCRIBE|NO_MENTION_FILTER|CHANNELS|KINDS|RESPOND_TO|RESPOND_TO_ALLOWLIST|SESSION_POLICY|IDLE_TIMEOUT|MAX_TURN_DURATION|TURN_TIMEOUT|AGENTS|HEARTBEAT_INTERVAL|DEDUP|MULTIPLE_EVENT_HANDLING|RELAY_OBSERVER|LAZY_POOL)=[A-Za-z0-9,._:-]*$" "$D/acp.env" 2>/dev/null || true) \
+  /bin/bash -c 'set -eu; BUZZ_PRIVATE_KEY=$(cat "$1"); BUZZ_AUTH_TAG=$(cat "$2"); export BUZZ_PRIVATE_KEY BUZZ_AUTH_TAG; exec "$3"' \
+  buzz-run "$D/nostr.key" "$D/auth-tag.json" "$BUZZ_ACP"

package/assets/buzz/tb-provider-apply.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+# tealbrick-buzz-host: installed by `tealbrick buzz host setup`; rewritten on every setup run.
+"""Host side of the Teal Brick Buzz Desktop provider. Reads ONE JSON request on stdin (it carries the agent
+key; never argv/env), materialises ~/agents/buzz/<label>/, (re)loads its launchd unit and reports health
+as one JSON line. Idempotent: a redeploy rewrites config and restarts the unit. Host paths come from
+~/agents/buzz/host.json (written by `tealbrick buzz host setup`)."""
+import json, os, re, subprocess, sys, time
+H = os.path.expanduser('~'); BUZZ = os.path.join(H, 'agents', 'buzz')
+HEX = re.compile(r'^[0-9a-f]{64}$')
+LAUNCHCTL = '/bin/launchctl'
+def out(o, code=0): print(json.dumps(o)); sys.exit(code)
+def redact(text): return re.sub(r'nsec1[0-9a-z]+|[0-9a-fA-F]{64}', '<redacted>', text)
+def fail(msg): out({'ok': False, 'error': redact(msg)}, 1)
+def write(path, text, mode=0o600):
+    tmp = path + '.tmp'; fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+    with os.fdopen(fd, 'w') as f: f.write(text)
+    os.chmod(tmp, mode); os.replace(tmp, path)
+SAFE = re.compile(r'^[A-Za-z0-9,._:-]*$')
+ALLOWED_POLICY = {'BUZZ_ACP_SESSION_POLICY', 'BUZZ_ACP_IDLE_TIMEOUT', 'BUZZ_ACP_MAX_TURN_DURATION',
+                  'BUZZ_ACP_TURN_TIMEOUT', 'BUZZ_ACP_HEARTBEAT_INTERVAL', 'BUZZ_ACP_DEDUP',
+                  'BUZZ_ACP_MULTIPLE_EVENT_HANDLING', 'BUZZ_ACP_SUBSCRIBE', 'BUZZ_ACP_NO_MENTION_FILTER',
+                  'BUZZ_ACP_CHANNELS', 'BUZZ_ACP_KINDS', 'BUZZ_ACP_RELAY_OBSERVER', 'BUZZ_ACP_LAZY_POOL', 'BUZZ_ACP_AGENTS'}
+def host_config():
+    try:
+        with open(os.path.join(BUZZ, 'host.json')) as f: cfg = json.load(f)
+    except FileNotFoundError: fail('host is not set up: run `tealbrick buzz host setup` on the host')
+    if not isinstance(cfg, dict) or not isinstance(cfg.get('ownersDir'), str) or not os.path.isabs(cfg['ownersDir']):
+        fail('host.json has no absolute ownersDir: re-run `tealbrick buzz host setup`')
+    return cfg
+def main():
+    req = json.loads(sys.stdin.read())
+    if not isinstance(req, dict): fail('bad request')
+    label, owner, relay = str(req.get('label') or ''), str(req.get('owner') or ''), str(req.get('relay_url') or '')
+    if not re.fullmatch(r'[a-z0-9][a-z0-9-]{2,62}', label): fail('bad label')
+    if not re.fullmatch(r'[a-z0-9-]{2,32}', owner) or not label.startswith(owner + '-'): fail('bad owner')
+    owners_dir = host_config()['ownersDir']
+    if not os.path.isfile(os.path.join(owners_dir, owner, '.tealbrick', 'native-serve.json')):
+        fail(f'unknown or unenrolled kit owner {owner!r} on this host')
+    if not re.fullmatch(r'wss?://[A-Za-z0-9.-]+(:\d+)?/?', relay): fail('bad relay_url')
+    owner_pub = str(req.get('owner_pubkey') or ''); agent_pub = str(req.get('agent_pubkey') or '')
+    if not (HEX.match(owner_pub) and HEX.match(agent_pub)): fail('bad pubkeys')
+    try: tag = json.loads(req.get('auth_tag') or '')
+    except (TypeError, ValueError): tag = None
+    if not (isinstance(tag, list) and len(tag) == 4 and tag[0] == 'auth' and tag[1] == owner_pub and all(isinstance(x, str) for x in tag)):
+        fail('bad auth_tag')
+    desktop_rt = req.get('respond_to') or 'owner-only'
+    if desktop_rt not in ('owner-only', 'allowlist', 'anyone', 'nobody'): fail('bad respond_to')
+    # Fleet default (~/agents/buzz/fleet-defaults.json, e.g. {"respond_to": "anyone"}) replaces Desktop's
+    # *default* owner-only on a membership-only relay; a stricter explicit choice (nobody/allowlist) wins.
+    try:
+        with open(os.path.join(BUZZ, 'fleet-defaults.json')) as f: fleet = json.load(f)
+    except FileNotFoundError: fleet = {}
+    if not isinstance(fleet, dict): fleet = {}
+    rt = fleet.get('respond_to') if desktop_rt == 'owner-only' and fleet.get('respond_to') in ('anyone', 'owner-only') else desktop_rt
+    req['respond_to_effective'] = rt; req['respond_to_desktop'] = desktop_rt
+    allow = [p for p in (req.get('respond_to_allowlist') or []) if isinstance(p, str) and HEX.match(p)]
+    sk = str(req.get('private_key') or '')
+    if not (HEX.match(sk) or re.fullmatch(r'nsec1[0-9a-z]{58}', sk)): fail('bad private key')
+    rules = req.get('rules_toml')
+    if not isinstance(rules, str) or len(rules) > 4096: fail('bad rules_toml')
+    D = os.path.join(BUZZ, label); os.makedirs(os.path.join(D, 'logs'), mode=0o700, exist_ok=True); os.chmod(D, 0o700)
+    write(f'{D}/nostr.key', sk + '\n'); write(f'{D}/nostr.pub', agent_pub + '\n', 0o644)
+    write(f'{D}/auth-tag.json', json.dumps(tag)); write(f'{D}/owner', owner + '\n'); write(f'{D}/relay-url', relay + '\n')
+    env = {'BUZZ_ACP_SUBSCRIBE': 'config', 'BUZZ_ACP_RESPOND_TO': rt}
+    if rt == 'allowlist': env['BUZZ_ACP_RESPOND_TO_ALLOWLIST'] = ','.join(allow)
+    policy = req.get('policy_env') or {}
+    for k, v in (policy.items() if isinstance(policy, dict) else []):
+        if k in ALLOWED_POLICY and SAFE.match(str(v)) and k != 'BUZZ_ACP_SUBSCRIBE': env[k] = str(v)
+    if 'BUZZ_ACP_AGENTS' in env:  # Desktop parallelism, capped: each slot is one kit native acp process
+        env['BUZZ_ACP_AGENTS'] = str(min(4, max(1, int(env['BUZZ_ACP_AGENTS']) if env['BUZZ_ACP_AGENTS'].isdigit() else 1)))
+    write(f'{D}/acp.env', ''.join(f'{k}={v}\n' for k, v in sorted(env.items())))
+    write(f'{D}/buzz-acp.toml', rules)
+    write(f'{D}/deploy.json', json.dumps({k: req.get(k) for k in ('label', 'owner', 'relay_url', 'agent_pubkey', 'owner_pubkey', 'respond_to_desktop', 'respond_to_effective', 'name')}, indent=1))
+    subprocess.run([sys.executable, os.path.join(BUZZ, 'bin', 'buzz-plist.py'), label], check=True, capture_output=True)
+    uid = os.getuid(); svc = f'gui/{uid}/com.tealbrick.buzz-acp.{label}'
+    plist = os.path.join(H, 'Library', 'LaunchAgents', f'com.tealbrick.buzz-acp.{label}.plist')
+    log = f'{D}/logs/buzz-acp.err.log'; start = os.path.getsize(log) if os.path.exists(log) else 0
+    loaded = subprocess.run([LAUNCHCTL, 'print', svc], capture_output=True).returncode == 0
+    if loaded: subprocess.run([LAUNCHCTL, 'kickstart', '-k', svc], check=True, capture_output=True)
+    else: subprocess.run([LAUNCHCTL, 'bootstrap', f'gui/{uid}', plist], check=True, capture_output=True)
+    ansi = re.compile(r'\x1b\[[0-9;]*m'); tail = ''
+    for _ in range(40):
+        time.sleep(1)
+        if not os.path.exists(log): continue
+        with open(log, errors='replace') as f: f.seek(start); tail = ansi.sub('', f.read())
+        if 'subscribed to membership notifications' in tail or 'subscribed to channel' in tail:
+            out({'ok': True, 'label': label, 'service': svc})
+        bad = re.search(r'(?i)(relay_membership_required|auth[^\n]*(fail|denied|invalid)|ERROR[^\n]*)', tail)
+        if bad:
+            subprocess.run([LAUNCHCTL, 'bootout', svc], capture_output=True)  # no crash-looping unit on a failed deploy
+            fail('harness failed: ' + bad.group(0)[:300])
+    subprocess.run([LAUNCHCTL, 'bootout', svc], capture_output=True)
+    fail('harness did not subscribe within 40s')
+if __name__ == '__main__':
+    try: main()
+    except SystemExit: raise
+    except Exception as e: fail(f'{type(e).__name__}: {str(e)[:200]}')

package/dist/buzz.d.ts

@@ -0,0 +1,63 @@
+export declare const PROVIDER_MARKER = "tealbrick-buzz-provider";
+export declare const buzzUsage = "Usage: tealbrick buzz provider install [--name NAME] [--bin-dir DIRECTORY] [--force]\n       tealbrick buzz host setup [--owners-dir DIRECTORY] [--buzz-app PATH] [--node PATH] [--kit-cli PATH] [--respond-to-default owner-only|anyone]\n       tealbrick buzz host remove <label>";
+export declare function installProvider(options?: {
+    name?: string;
+    binDir?: string;
+    force?: boolean;
+    home?: string;
+}): Promise<{
+    path: string;
+    name: string;
+    version: string;
+    updated: boolean;
+    discoverable: boolean;
+    python3: boolean;
+}>;
+export type HostSetupOptions = {
+    home?: string;
+    ownersDir?: string;
+    buzzApp?: string;
+    node?: string;
+    kitCli?: string;
+    respondToDefault?: 'owner-only' | 'anyone';
+    /** Installs @tealbrick/kit@version under prefix and returns the installed dist/cli.js (tests inject this). */
+    installKit?: (prefix: string, version: string) => Promise<string>;
+};
+export declare function setupBuzzHost(options?: HostSetupOptions): Promise<{
+    scripts: string[];
+    fleetDefaults: "owner-only" | "anyone" | null;
+    owners: string[];
+    warnings: string[];
+    version: number;
+    kitVersion: string;
+    node: string;
+    kitCli: string;
+    ownersDir: string;
+    buzzBin: string;
+    buzzAcpBin: string;
+    buzzAppVersion: string;
+    buzzSha256: {
+        buzz: string;
+        'buzz-acp': string;
+    };
+    hostJson: string;
+}>;
+export type LaunchctlRun = (args: string[]) => Promise<number>;
+/**
+ * Remove one provider-managed agent from this host (Buzz Desktop has no undeploy operation): boot out its
+ * launchd unit, delete the plist and move ~/agents/buzz/<label> to ~/agents/buzz/.removed/<label>-<ts>
+ * (0700; it still holds the agent key until you delete it).
+ */
+export declare function removeBuzzAgent(label: string, options?: {
+    home?: string;
+    uid?: number;
+    launchctl?: LaunchctlRun;
+    now?: () => Date;
+}): Promise<{
+    label: string;
+    service: string;
+    bootedOut: boolean;
+    plistRemoved: boolean;
+    movedTo: string | undefined;
+}>;
+export declare function buzzCommand(args: string[]): Promise<void>;

package/dist/buzz.js

@@ -0,0 +1,262 @@
+import { chmod, copyFile, lstat, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+/** Buzz Desktop managed-agent provider (client Mac) and its agent host (Mac running buzz-acp + kit native acp). */
+const run = promisify(execFile);
+const assets = fileURLToPath(new URL('../assets/buzz/', import.meta.url));
+export const PROVIDER_MARKER = 'tealbrick-buzz-provider';
+export const buzzUsage = `Usage: tealbrick buzz provider install [--name NAME] [--bin-dir DIRECTORY] [--force]
+       tealbrick buzz host setup [--owners-dir DIRECTORY] [--buzz-app PATH] [--node PATH] [--kit-cli PATH] [--respond-to-default owner-only|anyone]
+       tealbrick buzz host remove <label>`;
+async function kitVersion() { return JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version; }
+function flagsOf(args, values, switches) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const name = /^--([a-z-]+)$/.exec(args[i])?.[1];
+        if (!name || flags[name] !== undefined)
+            throw Error('kit_buzz_invalid_arguments');
+        if (switches.includes(name)) {
+            flags[name] = true;
+            continue;
+        }
+        if (!values.includes(name) || !args[i + 1] || args[i + 1].startsWith('--'))
+            throw Error('kit_buzz_invalid_arguments');
+        flags[name] = args[++i];
+    }
+    return flags;
+}
+function expand(path, home) { return resolve(path === '~' ? home : path.startsWith('~/') ? join(home, path.slice(2)) : path); }
+async function exists(path) { try {
+    await stat(path);
+    return true;
+}
+catch {
+    return false;
+} }
+async function writeAtomic(path, body, mode) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    await writeFile(tmp, body, { mode });
+    await chmod(tmp, mode);
+    await rename(tmp, path);
+}
+/** Paths end up in a shell script and in buzz-acp's comma-separated BUZZ_ACP_AGENT_ARGS. */
+function hostPath(name, path) {
+    if (!isAbsolute(path) || /[,\x00-\x1f\x7f]/.test(path))
+        throw Error(`kit_buzz_${name}_path_invalid`);
+    return path;
+}
+function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
+async function python3Ok() { try {
+    await run('/usr/bin/python3', ['-c', 'import json, plistlib']);
+    return true;
+}
+catch {
+    return false;
+} }
+export async function installProvider(options = {}) {
+    const home = options.home ?? homedir(), name = options.name ?? 'tealbrick-mac';
+    if (!/^[a-z0-9-]{3,40}$/.test(name))
+        throw Error('kit_buzz_provider_name_invalid');
+    const binDir = expand(options.binDir ?? '~/.local/bin', home), path = join(binDir, `buzz-backend-${name}`);
+    let existing;
+    try {
+        existing = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
+    }
+    if (existing !== undefined && !existing.split('\n', 3).some(line => line.includes(PROVIDER_MARKER)) && !options.force)
+        throw Error('kit_buzz_provider_foreign_file');
+    const version = await kitVersion();
+    const body = (await readFile(join(assets, 'buzz-backend-provider.py'), 'utf8')).replaceAll('__TB_PROVIDER_ID__', name).replaceAll('__TB_KIT_VERSION__', version);
+    await mkdir(binDir, { recursive: true });
+    await writeAtomic(path, body, 0o755);
+    const onPath = (process.env.PATH ?? '').split(delimiter).some(entry => entry && resolve(entry) === binDir);
+    return { path, name, version, updated: existing !== undefined, discoverable: onPath || binDir === join(home, '.local', 'bin'), python3: await python3Ok() };
+}
+async function npmInstallKit(prefix, version) {
+    const local = join(dirname(process.execPath), 'npm');
+    const npm = await exists(local) ? local : 'npm';
+    try {
+        await run(npm, ['install', '--prefix', prefix, '--no-audit', '--no-fund', '--save-exact', `@tealbrick/kit@${version}`], { maxBuffer: 16 * 1024 * 1024 });
+    }
+    catch {
+        throw Error('kit_buzz_kit_install_failed');
+    }
+    return join(prefix, 'node_modules', '@tealbrick', 'kit', 'dist', 'cli.js');
+}
+async function bundleVersion(app) {
+    const plist = join(app, 'Contents', 'Info.plist');
+    try {
+        const { stdout } = await run('/usr/bin/plutil', ['-extract', 'CFBundleShortVersionString', 'raw', '-o', '-', plist]);
+        if (stdout.trim())
+            return stdout.trim();
+    }
+    catch { }
+    try {
+        const text = await readFile(plist, 'utf8');
+        return /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(text)?.[1] ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+async function sha256(path) { return createHash('sha256').update(await readFile(path)).digest('hex'); }
+export async function setupBuzzHost(options = {}) {
+    const home = options.home ?? homedir(), version = await kitVersion();
+    if (options.respondToDefault !== undefined && !['owner-only', 'anyone'].includes(options.respondToDefault))
+        throw Error('kit_buzz_respond_to_default_invalid');
+    const ownersDir = hostPath('owners_dir', expand(options.ownersDir ?? '~/agents/tealbrick-connections', home));
+    const app = expand(options.buzzApp ?? '/Applications/Buzz.app', home);
+    const node = hostPath('node', expand(options.node ?? process.execPath, home));
+    if (!(await stat(node).catch(() => undefined))?.isFile())
+        throw Error('kit_buzz_node_missing');
+    const sources = { buzz: join(app, 'Contents', 'MacOS', 'buzz'), 'buzz-acp': join(app, 'Contents', 'MacOS', 'buzz-acp') };
+    for (const source of Object.values(sources))
+        if (!(await stat(source).catch(() => undefined))?.isFile())
+            throw Error('kit_buzz_app_binaries_missing');
+    const root = join(home, 'agents', 'buzz'), bin = join(root, 'bin'), runtime = join(root, 'runtime');
+    for (const dir of [root, bin, runtime]) {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        await chmod(dir, 0o700);
+    }
+    const buzzBin = hostPath('buzz_bin', join(bin, 'buzz')), buzzAcpBin = hostPath('buzz_acp_bin', join(bin, 'buzz-acp'));
+    // Copy then rename, so a running buzz-acp keeps its inode and a Buzz.app update never changes agents silently.
+    for (const [source, target] of [[sources.buzz, buzzBin], [sources['buzz-acp'], buzzAcpBin]]) {
+        const tmp = `${target}.${process.pid}.tmp`;
+        await copyFile(source, tmp);
+        await chmod(tmp, 0o755);
+        await rename(tmp, target);
+    }
+    const kitCli = hostPath('kit_cli', options.kitCli ? expand(options.kitCli, home) : await (options.installKit ?? npmInstallKit)(runtime, version));
+    if (!(await stat(kitCli).catch(() => undefined))?.isFile())
+        throw Error('kit_buzz_kit_cli_missing');
+    const host = { version: 1, kitVersion: version, node, kitCli, ownersDir, buzzBin, buzzAcpBin, buzzAppVersion: await bundleVersion(app),
+        buzzSha256: { buzz: await sha256(buzzBin), 'buzz-acp': await sha256(buzzAcpBin) } };
+    await writeAtomic(join(root, 'host.json'), JSON.stringify(host, null, 1) + '\n', 0o600);
+    const values = { NODE: node, KIT_CLI: kitCli, OWNERS_DIR: ownersDir, BUZZ_BIN: buzzBin, BUZZ_ACP_BIN: buzzAcpBin };
+    const runner = (await readFile(join(assets, 'buzz-run.sh'), 'utf8')).replace(/@@([A-Z_]+)@@/g, (_, key) => { if (!Object.hasOwn(values, key))
+        throw Error('kit_buzz_asset_placeholder_unknown'); return shellQuote(values[key]); });
+    await writeAtomic(join(bin, 'buzz-run.sh'), runner, 0o700);
+    for (const script of ['buzz-plist.py', 'tb-provider-apply.py'])
+        await writeAtomic(join(bin, script), await readFile(join(assets, script)), 0o700);
+    if (options.respondToDefault)
+        await writeAtomic(join(root, 'fleet-defaults.json'), JSON.stringify({ respond_to: options.respondToDefault }) + '\n', 0o600);
+    const owners = [];
+    try {
+        for (const entry of await readdir(ownersDir, { withFileTypes: true }))
+            if (entry.isDirectory() && /^[a-z0-9-]{2,32}$/.test(entry.name) && await exists(join(ownersDir, entry.name, '.tealbrick', 'native-serve.json')))
+                owners.push(entry.name);
+    }
+    catch { }
+    const warnings = [];
+    if (!await python3Ok())
+        warnings.push('/usr/bin/python3 is not usable; install the Xcode Command Line Tools (xcode-select --install).');
+    if (!owners.length)
+        warnings.push(`No enrolled kit owners under ${ownersDir}; run \`tealbrick native setup\` and \`tealbrick native enroll\` in ${ownersDir}/<owner>.`);
+    return { hostJson: join(root, 'host.json'), ...host, scripts: ['buzz-run.sh', 'buzz-plist.py', 'tb-provider-apply.py'].map(name => join(bin, name)),
+        fleetDefaults: options.respondToDefault ?? null, owners, warnings };
+}
+const launchctl = args => run('/bin/launchctl', args).then(() => 0, (e) => typeof e?.code === 'number' ? e.code : 1);
+const AGENT_LABEL = /^[a-z0-9][a-z0-9-]{2,62}$/;
+/** Names under ~/agents/buzz that are host files, never agents. */
+const RESERVED_LABELS = ['bin', 'runtime', 'logs'];
+/**
+ * Remove one provider-managed agent from this host (Buzz Desktop has no undeploy operation): boot out its
+ * launchd unit, delete the plist and move ~/agents/buzz/<label> to ~/agents/buzz/.removed/<label>-<ts>
+ * (0700; it still holds the agent key until you delete it).
+ */
+export async function removeBuzzAgent(label, options = {}) {
+    if (!AGENT_LABEL.test(label) || RESERVED_LABELS.includes(label))
+        throw Error('kit_buzz_label_invalid');
+    const home = options.home ?? homedir(), uid = options.uid ?? process.getuid?.() ?? 0, unit = `com.tealbrick.buzz-acp.${label}`, service = `gui/${uid}/${unit}`;
+    const root = join(home, 'agents', 'buzz'), dir = join(root, label), plist = join(home, 'Library', 'LaunchAgents', `${unit}.plist`);
+    const exec = options.launchctl ?? launchctl;
+    const loaded = await exec(['print', service]) === 0;
+    if (loaded && await exec(['bootout', service]) !== 0)
+        throw Error('kit_buzz_bootout_failed');
+    const plistStat = await lstat(plist).catch(() => undefined);
+    if (plistStat) {
+        if (!plistStat.isFile() || plistStat.isSymbolicLink())
+            throw Error('kit_buzz_plist_unsafe');
+        await unlink(plist);
+    }
+    const dirStat = await lstat(dir).catch(() => undefined);
+    let movedTo;
+    if (dirStat) {
+        if (!dirStat.isDirectory() || dirStat.isSymbolicLink())
+            throw Error('kit_buzz_agent_dir_unsafe');
+        const removed = join(root, '.removed');
+        await mkdir(removed, { recursive: true, mode: 0o700 });
+        const removedStat = await lstat(removed);
+        if (!removedStat.isDirectory() || removedStat.isSymbolicLink())
+            throw Error('kit_buzz_removed_dir_unsafe');
+        await chmod(removed, 0o700);
+        movedTo = join(removed, `${label}-${(options.now?.() ?? new Date()).toISOString().replace(/[:.]/g, '-')}`);
+        await rename(dir, movedTo);
+        await chmod(movedTo, 0o700);
+    }
+    if (!loaded && !plistStat && !dirStat)
+        throw Error('kit_buzz_agent_not_found');
+    return { label, service, bootedOut: loaded, plistRemoved: !!plistStat, movedTo };
+}
+export async function buzzCommand(args) {
+    const [group, action, ...rest] = args;
+    if (!group || group === 'help' || group === '--help' || group === '-h') {
+        console.log(buzzUsage);
+        return;
+    }
+    if (group === 'provider' && action === 'install') {
+        const flags = flagsOf(rest, ['name', 'bin-dir'], ['force']);
+        const result = await installProvider({ ...(typeof flags.name === 'string' ? { name: flags.name } : {}), ...(typeof flags['bin-dir'] === 'string' ? { binDir: flags['bin-dir'] } : {}), force: flags.force === true });
+        console.log(`${result.updated ? 'Updated' : 'Installed'} Buzz Desktop provider ${result.name} (kit ${result.version}):\n  ${result.path}`);
+        if (!result.discoverable)
+            console.log(`Warning: ${dirname(result.path)} is not on PATH; Buzz Desktop looks in ~/.local/bin and on PATH.`);
+        if (!result.python3)
+            console.log('Warning: /usr/bin/python3 is not usable; install the Xcode Command Line Tools (xcode-select --install).');
+        console.log(`Next, in Buzz Desktop:
+  1. Restart Buzz Desktop so it finds the new provider.
+  2. Open Agents > New agent.
+  3. Set "Run on" to ${result.name} (Teal Brick · ${result.name}).
+  4. Enter owner (the kit owner directory on the host) and host (the ssh alias or user@host of the agent host).
+  5. Create the agent. Desktop deploys it over ssh; the host must have run \`tealbrick buzz host setup\`.`);
+        return;
+    }
+    if (group === 'host' && action === 'setup') {
+        const flags = flagsOf(rest, ['owners-dir', 'buzz-app', 'node', 'kit-cli', 'respond-to-default'], []);
+        const str = (name) => typeof flags[name] === 'string' ? flags[name] : undefined;
+        const respond = str('respond-to-default');
+        if (respond !== undefined && respond !== 'owner-only' && respond !== 'anyone')
+            throw Error('kit_buzz_respond_to_default_invalid');
+        const result = await setupBuzzHost({ ownersDir: str('owners-dir'), buzzApp: str('buzz-app'), node: str('node'), kitCli: str('kit-cli'), respondToDefault: respond });
+        console.log(`Buzz agent host ready (kit ${result.kitVersion}, Buzz ${result.buzzAppVersion}).
+  host.json:  ${result.hostJson}
+  node:       ${result.node}
+  kit cli:    ${result.kitCli}
+  owners dir: ${result.ownersDir}${result.owners.length ? ` (enrolled: ${result.owners.join(', ')})` : ''}
+  buzz:       ${result.buzzBin}
+  buzz-acp:   ${result.buzzAcpBin}
+  fleet respond_to default: ${result.fleetDefaults ?? '(none; Desktop choice applies)'}`);
+        for (const warning of result.warnings)
+            console.log(`Warning: ${warning}`);
+        return;
+    }
+    if (group === 'host' && action === 'remove') {
+        if (rest.length !== 1)
+            throw Error('kit_buzz_invalid_arguments');
+        const result = await removeBuzzAgent(rest[0]);
+        console.log(`Removed Buzz agent ${result.label}:
+  launchd unit: ${result.bootedOut ? `booted out (${result.service})` : 'was not loaded'}
+  plist:        ${result.plistRemoved ? 'deleted' : 'not present'}
+  agent dir:    ${result.movedTo ? `moved to ${result.movedTo} (still holds the agent key; delete it when no longer needed)` : 'not present'}
+Also delete the agent in Buzz Desktop so it is not deployed again.`);
+        return;
+    }
+    console.error(buzzUsage);
+    process.exitCode = 2;
+}