@tealbrick/kit 0.3.0-rc.1 → 0.3.0-rc.10

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;
+}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { checkbox, input, password, select, confirm } from '@inquirer/prompts';
 import { readFile } from 'node:fs/promises';
-import { loginPortal, registerPortalCard, portalOrigin, agentOrigin } from './onboarding.js';
+import { deviceLabel, loginPortal, registerPortalCard, portalOrigin, agentOrigin } from './onboarding.js';
 import { collectSetup } from '@tealbrick/deliver/setup';
 import { applyKit, planKit, readKit } from './index.js';
 import { nativeCommand } from './native.js';
@@ -20,6 +20,11 @@ async function main() {
         await nativeCommand(process.argv.slice(3), root);
         return;
     }
+    if (command === 'buzz') {
+        const { buzzCommand } = await import('./buzz.js');
+        await buzzCommand(process.argv.slice(3));
+        return;
+    }
     if (command === 'connect') {
         await runtimeOnboarding('connect', process.argv.slice(3), root);
         return;
@@ -41,7 +46,7 @@ async function main() {
         return;
     }
     if (command !== 'setup') {
-        console.log('Usage: tealbrick setup | status | apply <config.json>\n  tealbrick connect --workspace ID --node ID --agent ID [--issuer URL]\n  tealbrick app claim --workspace ID --node ID --binding REF --endpoint HTTPS_ORIGIN --company PARTITION [--issuer URL]\nInstalled dependencies expose nothing until activated. Rebuild/restart Eve after changing selection.');
+        console.log('Usage: tealbrick setup | status | apply <config.json>\n  tealbrick connect --workspace ID --node ID --agent ID [--issuer URL]\n  tealbrick app claim --workspace ID --node ID --binding REF --endpoint HTTPS_ORIGIN --company PARTITION [--issuer URL]\n  tealbrick buzz provider install | buzz host setup  (Buzz Desktop agents on a Mac host; see BUZZ.md)\nInstalled dependencies expose nothing until activated. Rebuild/restart Eve after changing selection.');
         return;
     }
     console.log('Setup requires Portal sign-in and saves an agent card in your chosen workspace. Other capabilities are optional.');
@@ -56,7 +61,7 @@ async function main() {
         ] });
     const config = { version: 1 }, credentials = {};
     const issuer = portalOrigin(await input({ message: 'Portal issuer URL', default: old.portal?.issuer ?? 'https://portal.tealbrick.com' }));
-    const login = await loginPortal(issuer, (url, code) => console.log(`Sign in and approve this setup in your browser: ${url}\nVerification code: ${code}`));
+    const login = await loginPortal(issuer, (url, code) => console.log(`Sign in and approve this setup in your browser: ${url}\nVerification code: ${code}`), { label: deviceLabel('Eve setup', root) });
     if (!login.workspaces.length)
         throw Error('kit_portal_create_workspace_then_retry');
     const workspaceId = await select({ message: 'Portal workspace for this agent card', choices: login.workspaces.map(w => ({ name: w.name, value: w.id })) });
@@ -127,4 +132,4 @@ async function main() {
     console.log('Portal agent card saved and confirmed in workspace discovery. Rebuild/restart Eve to connect.');
     console.log('Local credentials stay in .tealbrick/kit.credentials.json (owner-only). Supply them as runtime secrets when deploying. Provider connectivity has not been tested.');
 }
-main().catch(error => { const message = error instanceof Error ? error.message : ''; console.error(/^kit_[a-z_]+(?::agent\/[a-zA-Z0-9_./-]+)?$/.test(message) ? message : 'Kit setup failed; check configuration and permissions. Credentials omitted.'); process.exitCode = 1; });
+main().catch(error => { const message = error instanceof Error ? error.message : ''; console.error(/^(?:kit_[a-z_]+(?::agent\/[a-zA-Z0-9_./-]+|:[a-zA-Z0-9_.,]+)?|runtime_product_inactive)$/.test(message) ? message : 'Kit setup failed; check configuration and permissions. Credentials omitted.'); process.exitCode = 1; });