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

package/dist/native-serve-config.d.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+export declare const hostPattern: RegExp;
+declare const stdio: z.ZodObject<{
+    type: z.ZodOptional<z.ZodLiteral<"stdio">>;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export declare const tealbrickCallGrant: z.ZodObject<{
+    registrationId: z.ZodString;
+    operation: z.ZodString;
+    inputEquals: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, z.core.$strict>;
+declare const effort: z.ZodEnum<{
+    low: "low";
+    high: "high";
+    medium: "medium";
+    xhigh: "xhigh";
+    max: "max";
+}>;
+/** Tools an agent may add to its default (Restricted) session access: research and expert delegation, never shell or writes. */
+export declare const defaultAccessTools: readonly ["WebSearch", "WebFetch", "Agent", "TodoWrite"];
+export declare const serveConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    port: z.ZodNumber;
+    publicUrl: z.ZodOptional<z.ZodString>;
+    allowedHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxActiveTurns: z.ZodOptional<z.ZodNumber>;
+    agent: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        ownerId: z.ZodString;
+    }, z.core.$strict>>;
+    claude: z.ZodOptional<z.ZodObject<{
+        sdkModule: z.ZodOptional<z.ZodString>;
+        cwd: z.ZodString;
+        instructionsFile: z.ZodOptional<z.ZodString>;
+        recipe: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            agent: z.ZodString;
+        }, z.core.$strict>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            high: "high";
+            medium: "medium";
+            xhigh: "xhigh";
+            max: "max";
+        }>>;
+        maxTurns: z.ZodOptional<z.ZodNumber>;
+        maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        defaultTools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            WebSearch: "WebSearch";
+            WebFetch: "WebFetch";
+            Agent: "Agent";
+            TodoWrite: "TodoWrite";
+        }>>>;
+        experts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            promptFile: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                WebSearch: "WebSearch";
+                WebFetch: "WebFetch";
+                Read: "Read";
+                Glob: "Glob";
+                Grep: "Grep";
+            }>>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                high: "high";
+                medium: "medium";
+                xhigh: "xhigh";
+                max: "max";
+            }>>;
+        }, z.core.$strict>>>;
+        nativeTools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>>;
+        readTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodOptional<z.ZodLiteral<"stdio">>;
+            command: z.ZodString;
+            args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>>;
+        tealbrickCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            registrationId: z.ZodString;
+            operation: z.ZodString;
+            inputEquals: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+        }, z.core.$strict>>>;
+        requireSubscription: z.ZodOptional<z.ZodBoolean>;
+        envPassthrough: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    codex: z.ZodOptional<z.ZodObject<{
+        codexBin: z.ZodString;
+        cwd: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ServeConfig = z.infer<typeof serveConfigSchema>;
+export interface ClaudeProfile {
+    cwd: string;
+    sdkModule?: string;
+    instructions?: string;
+    model?: string;
+    effort?: z.infer<typeof effort>;
+    maxTurns: number;
+    maxBudgetUsd?: number;
+    timeoutSeconds: number;
+    defaultTools: string[];
+    experts: Record<string, ClaudeExpert>;
+    nativeTools: string[];
+    readTools: string[];
+    mcpServers: Record<string, z.infer<typeof stdio>>;
+    tealbrickCalls: Array<z.infer<typeof tealbrickCallGrant>>;
+    requireSubscription: boolean;
+    envPassthrough: string[];
+}
+export interface ClaudeExpert {
+    description: string;
+    prompt: string;
+    tools: string[];
+    maxTurns: number;
+    effort?: z.infer<typeof effort>;
+}
+export declare const servePaths: (root: string) => {
+    config: string;
+    state: string;
+    sdk: string;
+};
+export declare function normalizeOrigin(value: string): string;
+/** Host header values a TLS-terminating proxy for `publicUrl` may present. */
+export declare function publicHosts(config: ServeConfig): string[];
+export declare function readServeConfig(root: string): Promise<ServeConfig | undefined>;
+export declare function writeServeConfig(root: string, config: ServeConfig): Promise<void>;
+/** The kit-generated Claude attachment: tealbrick MCP server plus the child guard hook. */
+declare const generatedClaude: z.ZodObject<{
+    settings: z.ZodObject<{
+        hooks: z.ZodObject<{
+            PreToolUse: z.ZodArray<z.ZodObject<{
+                matcher: z.ZodLiteral<"mcp__tealbrick__.*">;
+                hooks: z.ZodArray<z.ZodObject<{
+                    type: z.ZodLiteral<"command">;
+                    command: z.ZodString;
+                    args: z.ZodArray<z.ZodString>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    mcpServers: z.ZodObject<{
+        tealbrick: z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ClaudeAttachment = z.infer<typeof generatedClaude>;
+export declare function readClaudeAttachment(root: string): Promise<ClaudeAttachment>;
+/** Resolve the effective Claude profile. Explicit serve fields override the imported recipe. */
+export declare function resolveClaudeProfile(root: string, config: ServeConfig): Promise<ClaudeProfile>;
+export {};

package/dist/native-serve-config.js

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { lstat, readFile, realpath, writeFile, rename, mkdir } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Operator configuration for `tealbrick native serve`. Contains no credentials. */
+const absolute = z.string().min(1).refine(v => isAbsolute(v) && !v.includes('\0'), 'absolute path required');
+export const hostPattern = /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*(?::\d{1,5})?$/i;
+const mcpTool = z.string().regex(/^mcp__[a-zA-Z0-9_-]+__[a-zA-Z0-9_-]+$/);
+const tool = z.union([z.string().regex(/^[A-Z][A-Za-z]{1,40}$/), mcpTool]);
+const serverName = z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/).refine(n => n !== 'tealbrick', 'the tealbrick MCP server comes from .tealbrick/native-sdk.json');
+const stdio = z.object({ type: z.literal('stdio').optional(), command: z.string().min(1), args: z.array(z.string()).optional(), env: z.record(z.string(), z.string()).optional() }).strict();
+export const tealbrickCallGrant = z.object({ registrationId: z.string().min(1), operation: z.string().min(1), inputEquals: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])).default({}) }).strict();
+const effort = z.enum(['low', 'medium', 'high', 'xhigh', 'max']);
+/** Tools an agent may add to its default (Restricted) session access: research and expert delegation, never shell or writes. */
+export const defaultAccessTools = ['WebSearch', 'WebFetch', 'Agent', 'TodoWrite'];
+/** Tools an expert subagent may hold; workspace reads stay contained and network content stays untrusted. */
+const expertTool = z.enum(['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch']);
+const expertName = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+const expert = z.object({ promptFile: absolute, description: z.string().min(1).max(300).optional(), tools: z.array(expertTool).max(8).optional(), maxTurns: z.number().int().min(1).max(50).optional(), effort: effort.optional() }).strict();
+const claude = z.object({
+    /** Package directory or entry file of @anthropic-ai/claude-agent-sdk. Default: resolved from the kit root. */
+    sdkModule: absolute.optional(),
+    /** Working directory. Claude session transcripts are keyed by it; keep it stable. */
+    cwd: absolute,
+    instructionsFile: absolute.optional(),
+    /** Import model/limits/MCP/read tools/app-call ceilings from an existing tealbrick-native recipe file. */
+    recipe: z.object({ path: absolute, agent: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/) }).strict().optional(),
+    model: z.string().min(1).max(100).optional(),
+    effort: effort.optional(),
+    maxTurns: z.number().int().min(1).max(200).optional(),
+    maxBudgetUsd: z.number().positive().max(100).optional(),
+    timeoutSeconds: z.number().int().min(10).max(7200).optional(),
+    /** Extra tools in this agent's default (Restricted) session access. */
+    defaultTools: z.array(z.enum(defaultAccessTools)).max(4).optional(),
+    /** Expert subagents the Agent tool may delegate to, foreground only, inheriting the session model. */
+    experts: z.record(expertName, expert).optional(),
+    /** Tool allowlist for the opt-in "Native defaults" session access mode. */
+    nativeTools: z.array(tool).max(64).optional(),
+    /** Operator-vetted read-only MCP tools, also available in Restricted mode. */
+    readTools: z.array(mcpTool).max(32).optional(),
+    mcpServers: z.record(serverName, stdio).optional(),
+    tealbrickCalls: z.array(tealbrickCallGrant).max(64).optional(),
+    /** Refuse turns unless the SDK reports first-party subscription sign-in (no API-key fallback). */
+    requireSubscription: z.boolean().optional(),
+    /** Extra environment variable names passed to the SDK process. TEALBRICK_* is never passed. */
+    envPassthrough: z.array(z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/).refine(n => !n.startsWith('TEALBRICK_'), 'Teal Brick credentials are never passed to the harness')).max(32).optional(),
+}).strict();
+const codex = z.object({ codexBin: absolute, cwd: absolute }).strict();
+export const serveConfigSchema = z.object({
+    version: z.literal(1),
+    port: z.number().int().min(1024).max(65535),
+    /** Public HTTPS origin registered on Portal (for example a tailscale serve URL). */
+    publicUrl: z.string().url().optional(),
+    /** Extra exact Host header values. The public URL host and loopback are added automatically. */
+    allowedHosts: z.array(z.string().regex(hostPattern)).max(8).optional(),
+    maxActiveTurns: z.number().int().min(1).max(16).optional(),
+    /** Written by `native enroll`: Portal identity used to verify every request. */
+    agent: z.object({ id: z.string().min(1), name: z.string().min(1).max(80), ownerId: z.string().min(1) }).strict().optional(),
+    claude: claude.optional(),
+    codex: codex.optional(),
+}).strict();
+export const servePaths = (root) => ({ config: join(root, '.tealbrick', 'native-serve.json'), state: join(root, '.tealbrick', 'native-serve'), sdk: join(root, '.tealbrick', 'native-sdk.json') });
+async function regularFile(path, { ownerOnly }) {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw Error('kit_native_serve_unsafe_file');
+    if (process.platform !== 'win32' && (stat.mode & (ownerOnly ? 0o077 : 0o022)))
+        throw Error('kit_native_serve_file_permissions');
+}
+/** Stable, value-free error codes for operator files; never echo file contents. */
+function parsed(schema, text, code) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw Error(code);
+    }
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw Error(code + ':' + result.error.issues.map(i => i.path.join('.') || 'root').slice(0, 5).join(','));
+    return result.data;
+}
+export function normalizeOrigin(value) {
+    const url = new URL(value);
+    const loopback = ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+    if (!(url.protocol === 'https:' || url.protocol === 'http:' && loopback) || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+        throw Error('kit_native_public_url_https_origin_required');
+    return url.origin;
+}
+/** Host header values a TLS-terminating proxy for `publicUrl` may present. */
+export function publicHosts(config) {
+    const hosts = [...(config.allowedHosts ?? [])];
+    if (config.publicUrl) {
+        const url = new URL(config.publicUrl);
+        hosts.push(url.host);
+        if (!url.port)
+            hosts.push(url.hostname + ':' + (url.protocol === 'https:' ? 443 : 80));
+    }
+    return [...new Set(hosts.map(h => h.toLowerCase()))];
+}
+export async function readServeConfig(root) {
+    const path = servePaths(root).config;
+    try {
+        await regularFile(path, { ownerOnly: true });
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+    const config = parsed(serveConfigSchema, await readFile(path, 'utf8'), 'kit_native_serve_config_invalid');
+    if (config.publicUrl && normalizeOrigin(config.publicUrl) !== config.publicUrl)
+        throw Error('kit_native_public_url_https_origin_required');
+    return config;
+}
+export async function writeServeConfig(root, config) {
+    const value = serveConfigSchema.parse(config), { config: path } = servePaths(root);
+    await mkdir(join(root, '.tealbrick'), { recursive: true, mode: 0o700 });
+    try {
+        if ((await lstat(path)).isSymbolicLink())
+            throw Error('kit_symlink_path');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const tmp = path + '.' + randomUUID();
+    await writeFile(tmp, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(tmp, path);
+}
+/** The kit-generated Claude attachment: tealbrick MCP server plus the child guard hook. */
+const generatedClaude = z.object({
+    settings: z.object({ hooks: z.object({ PreToolUse: z.array(z.object({ matcher: z.literal('mcp__tealbrick__.*'), hooks: z.array(z.object({ type: z.literal('command'), command: z.string().min(1), args: z.array(z.string()).min(1) }).strict()).min(1) }).strict()).min(1) }).strict() }).strict(),
+    mcpServers: z.object({ tealbrick: z.object({ command: z.string().min(1), args: z.array(z.string()).min(1) }).strict() }).strict(),
+}).strict();
+export async function readClaudeAttachment(root) {
+    const path = servePaths(root).sdk;
+    await regularFile(path, { ownerOnly: true });
+    const value = parsed(generatedClaude, await readFile(path, 'utf8'), 'kit_native_sdk_config_invalid');
+    const args = value.mcpServers.tealbrick.args, at = args.indexOf('--root');
+    if (args.slice(-4, -2).join(' ') !== 'native mcp' || at < 0 || resolve(args[at + 1] ?? '') !== await realpath(root))
+        throw Error('kit_native_sdk_config_root_mismatch');
+    return value;
+}
+const recipeSchema = z.object({
+    model: z.string().min(1).optional(), effort: effort.optional(), maxTurns: z.number().int().min(1).max(200).optional(),
+    maxBudgetUsd: z.number().positive().max(100).optional(), timeoutSeconds: z.number().int().min(10).max(7200).optional(),
+    agents: z.record(z.string(), z.object({ mcpServers: z.record(serverName, stdio).optional(), readTools: z.array(mcpTool).max(32).optional(), tealbrickCalls: z.array(tealbrickCallGrant).max(64).optional(), tealbrickSdkConfig: absolute.optional() }).passthrough()),
+}).passthrough();
+/** Resolve the effective Claude profile. Explicit serve fields override the imported recipe. */
+export async function resolveClaudeProfile(root, config) {
+    const c = config.claude;
+    if (!c)
+        throw Error('kit_native_serve_claude_profile_required');
+    let recipe, agent;
+    if (c.recipe) {
+        await regularFile(c.recipe.path, { ownerOnly: false });
+        recipe = parsed(recipeSchema, await readFile(c.recipe.path, 'utf8'), 'kit_native_serve_recipe_invalid');
+        agent = recipe.agents[c.recipe.agent];
+        if (!agent)
+            throw Error('kit_native_serve_recipe_agent_missing');
+        // The recipe must describe THIS kit root's Portal connection, never another agent's.
+        if (agent.tealbrickSdkConfig && await realpath(agent.tealbrickSdkConfig) !== await realpath(servePaths(root).sdk))
+            throw Error('kit_native_serve_recipe_connection_mismatch');
+    }
+    const cwd = resolve(c.cwd), protectedRoot = join(await realpath(root), '.tealbrick');
+    if (protectedRoot.startsWith(cwd + '/') || cwd === protectedRoot || cwd.startsWith(protectedRoot + '/'))
+        throw Error('kit_native_serve_cwd_contains_credentials');
+    if (!(await lstat(cwd).catch(() => undefined))?.isDirectory())
+        throw Error('kit_native_serve_cwd_missing');
+    const instructions = c.instructionsFile ? (await regularFile(c.instructionsFile, { ownerOnly: false }), await readFile(c.instructionsFile, 'utf8')) : undefined;
+    if (instructions && instructions.length > 200000)
+        throw Error('kit_native_serve_instructions_too_large');
+    const readTools = c.readTools ?? agent?.readTools ?? [];
+    const experts = {};
+    for (const [name, e] of Object.entries(c.experts ?? {})) {
+        await regularFile(e.promptFile, { ownerOnly: false });
+        const prompt = await readFile(e.promptFile, 'utf8');
+        if (!prompt.trim() || prompt.length > 50000)
+            throw Error('kit_native_serve_expert_prompt_invalid:' + name);
+        experts[name] = { description: e.description ?? name.replaceAll('-', ' ') + ' for a bounded assignment', prompt, tools: [...new Set(e.tools ?? [])], maxTurns: e.maxTurns ?? 8, ...(e.effort ? { effort: e.effort } : {}) };
+    }
+    return { cwd, sdkModule: c.sdkModule, instructions, model: c.model ?? recipe?.model, effort: c.effort ?? recipe?.effort,
+        maxTurns: c.maxTurns ?? recipe?.maxTurns ?? 24, maxBudgetUsd: c.maxBudgetUsd ?? recipe?.maxBudgetUsd, timeoutSeconds: c.timeoutSeconds ?? recipe?.timeoutSeconds ?? 900,
+        defaultTools: [...new Set(c.defaultTools ?? [])], experts,
+        nativeTools: c.nativeTools ?? ['Read', 'Glob', 'Grep', 'TodoWrite'], readTools: readTools.filter(t => !t.startsWith('mcp__tealbrick__')),
+        mcpServers: c.mcpServers ?? agent?.mcpServers ?? {}, tealbrickCalls: c.tealbrickCalls ?? agent?.tealbrickCalls ?? [],
+        requireSubscription: c.requireSubscription ?? false, envPassthrough: c.envPassthrough ?? [] };
+}

package/dist/native-serve.d.ts

@@ -0,0 +1,50 @@
+import { type AuthResult } from '@tealbrick/portal';
+import { type ClaudeSdk } from './native-claude.js';
+/** LangChain has no stable session/stream/cancel contract to drive from here yet. */
+export declare function langchainHarness(): never;
+export interface ServeDependencies {
+    authenticate?: (request: Request) => Promise<AuthResult>;
+    claudeSdk?: ClaudeSdk;
+    log?: (event: Record<string, unknown>) => void;
+    env?: NodeJS.ProcessEnv;
+}
+/** Build (but do not bind) the owner-authenticated chat endpoint for this kit root. */
+export declare function createNativeServe(root: string, deps?: ServeDependencies): Promise<{
+    port: number;
+    harness: "claude" | "codex" | "langchain";
+    close: () => Promise<void>;
+    server: import("http").Server;
+    sessions: Map<string, import("@tealbrick/portal/native-bridge").BridgeSession<any>>;
+}>;
+export declare function serveNative(root: string): Promise<void>;
+export declare function launchdLabel(root: string): string;
+/** User LaunchAgent: restarts on crash, logs to the kit root's private state directory. */
+export declare function launchdPlist(root: string, options?: {
+    node?: string;
+    cli?: string;
+}): string;
+type Exec = (file: string, args: string[]) => Promise<unknown>;
+export declare function installLaunchd(root: string, options?: {
+    home?: string;
+    exec?: Exec;
+    load?: boolean;
+    uid?: number;
+    platform?: string;
+}): Promise<{
+    installed: boolean;
+    label: string;
+    plist: string;
+    loaded: boolean;
+    logs: string;
+}>;
+export declare function uninstallLaunchd(root: string, options?: {
+    home?: string;
+    exec?: Exec;
+    uid?: number;
+    platform?: string;
+}): Promise<{
+    uninstalled: boolean;
+    label: string;
+    plist: string;
+}>;
+export {};

package/dist/native-serve.js

@@ -0,0 +1,124 @@
+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 { 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 });
+    return { ...bridge, port: config.port, harness: kit.native.harness, close: async () => { 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/kit",
-  "version": "0.3.0-rc.3",
+  "version": "0.3.0-rc.4",
   "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.4",
+    "@tealbrick/avm": "0.3.0-rc.4",
+    "@tealbrick/voice": "0.3.0-rc.4",
+    "@tealbrick/vision": "0.3.0-rc.4",
+    "@tealbrick/deliver": "0.3.0-rc.4",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },