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

package/BOOTSTRAP.md

@@ -1,4 +1,4 @@
-> 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.
+> Prerelease 0.3.0-rc.6 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.4` inside that project.
+3. Install `@tealbrick/kit@0.3.0-rc.6` 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.4
+npm install --save-exact @tealbrick/kit@0.3.0-rc.6
 ```
 
 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.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).
+Prerelease suite **0.3.0-rc.6** 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 added `tealbrick native serve` and `native enroll` (see README.md). RC5 keeps an idle serve process's runtime acknowledged in Portal, and lets the runtime reach Portal-provisioned Knowledge with short-lived Portal grants when no local app binding exists. RC6 adds the owner-only `/tealbrick/v1/capabilities` snapshot (Portal-granted apps and Marketplace consents) used by TBD Chat → Plugins, and `tealbrick native` without a subcommand prints usage.
 
 ## Install and connect
 
-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`.
+Install with `npm install --save-exact tealbrick@0.3.0-rc.6` (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:
 

package/README.md

@@ -1,4 +1,4 @@
-> 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.
+> Prerelease 0.3.0-rc.6 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.4
+npm install --save-exact @tealbrick/kit@0.3.0-rc.6
 npx --no-install tealbrick setup
 ```
 
@@ -110,6 +110,14 @@ 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.
 
+While running, serve keeps the runtime connection synced with Portal even when
+no turn is active: it fetches the signed runtime config and acknowledges it on
+start and every 60–120 s (jittered; exponential backoff to 4 min on errors), so
+Portal does not mark an idle runtime as expired after the 300 s config lease.
+Changes are logged as `native.runtime.synced`; a revoked credential (HTTP 401)
+stops the loop with one `native.runtime.sync.stopped` line. The per-turn
+`tealbrick` MCP child still fetches a fresh authorization for every call.
+
 ### Security posture
 
 - Binds `127.0.0.1` only. Reach it from the tailnet through a TLS-terminating
@@ -131,6 +139,11 @@ and a restarted server only re-attaches transcripts that still exist.
   `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.
+- `GET /tealbrick/v1/capabilities` (same owner auth) reports what Portal
+  currently grants this agent: Knowledge apps from the background runtime sync
+  and, when `tealbrick native marketplace-enable` is set, Marketplace consents
+  (plugin and action names only; no credentials, leases or account
+  references). TBD uses it for Chat → Plugins.
 - 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

package/dist/native-app-capabilities.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeSync } from './native-runtime-sync.js';
+export interface AppCapabilitiesOptions {
+    fetch?: typeof fetch;
+    now?: () => number;
+    marketplaceTtlMs?: number;
+}
+/**
+ * Owner-facing snapshot of what Portal currently grants this agent: Knowledge apps from the background
+ * runtime sync, and Marketplace consents when Marketplace is activated in this kit root. Identifiers,
+ * actions and plugin/action names only; never credentials, leases or provider account references.
+ */
+export declare function appCapabilitiesProvider(root: string, runtime: () => RuntimeSync | undefined, options?: AppCapabilitiesOptions): () => Promise<{
+    schema: number;
+    sync: {
+        error?: string | undefined;
+        lastSyncAt?: number | undefined;
+        expiresAt?: number | undefined;
+        revision?: string | undefined;
+        status: string;
+    };
+    apps: {
+        registrationId: string;
+        appId: "knowledge";
+        actions: import("@tealbrick/portal/runtime").CrudAction[];
+        available: boolean;
+        operations: import("@tealbrick/portal/runtime").KnowledgeOperation[];
+    }[];
+    marketplace: Record<string, unknown>;
+}>;

package/dist/native-app-capabilities.js

@@ -0,0 +1,36 @@
+import { MarketplaceRuntimeConnector } from '@tealbrick/portal/marketplace-runtime';
+import { readKit } from './index.js';
+import { runtimeSecret } from './secrets.js';
+const code = (v) => typeof v === 'string' && /^[a-z][a-z0-9_]{0,80}$/.test(v) ? v : undefined;
+/**
+ * Owner-facing snapshot of what Portal currently grants this agent: Knowledge apps from the background
+ * runtime sync, and Marketplace consents when Marketplace is activated in this kit root. Identifiers,
+ * actions and plugin/action names only; never credentials, leases or provider account references.
+ */
+export function appCapabilitiesProvider(root, runtime, options = {}) {
+    const now = options.now ?? Date.now, ttl = options.marketplaceTtlMs ?? 30_000;
+    let cached;
+    async function marketplace() {
+        const kit = await readKit(root);
+        if (!kit.native?.active || !kit.native.marketplace || !kit.runtime)
+            return { enabled: false, status: 'inactive', grants: [] };
+        const { credentialRef, ...identity } = kit.runtime, key = JSON.stringify(kit.runtime);
+        if (cached && cached.key === key && now() - cached.at < ttl)
+            return cached.value;
+        let value;
+        try {
+            const consents = await new MarketplaceRuntimeConnector({ ...identity, credential: () => runtimeSecret(credentialRef, root), ...(options.fetch ? { fetch: options.fetch } : {}) }).discover();
+            value = { enabled: true, status: 'ok', grants: consents.map(c => ({ registrationId: `marketplace:${c.consentId}`, consentId: c.consentId, consentRevision: c.consentRevision, deploymentId: c.deploymentId, state: c.state, plugin: c.selection.pluginId, action: c.selection.actionKey, resourceKind: c.selection.resourceKind, operations: ['marketplace_execute'] })) };
+        }
+        catch (e) {
+            value = { enabled: true, status: 'unavailable', error: code(e?.message) ?? 'runtime_marketplace_unavailable', grants: [] };
+        }
+        cached = { at: now(), key, value };
+        return value;
+    }
+    return async () => {
+        const snap = runtime()?.snapshot();
+        const apps = (snap?.capabilities?.apps ?? []).map(a => ({ registrationId: a.registrationId, appId: a.appId, actions: [...a.actions], available: a.available, operations: [...a.operations] }));
+        return { schema: 1, sync: { status: snap?.status ?? 'disabled', ...(snap?.revision ? { revision: snap.revision } : {}), ...(snap?.expiresAt ? { expiresAt: snap.expiresAt } : {}), ...(snap?.lastSyncAt ? { lastSyncAt: snap.lastSyncAt } : {}), ...(snap?.error ? { error: snap.error } : {}) }, apps, marketplace: await marketplace() };
+    };
+}

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

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

package/dist/native-runtime-sync.js

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

package/dist/native-serve.d.ts

@@ -1,5 +1,7 @@
 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';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export declare function langchainHarness(): never;
 export interface ServeDependencies {
@@ -7,11 +9,31 @@ export interface ServeDependencies {
     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;
 }
 /** 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>>;

package/dist/native-serve.js

@@ -11,6 +11,8 @@ 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';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export function langchainHarness() { throw Error('kit_native_serve_langchain_unsupported'); }
@@ -48,8 +50,13 @@ 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;
-    const bridge = await createNativeBridge({ name: config.agent.name, ownerId: config.agent.ownerId, root: paths.state, port: config.port, allowedHosts: publicHosts(config), authenticate, adapter, maxActiveTurns: config.maxActiveTurns ?? 2, log });
-    return { ...bridge, port: config.port, harness: kit.native.harness, close: async () => { await bridge.close(); await codex?.close(); } };
+    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.
+    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);

package/dist/native.d.ts

@@ -37,5 +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 function nativeCommand(args: string[], root: string): Promise<void>;
 export { guidedNativeSetup, nativeSdkConfig };

package/dist/native.js

@@ -64,6 +64,7 @@ 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 async function nativeCommand(args, root) {
     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']);
@@ -111,6 +112,11 @@ export async function nativeCommand(args, root) {
         return;
     }
     const command = args[0], flags = {};
+    // A bare `tealbrick native` or help request prints usage; it is not a failed setup.
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        console.log(nativeUsage);
+        return;
+    }
     for (let i = 1; i < args.length; i += 2) {
         if (!/^--(root|harness|workspace|workspace-name|create-workspace|node|agent|agent-name|create-agent|delegation|issuer)$/.test(args[i]) || !args[i + 1] || flags[args[i].slice(2)])
             throw Error('kit_native_invalid_arguments');
@@ -171,6 +177,7 @@ export async function nativeCommand(args, root) {
         console.log(JSON.stringify({ active: command === 'enable' }));
         return;
     }
-    throw Error('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');
+    console.error(nativeUsage);
+    process.exitCode = 2;
 }
 export { guidedNativeSetup, nativeSdkConfig };

package/dist/secrets.d.ts

@@ -1,3 +1,4 @@
-export declare function runtimeSecret(name: string): string;
+/** Reads from the environment, then the kit root's private credentials file (cwd unless `root` is given). */
+export declare function runtimeSecret(name: string, root?: string): string;
 /** Lazy: does not read credentials during discovery/build or for unused providers. */
 export declare function secretEnvironment(): NodeJS.ProcessEnv;

package/dist/secrets.js

@@ -1,12 +1,14 @@
 import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
 const namePattern = /^TEALBRICK_[A-Z0-9_]+$/;
-export function runtimeSecret(name) {
+/** Reads from the environment, then the kit root's private credentials file (cwd unless `root` is given). */
+export function runtimeSecret(name, root) {
     if (!namePattern.test(name))
         throw Error('kit_invalid_secret_reference');
     let value = process.env[name];
     if (!value) {
         try {
-            const path = '.tealbrick/kit.credentials.json', stat = lstatSync(path);
+            const path = root === undefined ? '.tealbrick/kit.credentials.json' : join(root, '.tealbrick', 'kit.credentials.json'), stat = lstatSync(path);
             if (!stat.isFile() || stat.isSymbolicLink() || (process.platform !== 'win32' && (stat.mode & 0o077)))
                 throw Error('kit_secret_permissions');
             const data = JSON.parse(readFileSync(path, 'utf8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/kit",
-  "version": "0.3.0-rc.4",
+  "version": "0.3.0-rc.6",
   "type": "module",
   "license": "MIT",
   "description": "Complete Teal Brick package kit with explicit Eve capability activation",
@@ -43,11 +43,11 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@tealbrick/portal": "0.3.0-rc.4",
-    "@tealbrick/avm": "0.3.0-rc.4",
-    "@tealbrick/voice": "0.3.0-rc.4",
-    "@tealbrick/vision": "0.3.0-rc.4",
-    "@tealbrick/deliver": "0.3.0-rc.4",
+    "@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",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },