@tealbrick/kit 0.2.7 → 0.3.0-rc.10

package/BOOTSTRAP.md

@@ -1,12 +1,12 @@
-> Eve 0.66.0 is the supported baseline. Suite 0.2.7 contains deployment fixes and is not yet published; npm latest remains 0.2.6.
+> Prerelease 0.3.0-rc.10 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
 
 This guide installs the seven implemented packages through one kit and activates
-only the capabilities you select. The supported harness line is **Eve 0.66.x**;
-**0.66.0** and **AI SDK 7.0.107** are the current tested versions. Use Node **24**.
+only the capabilities you select. The supported harness line is **Eve 0.70.x**;
+**0.70.0** and **AI SDK 7.0.127** are the current tested versions. Use Node **24**.
 
-**Release status:** `@tealbrick/kit@0.2.7` is the unpublished deployment-fix suite. Until publication, install the validated local tarballs with workspace dependency overrides; the versioned npm command in step 3 applies after publication. Do not substitute an unrelated unscoped `tealbrick` package.
+**Release status:** this prerelease is prepared for the `next` tag. Until publication, use the reviewed local tarballs. The versioned npm commands apply after publication. Native onboarding additionally requires the matching Portal runtime setup endpoints.
 
 ## What installs what
 
@@ -18,12 +18,12 @@ Eve runs the agent and needs its own working primary-model authentication.
 For a fresh machine, the sequence is:
 
 1. Install Node 24 and npm.
-2. Create an Eve 0.66.0 project and configure its primary model credentials.
-3. Install `@tealbrick/kit@0.2.7` inside that project.
+2. Create an Eve 0.70.0 project and configure its primary model credentials.
+3. Install `@tealbrick/kit@0.3.0-rc.10` 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.
 
-For an **existing Eve 0.66.0 project**, start at step 3 from its project directory.
+For an **existing Eve 0.70.0 project**, start at step 3 from its project directory.
 Do not run `eve init` over an existing agent. Preserve its model configuration and
 review any existing Eve channel before setup, as explained under Portal below.
 
@@ -38,15 +38,15 @@ npm --version
 ```
 
 The first command should report `v24.x`. Run the remaining commands as the account
-that will own the new agent project. For our deployment this account runs on
-an AVMM guest on Neuu after the September23 migration. This package guide does not provision a VM or install AVMM.
+that will own the new agent project. In a typical deployment this account runs on
+an AVMM guest on the agent host. This package guide does not provision a VM or install AVMM.
 
 ## 2. Create a fresh Eve project
 
 Choose an unused project directory, outside any existing live agent:
 
 ```bash
-npx --yes eve@0.66.0 init tealbrick-agent --model openai/gpt-5.6-terra
+npx --yes eve@0.70.0 init tealbrick-agent --model openai/gpt-5.6-terra
 ```
 
 Finish scaffolding and return to the terminal before continuing. If Eve starts
@@ -54,12 +54,12 @@ Finish scaffolding and return to the terminal before continuing. If Eve starts
 
 ```bash
 cd tealbrick-agent
-npm install --save-exact eve@0.66.0 ai@7.0.107
+npm install --save-exact eve@0.70.0 ai@7.0.127
 ```
 
 Keep `package-lock.json` under version control.
 The exact Eve pin is intentional: the compatibility workflow validates patches
-before advancing it and will not cross into 0.59 automatically.
+before advancing it. No production pin changes automatically.
 
 The example model uses the Vercel AI Gateway. To supply its key for this terminal
 without putting the key in shell history, in Bash run:
@@ -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.2.7
+npm install --save-exact @tealbrick/kit@0.3.0-rc.10
 ```
 
 This installs Portal, AVM, Voice, Vision, Deliver and the shared provider transport
@@ -184,9 +184,9 @@ does not install AVMM or grant VM administration.
 
 For a paired connection use `agentvm-client@<resolvable-hostname>` and the path to
 that paired user's dedicated SSH key. The host must already be enrolled and its
-SSH host key trusted. AVMM binds the key to its user/workspace. For our host, the
-hostname is `fedora-n150.taild2144d.ts.net`. Paired mode does not read SSH aliases.
-Operator mode can use the configured `nucbox` alias and has that account's authority.
+SSH host key trusted. AVMM binds the key to its user/workspace. For example, the
+hostname might be `agent-host.tailnet.invalid`. Paired mode does not read SSH aliases.
+Operator mode can use a configured SSH alias (for example `agent-host`) and has that account's authority.
 
 Named profiles and exact mutation grants can be supplied through a reviewed
 configuration file using `npx --no-install tealbrick apply config.json`. Follow the
@@ -253,6 +253,5 @@ CRUD, production dispatch and desktop delivery together. Self-evolution requires
 an existing `deployment/*.ts` native Eve policy module outside the writable agent
 tree. Native proposals require the deployment's existing governed activation path.
 
-AVMM/guests migrated to Neuu on September23. Verify current canonical migration
-records before targeting either host. Do not create new canary agents. Committed
+Verify the deployment's canonical host records before targeting an AVMM host. Do not create new canary agents. Committed
 source, npm publication and installed deployment are separate states.

package/BUZZ.md

@@ -0,0 +1,146 @@
+# 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.
+
+## Sharing files
+
+In workspace mode the agent attaches files with `buzz_send_message` `files`
+(paths in its workspace; at most 10 files, 25 MB each, 50 MB per message). It
+never posts a local path. The kit opens each file without following links,
+refuses dotfiles, `inbox`, `.tealbrick`, hard links and anything that is not a
+regular file, copies the bytes from the opened file into
+`<root>/.tealbrick/native-serve/outbox/<uuid>/`, uploads that copy with
+`buzz messages send --file`, and deletes it. Logs carry names and sizes only.
+Incoming attachments still use `buzz_fetch_attachment`.
+
+## 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

@@ -0,0 +1,83 @@
+# Native agent setup — Stage A candidate
+
+Prerelease suite **0.3.0-rc.10** 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.10` (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:
+
+```sh
+npx --no-install tealbrick setup
+```
+
+Choose Claude Agent SDK, Codex TypeScript SDK, LangChain or the existing Eve setup. Native setup then:
+
+1. Opens the existing Portal device-consent flow for your account.
+2. Lets you choose or create an owned workspace.
+3. Lets you create an accurately labelled agent or select an owned existing one.
+4. Creates/reuses its stable card through Portal, then enrolls its runtime connection.
+5. Saves ordinary SDK configuration at `.tealbrick/native-sdk.json`.
+
+No pre-created card, endpoint, Fleet licence, or UUID lookup is required. Names that match multiple identities require an explicit selection. Creation does not grant apps. Eve identities cannot be silently converted to native identities.
+
+Named selections also work:
+
+```sh
+npx --no-install tealbrick setup --harness claude --create-workspace Community --create-agent Researcher
+npx --no-install tealbrick setup --harness langchain --workspace-name Community --agent-name Researcher
+```
+
+The second example requires an existing **LangChain** identity. `--workspace ID --agent ID [--node ID]` remain advanced selections. Setup requires the Portal candidate's authenticated `GET/POST /api/runtime/setup`; a public gateway must expose that reviewed route. It then uses the unchanged `/api/runtime/connections` credential exchange.
+
+Repeat setup in the same workspace to reconnect. `.tealbrick/native-setup.json` retains the account-bound identity intent and idempotency key, without credentials. A lost response or enrollment failure reuses that key on retry. The local setup lock prevents concurrent installers. If the installer is killed, verify that the PID in `.tealbrick/native-setup.lock` is no longer running before removing **only that lock** and retrying; retain the journal. A different account/harness or an attempt to replace an already-bound identity fails closed.
+
+## Native SDK configuration
+
+Load `.tealbrick/native-sdk.json` into the SDK's ordinary options. No tokens are present; the installed CLI path and workspace root are absolute. Keep the package at that path. Use native SDK session persistence and continuation.
+
+```js
+const config = JSON.parse(await readFile('.tealbrick/native-sdk.json', 'utf8'));
+// Claude Agent SDK 0.3.287: preserve the generated settings hook when merging.
+const stream = query({prompt, options: {...config, model: selectedModel,
+  ...(savedSessionId ? {resume: savedSessionId} : {})}});
+// Codex TypeScript SDK 0.160.0 (not OpenAI Agents SDK)
+const codex = new Codex(config);
+const thread = savedThreadId ? codex.resumeThread(savedThreadId, options) : codex.startThread(options);
+// LangChain 1.5.15 and MCP adapters 2.0.0
+const adapter = new MCPAdapter(config);
+const agent = createAgent({model: configuredModel, tools: await adapter.listTools(), checkpointer});
+```
+
+Configure provider authentication on the native host through its supported SDK. Kit does not copy login caches, choose providers or change billing. No Eve daemon, AVMM or inbound bridge is required. An optional owner-only chat endpoint for Teal Brick Desktop is available through `tealbrick native serve` and `tealbrick native enroll`; see README.md. Native mode emits no Eve mounts and uses the existing kit state and owner-only credential file.
+
+## Children and host authority
+
+- **Claude:** generated `settings.hooks.PreToolUse` executes the packaged guard for `mcp__tealbrick__*`. It denies requests with SDK-authored `agent_id`; parent calls receive no permission override. It preserves the host's `Agent` tool, independently scoped agents and non-Tealbrick tools. Merge this hook with existing settings instead of dropping it. Unit/process tests verify the hook; live delegated execution is still unverified.
+- **Codex:** no verified per-child credential boundary exists in this attachment. Setup explicitly asks before generating a profile with `multi_agent` and `multi_agent_v2` disabled. For scripted selection use `--delegation disabled`; the same flag is required for `native config`. It never edits the host's existing Codex config. Do not merge this profile into a delegation-enabled agent and claim isolation.
+- **LangChain:** `createAgent` receives only the two Tealbrick tools; no child tool is introduced. Do not pass this adapter into another agent. Child grants are unsupported.
+
+These controls do not isolate processes sharing an OS user. A child with unrestricted filesystem/shell access can read parent files. Keep the credential directory outside child filesystem authority; independently scoped child runtimes must receive their own grants, not the parent root or credential. No full delegated-access acceptance is claimed.
+
+## Knowledge and revocation
+
+In the selected workspace, licence/configure Knowledge, verify its instance using the existing `tealbrick app claim` flow, and save explicit CRUD tethers. The instance admin approves the claim; runtime uses a separate scoped service-principal token. Nothing automatically grants all products.
+
+```sh
+npx --no-install tealbrick app claim --workspace WORKSPACE_ID --node KNOWLEDGE_NODE_ID --binding community --endpoint https://YOUR_KNOWLEDGE_ORIGIN --company YOUR_PARTITION --issuer https://portal.tealbrick.com
+npx --no-install tealbrick native disable
+npx --no-install tealbrick native enable
+```
+
+Each request reloads local activation and fetches signed Portal authorization. Revoke or unavailable authorization blocks the next app request. In-flight side effects are not undone; cancellation reaches the app request but does not prove a write rolled back. No automatic write retry is added. Re-enrollment rotates the runtime credential and keeps the logical agent. Portal logout does not revoke that connection.
+
+## Acceptance boundary
+
+Disposable installed-artifact tests cover empty-account creation, named selection, permission/ambiguity denial, lost-response retry, signed config, scoped Knowledge-fixture read, revoke/reconnect, deactivation and MCP cancellation. They are not real browser consent or real Knowledge product proof. Root's separate canary-agent receipt proves the earlier packed candidate's live Claude MCP inactive denial, exact-session process restart and compaction. Codex and LangChain have independent narrower fixture evidence, not live-provider parity. Marketplace, voice/vision and delegated Tealbrick grants are outside this Stage A claim.
+
+## Name conflicts and interrupted setup
+
+Existing cards are shown with their harness. A card for Eve cannot be converted to Claude by choosing its name. If a name is already used, select an explicitly compatible card or choose another name; setup keeps the approved login during this interaction. Duplicate compatible names require selecting the exact card ID.
+
+A definitive Portal name-conflict rejection permits changing the proposed identity. A timeout or lost response does not: the private journal keeps the original request and idempotency key. Repeat `tealbrick setup --harness <harness>` without new identity-selection flags to reconcile that request. Changing an uncertain request fails with `kit_native_setup_pending_intent_mismatch`; do not delete the journal to bypass it.

package/README.md

@@ -1,4 +1,4 @@
-> Eve 0.66.0 is the supported baseline. Suite 0.2.7 contains deployment fixes and is not yet published; npm latest remains 0.2.6.
+> Prerelease 0.3.0-rc.10 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
 
@@ -6,16 +6,16 @@ One installation, explicitly selected capabilities. The kit includes the current
 implemented Portal, Voice, Vision, Deliver and AVM packages. Dependencies are code
 availability, not agent permissions. Nothing is mounted by installing the kit.
 
-Install inside an existing Eve 0.66.0 project:
+Install inside an existing Eve 0.70.0 project:
 
 ```sh
-npm install --save-exact @tealbrick/kit@0.2.7
+npm install --save-exact @tealbrick/kit@0.3.0-rc.10
 npx --no-install tealbrick setup
 ```
 
 The suite is published on npm. The kit does not install, create or start Eve.
 Create the Eve project first and configure its primary-model authentication.
-Eve 0.66.0 and Node 24 are the validated host versions; VM provisioning remains
+Eve 0.70.0 and Node 24 are the validated host versions; VM provisioning remains
 host setup. After Teal Brick setup, build and start Eve to make the agent usable.
 
 See [BOOTSTRAP.md](BOOTSTRAP.md) for the complete deployment guide, including fresh-machine and existing-agent paths, provider prompts and verification.
@@ -92,3 +92,264 @@ including a single deduplicated provider-transport installation.
 ## AVMM profiles
 
 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**
+agent from TBD. The agent must already be set up with
+`tealbrick setup --harness claude|codex` (kit state, runtime connection and
+`.tealbrick/native-sdk.json`). LangChain is refused with
+`kit_native_serve_langchain_unsupported`.
+
+The endpoint is the Eve session subset Desktop uses (`/eve/v1/health`,
+`/eve/v1/session` create/send, NDJSON stream with cursor catch-up, cancel,
+`/eve/v1/session/:id/access`) plus `GET /tealbrick/v1/info`, which reports
+`harness`, `protocol: "tealbrick-native"`, `model`, `capabilities` and
+`unsupported` honestly. `/eve/v1/info`, reset/clear/compact, attachments,
+approvals, subagents, workflows and schedules return 404/400. The native
+harness keeps the conversation: Claude turns resume the same SDK session id,
+and a restarted server only re-attaches transcripts that still exist.
+
+While running, serve keeps the runtime connection synced with Portal even when
+no turn is active: it fetches the signed runtime config and acknowledges it on
+start and every 60–120 s (jittered; exponential backoff to 4 min on errors), so
+Portal does not mark an idle runtime as expired after the 300 s config lease.
+Changes are logged as `native.runtime.synced`; a revoked credential (HTTP 401)
+stops the loop with one `native.runtime.sync.stopped` line. The per-turn
+`tealbrick` MCP child still fetches a fresh authorization for every call.
+
+### Security posture
+
+- Binds `127.0.0.1` only. Reach it from the tailnet through a TLS-terminating
+  proxy (preferred: `tailscale serve`, including for customer deployments).
+- Every request except `/healthz` is verified against Portal (identity token
+  plus policy bundle for this agent) and must come from the enrolled owner.
+- The `Host` header must be loopback, the enrolled `publicUrl` host or an
+  explicit `allowedHosts` entry. Any `Origin` header is rejected. Bodies are
+  limited to 128 KiB and two concurrent turns by default (`maxActiveTurns`).
+- New sessions are **Restricted**: `Read`/`Glob`/`Grep` contained to the
+  profile `cwd` (never the kit's `.tealbrick`), operator-vetted `readTools`, and
+  `mcp__tealbrick__*` only. Shell, file writes, network tools, delegation and
+  project/user Claude settings are unavailable; a PreToolUse hook and
+  `canUseTool` enforce the same decision. The kit's child-agent guard still
+  denies Teal Brick tools to subagents. Optional `tealbrickCalls` adds a
+  local operation ceiling on top of Portal grants.
+- A per-agent default can widen Restricted with `defaultTools` (only
+  `WebSearch`, `WebFetch`, `Agent`, `TodoWrite`; never shell or writes).
+  `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.
+  Owner **standing grants** (below) can pre-approve bounded classes of these
+  calls.
+  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
+  (plugin and action names only; no credentials, leases or account
+  references). TBD uses it for Chat → Plugins.
+- Elevation only through Desktop's session-access control (owner, explicit
+  confirmation, optimistic revision, no turn in flight). **Native defaults**
+  snapshots `nativeTools` (still workspace-contained); **Full** uses the
+  Claude Code tool preset with permission bypass. Full is not a security
+  boundary against the local OS user.
+- The SDK process receives an allowlisted environment (`PATH`, `HOME`, locale,
+  CA settings, `envPassthrough`) and never `TEALBRICK_*` values. Logs carry ids,
+  tool names and status codes, never prompts, tool inputs or results.
+
+### Standing grants (`claude.standingGrants`, opt-in)
+
+The owner can pre-approve bounded classes of approval-gated calls, so matching
+calls run without a per-payload prompt. The kit's PreToolUse hook enforces
+them (never the model); a grant only replaces the prompt and never widens
+what Portal grants, the `tealbrickCalls` ceiling or an expert contract allow.
+
+```json
+"standingGrants": [
+  {
+    "id": "community-telegram",
+    "description": "Post event announcements to the community channel",
+    "operation": "marketplace_execute",
+    "match": {"plugin": "community-telegram", "action": "telegram.send_*"},
+    "experts": ["publication-operator"],
+    "caps": {"perDay": 10, "perHour": 3, "minIntervalSeconds": 120},
+    "expires": "2026-12-31T23:59:59Z",
+    "deny": {"inputPattern": ["@everyone", "invoice"]}
+  }
+]
+```
+
+- **Scope.** Up to 64 grants, checked in order, only for
+  `mcp__tealbrick__tealbrick_call` calls that would otherwise pause for
+  approval (`approvalOperations` or a contract's approval rules). `operation`
+  (default `marketplace_execute`) must equal the call's operation. `match`
+  needs at least one of `registrationId` (case-sensitive), `plugin`, `action`
+  (case-insensitive); each is an exact string or a simple `*` glob, and
+  `plugin`/`action` may be lists. Plugin and action come from this runtime's
+  own Marketplace grant snapshot for the call's `registrationId`; when they
+  cannot be resolved the grant does not match.
+- **Who.** Without `experts` a grant covers the owner session only. `experts`
+  lists contract ids whose subagents may also use it (unknown ids are refused
+  at load).
+- **Caps.** `perDay` (1-200, rolling 24 hours), optional `perHour` and
+  `minIntervalSeconds`. A capped or expired grant falls back to the normal
+  payload approval (never a silent deny) and is traced as
+  `standing_grant.exhausted`. `deny.inputPattern` entries are case-insensitive
+  literal substrings of the call's JSON input; a hit makes the grant not apply.
+- **Expiry.** `expires` (ISO 8601 with offset) is required; expired grants never
+  match and are not advertised to the model.
+- **Revoke.** Remove (or edit) the grant in `native-serve.json` and restart
+  `native serve` and `native acp`.
+- **Counters.** Usage timestamps per grant id persist in
+  `.tealbrick/native-serve/standing-grants.json` (0600, pruned to 24 hours) and
+  are shared by `native serve` and `native acp` on the same kit root. Each
+  check-and-record runs under an exclusive `standing-grants.json.lock` file
+  (`O_EXCL`, retried for up to 3 s; a lock older than 30 s is treated as
+  abandoned) and writes are tmp + rename. If the lock or the file is
+  unavailable, no standing approval is given.
+- **Audit.** Each use logs `claude.tool` with `approval: "standing:<id>"` and
+  traces `owner.approval` with `approval: "standing"`, `grantId`, operation,
+  registration, plugin and action (no payload). `GET /tealbrick/v1/capabilities`
+  lists every grant with its caps, remaining uses today, expiry and expired
+  flag (deny patterns as a count only). The owner session's system prompt
+  lists unexpired grants and states that anything else still needs approval,
+  and that spending, contracts or signatures and first contact with strangers
+  are never covered unless a grant explicitly says so.
+- **`native acp`** has no approval surface: calls covered by a grant proceed,
+  everything else is still declined.
+
+### 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:
+
+```json
+{
+  "version": 1,
+  "port": 5331,
+  "claude": {
+    "cwd": "/Users/you/agents/agent-serve/workspace",
+    "instructionsFile": "/Users/you/agents/agent-profile/agents/agent/INSTRUCTIONS.md",
+    "recipe": {"path": "/Users/you/.config/tealbrick-native/config.json", "agent": "agent"},
+    "requireSubscription": true,
+    "defaultTools": ["WebSearch", "WebFetch", "Agent"],
+    "experts": {
+      "source-researcher": {"promptFile": "/Users/you/agents/agent-profile/experts/source-researcher.md", "tools": ["WebSearch", "WebFetch"]},
+      "independent-reviewer": {"promptFile": "/Users/you/agents/agent-profile/experts/independent-reviewer.md"}
+    },
+    "nativeTools": ["Read", "Glob", "Grep", "Write", "Edit", "TodoWrite", "WebSearch", "WebFetch"]
+  }
+}
+```
+
+`recipe` imports `model`, `effort`, `maxTurns`, `maxBudgetUsd`,
+`timeoutSeconds` and the agent's `mcpServers`, `readTools` and
+`tealbrickCalls` from an existing tealbrick-native recipe; its
+`tealbrickSdkConfig` must point at this kit root's `native-sdk.json`. Any of
+those keys set directly under `claude` override the recipe. Keep `cwd` stable:
+Claude session transcripts are stored per working directory. `requireSubscription`
+refuses turns unless the SDK reports first-party subscription sign-in.
+Codex roots use `"codex": {"codexBin": "/abs/codex", "cwd": "/abs/dir"}`.
+
+Install the Claude Agent SDK next to the kit (or set `claude.sdkModule` to an
+absolute SDK package directory):
+
+```sh
+npm install --save-exact @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+### Run, expose, enroll
+
+```sh
+# 1. Tailnet HTTPS in front of the loopback port (pick a free HTTPS port).
+tailscale serve --bg --https=8444 http://127.0.0.1:5331
+# 2. Record the Portal identity and register the URL on the EXISTING agent.
+npx --no-install tealbrick native enroll --url https://HOST.TAILNET.ts.net:8444
+# 3. Start the endpoint (foreground) ...
+npx --no-install tealbrick native serve
+# ... or supervise it with a user LaunchAgent (macOS, opt-in).
+npx --no-install tealbrick native serve --install-launchd
+npx --no-install tealbrick native serve --uninstall
+# 4. Re-run enroll to confirm /healthz and authenticated /tealbrick/v1/info.
+npx --no-install tealbrick native enroll --url https://HOST.TAILNET.ts.net:8444
+```
+
+`enroll` signs in with Portal device approval, requires the kit root's owned
+agent and canvas card to carry the native harness label, registers the origin
+through Portal's owned-connection API (which keeps the harness label; it never
+uses the Eve registration route, which relabels agents as Eve), records
+`agent` and `publicUrl` in `native-serve.json`, updates the card endpoint with
+a revision-checked draft write and verifies the sidebar URL. It then probes the
+endpoint; exit code 2 means Portal is updated but the endpoint was not yet
+reachable or authenticated. The user token is never written to disk.
+LaunchAgent logs go to `.tealbrick/native-serve/logs/`; session projections
+(customer data) to `.tealbrick/native-serve/sessions/`.

package/RUNTIME.md

@@ -26,7 +26,7 @@ The Portal signs a metadata-only configuration lease (maximum five minutes). The
 
 ### Canary verification, 2026-09-18
 
-Private candidate tarballs installed only in Aura Canary on Nucbox exposed the three memory reads. The authenticated desktop conversation retrieved a synthetic Knowledge document with its citation; a subsequent scoped fact-only recall returned six facts extracted by native GBrain. Update/Delete, cross-partition reads and agent extraction/admin requests were denied. This is not an npm publication or a general memory-quality certification. Query expansion degraded on one live request; serialized background extraction temporarily blocked entity enumeration, and the completed entity register remained empty despite fact-linked entity slugs. See the LABS report `report/readiness-2026-09-18-knowledge-live-canary.md` for exact deployment and remaining defects.
+Private candidate tarballs installed only in a private canary agent on the deployment host exposed the three memory reads. The authenticated desktop conversation retrieved a synthetic Knowledge document with its citation; a subsequent scoped fact-only recall returned six facts extracted by native GBrain. Update/Delete, cross-partition reads and agent extraction/admin requests were denied. This is not an npm publication or a general memory-quality certification. Query expansion degraded on one live request; serialized background extraction temporarily blocked entity enumeration, and the completed entity register remained empty despite fact-linked entity slugs. See the LABS report `report/readiness-2026-09-18-knowledge-live-canary.md` for exact deployment and remaining defects.
 
 ## Native workflows