@tealbrick/kit 0.2.7 → 0.3.0-rc.10

package/dist/native-serve-config.js

@@ -0,0 +1,296 @@
+import { z } from 'zod';
+import { lstat, readFile, realpath, writeFile, rename, mkdir } from 'node:fs/promises';
+import { isAbsolute, join, relative, 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}$/);
+/** Sandboxed owner workspace: all file work runs through the sandboxed Bash inside `dir`; shell network limited to allowedDomains. */
+const domain = z.string().regex(/^(?:\*\.)?[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/, 'lowercase host name or *.host');
+const envName = z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/);
+const workspace = z.object({ dir: absolute, network: z.object({ allowedDomains: z.array(domain).max(64) }).strict().optional(),
+    /** envPassthrough names that are NOT secret and may stay visible to sandboxed shell commands (all others are removed there). */
+    envAllow: z.array(envName).max(32).optional() }).strict();
+/** Versioned expert contract (tealbrick.expert-contract/v1). The contract is a ceiling; Portal grants still apply. */
+const opName = z.string().regex(/^[a-z][a-z0-9_.]{1,120}$/);
+export const expertContractSchema = z.object({
+    schema: z.literal('tealbrick.expert-contract/v1'),
+    id: z.string().regex(/^[a-z][a-z0-9-]{1,62}$/),
+    version: z.string().regex(/^\d+\.\d+\.\d+$/),
+    purpose: z.string().min(10).max(300),
+    instructions: z.string().min(40).max(8000),
+    input: z.object({ type: z.literal('object') }).passthrough(),
+    output: z.object({ type: z.literal('object') }).passthrough(),
+    capabilities: z.object({
+        builtinTools: z.array(expertTool).max(8),
+        apps: z.array(z.object({ appId: z.string().regex(/^[a-z][a-z0-9-]{1,40}$/), operations: z.array(z.string().regex(/^[a-z][a-z0-9_]{1,80}$/)).min(1) }).strict()).max(12),
+        marketplace: z.array(z.object({ plugin: z.string().regex(/^[a-z0-9][a-z0-9-]{1,80}$/), actions: z.array(z.string().regex(/^[a-z0-9][a-z0-9._-]{1,120}$/)).min(1) }).strict()).max(12),
+    }).strict(),
+    approval: z.object({ outwardWrites: z.enum(['always', 'never-allowed']), operations: z.array(opName) }).strict(),
+    model: z.enum(['inherit', 'opus', 'sonnet', 'haiku']),
+    effort: z.enum(['low', 'medium', 'high']).optional(),
+    budget: z.object({ maxTurns: z.number().int().min(1).max(50) }).strict(),
+    runtime: z.enum(['subagent', 'desktop-operator']),
+    changelog: z.array(z.string().max(300)).optional(),
+}).strict();
+/** Simple glob: exact text, or '*' for any run of characters. */
+const globText = z.string().min(1).max(200);
+const globList = z.union([globText, z.array(globText).min(1).max(32)]);
+/**
+ * Owner-defined standing grant: a bounded class of calls that would otherwise pause for payload approval
+ * and that the kit hook approves without a prompt, within caps, until it expires. Never a wider scope than
+ * decideTool already allows; it only replaces the per-payload prompt.
+ */
+export const standingGrantSchema = z.object({
+    id: z.string().regex(/^[a-z0-9][a-z0-9-]{1,47}$/),
+    description: z.string().min(1).max(300),
+    operation: opName.default('marketplace_execute'),
+    /** registrationId is case-sensitive; plugin/action are case-insensitive. All support '*'. At least one is required. */
+    match: z.object({ registrationId: globText.optional(), plugin: globList.optional(), action: globList.optional() }).strict()
+        .refine(m => m.registrationId !== undefined || m.plugin !== undefined || m.action !== undefined, 'match needs registrationId, plugin or action (use "*" to mean any)'),
+    /** Contract ids whose expert subagents may also use this grant. Omitted: the owner session only. */
+    experts: z.array(z.string().regex(/^[a-z][a-z0-9-]{1,62}$/)).max(32).optional(),
+    caps: z.object({ perDay: z.number().int().min(1).max(200), perHour: z.number().int().min(1).max(200).optional(), minIntervalSeconds: z.number().int().min(1).max(86400).optional() }).strict(),
+    /** ISO 8601 date-time with offset. Expired grants never match. */
+    expires: z.iso.datetime({ offset: true }),
+    /** Case-insensitive literal substrings of JSON.stringify(call input); any hit means the grant does not apply. */
+    deny: z.object({ inputPattern: z.array(z.string().min(1).max(200)).max(32).optional() }).strict().optional(),
+}).strict();
+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(),
+    /** Versioned expert contracts (JSON files) run as SDK subagents. Effective scope = contract ceiling ∩ owner grants. */
+    contracts: z.array(absolute).max(32).optional(),
+    /** Operations that always pause for the owner's approval of the exact payload, whoever calls them. */
+    approvalOperations: z.array(opName).max(64).optional(),
+    /** Owner pre-approvals for bounded classes of approval-gated calls (see README "Standing grants"). */
+    standingGrants: z.array(standingGrantSchema).max(64).optional()
+        .refine(g => !g || new Set(g.map(x => x.id)).size === g.length, 'standing grant ids must be unique'),
+    /** 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(),
+    /** Opt-in sandboxed workspace for the owner session (inside the kit root, never containing .tealbrick). */
+    workspace: workspace.optional(),
+    /** Extra environment variable names passed to the SDK process. TEALBRICK_* is never passed. */
+    envPassthrough: z.array(envName.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'),
+    /** Kit-owned attachment inbox: written only by the kit process, readable (never writable) by the sandboxed workspace session. */
+    inbox: join(root, 'inbox') });
+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');
+    }
+    let cwd = resolve(c.cwd);
+    const 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');
+    let workspace;
+    if (c.workspace) {
+        const realRoot = await realpath(root), inside = (base, p) => { const rel = relative(base, p); return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel); };
+        const dir = resolve(c.workspace.dir), tb = (base) => join(base, '.tealbrick');
+        const lexical = (base) => inside(base, dir) && dir !== tb(base) && !inside(tb(base), dir);
+        if (!lexical(realRoot) && !lexical(resolve(root)))
+            throw Error('kit_native_serve_workspace_outside_root');
+        // The attachment inbox must stay outside anything the sandbox can write.
+        const overlapsInbox = (base, p) => { const inbox = servePaths(base).inbox; return p === inbox || inside(inbox, p); };
+        if (overlapsInbox(realRoot, dir) || overlapsInbox(resolve(root), dir))
+            throw Error('kit_native_serve_workspace_overlaps_inbox');
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const real = await realpath(dir);
+        if (!inside(realRoot, real) || real === tb(realRoot) || inside(tb(realRoot), real))
+            throw Error('kit_native_serve_workspace_outside_root');
+        if (overlapsInbox(realRoot, real))
+            throw Error('kit_native_serve_workspace_overlaps_inbox');
+        if (await lstat(join(real, '.tealbrick')).then(() => true, () => false))
+            throw Error('kit_native_serve_workspace_contains_credentials');
+        workspace = { dir: real, root: realRoot, allowedDomains: [...new Set(c.workspace.network?.allowedDomains ?? [])], envAllow: [...new Set(c.workspace.envAllow ?? [])] };
+        cwd = real;
+    }
+    const readTools = c.readTools ?? agent?.readTools ?? [];
+    const contracts = {};
+    for (const path of c.contracts ?? []) {
+        await regularFile(path, { ownerOnly: false });
+        const text = await readFile(path, 'utf8');
+        if (text.length > 65536)
+            throw Error('kit_native_serve_contract_too_large');
+        const contract = parsed(expertContractSchema, text, 'kit_native_serve_contract_invalid');
+        if (contract.runtime !== 'subagent')
+            throw Error('kit_native_serve_contract_runtime_unsupported:' + contract.id);
+        if (Object.hasOwn(contracts, contract.id))
+            throw Error('kit_native_serve_contract_duplicate:' + contract.id);
+        contracts[contract.id] = contract;
+    }
+    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 } : {}) };
+    }
+    for (const id of Object.keys(contracts))
+        if (Object.hasOwn(experts, id))
+            throw Error('kit_native_serve_contract_duplicate:' + id);
+    const standingGrants = c.standingGrants ?? [];
+    for (const g of standingGrants)
+        for (const id of g.experts ?? [])
+            if (!Object.hasOwn(contracts, id))
+                throw Error('kit_native_serve_standing_grant_unknown_expert:' + g.id);
+    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, contracts, approvalOperations: [...new Set(c.approvalOperations ?? ['marketplace_execute'])], standingGrants,
+        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 ?? [], ...(workspace ? { workspace } : {}) };
+}

package/dist/native-serve.d.ts

@@ -0,0 +1,76 @@
+import { type AuthResult } from '@tealbrick/portal';
+import { type ClaudeSdk } from './native-claude.js';
+import { type RuntimeSyncOptions } from './native-runtime-sync.js';
+import { type AppCapabilitiesOptions } from './native-app-capabilities.js';
+import { type GrantStoreOptions } from './native-standing-grants.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;
+    /** Test seams for the owner-only /tealbrick/v1/capabilities snapshot. */
+    appCapabilities?: AppCapabilitiesOptions;
+    approvalTimeoutMs?: number;
+    /** Test seams for the standing-grant usage store (clock, lock timing). */
+    standingGrants?: GrantStoreOptions;
+}
+/** 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 {};

package/dist/native-serve.js

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdir, realpath, writeFile, rename, unlink, lstat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { createPortalVerifier } from '@tealbrick/portal';
+import { createNativeBridge } from '@tealbrick/portal/native-bridge';
+import { CodexAppServer, codexHarness } from '@tealbrick/portal/native-codex';
+import { readKit } from './index.js';
+import { nativeSdkConfig } from './native-setup.js';
+import { claudeHarness, loadClaudeSdk } from './native-claude.js';
+import { startRuntimeSync } from './native-runtime-sync.js';
+import { appCapabilitiesProvider } from './native-app-capabilities.js';
+import { publicHosts, readClaudeAttachment, readServeConfig, resolveClaudeProfile, servePaths } from './native-serve-config.js';
+import { standingGrantStore, standingGrantSummary } from './native-standing-grants.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;
+    let runtime;
+    let grantSummary;
+    const appCapabilities = appCapabilitiesProvider(root, () => runtime, { ...deps.appCapabilities, ...(kit.native.harness === 'claude' ? { standingGrants: async () => grantSummary?.() ?? [] } : {}) });
+    if (kit.native.harness === 'claude') {
+        const profile = await resolveClaudeProfile(root, config);
+        // Shared with `native acp` on this kit root (same file, lock-guarded).
+        const grants = standingGrantStore(join(paths.state, 'standing-grants.json'), deps.standingGrants);
+        grantSummary = () => standingGrantSummary(profile.standingGrants, grants);
+        // Contract scope checks resolve registration ids from this runtime's own Portal-granted snapshot.
+        const resolveApp = async (registrationId) => {
+            const snap = await appCapabilities();
+            const app = snap.apps.find(a => a.registrationId === registrationId);
+            if (app)
+                return { appId: app.appId };
+            const grant = snap.marketplace.grants.find(g => g.registrationId === registrationId);
+            return grant ? { appId: 'marketplace', plugin: grant.plugin, action: grant.action } : undefined;
+        };
+        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, resolveApp, traceDir: join(paths.state, 'traces'), standingGrants: grants, ...(deps.approvalTimeoutMs ? { approvalTimeoutMs: deps.approvalTimeoutMs } : {}) });
+    }
+    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, appCapabilities });
+    // Portal marks a runtime expired unless it re-acknowledges its signed config within the 300s lease;
+    // an idle serve process has no per-turn MCP child doing that, so it keeps the lease itself.
+    runtime = deps.runtimeSync === false ? undefined : startRuntimeSync(root, { log, ...deps.runtimeSync });
+    return { ...bridge, port: config.port, harness: kit.native.harness, runtime, close: async () => { await runtime?.stop(); await bridge.close(); await codex?.close(); } };
+}
+export async function serveNative(root) {
+    const serve = await createNativeServe(root);
+    // Loopback only. Remote reachability is a TLS-terminating proxy such as tailscale serve.
+    await new Promise((resolve, reject) => { serve.server.once('error', reject); serve.server.listen(serve.port, '127.0.0.1', () => resolve()); });
+    process.stderr.write(JSON.stringify({ event: 'native.serve.ready', harness: serve.harness, port: serve.port }) + '\n');
+    for (const signal of ['SIGTERM', 'SIGINT'])
+        process.once(signal, () => { void serve.close().finally(() => process.exit(0)); });
+}
+const xml = (v) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function launchdLabel(root) { return 'com.tealbrick.native-serve.' + createHash('sha256').update(root).digest('hex').slice(0, 12); }
+/** User LaunchAgent: restarts on crash, logs to the kit root's private state directory. */
+export function launchdPlist(root, options = {}) {
+    const node = options.node ?? process.execPath, cli = options.cli ?? fileURLToPath(new URL('./cli.js', import.meta.url)), logs = join(servePaths(root).state, 'logs');
+    const args = [node, cli, 'native', 'serve', '--root', root];
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>Label</key><string>${xml(launchdLabel(root))}</string>
+ <key>ProgramArguments</key><array>${args.map(a => `<string>${xml(a)}</string>`).join('')}</array>
+ <key>WorkingDirectory</key><string>${xml(root)}</string>
+ <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(dirname(node))}:/usr/bin:/bin:/usr/sbin:/sbin</string></dict>
+ <key>RunAtLoad</key><true/>
+ <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+ <key>ThrottleInterval</key><integer>30</integer>
+ <key>ProcessType</key><string>Background</string>
+ <key>Umask</key><integer>63</integer>
+ <key>StandardOutPath</key><string>${xml(join(logs, 'serve.out.log'))}</string>
+ <key>StandardErrorPath</key><string>${xml(join(logs, 'serve.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+export async function installLaunchd(root, options = {}) {
+    if ((options.platform ?? process.platform) !== 'darwin')
+        throw Error('kit_launchd_macos_only');
+    root = await realpath(root);
+    const config = await readServeConfig(root);
+    if (!config?.agent)
+        throw Error('kit_native_serve_enroll_required');
+    const label = launchdLabel(root), dir = join(options.home ?? homedir(), 'Library', 'LaunchAgents'), path = join(dir, label + '.plist');
+    await mkdir(join(servePaths(root).state, 'logs'), { recursive: true, mode: 0o700 });
+    await mkdir(dir, { recursive: true });
+    try {
+        if ((await lstat(path)).isSymbolicLink())
+            throw Error('kit_symlink_path');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await writeFile(path + '.tmp', launchdPlist(root), { mode: 0o600 });
+    await rename(path + '.tmp', path);
+    const exec = options.exec ?? promisify(execFile), domain = 'gui/' + (options.uid ?? process.getuid?.() ?? 0);
+    if (options.load !== false) {
+        await exec('launchctl', ['bootout', domain + '/' + label]).catch(() => { });
+        await exec('launchctl', ['bootstrap', domain, path]);
+    }
+    return { installed: true, label, plist: path, loaded: options.load !== false, logs: join(servePaths(root).state, 'logs') };
+}
+export async function uninstallLaunchd(root, options = {}) {
+    if ((options.platform ?? process.platform) !== 'darwin')
+        throw Error('kit_launchd_macos_only');
+    root = await realpath(root);
+    const label = launchdLabel(root), path = join(options.home ?? homedir(), 'Library', 'LaunchAgents', label + '.plist');
+    const exec = options.exec ?? promisify(execFile);
+    await exec('launchctl', ['bootout', 'gui/' + (options.uid ?? process.getuid?.() ?? 0) + '/' + label]).catch(() => { });
+    await unlink(path).catch(e => { if (e.code !== 'ENOENT')
+        throw e; });
+    return { uninstalled: true, label, plist: path };
+}

package/dist/native-setup.d.ts

@@ -0,0 +1,63 @@
+import type { PortalLogin } from './onboarding.js';
+import { type SetupPrompts } from './native-selection.js';
+import { type NativeHarness } from './native.js';
+export declare function nativeSdkConfig(harness: NativeHarness, root: string, options?: {
+    codexDelegationDisabled?: boolean;
+}): {
+    config: {
+        features: {
+            multi_agent: boolean;
+            multi_agent_v2: boolean;
+        };
+        mcp_servers: {
+            tealbrick: {
+                command: string;
+                args: string[];
+            };
+        };
+    };
+    servers?: undefined;
+    settings?: undefined;
+    mcpServers?: undefined;
+} | {
+    servers: {
+        tealbrick: {
+            command: string;
+            args: string[];
+        };
+    };
+    config?: undefined;
+    settings?: undefined;
+    mcpServers?: undefined;
+} | {
+    settings: {
+        hooks: {
+            PreToolUse: {
+                matcher: string;
+                hooks: {
+                    type: string;
+                    command: string;
+                    args: string[];
+                }[];
+            }[];
+        };
+    };
+    mcpServers: {
+        tealbrick: {
+            command: string;
+            args: string[];
+        };
+    };
+    config?: undefined;
+    servers?: undefined;
+};
+/** Private setup journal stores only identity intent, never account/runtime credentials. */
+export declare function guidedNativeSetup(root: string, flags: Record<string, string>, login: PortalLogin, prompts: SetupPrompts): Promise<{
+    workspaceId: string;
+    nodeId: string;
+    configPath: string;
+    connected: boolean;
+    agentId: string;
+    connectionId: string;
+    harness: "claude" | "codex" | "langchain";
+}>;