@tealbrick/kit 0.3.0-rc.6 → 0.3.0-rc.8

package/dist/native-serve-config.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { lstat, readFile, realpath, writeFile, rename, mkdir } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+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');
@@ -16,6 +16,34 @@ 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();
 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. */
@@ -34,6 +62,10 @@ const claude = z.object({
     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(),
     /** 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. */
@@ -42,8 +74,10 @@ const claude = z.object({
     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(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(),
+    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({
@@ -59,7 +93,9 @@ export const serveConfigSchema = z.object({
     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') });
+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())
@@ -164,7 +200,8 @@ export async function resolveClaudeProfile(root, config) {
         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');
+    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())
@@ -172,7 +209,42 @@ export async function resolveClaudeProfile(root, config) {
     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 });
@@ -181,10 +253,13 @@ export async function resolveClaudeProfile(root, config) {
             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);
     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,
+        defaultTools: [...new Set(c.defaultTools ?? [])], experts, contracts, approvalOperations: [...new Set(c.approvalOperations ?? ['marketplace_execute'])],
         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 ?? [] };
+        requireSubscription: c.requireSubscription ?? false, envPassthrough: c.envPassthrough ?? [], ...(workspace ? { workspace } : {}) };
 }

package/dist/native-serve.d.ts

@@ -13,6 +13,7 @@ export interface ServeDependencies {
     runtimeSync?: RuntimeSyncOptions | false;
     /** Test seams for the owner-only /tealbrick/v1/capabilities snapshot. */
     appCapabilities?: AppCapabilitiesOptions;
+    approvalTimeoutMs?: number;
 }
 /** Build (but do not bind) the owner-authenticated chat endpoint for this kit root. */
 export declare function createNativeServe(root: string, deps?: ServeDependencies): Promise<{

package/dist/native-serve.js

@@ -35,9 +35,20 @@ export async function createNativeServe(root, deps = {}) {
     await mkdir(paths.state, { recursive: true, mode: 0o700 });
     let adapter;
     let codex;
+    let runtime;
+    const appCapabilities = appCapabilitiesProvider(root, () => runtime, deps.appCapabilities);
     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 });
+        // 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'), ...(deps.approvalTimeoutMs ? { approvalTimeoutMs: deps.approvalTimeoutMs } : {}) });
     }
     else if (kit.native.harness === 'codex') {
         if (!config.codex)
@@ -50,8 +61,6 @@ export async function createNativeServe(root, deps = {}) {
     else
         adapter = langchainHarness();
     const authenticate = deps.authenticate ?? createPortalVerifier({ issuer: kit.runtime.issuer, org: kit.runtime.org, agent: config.agent.name }).authenticate;
-    let runtime;
-    const appCapabilities = appCapabilitiesProvider(root, () => runtime, deps.appCapabilities);
     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.

package/dist/native.d.ts

@@ -37,6 +37,6 @@ export declare function nativeConnector(): {
     }>;
     call: (registrationId: string, operation: KnowledgeOperation, input?: Record<string, unknown>, signal?: AbortSignal) => Promise<any>;
 };
-export declare const nativeUsage = "Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native enable|disable | native marketplace-enable|marketplace-disable";
+export declare const nativeUsage = "Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native acp [--root DIRECTORY] [--buzz-cli PATH] | native enable|disable | native marketplace-enable|marketplace-disable";
 export declare function nativeCommand(args: string[], root: string): Promise<void>;
 export { guidedNativeSetup, nativeSdkConfig };

package/dist/native.js

@@ -64,8 +64,18 @@ function serveFlags(args, values, switches) {
     }
     return flags;
 }
-export const nativeUsage = 'Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native enable|disable | native marketplace-enable|marketplace-disable';
+export const nativeUsage = 'Usage: tealbrick native setup --harness claude|codex|langchain [--workspace-name NAME | --create-workspace NAME] [--agent-name NAME | --create-agent NAME] [--issuer HTTPS_ORIGIN] | native mcp [--root DIRECTORY] | native serve [--root DIRECTORY] [--install-launchd [--no-load] | --uninstall] | native enroll --url HTTPS_ORIGIN [--port PORT] [--root DIRECTORY] [--skip-endpoint-check] | native acp [--root DIRECTORY] [--buzz-cli PATH] | native enable|disable | native marketplace-enable|marketplace-disable';
 export async function nativeCommand(args, root) {
+    if (args[0] === 'acp') {
+        const flags = serveFlags(args.slice(1), ['root', 'buzz-cli'], []);
+        if (typeof flags.root === 'string') {
+            root = resolve(flags.root);
+            process.chdir(root);
+        }
+        const { serveAcp } = await import('./native-acp.js');
+        await serveAcp(root, typeof flags['buzz-cli'] === 'string' ? { buzzCli: resolve(flags['buzz-cli']) } : {});
+        return;
+    }
     if (args[0] === 'serve' || args[0] === 'enroll') {
         const flags = args[0] === 'serve' ? serveFlags(args.slice(1), ['root'], ['install-launchd', 'uninstall', 'no-load']) : serveFlags(args.slice(1), ['root', 'url', 'port'], ['skip-endpoint-check']);
         if (typeof flags.root === 'string') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/kit",
-  "version": "0.3.0-rc.6",
+  "version": "0.3.0-rc.8",
   "type": "module",
   "license": "MIT",
   "description": "Complete Teal Brick package kit with explicit Eve capability activation",
@@ -14,7 +14,9 @@
     "NOTICE",
     "BOOTSTRAP.md",
     "RUNTIME.md",
-    "NATIVE.md"
+    "NATIVE.md",
+    "BUZZ.md",
+    "assets"
   ],
   "bin": {
     "tealbrick": "dist/cli.js"
@@ -43,11 +45,11 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@tealbrick/portal": "0.3.0-rc.6",
-    "@tealbrick/avm": "0.3.0-rc.6",
-    "@tealbrick/voice": "0.3.0-rc.6",
-    "@tealbrick/vision": "0.3.0-rc.6",
-    "@tealbrick/deliver": "0.3.0-rc.6",
+    "@tealbrick/portal": "0.3.0-rc.8",
+    "@tealbrick/avm": "0.3.0-rc.8",
+    "@tealbrick/voice": "0.3.0-rc.8",
+    "@tealbrick/vision": "0.3.0-rc.8",
+    "@tealbrick/deliver": "0.3.0-rc.8",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },