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

package/BOOTSTRAP.md

@@ -1,4 +1,4 @@
-> Prerelease 0.3.0-rc.2 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
+> Prerelease 0.3.0-rc.4 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
 
 # Deployment guide: Eve agent + Teal Brick kit
 
@@ -19,7 +19,7 @@ For a fresh machine, the sequence is:
 
 1. Install Node 24 and npm.
 2. Create an Eve 0.70.0 project and configure its primary model credentials.
-3. Install `@tealbrick/kit@0.3.0-rc.2` inside that project.
+3. Install `@tealbrick/kit@0.3.0-rc.4` inside that project.
 4. Run `tealbrick setup` to sign in, select capabilities and register the card.
 5. Build and start Eve, then check a real chat from desktop.
 
@@ -81,7 +81,7 @@ Run this inside the Eve project created in step 2 (or your existing compatible
 project), not in an empty directory or as a global install:
 
 ```bash
-npm install --save-exact @tealbrick/kit@0.3.0-rc.2
+npm install --save-exact @tealbrick/kit@0.3.0-rc.4
 ```
 
 This installs Portal, AVM, Voice, Vision, Deliver and the shared provider transport

package/NATIVE.md

@@ -1,10 +1,10 @@
 # Native agent setup — Stage A candidate
 
-Prerelease suite **0.3.0-rc.2** targets the `next` tag. The seven scoped `@tealbrick/*` packages keep `latest` at 0.2.7, which lacks this flow. The unscoped `tealbrick` facade currently serves RC1 on both `latest` and `next`; RC2 will initially target `next`, with facade `latest` moved only after registry verification. The `tealbrick` facade forwards the existing kit CLI; it is not another SDK. Matching Portal runtime setup endpoints must be deployed before native onboarding can succeed.
+Prerelease suite **0.3.0-rc.4** targets the `next` tag. The seven scoped `@tealbrick/*` packages keep `latest` at 0.2.7, which lacks this flow; the unscoped `tealbrick` facade keeps `latest` at 0.3.0-rc.1. The `tealbrick` facade forwards the existing kit CLI; it is not another SDK. Matching Portal runtime setup endpoints must be deployed before native onboarding can succeed. RC4 adds `tealbrick native serve` and `native enroll` (see README.md).
 
 ## Install and connect
 
-Install the review tarballs with the supplied checksum-verifying `install-candidate.mjs`. Once the release is actually published, the intended installation is `npm install --save-exact tealbrick@0.3.0-rc.2`. RC1 registry installation and live Foxy onboarding have been verified separately. The RC2 command below requires RC2 publication and registry verification; it is not yet a published installation path.
+Install with `npm install --save-exact tealbrick@0.3.0-rc.4` (or `tealbrick@next`) once registry publication is verified. Until then, use the review tarballs with the checksum-verifying `install-candidate.mjs`.
 
 From your native agent workspace:
 
@@ -50,7 +50,7 @@ const adapter = new MCPAdapter(config);
 const agent = createAgent({model: configuredModel, tools: await adapter.listTools(), checkpointer});
 ```
 
-Configure provider authentication on the native host through its supported SDK. Kit does not copy login caches, choose providers or change billing. No Eve daemon, AVMM or inbound bridge is required. Native mode emits no Eve mounts and uses the existing kit state and owner-only credential file.
+Configure provider authentication on the native host through its supported SDK. Kit does not copy login caches, choose providers or change billing. No Eve daemon, AVMM or inbound bridge is required. An optional owner-only chat endpoint for Teal Brick Desktop is available through `tealbrick native serve` and `tealbrick native enroll`; see README.md. Native mode emits no Eve mounts and uses the existing kit state and owner-only credential file.
 
 ## Children and host authority
 

package/README.md

@@ -1,4 +1,4 @@
-> Prerelease 0.3.0-rc.2 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
+> Prerelease 0.3.0-rc.4 targets fresh Eve 0.70 installations. Use the explicit candidate version or `next` tag after publication. Scoped `@tealbrick/*` `latest` remains 0.2.7 for existing Eve 0.66 installations; durable cross-version session migration is not validated.
 
 # @tealbrick/kit
 
@@ -9,7 +9,7 @@ availability, not agent permissions. Nothing is mounted by installing the kit.
 Install inside an existing Eve 0.70.0 project:
 
 ```sh
-npm install --save-exact @tealbrick/kit@0.3.0-rc.2
+npm install --save-exact @tealbrick/kit@0.3.0-rc.4
 npx --no-install tealbrick setup
 ```
 
@@ -92,3 +92,116 @@ including a single deduplicated provider-transport installation.
 ## AVMM profiles
 
 The `avm` selection accepts the [AVM package connection/policy schema](../avm/README.md): either `{target,sudo}` or `{selectedProfile,profiles}`. Setup can select a saved profile and preserves its grants. New connections can use paired AVMM users or operator SSH. Paired mode requires a dedicated SSH identity path and a resolvable hostname; no credentials are copied. Use `tealbrick apply config.json` for full workspace, ownership, sharing, pool and ingress grants. Disabling AVM removes its entire mount.
+
+## Native chat endpoint: `tealbrick native serve`
+
+Optional. Lets the owner chat with a native **Claude Agent SDK** or **Codex**
+agent from TBD. The agent must already be set up with
+`tealbrick setup --harness claude|codex` (kit state, runtime connection and
+`.tealbrick/native-sdk.json`). LangChain is refused with
+`kit_native_serve_langchain_unsupported`.
+
+The endpoint is the Eve session subset Desktop uses (`/eve/v1/health`,
+`/eve/v1/session` create/send, NDJSON stream with cursor catch-up, cancel,
+`/eve/v1/session/:id/access`) plus `GET /tealbrick/v1/info`, which reports
+`harness`, `protocol: "tealbrick-native"`, `model`, `capabilities` and
+`unsupported` honestly. `/eve/v1/info`, reset/clear/compact, attachments,
+approvals, subagents, workflows and schedules return 404/400. The native
+harness keeps the conversation: Claude turns resume the same SDK session id,
+and a restarted server only re-attaches transcripts that still exist.
+
+### Security posture
+
+- Binds `127.0.0.1` only. Reach it from the tailnet through a TLS-terminating
+  proxy (preferred: `tailscale serve`, including for customer deployments).
+- Every request except `/healthz` is verified against Portal (identity token
+  plus policy bundle for this agent) and must come from the enrolled owner.
+- The `Host` header must be loopback, the enrolled `publicUrl` host or an
+  explicit `allowedHosts` entry. Any `Origin` header is rejected. Bodies are
+  limited to 128 KiB and two concurrent turns by default (`maxActiveTurns`).
+- New sessions are **Restricted**: `Read`/`Glob`/`Grep` contained to the
+  profile `cwd` (never the kit's `.tealbrick`), operator-vetted `readTools`, and
+  `mcp__tealbrick__*` only. Shell, file writes, network tools, delegation and
+  project/user Claude settings are unavailable; a PreToolUse hook and
+  `canUseTool` enforce the same decision. The kit's child-agent guard still
+  denies Teal Brick tools to subagents. Optional `tealbrickCalls` adds a
+  local operation ceiling on top of Portal grants.
+- A per-agent default can widen Restricted with `defaultTools` (only
+  `WebSearch`, `WebFetch`, `Agent`, `TodoWrite`; never shell or writes).
+  `Agent` delegates only to the configured `experts`, in the foreground with
+  the session model; each expert runs with its own `tools` (workspace reads,
+  `WebSearch`, `WebFetch`) and never receives Teal Brick tools.
+- Elevation only through Desktop's session-access control (owner, explicit
+  confirmation, optimistic revision, no turn in flight). **Native defaults**
+  snapshots `nativeTools` (still workspace-contained); **Full** uses the
+  Claude Code tool preset with permission bypass. Full is not a security
+  boundary against the local OS user.
+- The SDK process receives an allowlisted environment (`PATH`, `HOME`, locale,
+  CA settings, `envPassthrough`) and never `TEALBRICK_*` values. Logs carry ids,
+  tool names and status codes, never prompts, tool inputs or results.
+
+### Configure
+
+`.tealbrick/native-serve.json` (owner-only, `chmod 600`) holds no secrets:
+
+```json
+{
+  "version": 1,
+  "port": 5331,
+  "claude": {
+    "cwd": "/Users/you/agents/henry-serve/workspace",
+    "instructionsFile": "/Users/you/agents/henry-calendar/agents/henry/INSTRUCTIONS.md",
+    "recipe": {"path": "/Users/you/.config/tealbrick-native/config.json", "agent": "henry"},
+    "requireSubscription": true,
+    "defaultTools": ["WebSearch", "WebFetch", "Agent"],
+    "experts": {
+      "source-researcher": {"promptFile": "/Users/you/agents/henry-calendar/experts/source-researcher.md", "tools": ["WebSearch", "WebFetch"]},
+      "independent-reviewer": {"promptFile": "/Users/you/agents/henry-calendar/experts/independent-reviewer.md"}
+    },
+    "nativeTools": ["Read", "Glob", "Grep", "Write", "Edit", "TodoWrite", "WebSearch", "WebFetch"]
+  }
+}
+```
+
+`recipe` imports `model`, `effort`, `maxTurns`, `maxBudgetUsd`,
+`timeoutSeconds` and the agent's `mcpServers`, `readTools` and
+`tealbrickCalls` from an existing tealbrick-native recipe; its
+`tealbrickSdkConfig` must point at this kit root's `native-sdk.json`. Any of
+those keys set directly under `claude` override the recipe. Keep `cwd` stable:
+Claude session transcripts are stored per working directory. `requireSubscription`
+refuses turns unless the SDK reports first-party subscription sign-in.
+Codex roots use `"codex": {"codexBin": "/abs/codex", "cwd": "/abs/dir"}`.
+
+Install the Claude Agent SDK next to the kit (or set `claude.sdkModule` to an
+absolute SDK package directory):
+
+```sh
+npm install --save-exact @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+### Run, expose, enroll
+
+```sh
+# 1. Tailnet HTTPS in front of the loopback port (pick a free HTTPS port).
+tailscale serve --bg --https=8444 http://127.0.0.1:5331
+# 2. Record the Portal identity and register the URL on the EXISTING agent.
+npx --no-install tealbrick native enroll --url https://HOST.TAILNET.ts.net:8444
+# 3. Start the endpoint (foreground) ...
+npx --no-install tealbrick native serve
+# ... or supervise it with a user LaunchAgent (macOS, opt-in).
+npx --no-install tealbrick native serve --install-launchd
+npx --no-install tealbrick native serve --uninstall
+# 4. Re-run enroll to confirm /healthz and authenticated /tealbrick/v1/info.
+npx --no-install tealbrick native enroll --url https://HOST.TAILNET.ts.net:8444
+```
+
+`enroll` signs in with Portal device approval, requires the kit root's owned
+agent and canvas card to carry the native harness label, registers the origin
+through Portal's owned-connection API (which keeps the harness label; it never
+uses the Eve registration route, which relabels agents as Eve), records
+`agent` and `publicUrl` in `native-serve.json`, updates the card endpoint with
+a revision-checked draft write and verifies the sidebar URL. It then probes the
+endpoint; exit code 2 means Portal is updated but the endpoint was not yet
+reachable or authenticated. The user token is never written to disk.
+LaunchAgent logs go to `.tealbrick/native-serve/logs/`; session projections
+(customer data) to `.tealbrick/native-serve/sessions/`.

package/dist/cli.js

@@ -127,4 +127,4 @@ async function main() {
     console.log('Portal agent card saved and confirmed in workspace discovery. Rebuild/restart Eve to connect.');
     console.log('Local credentials stay in .tealbrick/kit.credentials.json (owner-only). Supply them as runtime secrets when deploying. Provider connectivity has not been tested.');
 }
-main().catch(error => { const message = error instanceof Error ? error.message : ''; console.error(/^kit_[a-z_]+(?::agent\/[a-zA-Z0-9_./-]+)?$/.test(message) ? message : 'Kit setup failed; check configuration and permissions. Credentials omitted.'); process.exitCode = 1; });
+main().catch(error => { const message = error instanceof Error ? error.message : ''; console.error(/^(?:kit_[a-z_]+(?::agent\/[a-zA-Z0-9_./-]+|:[a-zA-Z0-9_.,]+)?|runtime_product_inactive)$/.test(message) ? message : 'Kit setup failed; check configuration and permissions. Credentials omitted.'); process.exitCode = 1; });

package/dist/native-claude.d.ts

@@ -0,0 +1,49 @@
+import type { AccessMode, HarnessAdapter } from '@tealbrick/portal/native-bridge';
+import type { ClaudeAttachment, ClaudeProfile } from './native-serve-config.js';
+/** Minimal structural view of @anthropic-ai/claude-agent-sdk (validated against 0.3.287). */
+export interface ClaudeQuery extends AsyncIterable<any> {
+    interrupt?(): Promise<unknown>;
+    close?(): void;
+    accountInfo?(): Promise<any>;
+}
+export interface ClaudeSdk {
+    query(params: {
+        prompt: AsyncIterable<any>;
+        options: Record<string, any>;
+    }): ClaudeQuery;
+    getSessionInfo?(sessionId: string, options?: {
+        dir?: string;
+    }): Promise<unknown>;
+}
+export declare function loadClaudeSdk(root: string, sdkModule?: string): Promise<ClaudeSdk>;
+export type ClaudeAccess = {
+    mode: AccessMode;
+    revision: number;
+    tools: string[];
+};
+/** Built-in tools Restricted mode exposes: read-only and contained to the workspace. */
+export declare const readOnlyTools: string[];
+/** Removed from the model's context unless a wider access mode explicitly lists them. */
+export declare const restrictedDenied: string[];
+export interface ToolPolicy {
+    access: ClaudeAccess;
+    profile: ClaudeProfile;
+    protectedPaths: string[];
+}
+/** Single decision point for PreToolUse hooks and canUseTool. Names and decisions only are logged. */
+export declare function decideTool(policy: ToolPolicy, name: string, input: Record<string, unknown>, agentId?: string, agentType?: string): Promise<{
+    allow: boolean;
+    reason: string;
+}>;
+export interface ClaudeHarnessOptions {
+    name: string;
+    profile: ClaudeProfile;
+    attachment: ClaudeAttachment;
+    sdk: ClaudeSdk;
+    protectedPaths: string[];
+    log?: (event: Record<string, unknown>) => void;
+    env?: NodeJS.ProcessEnv;
+}
+/** Claude Agent SDK adapter. Claude's persisted session transcript is the source of truth;
+ * every turn is a fresh query() that resumes the same session id. */
+export declare function claudeHarness(options: ClaudeHarnessOptions): HarnessAdapter<ClaudeAccess>;

package/dist/native-claude.js

@@ -0,0 +1,287 @@
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+export async function loadClaudeSdk(root, sdkModule) {
+    let entry;
+    try {
+        entry = sdkModule ? createRequire(import.meta.url).resolve(sdkModule) : createRequire(join(root, 'package.json')).resolve('@anthropic-ai/claude-agent-sdk');
+    }
+    catch {
+        throw Error('kit_native_claude_sdk_missing');
+    }
+    const sdk = await import(pathToFileURL(entry).href);
+    if (typeof sdk.query !== 'function')
+        throw Error('kit_native_claude_sdk_invalid');
+    return sdk;
+}
+/** Built-in tools Restricted mode exposes: read-only and contained to the workspace. */
+export const readOnlyTools = ['Read', 'Glob', 'Grep'];
+/** Removed from the model's context unless a wider access mode explicitly lists them. */
+export const restrictedDenied = ['Bash', 'BashOutput', 'KillShell', 'KillBash', 'Monitor', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'WebFetch', 'WebSearch', 'Agent', 'Task', 'TodoWrite', 'Skill', 'SlashCommand', 'ExitPlanMode', 'EnterWorktree', 'ExitWorktree'];
+const pathTools = { Read: ['file_path'], Write: ['file_path'], Edit: ['file_path'], MultiEdit: ['file_path'], NotebookEdit: ['notebook_path'], Glob: ['path'], Grep: ['path'] };
+const safeEnvNames = ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'LC_ALL', 'SSL_CERT_FILE', 'NODE_EXTRA_CA_CERTS'];
+async function contained(root, input, deny) {
+    let path = resolve(root, input), tail = [];
+    for (;;) {
+        try {
+            path = resolve(await realpath(path), ...tail);
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                return false;
+            const parent = dirname(path);
+            if (parent === path)
+                return false;
+            tail.unshift(basename(path));
+            path = parent;
+        }
+    }
+    const inside = (base) => { const rel = relative(base, path); return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)); };
+    return inside(await realpath(root)) && !deny.some(inside);
+}
+/** Single decision point for PreToolUse hooks and canUseTool. Names and decisions only are logged. */
+export async function decideTool(policy, name, input, agentId, agentType) {
+    const { access, profile } = policy;
+    if (name.startsWith('mcp__tealbrick__')) {
+        if (agentId !== undefined)
+            return { allow: false, reason: 'Teal Brick authority is not delegated to child agents' };
+        if (name === 'mcp__tealbrick__tealbrick_call' && profile.tealbrickCalls.length) {
+            const args = input.input;
+            const ok = !Object.keys(input).some(k => !['registrationId', 'operation', 'input'].includes(k)) && !!args && typeof args === 'object' && !Array.isArray(args) && profile.tealbrickCalls.some(g => g.registrationId === input.registrationId && g.operation === input.operation && Object.entries(g.inputEquals).every(([k, v]) => Object.hasOwn(args, k) && args[k] === v));
+            if (!ok)
+                return { allow: false, reason: 'Outside the configured Teal Brick operation ceiling' };
+        }
+        return { allow: true, reason: 'Portal-governed Teal Brick tool' };
+    }
+    if (access.mode === 'full')
+        return { allow: true, reason: 'Full session access' };
+    // The SDK still surfaces the delegation tool under its legacy name Task.
+    if (name === 'Task')
+        name = 'Agent';
+    const allowed = access.mode === 'restricted' ? [...[...readOnlyTools, ...profile.defaultTools].filter(t => access.tools.includes(t)), ...profile.readTools] : [...access.tools, ...profile.readTools];
+    if (!allowed.includes(name))
+        return { allow: false, reason: `Not available in ${access.mode} session access` };
+    if (agentId !== undefined && !(agentType !== undefined && Object.hasOwn(profile.experts, agentType) ? [profile.experts[agentType]] : Object.values(profile.experts)).some(e => e.tools.includes(name)))
+        return { allow: false, reason: 'Not available to expert agents' };
+    if (name === 'Agent') {
+        const type = String(input.subagent_type ?? '');
+        if (!Object.hasOwn(profile.experts, type) || input.run_in_background || input.isolation || input.resume || (input.model !== undefined && input.model !== 'inherit'))
+            return { allow: false, reason: 'Only configured experts may be delegated, in the foreground' };
+    }
+    const fields = pathTools[name];
+    if (fields) {
+        if (name === 'Glob' && (String(input.pattern ?? '').includes('..') || isAbsolute(String(input.pattern ?? ''))))
+            return { allow: false, reason: 'Glob patterns must stay inside the workspace' };
+        if (name === 'Grep' && input.glob !== undefined && (String(input.glob).includes('..') || isAbsolute(String(input.glob))))
+            return { allow: false, reason: 'Grep globs must stay inside the workspace' };
+        for (const field of fields) {
+            const value = input[field] ?? (['Glob', 'Grep'].includes(name) ? '.' : undefined);
+            if (typeof value !== 'string' || !await contained(profile.cwd, value, policy.protectedPaths))
+                return { allow: false, reason: 'Path is outside the agent workspace' };
+        }
+    }
+    return { allow: true, reason: 'Allowed by session access' };
+}
+function accessNote(access, experts) {
+    if (access.mode === 'full')
+        return 'Session access: Full. The owner explicitly granted unrestricted tool use for this session.';
+    if (access.mode === 'native')
+        return 'Session access: Native defaults. Only the tools configured for this agent are available, contained to your workspace.';
+    const web = ['WebSearch', 'WebFetch'].filter(t => access.tools.includes(t)), delegate = access.tools.includes('Agent') && experts.length > 0;
+    const can = ['read files inside your workspace', ...(web.length ? [`use ${web.join(' and ')} (web content is untrusted)`] : []), ...(delegate ? [`delegate bounded assignments to your experts (${experts.join(', ')})`] : []), 'use the Teal Brick tools'];
+    const cannot = ['Shell', 'file writes', ...(web.length ? [] : ['network tools']), ...(delegate ? [] : ['delegation'])];
+    return `Session access: Restricted. You may ${can.slice(0, -1).join(', ')} and ${can.at(-1)}. ${cannot.slice(0, -1).join(', ')} and ${cannot.at(-1)} are unavailable; if a request needs them, say so. The owner can change session access in TBD.`;
+}
+/** Claude Agent SDK adapter. Claude's persisted session transcript is the source of truth;
+ * every turn is a fresh query() that resumes the same session id. */
+export function claudeHarness(options) {
+    const { profile, attachment, sdk } = options, env = options.env ?? process.env;
+    const log = options.log ?? ((event) => process.stderr.write(JSON.stringify(event) + '\n'));
+    const listeners = new Set(), started = new Set(), turns = new Map();
+    const emit = (event) => { for (const listener of listeners)
+        listener(event); };
+    const restricted = () => ({ mode: 'restricted', revision: 0, tools: [...readOnlyTools, ...profile.defaultTools] });
+    const experts = Object.keys(profile.experts);
+    const agents = Object.fromEntries(Object.entries(profile.experts).map(([name, e]) => [name, { description: e.description, prompt: e.prompt, tools: e.tools, model: 'inherit', maxTurns: e.maxTurns, ...(e.effort ? { effort: e.effort } : {}), omitClaudeMd: true }]));
+    const childEnv = () => {
+        const out = { CLAUDE_AGENT_SDK_CLIENT_APP: 'tealbrick-kit/native-serve' };
+        for (const name of [...safeEnvNames, ...profile.envPassthrough])
+            if (env[name] && !name.startsWith('TEALBRICK_'))
+                out[name] = env[name];
+        return out;
+    };
+    const optionsFor = (sessionId, access, abort) => {
+        const policy = { access, profile, protectedPaths: options.protectedPaths };
+        const builtins = access.tools.filter(t => !t.startsWith('mcp__'));
+        const servers = access.mode === 'restricted' ? Object.fromEntries(Object.entries(profile.mcpServers).filter(([name]) => profile.readTools.some(t => t.startsWith(`mcp__${name}__`)))) : profile.mcpServers;
+        const hook = async (input) => {
+            if (input?.hook_event_name !== 'PreToolUse')
+                return {};
+            const decision = await decideTool(policy, String(input.tool_name), input.tool_input ?? {}, input.agent_id, input.agent_type);
+            log({ event: 'claude.tool', sessionId, tool: String(input.tool_name).slice(0, 120), allowed: decision.allow, child: input.agent_id !== undefined });
+            return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision.allow ? 'allow' : 'deny', permissionDecisionReason: decision.reason } };
+        };
+        const append = [profile.instructions?.trim(), `You are ${options.name}, chatting with your owner through TBD. ${accessNote(access, experts)}`].filter(Boolean).join('\n\n');
+        const delegates = experts.length > 0 && (access.mode === 'full' || builtins.includes('Agent'));
+        return {
+            cwd: profile.cwd, env: childEnv(),
+            ...(profile.model ? { model: profile.model } : {}), ...(profile.effort ? { effort: profile.effort } : {}),
+            maxTurns: profile.maxTurns, ...(profile.maxBudgetUsd !== undefined ? { maxBudgetUsd: profile.maxBudgetUsd } : {}),
+            settingSources: [], strictMcpConfig: true,
+            mcpServers: { ...servers, tealbrick: attachment.mcpServers.tealbrick },
+            settings: attachment.settings,
+            tools: access.mode === 'full' ? { type: 'preset', preset: 'claude_code' } : builtins,
+            ...(delegates ? { agents } : {}),
+            disallowedTools: access.mode === 'full' ? [] : restrictedDenied.filter(t => !builtins.includes(t === 'Task' ? 'Agent' : t)),
+            permissionMode: access.mode === 'full' ? 'bypassPermissions' : 'default',
+            ...(access.mode === 'full' ? { allowDangerouslySkipPermissions: true } : {
+                canUseTool: async (name, input) => { const d = await decideTool(policy, name, input); return d.allow ? { behavior: 'allow', updatedInput: input } : { behavior: 'deny', message: d.reason }; },
+            }),
+            hooks: { PreToolUse: [{ hooks: [hook] }] },
+            systemPrompt: { type: 'preset', preset: 'claude_code', append },
+            persistSession: true, includePartialMessages: true,
+            ...(started.has(sessionId) ? { resume: sessionId } : { sessionId }),
+            abortController: abort,
+        };
+    };
+    async function run(sessionId, text, access) {
+        const turn = { cancelled: false, timedOut: false, turnId: randomUUID() }, abort = new AbortController();
+        turn.abort = abort;
+        turns.set(sessionId, turn);
+        emit({ type: 'turn.started', sessionId, turnId: turn.turnId });
+        let release;
+        const gate = new Promise(r => { release = r; });
+        async function* prompt() { await gate; if (abort.signal.aborted)
+            return; yield { type: 'user', session_id: '', parent_tool_use_id: null, message: { role: 'user', content: text } }; }
+        const timer = setTimeout(() => { turn.timedOut = true; abort.abort(); }, profile.timeoutSeconds * 1000);
+        let result, assistantError, failure, finalText = false, buffer = '', stopReason = null;
+        try {
+            const q = sdk.query({ prompt: prompt(), options: optionsFor(sessionId, access, abort) });
+            turn.query = q;
+            if (profile.requireSubscription) {
+                const account = await q.accountInfo?.();
+                if (!account || account.apiProvider !== 'firstParty' || !account.subscriptionType || account.apiKeySource === 'env')
+                    failure = { code: 'claude_subscription_required', message: 'Claude subscription sign-in is required on this host; API-key fallback is disabled.' };
+            }
+            if (failure)
+                abort.abort();
+            else
+                release();
+            if (!failure)
+                for await (const m of q) {
+                    if (m?.type === 'system' && m.subtype === 'init') {
+                        if (m.session_id !== sessionId) {
+                            failure = { code: 'claude_session_mismatch', message: 'The Claude session id did not match this conversation.' };
+                            abort.abort();
+                            break;
+                        }
+                        started.add(sessionId);
+                        continue;
+                    }
+                    if (m?.parent_tool_use_id !== null && m?.parent_tool_use_id !== undefined)
+                        continue;
+                    if (m?.type === 'stream_event') {
+                        const e = m.event ?? {};
+                        if (e.type === 'message_start') {
+                            buffer = '';
+                            stopReason = null;
+                        }
+                        else if (e.type === 'content_block_start' && e.content_block?.type === 'tool_use')
+                            emit({ type: 'action.requested', sessionId, toolName: String(e.content_block.name).slice(0, 120) });
+                        else if (e.type === 'content_block_delta' && e.delta?.type === 'text_delta' && typeof e.delta.text === 'string') {
+                            buffer += e.delta.text;
+                            emit({ type: 'message.delta', sessionId, text: e.delta.text });
+                        }
+                        else if (e.type === 'message_delta')
+                            stopReason = e.delta?.stop_reason ?? stopReason;
+                        else if (e.type === 'message_stop' && buffer.trim()) {
+                            const final = stopReason !== 'tool_use';
+                            emit({ type: 'message.completed', sessionId, text: buffer, finishReason: final ? 'stop' : 'tool-calls' });
+                            finalText ||= final;
+                            buffer = '';
+                        }
+                    }
+                    else if (m?.type === 'user' && Array.isArray(m.message?.content) && m.message.content.some((b) => b?.type === 'tool_result'))
+                        emit({ type: 'action.result', sessionId });
+                    else if (m?.type === 'assistant' && typeof m.error === 'string')
+                        assistantError = m.error;
+                    else if (m?.type === 'result')
+                        result = m;
+                }
+        }
+        catch { /* classified below; SDK error text is not echoed */ }
+        finally {
+            clearTimeout(timer);
+            release();
+            try {
+                turn.query?.close?.();
+            }
+            catch { }
+            turns.delete(sessionId);
+        }
+        if (turn.cancelled) {
+            emit({ type: 'turn.ended', sessionId, status: 'cancelled', turnId: turn.turnId });
+            return;
+        }
+        if (!failure && turn.timedOut)
+            failure = { code: 'claude_turn_timeout', message: `The turn exceeded ${profile.timeoutSeconds} seconds and was stopped.` };
+        if (!failure && result?.subtype === 'success' && !result.is_error) {
+            if (!finalText && typeof result.result === 'string' && result.result.trim())
+                emit({ type: 'message.completed', sessionId, text: result.result, finishReason: 'stop' });
+            emit({ type: 'turn.ended', sessionId, status: 'completed', turnId: turn.turnId });
+            return;
+        }
+        if (!failure) {
+            const subtype = typeof result?.subtype === 'string' && /^[a-z_]+$/.test(result.subtype) ? result.subtype : undefined;
+            const messages = { error_max_turns: `The turn reached its ${profile.maxTurns}-turn limit.`, error_max_budget_usd: 'The turn reached its configured budget limit.' };
+            failure = { code: 'claude_' + (subtype && subtype !== 'success' ? subtype : assistantError && /^[a-z_]+$/.test(assistantError) ? assistantError : 'turn_failed'), message: (subtype && messages[subtype]) ?? 'The Claude Agent SDK turn failed; check the host sign-in and logs.' };
+        }
+        log({ event: 'claude.turn.failed', sessionId, code: failure.code });
+        emit({ type: 'turn.ended', sessionId, status: 'failed', code: failure.code, message: failure.message, turnId: turn.turnId });
+    }
+    const capabilities = ['chat', 'resume', 'cancel', 'mcp', 'session-access'];
+    return {
+        info: { harness: 'claude', protocol: 'tealbrick-native', transport: 'claude-agent-sdk', workflowId: 'claude-agent-sdk', ...(profile.model ? { model: profile.model } : {}), capabilities,
+            unsupported: ['eve-info', 'eve-workflows', 'eve-schedules', 'file-attachments', 'approvals', 'subagents', 'session-reset', 'session-clear', 'session-compact', 'client-context', 'output-schema'] },
+        restricted,
+        subscribe: listener => { listeners.add(listener); },
+        async create() { return randomUUID(); },
+        async resume(sessionId) {
+            // Only re-attach a transcript that actually exists; never mint a replacement.
+            if (sdk.getSessionInfo && !await sdk.getSessionInfo(sessionId, { dir: profile.cwd }))
+                throw Error('claude_session_not_found');
+            started.add(sessionId);
+        },
+        async send(sessionId, message, access) { void run(sessionId, message, access).catch(() => emit({ type: 'turn.ended', sessionId, status: 'failed', code: 'claude_turn_failed', message: 'The Claude Agent SDK turn failed.' })); },
+        async cancel(sessionId) {
+            const turn = turns.get(sessionId);
+            if (!turn)
+                return false;
+            turn.cancelled = true;
+            const interrupted = await Promise.race([Promise.resolve(turn.query?.interrupt?.()).then(() => true, () => false), new Promise(r => setTimeout(() => r(false), 5000))]);
+            if (!interrupted)
+                turn.abort?.abort();
+            else
+                setTimeout(() => { if (turns.get(sessionId) === turn)
+                    turn.abort?.abort(); }, 10000).unref();
+            return true;
+        },
+        access: {
+            async select(mode, revision) {
+                if (mode === 'restricted')
+                    return { ...restricted(), revision };
+                if (mode === 'full')
+                    return { mode, revision, tools: ['*'] };
+                // Snapshot now: later profile edits never silently widen an existing session.
+                return { mode, revision, tools: [...profile.nativeTools] };
+            },
+        },
+        async close() { for (const turn of turns.values()) {
+            turn.cancelled = true;
+            turn.abort?.abort();
+        } },
+    };
+}

package/dist/native-enroll.d.ts

@@ -0,0 +1,22 @@
+import type { PortalLogin } from './onboarding.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 declare function enrollNative(root: string, input: {
+    url: string;
+    port?: number;
+}, login: PortalLogin, options?: {
+    fetch?: typeof fetch;
+    verifyEndpoint?: boolean;
+}): Promise<{
+    endpointReason?: string | undefined;
+    enrolled: boolean;
+    agentId: string;
+    name: string;
+    harness: "Claude Agent SDK" | "Codex" | "LangChain";
+    endpoint: string;
+    workspaceId: string;
+    portalVerified: boolean;
+    endpointVerified: boolean;
+}>;

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 } : {}) };
+}