@tealbrick/kit 0.1.0

package/dist/index.js

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import { avmConfigSchema } from '@tealbrick/avm/client';
+import { readFile, writeFile, mkdir, unlink, lstat, realpath, rename } from 'node:fs/promises';
+import { resolve, dirname, relative, sep } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { validateVoiceConfig } from '@tealbrick/voice';
+import { validateVisionConfig } from '@tealbrick/vision';
+import { validateDeliveryConfig } from '@tealbrick/deliver';
+const auth = z.object({ issuer: z.string().url().refine(v => new URL(v).protocol === 'https:'), org: z.string().min(1), agent: z.string().min(1) }).strict();
+const media = z.object({ settings: z.unknown(), authorizationModule: z.string().optional() }).strict();
+const schema = z.object({ version: z.literal(1), portal: auth.optional(), voice: media.optional(), vision: media.optional(), deliver: z.unknown().optional(), avm: z.custom(v => avmConfigSchema.safeParse(v).success).transform(v => 'target' in v ? { target: v.target, sudo: v.sudo ?? false, ...Object.fromEntries(Object.entries(v).filter(([k]) => k !== 'target' && k !== 'sudo')) } : v).optional() }).strict();
+export const capabilities = ['portal', 'voice', 'vision', 'deliver', 'avm'];
+const marker = '// Managed by @tealbrick/kit. Change selection with tealbrick setup.\n';
+const render = (body) => marker + body + '\n';
+const hash = (data) => createHash('sha256').update(data).digest('hex');
+/** Pure mount plan: dependencies alone never contribute capabilities to Eve. */
+export function planKit(value) {
+    const c = schema.parse(value), files = {};
+    if ((c.voice || c.vision) && !c.portal)
+        throw Error('kit_media_requires_portal_binding');
+    if (c.portal)
+        files['agent/channels/eve.ts'] = render(`import {eveChannel} from 'eve/channels/eve';\nimport {portalAuth} from '@tealbrick/portal/eve';\nexport default eveChannel({auth:[portalAuth(${JSON.stringify(c.portal)})]});`);
+    for (const kind of ['voice', 'vision']) {
+        const item = c[kind];
+        if (!item)
+            continue;
+        const settings = kind === 'voice' ? validateVoiceConfig(item.settings) : validateVisionConfig(item.settings);
+        if (!settings.enabled)
+            throw Error('kit_selected_media_must_be_enabled');
+        const endpoints = kind === 'vision' ? [settings.endpoint] : Object.values(settings).filter((v) => !!v && typeof v === 'object' && 'url' in v);
+        if (!endpoints.length)
+            throw Error('kit_selected_media_requires_endpoint');
+        const approved = new Map();
+        for (const e of endpoints) {
+            if (e.credentialRef && !/^TEALBRICK_[A-Z0-9_]+$/.test(e.credentialRef))
+                throw Error('kit_use_tealbrick_secret_environment_reference');
+            const previous = approved.get(e.url) ?? { url: e.url, credentialRefs: [], allowAnonymous: false, allowLoopback: new URL(e.url).protocol === 'http:' };
+            if (e.credentialRef)
+                previous.credentialRefs.push(e.credentialRef);
+            else
+                previous.allowAnonymous = true;
+            approved.set(e.url, previous);
+        }
+        const options = `{auth:${JSON.stringify(c.portal)},endpoints:${JSON.stringify([...approved.values()])},getConfig:()=>(${JSON.stringify(settings)}),resolveCredential:({reference})=>runtimeSecret(reference)}`;
+        files[`agent/channels/tealbrick-${kind}.ts`] = render(`import {${kind}Channel} from '@tealbrick/${kind}/eve';\nimport {runtimeSecret} from '@tealbrick/kit/secrets';\nexport default ${kind}Channel(${options});`);
+        if (kind === 'vision' && item.authorizationModule) {
+            const module = item.authorizationModule;
+            if (!/^agent\/lib\/[a-zA-Z0-9_/-]+\.(ts|js|mjs)$/.test(module) || module.includes('..'))
+                throw Error('kit_invalid_vision_authorization_module');
+            let specifier = relative('agent/tools', module).split(sep).join('/');
+            if (!specifier.startsWith('.'))
+                specifier = './' + specifier;
+            files['agent/tools/vision.ts'] = render(`import {visionTool} from '@tealbrick/vision/eve';\nimport {runtimeSecret} from '@tealbrick/kit/secrets';\nimport getAuthorization from ${JSON.stringify(specifier)};\nexport default visionTool({...${options},getAuthorization});`);
+        }
+    }
+    if (c.deliver !== undefined) {
+        const config = validateDeliveryConfig(c.deliver);
+        files['agent/tools/deliver.ts'] = render(`import {deliverTool} from '@tealbrick/deliver/eve';\nimport {secretEnvironment} from '@tealbrick/kit/secrets';\nexport default deliverTool({config:${JSON.stringify(config)},driverOptions:{env:secretEnvironment()}});`);
+    }
+    if (c.avm)
+        files['agent/extensions/tealbrick-avm.ts'] = render(`import avm from '@tealbrick/avm/eve';\nexport default avm(${JSON.stringify(c.avm)});`);
+    return { enabled: capabilities.filter(k => c[k] !== undefined), files };
+}
+async function optional(path) { try {
+    return await readFile(path, 'utf8');
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        return null;
+    throw e;
+} }
+/** Reject symlinked output parents; never write through project-controlled indirection. */
+async function safe(root, path) { const resolved = resolve(root, path); if (!resolved.startsWith(root + sep))
+    throw Error('kit_invalid_path'); let current = root; for (const part of relative(root, resolved).split(sep)) {
+    current = resolve(current, part);
+    try {
+        if ((await lstat(current)).isSymbolicLink())
+            throw Error('kit_symlink_path');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+} return resolved; }
+export async function readKit(root) { const raw = await optional(resolve(root, '.tealbrick/kit-state.json')); if (!raw)
+    return { version: 1 }; const s = JSON.parse(raw); planKit(s.config); return s.config; }
+/** Applies only exact kit-owned files. Unselected features have no mounts at all. */
+export async function applyKit(root, config, credentials = {}) {
+    if (Object.entries(credentials).some(([k, v]) => !/^TEALBRICK_[A-Z0-9_]+$/.test(k) || typeof v !== 'string' || !v || /[\r\n\0]/.test(v)))
+        throw Error('kit_invalid_credentials');
+    root = await realpath(root);
+    const plan = planKit(config), statePath = await safe(root, '.tealbrick/kit-state.json');
+    await mkdir(dirname(statePath), { recursive: true, mode: 0o700 });
+    const lock = await safe(root, '.tealbrick/kit.lock');
+    try {
+        await writeFile(lock, 'activation\n', { flag: 'wx', mode: 0o600 });
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            throw Error('kit_activation_locked');
+        throw e;
+    }
+    try {
+        const raw = await optional(statePath), old = raw ? JSON.parse(raw) : { version: 1, config: { version: 1 }, files: {} };
+        if (old.version !== 1 || !old.files || !old.config)
+            throw Error('kit_invalid_state');
+        const oldPlan = planKit(old.config);
+        if (JSON.stringify(Object.keys(old.files).sort()) !== JSON.stringify(Object.keys(oldPlan.files).sort()))
+            throw Error('kit_invalid_state');
+        for (const [name, digest] of Object.entries(old.files))
+            if (digest !== hash(oldPlan.files[name]))
+                throw Error('kit_invalid_state');
+        const names = [...new Set([...Object.keys(old.files), ...Object.keys(plan.files)])];
+        const before = new Map();
+        for (const name of names) {
+            const path = await safe(root, name), content = await optional(path);
+            before.set(name, content);
+            if (name in old.files) {
+                if (content === null || hash(content) !== old.files[name])
+                    throw Error(`kit_owned_file_changed:${name}`);
+            }
+            else if (content !== null)
+                throw Error(`kit_mount_conflict:${name}`);
+        }
+        if (config.vision?.authorizationModule) {
+            const path = await safe(root, config.vision.authorizationModule);
+            if (await optional(path) === null)
+                throw Error('kit_vision_authorization_module_missing');
+        }
+        const secretPath = await safe(root, '.tealbrick/kit.credentials.json'), secretBefore = await optional(secretPath);
+        if (secretBefore !== null && process.platform !== 'win32' && ((await lstat(secretPath)).mode & 0o077))
+            throw Error('kit_secret_permissions');
+        const mergedSecrets = { ...(secretBefore ? JSON.parse(secretBefore) : {}), ...credentials };
+        if (Object.entries(mergedSecrets).some(([k, v]) => !/^TEALBRICK_[A-Z0-9_]+$/.test(k) || typeof v !== 'string' || !v || /[\r\n\0]/.test(v)))
+            throw Error('kit_invalid_credentials');
+        const ignore = await safe(root, '.gitignore'), ignoreBefore = await optional(ignore);
+        const temp = `${statePath}.${randomUUID()}`;
+        try {
+            if (!(ignoreBefore ?? '').split(/\r?\n/).includes('/.tealbrick/'))
+                await writeFile(ignore, `${ignoreBefore ?? ''}${ignoreBefore && !ignoreBefore.endsWith('\n') ? '\n' : ''}/.tealbrick/\n`);
+            if (Object.keys(credentials).length)
+                await writeFile(secretPath, JSON.stringify(mergedSecrets, null, 2) + '\n', { mode: 0o600 });
+            for (const name of names) {
+                const path = resolve(root, name);
+                if (name in plan.files) {
+                    await mkdir(dirname(path), { recursive: true });
+                    await writeFile(path, plan.files[name]);
+                }
+                else
+                    await unlink(path);
+            }
+            const state = { version: 1, config, files: Object.fromEntries(Object.entries(plan.files).map(([k, v]) => [k, hash(v)])) };
+            await writeFile(temp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+            await rename(temp, statePath);
+        }
+        catch (error) {
+            await unlink(temp).catch(() => { });
+            if (secretBefore === null)
+                await unlink(secretPath).catch(() => { });
+            else
+                await writeFile(secretPath, secretBefore, { mode: 0o600 });
+            for (const [name, content] of before) {
+                const path = resolve(root, name);
+                if (content === null)
+                    await unlink(path).catch(() => { });
+                else
+                    await writeFile(path, content);
+            }
+            if (ignoreBefore === null)
+                await unlink(ignore).catch(() => { });
+            else
+                await writeFile(ignore, ignoreBefore);
+            throw error;
+        }
+        return { enabled: plan.enabled, mounted: Object.keys(plan.files), removed: Object.keys(old.files).filter(k => !(k in plan.files)), requiresReload: true };
+    }
+    finally {
+        await unlink(lock);
+    }
+}

package/dist/onboarding.d.ts

@@ -0,0 +1,32 @@
+import { PortalClient } from '@tealbrick/portal';
+export interface PortalLogin {
+    client: PortalClient;
+    org: string;
+    userId: string;
+    workspaces: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/** Reject URLs that would leak credentials or be silently truncated by registration. */
+export declare function portalOrigin(value: string): string;
+export declare function agentOrigin(value: string): string;
+/** Device authorization is interactive; user/refresh tokens never enter kit state. */
+export declare function loginPortal(issuer: string, show: (url: string, code: string) => void, options?: {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<PortalLogin>;
+/** Reuse Portal's owned registration + revision-checked canvas APIs, not a parallel card store. */
+export declare function registerPortalCard(login: PortalLogin, input: {
+    workspaceId: string;
+    name: string;
+    url: string;
+}): Promise<{
+    agentId: string;
+    workspaceId: string;
+    name: string;
+    url: string;
+    created: boolean;
+    discovered: boolean;
+}>;

package/dist/onboarding.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { PortalClient, PortalHttpError } from '@tealbrick/portal';
+/** Reject URLs that would leak credentials or be silently truncated by registration. */
+export function portalOrigin(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+        throw Error('kit_portal_https_origin_required');
+    return url.origin;
+}
+export function agentOrigin(value) {
+    const url = new URL(value);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+        throw Error('kit_agent_origin_required');
+    return url.origin;
+}
+/** Device authorization is interactive; user/refresh tokens never enter kit state. */
+export async function loginPortal(issuer, show, options = {}) {
+    issuer = portalOrigin(issuer);
+    const client = new PortalClient({ issuer, fetch: options.fetch });
+    const device = await client.startDevice({ deviceId: randomUUID(), deviceLabel: 'Teal Brick package setup' });
+    const verification = new URL(device.verification_uri_complete);
+    if (verification.origin !== issuer || verification.username || verification.password)
+        throw Error('kit_portal_verification_origin_mismatch');
+    show(verification.href, device.user_code);
+    const now = options.now ?? Date.now, sleep = options.sleep ?? (ms => new Promise(r => setTimeout(r, ms)));
+    const deadline = now() + Math.min(device.expires_in, 900) * 1000;
+    let interval = Math.max(1, device.interval) * 1000;
+    let session;
+    while (now() < deadline) {
+        await sleep(Math.min(interval, Math.max(0, deadline - now())));
+        if (now() >= deadline)
+            break;
+        try {
+            session = await client.pollDevice(device.device_code);
+            break;
+        }
+        catch (error) {
+            if (error instanceof PortalHttpError && error.code === 'authorization_pending')
+                continue;
+            if (error instanceof PortalHttpError && error.code === 'slow_down') {
+                interval += 5000;
+                continue;
+            }
+            throw error;
+        }
+    }
+    if (!session)
+        throw Error('kit_portal_login_expired');
+    if (session.issuer !== issuer)
+        throw Error('kit_portal_issuer_mismatch');
+    const authenticated = new PortalClient({ issuer, fetch: options.fetch, token: session.token });
+    const account = await authenticated.request('/api/account');
+    const directory = await authenticated.request('/api/me/workspaces');
+    if (!account.user?.id || !account.user.orgId || directory.accountId !== account.user.id || directory.organizationId !== account.user.orgId || !Array.isArray(directory.workspaces) || directory.workspaces.some(w => !w.id || !w.name))
+        throw Error('kit_portal_account_mismatch');
+    return { client: authenticated, org: account.user.orgId, userId: account.user.id, workspaces: directory.workspaces };
+}
+/** Reuse Portal's owned registration + revision-checked canvas APIs, not a parallel card store. */
+export async function registerPortalCard(login, input) {
+    const { client } = login, url = agentOrigin(input.url), name = input.name.trim();
+    if (!name || name.length > 80)
+        throw Error('kit_agent_name_required');
+    if (!login.workspaces.some(w => w.id === input.workspaceId))
+        throw Error('kit_portal_workspace_required');
+    const path = `/api/workspace?workspaceId=${encodeURIComponent(input.workspaceId)}`;
+    const initial = await client.request(path);
+    if (initial.workspace?.id !== input.workspaceId || !Array.isArray(initial.agents))
+        throw Error('kit_portal_workspace_mismatch');
+    const existing = initial.agents?.find(a => a.name.toLowerCase() === name.toLowerCase());
+    if (existing && existing.name !== name)
+        throw Error('kit_portal_use_existing_agent_name');
+    if (existing && !existing.bindable)
+        throw Error('kit_portal_agent_not_owned');
+    // The endpoint is an upsert scoped by the authenticated organization and name.
+    const registered = await client.registerAgent(name, url);
+    if (registered.url !== url || registered.name !== name)
+        throw Error('kit_portal_registered_identity_mismatch');
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const snapshot = await client.request(path);
+        if (snapshot.workspace?.id !== input.workspaceId || !Number.isInteger(snapshot.draftRevision) || !snapshot.agents?.some(a => a.id === registered.id && a.bindable))
+            throw Error('kit_portal_owned_agent_missing');
+        const draft = snapshot.draft ?? { version: 1, name: snapshot.workspace.name, nodes: [], edges: [] };
+        const matches = draft.nodes.filter(n => n.data.kind === 'agent' && n.data.agentId === registered.id);
+        if (matches.length > 1)
+            throw Error('kit_portal_duplicate_agent_card');
+        const previous = matches[0];
+        const card = { id: previous?.id ?? `tealbrick-${randomUUID()}`, type: 'instrument', position: previous?.position ?? { x: 80, y: 80 + draft.nodes.length * 120 }, data: { ...previous?.data, kind: 'agent', label: name, harness: 'eve', agentId: registered.id, endpoint: url, authMethod: 'portal-pairing' } };
+        if (!previous || previous.data.endpoint !== url || previous.data.label !== name || previous.data.harness !== 'eve' || previous.data.authMethod !== 'portal-pairing') {
+            const nodes = previous ? draft.nodes.map(n => n.id === previous.id ? card : n) : [...draft.nodes, card];
+            try {
+                await client.request('/api/workspace/draft', { workspaceId: input.workspaceId, draftRevision: snapshot.draftRevision, draft: { ...draft, nodes } });
+            }
+            catch (error) {
+                if (error instanceof PortalHttpError && error.code === 'draft_changed_reload' && attempt < 2)
+                    continue;
+                throw error;
+            }
+        }
+        const directory = await client.request(`/api/me/agents?workspaceId=${encodeURIComponent(input.workspaceId)}`);
+        if (directory.workspaceId !== input.workspaceId || !directory.agents.some(a => a.id === registered.id && a.url === url))
+            throw Error('kit_portal_sidebar_verification_failed');
+        return { agentId: registered.id, workspaceId: input.workspaceId, name, url, created: registered.created, discovered: true };
+    }
+    throw Error('kit_portal_canvas_changed_retry');
+}

package/dist/secrets.d.ts

@@ -0,0 +1,3 @@
+export declare function runtimeSecret(name: string): string;
+/** Lazy: does not read credentials during discovery/build or for unused providers. */
+export declare function secretEnvironment(): NodeJS.ProcessEnv;

package/dist/secrets.js

@@ -0,0 +1,25 @@
+import { readFileSync, lstatSync } from 'node:fs';
+const namePattern = /^TEALBRICK_[A-Z0-9_]+$/;
+export function runtimeSecret(name) {
+    if (!namePattern.test(name))
+        throw Error('kit_invalid_secret_reference');
+    let value = process.env[name];
+    if (!value) {
+        try {
+            const path = '.tealbrick/kit.credentials.json', stat = lstatSync(path);
+            if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== 'win32' && (stat.mode & 0o077)))
+                throw Error('kit_secret_permissions');
+            const data = JSON.parse(readFileSync(path, 'utf8'));
+            value = data[name];
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw Error('kit_secret_unavailable');
+        }
+    }
+    if (typeof value !== 'string' || !value || /[\r\n\0]/.test(value))
+        throw Error('kit_secret_unavailable');
+    return value;
+}
+/** Lazy: does not read credentials during discovery/build or for unused providers. */
+export function secretEnvironment() { return new Proxy({}, { get: (_target, name) => typeof name === 'string' ? runtimeSecret(name) : undefined }); }

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tealbrick/kit",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Complete Teal Brick package kit with explicit Eve capability activation",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "BOOTSTRAP.md"
+  ],
+  "bin": {
+    "tealbrick": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./secrets": {
+      "types": "./dist/secrets.d.ts",
+      "import": "./dist/secrets.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build --workspace @tealbrick/provider-transport --workspace @tealbrick/portal --workspace @tealbrick/voice --workspace @tealbrick/vision --workspace @tealbrick/deliver --workspace @tealbrick/avm && tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@tealbrick/portal": "0.1.0",
+    "@tealbrick/avm": "0.1.0",
+    "@tealbrick/voice": "0.1.0",
+    "@tealbrick/vision": "0.1.0",
+    "@tealbrick/deliver": "0.1.0",
+    "@inquirer/prompts": "8.7.2",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "eve": ">=0.55.0 <0.56.0"
+  },
+  "peerDependenciesMeta": {
+    "eve": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Doppelabs/tealbrick-packages.git",
+    "directory": "packages/kit"
+  }
+}