@tealbrick/kit 0.3.0-rc.6 → 0.3.0-rc.8

package/BOOTSTRAP.md

@@ -1,4 +1,4 @@
-> Prerelease 0.3.0-rc.6 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
+> Prerelease 0.3.0-rc.8 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
 
 # Deployment guide: Eve agent + Teal Brick kit
 
@@ -19,7 +19,7 @@ For a fresh machine, the sequence is:
 
 1. Install Node 24 and npm.
 2. Create an Eve 0.70.0 project and configure its primary model credentials.
-3. Install `@tealbrick/kit@0.3.0-rc.6` inside that project.
+3. Install `@tealbrick/kit@0.3.0-rc.8` inside that project.
 4. Run `tealbrick setup` to sign in, select capabilities and register the card.
 5. Build and start Eve, then check a real chat from desktop.
 
@@ -81,7 +81,7 @@ Run this inside the Eve project created in step 2 (or your existing compatible
 project), not in an empty directory or as a global install:
 
 ```bash
-npm install --save-exact @tealbrick/kit@0.3.0-rc.6
+npm install --save-exact @tealbrick/kit@0.3.0-rc.8
 ```
 
 This installs Portal, AVM, Voice, Vision, Deliver and the shared provider transport

package/BUZZ.md

@@ -0,0 +1,135 @@
+# Run fleet agents from Buzz Desktop on a Mac host
+
+Buzz Desktop can create a managed agent and hand it to an external provider.
+The kit ships such a provider: Desktop (on your client Mac) deploys the agent
+over ssh to an agent host Mac, which runs it as `buzz-acp` with
+`tealbrick native acp` as the ACP agent. The kit owner's profile, expert
+contracts and Portal grants stay the authority for what the agent may do.
+
+```
+client Mac: Buzz Desktop -> buzz-backend-<name> --ssh--> host Mac: tb-provider-apply.py -> launchd -> buzz-run.sh -> buzz-acp -> tealbrick native acp
+```
+
+## Prerequisites
+
+- Client Mac: Buzz Desktop, Node 24+, `/usr/bin/python3` (Xcode Command Line Tools).
+- Host Mac: Buzz.app installed (only its `buzz` and `buzz-acp` binaries are used),
+  Node 24+, `/usr/bin/python3`, and non-interactive ssh from the client
+  (key-based; `ssh agent-host true` must work without a prompt).
+- Host Mac: one kit root per owner under the owners directory (default
+  `~/agents/tealbrick-connections/<owner>`), set up with
+  `tealbrick native setup` and `tealbrick native enroll`. The host helper refuses
+  owners without `<owner>/.tealbrick/native-serve.json`.
+
+## Install
+
+On the host Mac:
+
+```sh
+npx -y @tealbrick/kit@next buzz host setup
+```
+
+On the client Mac (where Buzz Desktop runs):
+
+```sh
+npx -y @tealbrick/kit@next buzz provider install
+```
+
+Use the same kit version on both Macs (replace `next` with an exact version to pin it).
+The host setup installs exactly the version it runs as.
+
+`buzz host setup` creates `~/agents/buzz/{bin,runtime}` (0700), copies `buzz`
+and `buzz-acp` out of the app bundle into `~/agents/buzz/bin` (so a Buzz.app
+update never changes running agents; re-run setup to pick up a new Buzz), and
+writes `~/agents/buzz/host.json` with the node path, kit CLI, owners directory,
+binary paths, their sha256 and the Buzz.app version. Because npx caches are
+temporary, it installs the same kit version into `~/agents/buzz/runtime` with
+`npm install --prefix` and points the agents at that copy. Pass
+`--kit-cli /absolute/path/to/dist/cli.js` to use an existing install instead.
+Re-running it is safe; it rewrites the host scripts and `host.json`.
+
+| Flag | Default |
+|---|---|
+| `--owners-dir DIR` | `~/agents/tealbrick-connections` |
+| `--buzz-app PATH` | `/Applications/Buzz.app` |
+| `--node PATH` | the node running setup |
+| `--kit-cli PATH` | install into `~/agents/buzz/runtime` |
+| `--respond-to-default owner-only\|anyone` | none (Desktop choice applies) |
+
+`buzz provider install` writes `~/.local/bin/buzz-backend-tealbrick-mac`
+(0755), which Desktop discovers. `--name NAME` (`[a-z0-9-]{3,40}`) changes the
+provider id, `--bin-dir DIR` the location (it must be on Desktop's PATH or be
+`~/.local/bin`). It refuses to overwrite a file it did not write unless
+`--force` is given.
+
+## Create an agent in Buzz Desktop
+
+1. Restart Buzz Desktop after installing the provider.
+2. Open **Agents > New agent**.
+3. Set **Run on** to `tealbrick-mac` (shown as "Teal Brick · tealbrick-mac").
+4. Set **owner** to the kit owner directory name on the host (for example `owner-a`).
+5. Set **host** to the ssh alias or `user@host` of the host Mac (for example `agent-host`).
+6. Create the agent. Desktop deploys it; the deploy waits until the agent subscribes to the relay.
+
+The agent key goes only over ssh stdin to the host helper. It is never in a
+command line, an environment of the provider or a log; errors redact keys.
+On the host it is stored as `~/agents/buzz/<label>/nostr.key` (0600) and passed
+only to that agent's `buzz-acp` process. Each agent runs in its own empty
+environment. A failed deploy unloads its launchd unit again.
+
+## Who the agent answers
+
+- **Mentions:** every agent gets one rule: it wakes only when its own pubkey is
+  p-tagged (an explicit @mention), by anyone. Desktop DMs p-tag the agent, so
+  DMs work; untagged channel and thread messages are ignored.
+- **respond_to:** the Desktop choice (`owner-only`, `allowlist`, `anyone`,
+  `nobody`) applies. If the host has `~/agents/buzz/fleet-defaults.json`
+  (written by `--respond-to-default`), its value replaces only Desktop's
+  default `owner-only`; an explicit `allowlist` or `nobody` always wins.
+- Desktop policy settings (session policy, timeouts, parallelism up to 4, and
+  similar) pass through an allowlist; anything else is dropped.
+
+## Files and logs on the host
+
+| Path | Content |
+|---|---|
+| `~/agents/buzz/host.json` | host paths and versions from setup |
+| `~/agents/buzz/bin/` | `buzz`, `buzz-acp`, `buzz-run.sh`, `buzz-plist.py`, `tb-provider-apply.py` |
+| `~/agents/buzz/<label>/` | one agent: key, auth tag, owner, relay, `acp.env`, `buzz-acp.toml`, `deploy.json` |
+| `~/agents/buzz/<label>/logs/buzz-acp.{out,err}.log` | agent logs |
+| `~/Library/LaunchAgents/com.tealbrick.buzz-acp.<label>.plist` | launchd unit |
+
+`<label>` is `<owner>-<first 8 hex of the agent pubkey>-<relay host>-<4 hex>`.
+To stop an agent: `launchctl bootout gui/$(id -u)/com.tealbrick.buzz-acp.<label>`.
+
+The agent key and auth tag are read from their files by the last shell
+before `buzz-acp` starts; no process command line ever carries them, only
+their paths.
+
+If a precondition is missing (agent directory, owner kit root, relay URL,
+auth tag or key), `buzz-run.sh` writes one `buzz-run: <label>: ...; not
+starting` line to `buzz-acp.err.log` and exits 0. The unit keeps
+`KeepAlive` only for unsuccessful exits, so launchd does not restart it in a
+loop. Fix the cause, then start it again:
+`launchctl kickstart -k gui/$(id -u)/com.tealbrick.buzz-acp.<label>`.
+
+## Remove an agent
+
+Buzz Desktop has no undeploy operation for provider-managed agents. Delete
+the agent in Desktop, then on the host Mac:
+
+```sh
+npx -y @tealbrick/kit@next buzz host remove <label>
+```
+
+It boots out the launchd unit, deletes
+`~/Library/LaunchAgents/com.tealbrick.buzz-acp.<label>.plist` and moves
+`~/agents/buzz/<label>` to `~/agents/buzz/.removed/<label>-<timestamp>`
+(0700). The moved directory still holds the agent key; delete it when you no
+longer need it. By hand, the same steps are:
+
+```sh
+launchctl bootout gui/$(id -u)/com.tealbrick.buzz-acp.<label>
+rm ~/Library/LaunchAgents/com.tealbrick.buzz-acp.<label>.plist
+rm -rf ~/agents/buzz/<label>
+```

package/NATIVE.md

@@ -1,10 +1,10 @@
 # Native agent setup — Stage A candidate
 
-Prerelease suite **0.3.0-rc.6** targets the `next` tag. The seven scoped `@tealbrick/*` packages keep `latest` at 0.2.7, which lacks this flow; the unscoped `tealbrick` facade keeps `latest` at 0.3.0-rc.1. The `tealbrick` facade forwards the existing kit CLI; it is not another SDK. Matching Portal runtime setup endpoints must be deployed before native onboarding can succeed. RC4 added `tealbrick native serve` and `native enroll` (see README.md). RC5 keeps an idle serve process's runtime acknowledged in Portal, and lets the runtime reach Portal-provisioned Knowledge with short-lived Portal grants when no local app binding exists. RC6 adds the owner-only `/tealbrick/v1/capabilities` snapshot (Portal-granted apps and Marketplace consents) used by TBD Chat → Plugins, and `tealbrick native` without a subcommand prints usage.
+Prerelease suite **0.3.0-rc.8** targets the `next` tag. The seven scoped `@tealbrick/*` packages keep `latest` at 0.2.7, which lacks this flow; the unscoped `tealbrick` facade keeps `latest` at 0.3.0-rc.1. The `tealbrick` facade forwards the existing kit CLI; it is not another SDK. Matching Portal runtime setup endpoints must be deployed before native onboarding can succeed. RC4 added `tealbrick native serve` and `native enroll` (see README.md). RC5 keeps an idle serve process's runtime acknowledged in Portal, and lets the runtime reach Portal-provisioned Knowledge with short-lived Portal grants when no local app binding exists. RC6 adds the owner-only `/tealbrick/v1/capabilities` snapshot (Portal-granted apps and Marketplace consents) used by TBD Chat → Plugins, and `tealbrick native` without a subcommand prints usage. RC7 loads versioned expert contracts (`claude.contracts`) as SDK subagents with scope = contract ceiling ∩ owner grants, pauses approval operations for the owner's payload approval in TBD, and traces every delegation.
 
 ## Install and connect
 
-Install with `npm install --save-exact tealbrick@0.3.0-rc.6` (or `tealbrick@next`) once registry publication is verified. Until then, use the review tarballs with the checksum-verifying `install-candidate.mjs`.
+Install with `npm install --save-exact tealbrick@0.3.0-rc.8` (or `tealbrick@next`) once registry publication is verified. Until then, use the review tarballs with the checksum-verifying `install-candidate.mjs`.
 
 From your native agent workspace:
 

package/README.md

@@ -1,4 +1,4 @@
-> Prerelease 0.3.0-rc.6 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
+> Prerelease 0.3.0-rc.8 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
 
 # @tealbrick/kit
 
@@ -9,7 +9,7 @@ availability, not agent permissions. Nothing is mounted by installing the kit.
 Install inside an existing Eve 0.70.0 project:
 
 ```sh
-npm install --save-exact @tealbrick/kit@0.3.0-rc.6
+npm install --save-exact @tealbrick/kit@0.3.0-rc.8
 npx --no-install tealbrick setup
 ```
 
@@ -93,6 +93,21 @@ including a single deduplicated provider-transport installation.
 
 The `avm` selection accepts the [AVM package connection/policy schema](../avm/README.md): either `{target,sudo}` or `{selectedProfile,profiles}`. Setup can select a saved profile and preserves its grants. New connections can use paired AVMM users or operator SSH. Paired mode requires a dedicated SSH identity path and a resolvable hostname; no credentials are copied. Use `tealbrick apply config.json` for full workspace, ownership, sharing, pool and ingress grants. Disabling AVM removes its entire mount.
 
+## Buzz Desktop agents on a Mac host: `tealbrick buzz`
+
+Buzz Desktop can deploy a managed agent to another Mac that runs it as
+`buzz-acp` + `tealbrick native acp` for a kit owner. Two commands set it up:
+
+```sh
+npx -y @tealbrick/kit@next buzz host setup         # on the agent host Mac
+npx -y @tealbrick/kit@next buzz provider install   # on the Mac running Buzz Desktop
+```
+
+Then in Desktop: Agents > New agent > Run on `tealbrick-mac`, with the kit
+`owner` and the ssh `host`. `tealbrick buzz host remove <label>` removes an
+agent from the host. Prerequisites, mention and respond_to rules, flags, log
+locations and removal are in [BUZZ.md](BUZZ.md).
+
 ## Native chat endpoint: `tealbrick native serve`
 
 Optional. Lets the owner chat with a native **Claude Agent SDK** or **Codex**
@@ -139,6 +154,15 @@ stops the loop with one `native.runtime.sync.stopped` line. The per-turn
   `Agent` delegates only to the configured `experts`, in the foreground with
   the session model; each expert runs with its own `tools` (workspace reads,
   `WebSearch`, `WebFetch`) and never receives Teal Brick tools.
+- **Expert contracts** (`claude.contracts`: absolute paths to
+  `tealbrick.expert-contract/v1` JSON files, e.g. from the Agent-creation
+  cookbook) run as SDK subagents. Effective scope = contract ceiling ∩ the
+  owner's Portal grants ∩ the owner's `tealbrickCalls` ceiling; experts never
+  hold credentials or delegate. Payload approvals: `approvalOperations`
+  (default `marketplace_execute`) and a contract's outward writes pause the
+  exact call as an `input.requested` approval in TBD; decline or timeout denies.
+  Each delegation is traced to `.tealbrick/native-serve/traces/*.jsonl`
+  (owner, expert@version, brief, capabilities used, output digest).
 - `GET /tealbrick/v1/capabilities` (same owner auth) reports what Portal
   currently grants this agent: Knowledge apps from the background runtime sync
   and, when `tealbrick native marketplace-enable` is set, Marketplace consents
@@ -153,6 +177,54 @@ stops the loop with one `native.runtime.sync.stopped` line. The per-turn
   CA settings, `envPassthrough`) and never `TEALBRICK_*` values. Logs carry ids,
   tool names and status codes, never prompts, tool inputs or results.
 
+### Sandboxed workspace (`claude.workspace`, opt-in)
+
+With `"workspace": {"dir": "/abs/root/work", "network": {"allowedDomains": [...]}, "envAllow": [...]}`
+(inside the kit root; never `.tealbrick` or `inbox`), Restricted sessions become
+**Workspace (sandboxed)** sessions:
+
+- Tools: `Bash` (always in the Claude Code OS sandbox; `dangerouslyDisableSandbox`
+  and background commands are refused), `WebSearch`, `WebFetch`, `Agent` and the
+  Teal Brick tools. There is **no** `Read`, `Write`, `Edit`, `Glob`, `Grep`,
+  `NotebookEdit` or other in-process file tool: those run outside the sandbox
+  (symlink and check/use races), so they are removed, listed in
+  `disallowedTools` and denied by the tool gate. The model does all file work
+  with shell commands. Experts and contracts get their tools intersected with
+  this set, so they lose their file tools in this mode too.
+- `WebFetch` refuses non-http(s) URLs, `localhost`, `*.local`, `*.localhost`,
+  `*.internal`, `*.ts.net`, single-label names and loopback, private,
+  link-local and CGNAT (100.64/10) IP literals (IPv4 and IPv6).
+- Sandbox filesystem: writes only to the workspace (and its `.tmp`, used as
+  `TMPDIR`; git uses `.tmp/gitconfig` as its global config). Reads are denied for
+  the SDK process's `HOME`, the owners directory (the kit root's parent),
+  `<root>/.tealbrick`, `/Volumes` and `/private/var/folders`; `allowRead`
+  re-opens only the workspace, the attachment inbox, the node install prefix,
+  Claude Code's `shell-snapshots` and present `/opt/homebrew/{bin,lib,include,share,opt,Cellar}`.
+  The SDK documents that `allowRead` takes precedence over `denyRead` for
+  matching paths; a unit test pins the generated options.
+- Every `envPassthrough` name is removed from sandboxed commands
+  (`credentials.envVars` deny) unless listed in `envAllow`; `BUZZ_*` keys,
+  `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` and `TEALBRICK_*` are always removed.
+  The SDK keeps the host's Claude Code sign-in (`CLAUDE_CONFIG_DIR` is not changed).
+- Buzz attachments (`native acp`) are downloaded by the kit into `<root>/inbox`
+  (0700, readable but not writable by the sandbox); the model copies them into
+  the workspace with Bash.
+- macOS tools that write to the per-user system temp folder instead of `TMPDIR`
+  (for example `sips`) fail in the sandbox, because `/private/var/folders` is
+  shared by every owner on the host and stays denied. Install workspace-local
+  tools instead (a `.venv` with Pillow, or `npm install sharp`); PyPI and the npm
+  registry need to be in `allowedDomains`.
+- Owners on one host run as one OS user. Claude Code's sandbox points Bash `TMPDIR`
+  at `/tmp/claude-<uid>`, where every session also keeps its tool output (one
+  folder per working directory). The kit makes that root unreadable except this
+  owner's own folder, write-denies the other owners' folders (it stays writable
+  for Claude Code's own cwd tracking), and rewrites each sandboxed Bash command to
+  use the workspace `.tmp` as `TMPDIR`/`TMP`/`TEMP`.
+- No git inside the workspace: Claude Code's sandbox refuses writes to `.git/config`
+  and `.git/hooks`, and the kit does not work around it. Version an owner's
+  workspace from outside the sandbox (for example a host job that snapshots and
+  commits it).
+
 ### Configure
 
 `.tealbrick/native-serve.json` (owner-only, `chmod 600`) holds no secrets:

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