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

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.5 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.5` 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.5
 ```
 
 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.5** 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.
 
 ## 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.5` (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.5 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.5
 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

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,6 @@
 import { type AuthResult } from '@tealbrick/portal';
 import { type ClaudeSdk } from './native-claude.js';
+import { type RuntimeSyncOptions } from './native-runtime-sync.js';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export declare function langchainHarness(): never;
 export interface ServeDependencies {
@@ -7,11 +8,29 @@ 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;
 }
 /** 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,7 @@ 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 { 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'); }
@@ -49,7 +50,10 @@ export async function createNativeServe(root, deps = {}) {
         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(); } };
+    // 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.
+    const 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/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.5",
   "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.5",
+    "@tealbrick/avm": "0.3.0-rc.5",
+    "@tealbrick/voice": "0.3.0-rc.5",
+    "@tealbrick/vision": "0.3.0-rc.5",
+    "@tealbrick/deliver": "0.3.0-rc.5",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },