@tealbrick/kit 0.1.0

package/BOOTSTRAP.md

@@ -0,0 +1,252 @@
+# Bootstrap an Eve agent with Teal Brick
+
+This guide installs the seven implemented packages through one kit and activates
+only the capabilities you select. The supported harness line is **Eve 0.55.x**;
+**0.55.0** and **AI SDK 7.0.93** are the current tested versions. Use Node **24**.
+
+**Release status:** the npm installation in step 3 becomes available once
+`@tealbrick/kit@0.1.0` is published. Until then, use the local-tarball alternative
+below. Do not substitute an unrelated unscoped `tealbrick` npm package.
+
+## 1. Install Node and npm
+
+Install Node 24 using the [official Node.js installer or installation instructions](https://nodejs.org/en/download).
+Then open a terminal and check:
+
+```bash
+node --version
+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
+Nucbox/Fedora N150. 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.55.0 init tealbrick-agent --model openai/gpt-5.6-terra
+```
+
+Finish scaffolding and return to the terminal before continuing. If Eve starts
+`eve dev` automatically, press Ctrl+C to stop it. Then run:
+
+```bash
+cd tealbrick-agent
+npm install --save-exact eve@0.55.0 ai@7.0.93
+```
+
+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.56 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:
+
+```bash
+read -r -s -p 'AI Gateway API key: ' AI_GATEWAY_API_KEY
+export AI_GATEWAY_API_KEY
+printf '\n'
+```
+
+For an existing AVMM model broker, Codex subscription or direct model provider,
+configure Eve's model through that provider's supported path instead. Teal Brick
+Portal authentication and voice/vision keys do not authenticate the primary LLM.
+Never copy a host's provider login files into a worker to make this step work.
+
+## 3. Install the complete kit
+
+**After npm publication:**
+
+```bash
+npm install --save-exact @tealbrick/kit@0.1.0
+```
+
+This installs Portal, AVM, Voice, Vision, Deliver and the shared provider transport
+as dependencies. You do not install or select provider transport separately.
+Installation alone exposes no Teal Brick tools or routes.
+
+If the package is not yet available, perform the tarball installation below, then
+continue with step 4. An npm 404 is not a reason to install a different package.
+
+## 4. Run Teal Brick setup
+
+From the new Eve project root:
+
+```bash
+npx --no-install tealbrick setup
+```
+
+This is the real CLI command: `tealbrick` belongs to the installed kit. There is
+no `eve tealbrick setup` subcommand. `--no-install` ensures npm uses the local
+binary rather than downloading a similarly named package.
+
+Use Space to select capabilities, Enter to continue, and review the selection
+before applying it. Voice, Vision, Deliver and AVM start unchecked. Portal sign-in
+and its authenticated Eve channel are required by the interactive setup.
+
+| Select | What setup asks for | What becomes available |
+|---|---|---|
+| Portal (required) | Issuer URL, browser sign-in, workspace, agent name and reachable agent origin | Authenticated Eve channel, owned agent registration and workspace card |
+| Voice | Live voice, STT and/or TTS; endpoint URL, model, API token where needed, voice for synthesis/live | Only the configured voice routes |
+| Vision | Endpoint protocol, URL, model and API token | Vision HTTP routes; native tool requires an additional trusted auth adapter |
+| Deliver | Storage provider, bucket/target, credentials, link access and prefix | A `deliver` tool for sandbox files |
+| AVM | Paired or operator transport, SSH target, key path, optional operator sudo | Inspection; mutations require separately configured exact grants |
+
+### Portal
+
+Setup shows a Portal verification URL and code. Open it in your browser, sign in
+and approve the device request. Setup obtains your organization from the signed-in
+account; you do not enter organization IDs or copy tokens.
+
+Select an existing Portal workspace, enter the agent name and provide its origin
+(e.g. `https://agent.example.com`). The URL must be reachable from your desktop;
+it cannot contain credentials, query parameters or a path prefix. Create a workspace
+in Portal first if your account has none. An existing agent name updates that owned
+agent; use a distinct name for a different agent.
+
+After the configuration is applied, setup registers the owned agent, adds or updates
+its identity-bound canvas card, and verifies it appears in that workspace's desktop
+agent directory. It preserves other cards and edges, retries canvas revision
+conflicts, and does not create duplicate cards on a repeat setup with the same name.
+Select that same workspace in desktop and refresh discovery if needed.
+
+If registration or verification fails, setup exits unsuccessfully. Local settings
+may already be applied and the remote agent may already exist. Retry with the same
+name, issuer and workspace after resolving the error; do not assume the operation
+was rolled back. Setup never automatically retries an uncertain registration write.
+
+Portal currently stores the card's name, Eve harness, identity, agent URL and auth
+method. Its API does not accept provider/model/voice/vision configuration metadata;
+those settings remain in the local kit configuration. Raw keys are never uploaded.
+Browser login/refresh tokens remain in memory only for setup.
+
+If an existing `agent/channels/eve.ts` is already present, setup stops rather than
+replacing its authentication. Review and deliberately integrate that existing
+channel before retrying. A fresh project is the simplest first-run path.
+
+### Voice and Vision
+
+STT and TTS can use **different servers and separate API keys**. Their endpoints
+must implement the supported `openai-audio-v1` contract. Live voice uses a
+`live-json-v1` session endpoint; an arbitrary provider WebSocket URL is not a
+drop-in replacement. A live-voice client still has to negotiate/play the session.
+
+Vision supports OpenAI-compatible chat-completions or responses protocols. Start
+with the HTTP channel. Enable the optional native vision tool only when you have
+an existing trusted `agent/lib/...` module that supplies signed authorization for
+the current turn. Static owner tokens are not an acceptable substitute.
+
+### Document delivery with R2, S3 or a self-hosted bucket
+
+Choose the provider first. For Cloudflare R2, prepare the bucket and enter its S3
+API endpoint (`https://<account-id>.r2.cloudflarestorage.com`), bucket name and
+access key pair when prompted. AWS S3 and S3-compatible services such as MinIO have
+their own region/endpoint settings. Vercel Blob and an already-served directory
+are also supported; Vercel Blob is not required.
+
+Choose signed, expiring links where available, or public links deliberately.
+A public bucket option needs a working public HTTPS base URL. Directory delivery
+requires an existing writable directory and a separately configured HTTPS file
+server. Setup does not create buckets, configure DNS or start a file server.
+
+The resulting URL must be reachable by the intended desktop, mobile or Telegram
+client. A successful upload does not make a private LAN URL reachable externally.
+
+### AVM / AVMM
+
+Skip this checkbox if the agent does not need AVM inspection. Installing the kit
+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.
+
+Named profiles and exact mutation grants can be supplied through a reviewed
+configuration file using `npx --no-install tealbrick apply config.json`. Follow the
+AVM package README; workspace labels do not replace authenticated identities.
+
+## 5. Check and run
+
+```bash
+npx --no-install tealbrick status
+npx --no-install eve info --json
+npx --no-install eve build
+npx --no-install eve dev
+```
+
+Check that Eve reports ready with no errors, and that only the selected Teal Brick
+contributions appear. Eve's built-in tools are separate from the kit selection.
+`eve build` proves compilation; it does not verify your provider keys or endpoints.
+
+For a long-running deployment, stop development mode, build, then start the built
+agent with a process manager under the project owner's account:
+
+```bash
+npx --no-install eve build
+npx --no-install eve start --host 127.0.0.1 --port 2000
+```
+
+Choose an unused port. Put authenticated ingress in front of it when remote access
+is required. Portal registration is performed by setup; starting Eve does not enroll an AVMM host.
+
+## 6. Confirm the selected capabilities
+
+- Send one ordinary message and check that the configured primary model replies.
+- Deliver a disposable sandbox document, open its URL from the intended client,
+  and check public/signed access and expiry.
+- Exercise each selected voice endpoint separately, including separate STT/TTS
+  credentials. Check a live-voice session using its actual client.
+- Send an authorized image-analysis request and verify unauthorized callers are denied.
+- For AVM, begin with an allowed read. VM creation or lifecycle changes require an
+  explicit policy and their own acceptance checks.
+
+These are your deployment checks. Our automated suite uses deterministic models,
+fixture providers and disposable storage; it cannot prove your credentials work.
+
+## Change or disable a capability
+
+```bash
+npx --no-install tealbrick setup
+npx --no-install tealbrick status
+npx --no-install eve build
+```
+
+Restart the running Eve process after the rebuild. Deselecting a capability removes
+its kit-owned mounts. Setup refuses to overwrite hand-edited mounts. Saved settings
+and optional local secrets live under ignored `.tealbrick/`; secrets are not embedded
+in generated source. Disabling a capability does not revoke or delete its credentials.
+
+## Local-tarball installation before publication
+
+You need read access to the private package repository. On a development/build
+machine with Node 24:
+
+```bash
+git clone https://github.com/Doppelabs/tealbrick-packages.git
+cd tealbrick-packages
+npm ci --ignore-scripts
+npm run compatibility:validate
+```
+
+This produces verified `.tgz` files under `artifacts/packages/`. Copy all seven
+files together to the deployment account on Nucbox. From the fresh Eve project
+created in step 2, use the **absolute path** to that tarball directory:
+
+```bash
+TEALBRICK_TARBALLS=/absolute/path/to/tarballs
+for package in provider-transport portal avm voice vision deliver; do
+  npm pkg set "overrides.@tealbrick/$package=file:$TEALBRICK_TARBALLS/tealbrick-$package-0.1.0.tgz"
+done
+npm install --save-exact "$TEALBRICK_TARBALLS/tealbrick-kit-0.1.0.tgz"
+npx --no-install tealbrick setup
+```
+
+The overrides prevent npm from looking up unpublished internal dependencies.
+Keep the tarballs available while using these local overrides. When migrating to
+the public npm release, remove only these six Teal Brick override entries and
+replace the kit's file dependency with `@tealbrick/kit@0.1.0`, then run `npm install`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tealbrick contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,2 @@
+Independently authored for Teal Brick. Uses the existing Teal Brick capability
+packages; no upstream package implementation is copied. Eve compatibility 0.49.0.

package/README.md

@@ -0,0 +1,91 @@
+# @tealbrick/kit
+
+One installation, explicitly selected capabilities. The kit includes the currently
+implemented Portal, Voice, Vision, Deliver and AVM packages. Dependencies are code
+availability, not agent permissions. Nothing is mounted by installing the kit.
+
+Once published, the consumer workflow is:
+
+```sh
+npm install @tealbrick/kit
+npx --no-install tealbrick setup
+```
+
+The package is currently local/unpublished. Install the locally packed suite
+artifacts together until the npm scope is published. Eve 0.55.0 and Node 24 are the
+validated host versions; VM provisioning and Eve installation remain host setup.
+
+See [BOOTSTRAP.md](BOOTSTRAP.md) for the complete first-run guide, provider prompts, verification and pre-publication tarball installation.
+
+## Activation
+
+`tealbrick setup` presents unchecked capability choices for a fresh project. It
+requires Portal device sign-in and workspace selection, then asks for optional capability settings. Review and apply the selection, then
+rebuild/restart Eve. `tealbrick status` reports the saved selection and mount paths.
+
+| Choice | Exposed only when selected |
+|---|---|
+| Portal (required by setup) | Authenticated Eve channel and owned workspace agent card |
+| Voice | Voice manifest/session/transcribe/speak routes |
+| Vision | Vision manifest/analyze routes; optional native tool with trusted turn-auth module |
+| Deliver | Root deliver tool |
+| AVM | SSH inspection extension; no lifecycle mutation policy granted by setup |
+
+Interactive setup always binds Portal identity; offline `apply` retains explicit configuration control.
+Native Vision needs an existing module under `agent/lib/` default-exporting signed
+current-turn authorization headers. Setup never substitutes an owner token.
+Setup now registers and binds an agent card through existing Portal APIs and verifies
+workspace desktop discovery. Provider metadata synchronization and full live-voice
+client orchestration remain pending. The kit does not claim all planned Buzz/Knowledge/etc. work exists.
+
+Deselecting a capability removes its kit-owned mounts. Unselected capabilities add
+no tools, instructions, skills, hooks, channels, connections or schedules. Existing
+Eve built-ins and separately installed extensions remain the host's responsibility.
+The running process must be rebuilt/reloaded before removal takes effect there.
+
+## Ownership and credentials
+
+State lives in `.tealbrick/kit-state.json`. Generated mounts contain settings and
+secret references only. Optional local credentials go to owner-only
+`.tealbrick/kit.credentials.json`; `/.tealbrick/` is added to `.gitignore`.
+Runtime environment values take precedence. Secrets are loaded lazily during
+requests, never to discover/build disabled features. Deploy credentials using the
+host's secret facility and keep the runtime working directory at the project root.
+On Windows, configure account ACLs as well as the file permissions.
+
+Activation refuses to overwrite existing or operator-edited mounts. In particular,
+an existing `agent/channels/eve.ts` must be deliberately reconciled with Portal
+before kit management can own it. It never silently replaces another auth setup.
+Conflicting legacy standalone deliver mounts are likewise preserved. Deactivation
+keeps saved credentials; remove/revoke unused credentials separately when desired.
+A lock serializes kit operations; after a crashed operation inspect state/files
+before manually removing a stale `.tealbrick/kit.lock`.
+
+The internal `@tealbrick/provider-transport` is installed automatically through
+Voice/Vision/Deliver. npm deduplicates compatible versions. It is never a setup
+checkbox, running service or model-provider registry. The former unpublished
+`provider-runtime` name has been replaced.
+
+## Reproducible configuration
+
+`tealbrick apply config.json` applies a reviewed config; secrets must already be
+provided by runtime environment or the protected secret file. Empty config disables
+all kit-owned contributions:
+
+```json
+{"version":1}
+```
+
+Programmatic `planKit(config)` returns exactly which files would be mounted.
+`applyKit(projectRoot, config, credentials?)` checks ownership before changes,
+rolls back ordinary write failures and reports the required reload. No remote
+writes, service restarts or provider calls occur on installation or activation.
+
+Provider checks and native delivery-channel acceptance are separate. The terminal
+wizard can configure delivery storage but does not provision buckets or web servers.
+Tests validate empty/selected/deactivated discovery in a fresh packed Eve consumer,
+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.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/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 { collectSetup } from '@tealbrick/deliver/setup';
+import { applyKit, planKit, readKit } from './index.js';
+async function main() {
+    const command = process.argv[2], root = process.cwd();
+    if (command === 'status') {
+        const p = planKit(await readKit(root));
+        console.log(JSON.stringify({ enabled: p.enabled, mounts: Object.keys(p.files) }, null, 2));
+        return;
+    }
+    if (command === 'apply') {
+        const path = process.argv[3];
+        if (!path)
+            throw Error('kit_config_file_required');
+        console.log(JSON.stringify(await applyKit(root, JSON.parse(await readFile(path, 'utf8'))), null, 2));
+        return;
+    }
+    if (command !== 'setup') {
+        console.log('Usage: tealbrick setup | status | apply <config.json>\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.');
+    const old = await readKit(root);
+    const selected = await checkbox({ message: 'Activate capabilities (Space to select; everything else stays unmounted)', choices: [
+            { name: 'Voice: live-session / STT / TTS endpoints', value: 'voice', checked: !!old.voice },
+            { name: 'Vision API (native tool requires a trusted turn-auth adapter)', value: 'vision', checked: !!old.vision },
+            { name: 'Deliver files to chat', value: 'deliver', checked: old.deliver !== undefined },
+            { name: 'AVM inspection over SSH', value: 'avm', checked: !!old.avm },
+        ] });
+    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}`));
+    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 })) });
+    const name = (await input({ message: 'Agent name (unique in your organization)', default: old.portal?.agent })).trim();
+    const url = agentOrigin(await input({ message: 'Agent origin reachable from your desktop (https://agent.example.com)' }));
+    config.portal = { issuer, org: login.org, agent: name };
+    async function endpoint(label, protocol, spoken = false) {
+        const url = await input({ message: `${label} endpoint URL` }), model = await input({ message: `${label} model` });
+        const anonymous = await confirm({ message: `${label}: endpoint needs no API token?`, default: false });
+        const credentialRef = `TEALBRICK_${label.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_TOKEN`;
+        if (!anonymous) {
+            const value = await password({ message: `${label} API token (blank to use existing runtime secret ${credentialRef})`, mask: '*' });
+            if (value)
+                credentials[credentialRef] = value;
+        }
+        return { url, model, protocol, ...(!anonymous ? { credentialRef } : {}), ...(spoken ? { voice: await input({ message: `${label} voice` }) } : {}) };
+    }
+    if (selected.includes('voice')) {
+        const modes = await checkbox({ message: 'Voice capabilities', choices: [{ name: 'Live voice (live-json-v1 session API)', value: 'realtime' }, { name: 'Speech to text', value: 'transcription' }, { name: 'Text to speech', value: 'synthesis' }] });
+        if (!modes.length)
+            throw Error('kit_select_voice_mode');
+        const settings = { version: 1, enabled: true, displayName: 'Voice' };
+        for (const mode of modes)
+            settings[mode] = await endpoint(mode, mode === 'realtime' ? 'live-json-v1' : 'openai-audio-v1', mode !== 'transcription');
+        config.voice = { settings };
+    }
+    if (selected.includes('vision')) {
+        const protocol = await select({ message: 'Vision API protocol', choices: ['openai-chat-completions', 'openai-responses'] });
+        config.vision = { settings: { version: 1, enabled: true, displayName: 'Vision', endpoint: await endpoint('vision', protocol) } };
+        if (await confirm({ message: 'Also expose the native Vision tool? Requires an existing trusted turn-auth module.', default: false }))
+            config.vision.authorizationModule = await input({ message: 'Module exporting getAuthorization(context), under agent/lib/ (no static owner token)' });
+    }
+    if (selected.includes('deliver')) {
+        const result = await collectSetup({ select: (message, choices) => select({ message, choices }), input: (message, value) => input({ message, default: value }), password: message => password({ message, mask: '*' }), confirm: message => confirm({ message, default: false }) });
+        config.deliver = result.config;
+        Object.assign(credentials, result.credentials);
+    }
+    if (selected.includes('avm')) {
+        if (old.avm && 'profiles' in old.avm) {
+            const selectedProfile = await select({ message: 'AVM connection profile (paired identity and grants stay bound to this profile)', choices: Object.keys(old.avm.profiles), default: old.avm.selectedProfile });
+            config.avm = { ...old.avm, selectedProfile };
+        }
+        else {
+            const previous = old.avm;
+            const mode = await select({ message: 'AVM SSH transport', choices: [{ name: 'Paired AVMM user (workspace isolation)', value: 'paired' }, { name: 'Operator SSH account (host administration)', value: 'operator' }], default: previous?.mode ?? 'paired' });
+            const target = await input({ message: mode === 'paired' ? 'AVMM paired target (agentvm-client@hostname)' : 'SSH target for AVM', default: previous?.target });
+            const identityFile = await input({ message: 'Absolute path to SSH identity file (required for paired user)', default: previous?.identityFile });
+            const sudo = mode === 'operator' && await confirm({ message: 'Use sudo -n on that host?', default: previous?.sudo ?? false });
+            config.avm = { ...previous, target, mode, sudo, ...(identityFile ? { identityFile } : {}) };
+            if (mode === 'paired')
+                delete config.avm.identityTokenFile;
+        }
+    }
+    console.log(JSON.stringify({ enabled: planKit(config).enabled, mounts: Object.keys(planKit(config).files) }, null, 2));
+    if (!await confirm({ message: 'Apply settings and register this agent in the selected Portal workspace? Rebuild/restart Eve afterward.', default: false }))
+        return;
+    console.log(JSON.stringify(await applyKit(root, config, credentials), null, 2));
+    console.log(JSON.stringify(await registerPortalCard(login, { workspaceId, name, url }), null, 2));
+    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; });