@tealbrick/kit 0.3.0-rc.3 → 0.3.0-rc.5

package/dist/native-serve.js

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdir, realpath, writeFile, rename, unlink, lstat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { createPortalVerifier } from '@tealbrick/portal';
+import { createNativeBridge } from '@tealbrick/portal/native-bridge';
+import { CodexAppServer, codexHarness } from '@tealbrick/portal/native-codex';
+import { readKit } from './index.js';
+import { nativeSdkConfig } from './native-setup.js';
+import { claudeHarness, loadClaudeSdk } from './native-claude.js';
+import { startRuntimeSync } from './native-runtime-sync.js';
+import { publicHosts, readClaudeAttachment, readServeConfig, resolveClaudeProfile, servePaths } from './native-serve-config.js';
+/** LangChain has no stable session/stream/cancel contract to drive from here yet. */
+export function langchainHarness() { throw Error('kit_native_serve_langchain_unsupported'); }
+/** Build (but do not bind) the owner-authenticated chat endpoint for this kit root. */
+export async function createNativeServe(root, deps = {}) {
+    root = await realpath(root);
+    const kit = await readKit(root);
+    if (!kit.native || !kit.runtime)
+        throw Error('kit_native_setup_required');
+    if (!kit.native.active)
+        throw Error('runtime_product_inactive');
+    const config = await readServeConfig(root);
+    if (!config)
+        throw Error('kit_native_serve_config_required');
+    if (!config.agent)
+        throw Error('kit_native_serve_enroll_required');
+    if (config.agent.id !== kit.runtime.agentId)
+        throw Error('kit_native_serve_identity_mismatch');
+    const paths = servePaths(root), log = deps.log;
+    await mkdir(paths.state, { recursive: true, mode: 0o700 });
+    let adapter;
+    let codex;
+    if (kit.native.harness === 'claude') {
+        const profile = await resolveClaudeProfile(root, config);
+        adapter = claudeHarness({ name: config.agent.name, profile, attachment: await readClaudeAttachment(root), sdk: deps.claudeSdk ?? await loadClaudeSdk(root, profile.sdkModule), protectedPaths: [join(root, '.tealbrick')], log, env: deps.env });
+    }
+    else if (kit.native.harness === 'codex') {
+        if (!config.codex)
+            throw Error('kit_native_serve_codex_profile_required');
+        codex = new CodexAppServer(config.codex.codexBin, config.codex.cwd);
+        await codex.start();
+        const mcp = nativeSdkConfig('codex', root, { codexDelegationDisabled: true }).config.mcp_servers.tealbrick;
+        adapter = codexHarness(codex, { name: config.agent.name, cwd: config.codex.cwd, mcp, features: { multi_agent_v2: false }, log });
+    }
+    else
+        adapter = langchainHarness();
+    const authenticate = deps.authenticate ?? createPortalVerifier({ issuer: kit.runtime.issuer, org: kit.runtime.org, agent: config.agent.name }).authenticate;
+    const bridge = await createNativeBridge({ name: config.agent.name, ownerId: config.agent.ownerId, root: paths.state, port: config.port, allowedHosts: publicHosts(config), authenticate, adapter, maxActiveTurns: config.maxActiveTurns ?? 2, log });
+    // Portal marks a runtime expired unless it re-acknowledges its signed config within the 300s lease;
+    // an idle serve process has no per-turn MCP child doing that, so it keeps the lease itself.
+    const runtime = deps.runtimeSync === false ? undefined : startRuntimeSync(root, { log, ...deps.runtimeSync });
+    return { ...bridge, port: config.port, harness: kit.native.harness, runtime, close: async () => { await runtime?.stop(); await bridge.close(); await codex?.close(); } };
+}
+export async function serveNative(root) {
+    const serve = await createNativeServe(root);
+    // Loopback only. Remote reachability is a TLS-terminating proxy such as tailscale serve.
+    await new Promise((resolve, reject) => { serve.server.once('error', reject); serve.server.listen(serve.port, '127.0.0.1', () => resolve()); });
+    process.stderr.write(JSON.stringify({ event: 'native.serve.ready', harness: serve.harness, port: serve.port }) + '\n');
+    for (const signal of ['SIGTERM', 'SIGINT'])
+        process.once(signal, () => { void serve.close().finally(() => process.exit(0)); });
+}
+const xml = (v) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function launchdLabel(root) { return 'com.tealbrick.native-serve.' + createHash('sha256').update(root).digest('hex').slice(0, 12); }
+/** User LaunchAgent: restarts on crash, logs to the kit root's private state directory. */
+export function launchdPlist(root, options = {}) {
+    const node = options.node ?? process.execPath, cli = options.cli ?? fileURLToPath(new URL('./cli.js', import.meta.url)), logs = join(servePaths(root).state, 'logs');
+    const args = [node, cli, 'native', 'serve', '--root', root];
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>Label</key><string>${xml(launchdLabel(root))}</string>
+ <key>ProgramArguments</key><array>${args.map(a => `<string>${xml(a)}</string>`).join('')}</array>
+ <key>WorkingDirectory</key><string>${xml(root)}</string>
+ <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(dirname(node))}:/usr/bin:/bin:/usr/sbin:/sbin</string></dict>
+ <key>RunAtLoad</key><true/>
+ <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+ <key>ThrottleInterval</key><integer>30</integer>
+ <key>ProcessType</key><string>Background</string>
+ <key>Umask</key><integer>63</integer>
+ <key>StandardOutPath</key><string>${xml(join(logs, 'serve.out.log'))}</string>
+ <key>StandardErrorPath</key><string>${xml(join(logs, 'serve.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+export async function installLaunchd(root, options = {}) {
+    if ((options.platform ?? process.platform) !== 'darwin')
+        throw Error('kit_launchd_macos_only');
+    root = await realpath(root);
+    const config = await readServeConfig(root);
+    if (!config?.agent)
+        throw Error('kit_native_serve_enroll_required');
+    const label = launchdLabel(root), dir = join(options.home ?? homedir(), 'Library', 'LaunchAgents'), path = join(dir, label + '.plist');
+    await mkdir(join(servePaths(root).state, 'logs'), { recursive: true, mode: 0o700 });
+    await mkdir(dir, { recursive: true });
+    try {
+        if ((await lstat(path)).isSymbolicLink())
+            throw Error('kit_symlink_path');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await writeFile(path + '.tmp', launchdPlist(root), { mode: 0o600 });
+    await rename(path + '.tmp', path);
+    const exec = options.exec ?? promisify(execFile), domain = 'gui/' + (options.uid ?? process.getuid?.() ?? 0);
+    if (options.load !== false) {
+        await exec('launchctl', ['bootout', domain + '/' + label]).catch(() => { });
+        await exec('launchctl', ['bootstrap', domain, path]);
+    }
+    return { installed: true, label, plist: path, loaded: options.load !== false, logs: join(servePaths(root).state, 'logs') };
+}
+export async function uninstallLaunchd(root, options = {}) {
+    if ((options.platform ?? process.platform) !== 'darwin')
+        throw Error('kit_launchd_macos_only');
+    root = await realpath(root);
+    const label = launchdLabel(root), path = join(options.home ?? homedir(), 'Library', 'LaunchAgents', label + '.plist');
+    const exec = options.exec ?? promisify(execFile);
+    await exec('launchctl', ['bootout', 'gui/' + (options.uid ?? process.getuid?.() ?? 0) + '/' + label]).catch(() => { });
+    await unlink(path).catch(e => { if (e.code !== 'ENOENT')
+        throw e; });
+    return { uninstalled: true, label, plist: path };
+}

package/dist/native.js

@@ -47,7 +47,69 @@ export function nativeConnector() {
     return { marketplace: async () => { const config = await readKit(process.cwd()); if (!config.native?.active || !config.native.marketplace || !config.runtime)
             return undefined; const { credentialRef, ...identity } = config.runtime; return new MarketplaceRuntimeConnector({ ...identity, credential: () => runtimeSecret(credentialRef) }); }, capabilities: async () => (await current()).capabilities(true), call: async (registrationId, operation, input = {}, signal) => (await current()).call(registrationId, operation, input, signal) };
 }
+/** serve/enroll take boolean switches, so they are parsed separately from setup flags. */
+function serveFlags(args, values, switches) {
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const name = /^--([a-z-]+)$/.exec(args[i])?.[1];
+        if (!name || flags[name] !== undefined)
+            throw Error('kit_native_invalid_arguments');
+        if (switches.includes(name)) {
+            flags[name] = true;
+            continue;
+        }
+        if (!values.includes(name) || !args[i + 1] || args[i + 1].startsWith('--'))
+            throw Error('kit_native_invalid_arguments');
+        flags[name] = args[++i];
+    }
+    return flags;
+}
 export async function nativeCommand(args, root) {
+    if (args[0] === 'serve' || args[0] === 'enroll') {
+        const flags = args[0] === 'serve' ? serveFlags(args.slice(1), ['root'], ['install-launchd', 'uninstall', 'no-load']) : serveFlags(args.slice(1), ['root', 'url', 'port'], ['skip-endpoint-check']);
+        if (typeof flags.root === 'string') {
+            root = resolve(flags.root);
+            process.chdir(root);
+        }
+        if (args[0] === 'serve') {
+            const { serveNative, installLaunchd, uninstallLaunchd } = await import('./native-serve.js');
+            if (flags['install-launchd'] && flags.uninstall)
+                throw Error('kit_native_invalid_arguments');
+            if (flags.uninstall) {
+                console.log(JSON.stringify(await uninstallLaunchd(root)));
+                return;
+            }
+            if (flags['install-launchd']) {
+                console.log(JSON.stringify(await installLaunchd(root, { load: !flags['no-load'] })));
+                return;
+            }
+            if (flags['no-load'])
+                throw Error('kit_native_invalid_arguments');
+            await serveNative(root);
+            return;
+        }
+        if (typeof flags.url !== 'string')
+            throw Error('kit_native_public_url_required');
+        const { enrollNative } = await import('./native-enroll.js');
+        const state = await readKit(root);
+        if (!state.native || !state.runtime)
+            throw Error('kit_native_setup_required');
+        const login = await loginPortal(portalOrigin(state.runtime.issuer), (url, code) => console.error(`Approve Tealbrick endpoint registration: ${url}\nCode: ${code}`));
+        try {
+            const result = await enrollNative(root, { url: flags.url, ...(typeof flags.port === 'string' ? { port: Number(flags.port) } : {}) }, login, { verifyEndpoint: !flags['skip-endpoint-check'] });
+            console.log(JSON.stringify(result));
+            if (!flags['skip-endpoint-check'] && !result.endpointVerified) {
+                console.error('Portal registration is saved. Start `tealbrick native serve` and the HTTPS proxy, then re-run enroll to verify the endpoint.');
+                process.exitCode = 2;
+            }
+        }
+        catch (error) {
+            if (error instanceof PortalHttpError && /^[a-z_]+$/.test(error.code ?? ''))
+                throw Error('kit_portal_' + error.code);
+            throw error;
+        }
+        return;
+    }
     const command = args[0], flags = {};
     for (let i = 1; i < args.length; i += 2) {
         if (!/^--(root|harness|workspace|workspace-name|create-workspace|node|agent|agent-name|create-agent|delegation|issuer)$/.test(args[i]) || !args[i + 1] || flags[args[i].slice(2)])
@@ -109,6 +171,6 @@ export async function nativeCommand(args, root) {
         console.log(JSON.stringify({ active: command === 'enable' }));
         return;
     }
-    throw Error('Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native enable|disable | native marketplace-enable|marketplace-disable');
+    throw Error('Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native enable|disable | native marketplace-enable|marketplace-disable');
 }
 export { guidedNativeSetup, nativeSdkConfig };

package/dist/onboarding.d.ts

@@ -8,6 +8,11 @@ export interface PortalLogin {
         id: string;
         name: string;
     }>;
+    /** Ephemeral user identity for endpoint verification. Never persisted. */
+    identity?: {
+        token: string;
+        bundle: string;
+    };
 }
 /** Reject URLs that would leak credentials or be silently truncated by registration. */
 export declare function portalOrigin(value: string): string;

package/dist/onboarding.js

@@ -53,7 +53,7 @@ export async function loginPortal(issuer, show, options = {}) {
     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 { issuer, client: authenticated, org: account.user.orgId, userId: account.user.id, workspaces: directory.workspaces };
+    return { issuer, client: authenticated, org: account.user.orgId, userId: account.user.id, workspaces: directory.workspaces, identity: { token: session.token, bundle: session.bundle } };
 }
 /** Reuse Portal's owned registration + revision-checked canvas APIs, not a parallel card store. */
 export async function registerPortalCard(login, input) {

package/dist/secrets.d.ts

@@ -1,3 +1,4 @@
-export declare function runtimeSecret(name: string): string;
+/** Reads from the environment, then the kit root's private credentials file (cwd unless `root` is given). */
+export declare function runtimeSecret(name: string, root?: string): string;
 /** Lazy: does not read credentials during discovery/build or for unused providers. */
 export declare function secretEnvironment(): NodeJS.ProcessEnv;

package/dist/secrets.js

@@ -1,12 +1,14 @@
 import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
 const namePattern = /^TEALBRICK_[A-Z0-9_]+$/;
-export function runtimeSecret(name) {
+/** Reads from the environment, then the kit root's private credentials file (cwd unless `root` is given). */
+export function runtimeSecret(name, root) {
     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);
+            const path = root === undefined ? '.tealbrick/kit.credentials.json' : join(root, '.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'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/kit",
-  "version": "0.3.0-rc.3",
+  "version": "0.3.0-rc.5",
   "type": "module",
   "license": "MIT",
   "description": "Complete Teal Brick package kit with explicit Eve capability activation",
@@ -43,11 +43,11 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@tealbrick/portal": "0.3.0-rc.3",
-    "@tealbrick/avm": "0.3.0-rc.3",
-    "@tealbrick/voice": "0.3.0-rc.3",
-    "@tealbrick/vision": "0.3.0-rc.3",
-    "@tealbrick/deliver": "0.3.0-rc.3",
+    "@tealbrick/portal": "0.3.0-rc.5",
+    "@tealbrick/avm": "0.3.0-rc.5",
+    "@tealbrick/voice": "0.3.0-rc.5",
+    "@tealbrick/vision": "0.3.0-rc.5",
+    "@tealbrick/deliver": "0.3.0-rc.5",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },