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

package/dist/native-runtime-sync.d.ts

@@ -0,0 +1,49 @@
+import { RuntimeConnector } from '@tealbrick/portal/runtime';
+import type { JWTVerifyGetKey } from 'jose';
+export type RuntimeCapabilities = Awaited<ReturnType<RuntimeConnector['capabilities']>>;
+export type RuntimeSyncStatus = 'starting' | 'synced' | 'retrying' | 'inactive' | 'stopped';
+export interface RuntimeSyncSnapshot {
+    status: RuntimeSyncStatus;
+    revision?: string;
+    expiresAt?: number;
+    lastSyncAt?: number;
+    failures: number;
+    error?: string;
+    capabilities?: RuntimeCapabilities;
+}
+export interface RuntimeSyncOptions {
+    fetch?: typeof fetch;
+    keys?: JWTVerifyGetKey;
+    log?: (event: Record<string, unknown>) => void;
+    /** Base delay between successful syncs. Portal's signed config lives 300s, so this must stay well below it. */
+    intervalMs?: number;
+    jitterMs?: number;
+    /** First retry delay after a failure; doubles per consecutive failure up to maxRetryMs. */
+    retryMs?: number;
+    maxRetryMs?: number;
+    random?: () => number;
+    now?: () => number;
+}
+/**
+ * Keeps this customer runtime's Portal configuration acknowledged while `native serve` is idle.
+ * The per-turn Teal Brick MCP child still fetches a fresh authorization for every call; this loop
+ * only fetches the signed config, acknowledges it (Portal derives runtime sync freshness from that)
+ * and holds the latest capability snapshot in memory. App credentials never leave the kit root.
+ */
+export declare function startRuntimeSync(root: string, options?: RuntimeSyncOptions): {
+    snapshot: () => RuntimeSyncSnapshot;
+    capabilities: () => {
+        revision: string;
+        expiresAt: number;
+        apps: {
+            registrationId: string;
+            appId: "knowledge";
+            actions: import("@tealbrick/portal/runtime").CrudAction[];
+            available: boolean;
+            operations: import("@tealbrick/portal/runtime").KnowledgeOperation[];
+        }[];
+    } | undefined;
+    syncNow: () => Promise<void>;
+    stop(): Promise<void>;
+};
+export type RuntimeSync = ReturnType<typeof startRuntimeSync>;

package/dist/native-runtime-sync.js

@@ -0,0 +1,101 @@
+import { RuntimeConnector } from '@tealbrick/portal/runtime';
+import { readKit } from './index.js';
+import { runtimeSecret } from './secrets.js';
+const defaults = { intervalMs: 90_000, jitterMs: 30_000, retryMs: 15_000, maxRetryMs: 240_000 };
+const code = (v) => typeof v === 'string' && /^[a-z][a-z0-9_]{0,80}$/.test(v) ? v : undefined;
+/**
+ * Keeps this customer runtime's Portal configuration acknowledged while `native serve` is idle.
+ * The per-turn Teal Brick MCP child still fetches a fresh authorization for every call; this loop
+ * only fetches the signed config, acknowledges it (Portal derives runtime sync freshness from that)
+ * and holds the latest capability snapshot in memory. App credentials never leave the kit root.
+ */
+export function startRuntimeSync(root, options = {}) {
+    const o = { ...defaults, ...options }, random = o.random ?? Math.random, now = o.now ?? Date.now;
+    const log = o.log ?? ((event) => process.stderr.write(JSON.stringify(event) + '\n'));
+    const base = o.fetch ?? fetch;
+    let state = { status: 'starting', failures: 0 };
+    let timer, stopped = false, running;
+    let connector, connectorKey;
+    let observed = {};
+    const observe = async (input, init) => {
+        const response = await base(input, init);
+        const path = new URL(input instanceof Request ? input.url : String(input)).pathname;
+        if (path === '/api/runtime/config' || path === '/api/runtime/ack') {
+            observed[path === '/api/runtime/config' ? 'config' : 'ack'] = response.status;
+            if (!response.ok)
+                observed.code = code(await response.clone().json().then((b) => b?.error ?? b?.code, () => undefined)) ?? observed.code;
+        }
+        return response;
+    };
+    const jitter = (ms, spread) => Math.max(1, Math.round(ms + (random() * 2 - 1) * spread));
+    function schedule(ms) { if (stopped)
+        return; clearTimeout(timer); timer = setTimeout(() => { void syncNow(); }, ms); timer.unref?.(); }
+    async function cycle() {
+        let kit;
+        try {
+            kit = await readKit(root);
+        }
+        catch {
+            kit = undefined;
+        }
+        if (!kit?.native?.active || !kit.runtime) {
+            if (state.status !== 'inactive')
+                log({ event: 'native.runtime.sync.inactive', message: 'Teal Brick runtime is not active in this kit root; Portal sync is paused.' });
+            connector = undefined;
+            connectorKey = undefined;
+            state = { status: 'inactive', failures: 0 };
+            schedule(jitter(o.intervalMs, o.jitterMs));
+            return;
+        }
+        const { credentialRef, ...runtime } = kit.runtime, key = JSON.stringify(kit.runtime);
+        if (!connector || key !== connectorKey) {
+            connector = new RuntimeConnector({ ...runtime, credential: () => runtimeSecret(credentialRef, root), resolveCredential: name => runtimeSecret(name, root), fetch: observe, ...(o.keys ? { keys: o.keys } : {}) });
+            connectorKey = key;
+        }
+        observed = {};
+        let capabilities;
+        try {
+            capabilities = await connector.capabilities(true);
+        }
+        catch (error) {
+            const reason = code(error?.message) ?? 'runtime_sync_failed';
+            if (observed.config === 401) {
+                const why = observed.code ?? 'runtime_credential_invalid';
+                stopped = true;
+                clearTimeout(timer);
+                state = { ...state, status: 'stopped', error: why };
+                log({ event: 'native.runtime.sync.stopped', reason: 'credential_revoked', code: why, message: `Portal rejected this runtime's credential (${why}); background runtime sync has stopped and Portal will show the runtime as expired. Re-enroll with \`tealbrick native setup\`, then restart native serve.` });
+                return;
+            }
+            const failures = state.failures + 1, delay = jitter(Math.min(o.maxRetryMs, o.retryMs * 2 ** (failures - 1)), Math.min(o.maxRetryMs, o.retryMs * 2 ** (failures - 1)) * 0.2);
+            state = { ...state, status: 'retrying', failures, error: observed.code ?? reason };
+            log({ event: 'native.runtime.sync.failed', code: state.error, ...(observed.config !== undefined ? { status: observed.config } : {}), failures, retryInMs: delay });
+            schedule(delay);
+            return;
+        }
+        const changed = state.status !== 'synced' || state.revision !== capabilities.revision;
+        const ackFailed = observed.ack !== undefined && !(observed.ack >= 200 && observed.ack < 300);
+        state = { status: ackFailed ? 'retrying' : 'synced', revision: capabilities.revision, expiresAt: capabilities.expiresAt, lastSyncAt: now(), failures: ackFailed ? state.failures + 1 : 0, capabilities, ...(ackFailed ? { error: observed.code ?? 'runtime_ack_failed' } : {}) };
+        if (ackFailed)
+            log({ event: 'native.runtime.ack.failed', code: state.error, status: observed.ack, failures: state.failures });
+        else if (changed)
+            log({ event: 'native.runtime.synced', revision: capabilities.revision.slice(0, 12), apps: capabilities.apps.length, available: capabilities.apps.filter(a => a.available).length, expiresAt: new Date(capabilities.expiresAt).toISOString() });
+        // Never let the acknowledged lease lapse between syncs; a failed ack retries on the short schedule.
+        const next = ackFailed ? jitter(o.retryMs, o.retryMs * 0.2) : jitter(o.intervalMs, o.jitterMs);
+        schedule(Math.max(1, Math.min(next, capabilities.expiresAt - now() - 30_000)));
+    }
+    async function syncNow() {
+        if (stopped)
+            return;
+        running ??= cycle().catch(error => { log({ event: 'native.runtime.sync.failed', code: code(error?.message) ?? 'runtime_sync_failed' }); schedule(o.maxRetryMs); }).finally(() => { running = undefined; });
+        return running;
+    }
+    void syncNow();
+    return {
+        snapshot: () => ({ ...state }),
+        capabilities: () => state.capabilities,
+        syncNow,
+        async stop() { stopped = true; clearTimeout(timer); await running; if (state.status !== 'stopped')
+            state = { ...state, status: 'stopped' }; },
+    };
+}

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,69 @@
+import { type AuthResult } from '@tealbrick/portal';
+import { type ClaudeSdk } from './native-claude.js';
+import { type RuntimeSyncOptions } from './native-runtime-sync.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;
+    /** Background Portal config/ack sync for this runtime; false disables it (tests only). */
+    runtimeSync?: RuntimeSyncOptions | false;
+}
+/** 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";
+    runtime: {
+        snapshot: () => import("./native-runtime-sync.js").RuntimeSyncSnapshot;
+        capabilities: () => {
+            revision: string;
+            expiresAt: number;
+            apps: {
+                registrationId: string;
+                appId: "knowledge";
+                actions: import("@tealbrick/portal/runtime").CrudAction[];
+                available: boolean;
+                operations: import("@tealbrick/portal/runtime").KnowledgeOperation[];
+            }[];
+        } | undefined;
+        syncNow: () => Promise<void>;
+        stop(): Promise<void>;
+    } | undefined;
+    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 {};