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

package/dist/native-enroll.js

@@ -0,0 +1,85 @@
+import { realpath } from 'node:fs/promises';
+import { PortalHttpError } from '@tealbrick/portal';
+import { readKit } from './index.js';
+import { harnessLabels } from './native-selection.js';
+import { normalizeOrigin, readServeConfig, writeServeConfig } from './native-serve-config.js';
+/** Register this kit root's public chat endpoint on its EXISTING native Portal agent.
+ * Never creates or relabels an identity: the URL goes through Portal's owned-connection
+ * upsert, which preserves the agent's harness runtime (the Eve registration route would
+ * rewrite it to "eve"). The user token stays in memory. */
+export async function enrollNative(root, input, login, options = {}) {
+    root = await realpath(root);
+    const kit = await readKit(root);
+    if (!kit.native || !kit.runtime)
+        throw Error('kit_native_setup_required');
+    const { runtime } = kit, label = harnessLabels[kit.native.harness];
+    if (login.issuer !== runtime.issuer || login.org !== runtime.org)
+        throw Error('kit_runtime_existing_binding_mismatch');
+    const url = normalizeOrigin(input.url), old = await readServeConfig(root), port = input.port ?? old?.port ?? 5331;
+    if (!Number.isInteger(port) || port < 1024 || port > 65535)
+        throw Error('kit_native_serve_invalid_port');
+    const path = `/api/workspace?workspaceId=${encodeURIComponent(runtime.workspaceId)}`;
+    const owned = (snapshot) => {
+        const agent = snapshot.agents?.find(a => a.id === runtime.agentId && a.bindable);
+        const nodes = snapshot.draft?.nodes?.filter(n => n.data?.kind === 'agent' && n.data.agentId === runtime.agentId) ?? [];
+        if (snapshot.workspace?.id !== runtime.workspaceId || !agent || nodes.length !== 1)
+            throw Error('kit_owned_agent_card_required');
+        if (agent.runtime !== label || nodes[0].data.harness !== label)
+            throw Error('kit_native_portal_harness_mismatch');
+        return { agent, node: nodes[0] };
+    };
+    const { agent } = owned(await login.client.request(path));
+    let registered;
+    try {
+        registered = await login.client.request('/api/connections', { name: agent.name, runtime: label, url });
+    }
+    catch (error) {
+        if (error instanceof PortalHttpError && [404, 405].includes(error.status))
+            throw Error('kit_portal_connections_unsupported');
+        throw error;
+    }
+    const c = registered.connection;
+    if (c?.id !== agent.id || c.url !== url || c.runtime !== label)
+        throw Error('kit_portal_registration_mismatch');
+    await writeServeConfig(root, { ...(old ?? { version: 1, port }), version: 1, port, publicUrl: url, agent: { id: agent.id, name: agent.name, ownerId: login.userId } });
+    // Re-read after registration: preserve concurrent canvas changes and revision checks.
+    for (let attempt = 0;; attempt++) {
+        const fresh = await login.client.request(path), { node } = owned(fresh);
+        if (node.data.endpoint === url && node.data.authMethod === 'portal-pairing')
+            break;
+        const nodes = fresh.draft.nodes.map(n => n.id === node.id ? { ...n, data: { ...n.data, endpoint: url, authMethod: 'portal-pairing' } } : n);
+        try {
+            await login.client.request('/api/workspace/draft', { workspaceId: runtime.workspaceId, draftRevision: fresh.draftRevision, draft: { ...fresh.draft, nodes } });
+            break;
+        }
+        catch (error) {
+            if (error instanceof PortalHttpError && error.code === 'draft_changed_reload' && attempt < 2)
+                continue;
+            throw error;
+        }
+    }
+    const directory = await login.client.request(`/api/me/agents?workspaceId=${encodeURIComponent(runtime.workspaceId)}`);
+    if (directory.workspaceId !== runtime.workspaceId || !directory.agents?.some(a => a.id === agent.id && a.url === url))
+        throw Error('kit_portal_sidebar_verification_failed');
+    const endpoint = { healthy: false, authenticated: false, reason: undefined };
+    if (options.verifyEndpoint !== false) {
+        const f = options.fetch ?? fetch, get = (route, headers = {}) => f(url + route, { headers, redirect: 'error', signal: AbortSignal.timeout(10000) });
+        try {
+            const health = await get('/healthz'), body = health.ok ? await health.json() : undefined;
+            endpoint.healthy = body?.harness === kit.native.harness;
+            if (!endpoint.healthy)
+                endpoint.reason = 'health_check_failed';
+            else if (login.identity) {
+                const info = await get('/tealbrick/v1/info', { authorization: `Bearer ${login.identity.token}`, 'x-tealbrick-bundle': login.identity.bundle });
+                const value = info.ok ? await info.json() : undefined;
+                endpoint.authenticated = value?.harness === kit.native.harness && value.name === agent.name;
+                if (!endpoint.authenticated)
+                    endpoint.reason = 'authenticated_info_failed_' + info.status;
+            }
+        }
+        catch {
+            endpoint.reason = 'endpoint_unreachable';
+        }
+    }
+    return { enrolled: true, agentId: agent.id, name: agent.name, harness: label, endpoint: url, workspaceId: runtime.workspaceId, portalVerified: true, endpointVerified: endpoint.healthy && endpoint.authenticated, ...(endpoint.reason ? { endpointReason: endpoint.reason } : {}) };
+}

package/dist/native-selection.js

@@ -37,6 +37,8 @@ export async function selectNativeIdentity(root, flags, login, prompts) {
     if (workspaceName && flags.node)
         throw Error('kit_native_existing_node_requires_workspace');
     const cards = directory.agents.filter(a => a.harness === harness).map(agent => ({ agent }));
+    const unavailable = directory.agents.filter(a => a.harness !== harness).map(a => `${a.name} (${a.harness})`);
+    const context = unavailable.length ? ` Unavailable for ${harness}: ${unavailable.join(', ')}. Existing cards cannot be converted.` : '';
     let agentId = flags.agent;
     if (flags['agent-name']) {
         const matches = cards.filter((c) => c.agent.name === flags['agent-name']);
@@ -48,9 +50,9 @@ export async function selectNativeIdentity(root, flags, login, prompts) {
         agentId = old.runtime.agentId;
     let name = flags['create-agent'];
     if (!agentId && !name) {
-        const choice = cards.length ? await prompts.choose('Choose an agent to attach', [...cards.map((c) => ({ name: `${c.agent.name} (${c.agent.id})`, value: c.agent.id })), { name: 'Create an agent', value: '__create__' }]) : '__create__';
+        const choice = cards.length ? await prompts.choose('Choose an agent to attach.' + context, [...cards.map((c) => ({ name: `${c.agent.name} — ${c.agent.harness} (${c.agent.id})`, value: c.agent.id })), { name: 'Create an agent', value: '__create__' }]) : '__create__';
         if (choice === '__create__')
-            name = await prompts.name('New agent name');
+            name = await prompts.name('New agent name.' + context);
         else {
             const card = cards.find((c) => c.agent.id === choice);
             if (!card)
@@ -58,8 +60,21 @@ export async function selectNativeIdentity(root, flags, login, prompts) {
             agentId = card.agent.id;
         }
     }
-    if (name)
-        return { workspace, agent: { name: validName(name) } };
+    while (name) {
+        name = validName(name);
+        const conflicts = directory.agents.filter(a => a.name === name);
+        if (!conflicts.length)
+            return { workspace, agent: { name } };
+        const choice = await prompts.choose(`The name "${name}" already belongs to ${conflicts.map(a => `${a.name} (${a.harness}, ${a.id})`).join(', ')}. Select a compatible ${harness} card or choose another name.`, [...cards.map(c => ({ name: `${c.agent.name} — ${c.agent.harness} (${c.agent.id})`, value: c.agent.id })), { name: 'Choose another name', value: '__create__' }]);
+        if (choice === '__create__') {
+            name = await prompts.name('Different agent name.' + context);
+            continue;
+        }
+        if (!cards.some(c => c.agent.id === choice))
+            throw Error('kit_owned_agent_card_required');
+        agentId = choice;
+        name = undefined;
+    }
     const matches = cards.filter((c) => c.agent.id === agentId);
     if (matches.length !== 1)
         throw Error('kit_owned_agent_card_required');

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 };
+}