@tealbrick/kit 0.3.0-rc.7 → 0.3.0-rc.9

package/dist/native-serve.d.ts

@@ -2,6 +2,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';
+import { type GrantStoreOptions } from './native-standing-grants.js';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export declare function langchainHarness(): never;
 export interface ServeDependencies {
@@ -14,6 +15,8 @@ export interface ServeDependencies {
     /** Test seams for the owner-only /tealbrick/v1/capabilities snapshot. */
     appCapabilities?: AppCapabilitiesOptions;
     approvalTimeoutMs?: number;
+    /** Test seams for the standing-grant usage store (clock, lock timing). */
+    standingGrants?: GrantStoreOptions;
 }
 /** Build (but do not bind) the owner-authenticated chat endpoint for this kit root. */
 export declare function createNativeServe(root: string, deps?: ServeDependencies): Promise<{

package/dist/native-serve.js

@@ -14,6 +14,7 @@ import { claudeHarness, loadClaudeSdk } from './native-claude.js';
 import { startRuntimeSync } from './native-runtime-sync.js';
 import { appCapabilitiesProvider } from './native-app-capabilities.js';
 import { publicHosts, readClaudeAttachment, readServeConfig, resolveClaudeProfile, servePaths } from './native-serve-config.js';
+import { standingGrantStore, standingGrantSummary } from './native-standing-grants.js';
 /** LangChain has no stable session/stream/cancel contract to drive from here yet. */
 export function langchainHarness() { throw Error('kit_native_serve_langchain_unsupported'); }
 /** Build (but do not bind) the owner-authenticated chat endpoint for this kit root. */
@@ -36,9 +37,13 @@ export async function createNativeServe(root, deps = {}) {
     let adapter;
     let codex;
     let runtime;
-    const appCapabilities = appCapabilitiesProvider(root, () => runtime, deps.appCapabilities);
+    let grantSummary;
+    const appCapabilities = appCapabilitiesProvider(root, () => runtime, { ...deps.appCapabilities, ...(kit.native.harness === 'claude' ? { standingGrants: async () => grantSummary?.() ?? [] } : {}) });
     if (kit.native.harness === 'claude') {
         const profile = await resolveClaudeProfile(root, config);
+        // Shared with `native acp` on this kit root (same file, lock-guarded).
+        const grants = standingGrantStore(join(paths.state, 'standing-grants.json'), deps.standingGrants);
+        grantSummary = () => standingGrantSummary(profile.standingGrants, grants);
         // Contract scope checks resolve registration ids from this runtime's own Portal-granted snapshot.
         const resolveApp = async (registrationId) => {
             const snap = await appCapabilities();
@@ -48,7 +53,7 @@ export async function createNativeServe(root, deps = {}) {
             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 } : {}) });
+        adapter = claudeHarness({ name: config.agent.name, profile, attachment: await readClaudeAttachment(root), sdk: deps.claudeSdk ?? await loadClaudeSdk(root, profile.sdkModule), protectedPaths: [join(root, '.tealbrick')], log, env: deps.env, resolveApp, traceDir: join(paths.state, 'traces'), standingGrants: grants, ...(deps.approvalTimeoutMs ? { approvalTimeoutMs: deps.approvalTimeoutMs } : {}) });
     }
     else if (kit.native.harness === 'codex') {
         if (!config.codex)

package/dist/native-standing-grants.d.ts

@@ -0,0 +1,105 @@
+import type { ClaudeProfile, StandingGrant } from './native-serve-config.js';
+/**
+ * Standing grants: owner-defined pre-approvals for bounded classes of approval-gated Teal Brick calls.
+ * The kit's PreToolUse hook (never the model) decides: a matching, unexpired grant with remaining caps
+ * replaces the per-payload prompt. Anything else falls back to the normal payload approval.
+ *
+ * Usage counters live in `<state>/standing-grants.json` (0600): only timestamps per grant id, pruned to
+ * the 24h window. `native serve` and `native acp` on the same kit root share the file. Every
+ * check-and-record runs under an exclusive lock file created with O_EXCL (`<file>.lock`), retried until
+ * a timeout; a lock older than staleLockMs is treated as abandoned (crashed holder) and removed. Writes are
+ * tmp + rename, so readers never see a partial file. If the lock cannot be taken or the file is unreadable,
+ * no standing approval is given (fail closed to the prompt).
+ */
+export type GrantRefusal = 'per_day' | 'per_hour' | 'min_interval' | 'store_unavailable';
+export interface GrantUsageStore {
+    now(): number;
+    /** Atomically checks the grant's caps and records one use when they allow it. */
+    consume(grant: StandingGrant): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: GrantRefusal;
+    }>;
+    /** Read-only usage snapshot (timestamps per grant id), or undefined when unreadable. */
+    usage(): Promise<Record<string, number[]> | undefined>;
+}
+export declare function capRefusal(grant: StandingGrant, stamps: number[], now: number): GrantRefusal | undefined;
+export interface GrantStoreOptions {
+    now?: () => number;
+    lockTimeoutMs?: number;
+    staleLockMs?: number;
+}
+/** Persistent store at `file`, or an in-memory store when `file` is undefined (harness-only tests). */
+export declare function standingGrantStore(path: string | undefined, options?: GrantStoreOptions): GrantUsageStore;
+export declare const grantExpired: (grant: StandingGrant, now: number) => boolean;
+export type GrantRef = {
+    appId: string;
+    plugin?: string;
+    action?: string;
+};
+export interface GrantCall {
+    name: string;
+    input: Record<string, unknown>;
+    agentId?: string;
+    agentType?: string;
+}
+export type GrantDecision = {
+    grant: StandingGrant;
+    ref?: GrantRef;
+};
+export interface GrantContext {
+    profile: ClaudeProfile;
+    store: GrantUsageStore;
+    resolveApp?: (registrationId: string) => Promise<GrantRef | undefined>;
+    trace: (record: Record<string, unknown>) => void;
+}
+/**
+ * Finds the first configured grant (in order) that covers this approval-gated call and still has capacity,
+ * and records its use. Returns undefined when the normal payload approval must run.
+ */
+export declare function standingGrantFor(ctx: GrantContext, call: GrantCall): Promise<GrantDecision | undefined>;
+/** Owner-facing audit view: no deny patterns or inputs, only identifiers, caps, expiry and remaining uses. */
+export declare function standingGrantSummary(grants: StandingGrant[], store: GrantUsageStore): Promise<({
+    denyPatterns: number;
+    remainingThisHour?: number | undefined;
+    usedToday: number;
+    remainingToday: number;
+    id: string;
+    description: string;
+    operation: string;
+    match: {
+        registrationId?: string | undefined;
+        plugin?: string | string[] | undefined;
+        action?: string | string[] | undefined;
+    };
+    experts: string[];
+    caps: {
+        perDay: number;
+        perHour?: number | undefined;
+        minIntervalSeconds?: number | undefined;
+    };
+    expires: string;
+    expired: boolean;
+} | {
+    denyPatterns: number;
+    usage: string;
+    id: string;
+    description: string;
+    operation: string;
+    match: {
+        registrationId?: string | undefined;
+        plugin?: string | string[] | undefined;
+        action?: string | string[] | undefined;
+    };
+    experts: string[];
+    caps: {
+        perDay: number;
+        perHour?: number | undefined;
+        minIntervalSeconds?: number | undefined;
+    };
+    expires: string;
+    expired: boolean;
+})[]>;
+/** System-prompt note for the owner session; empty when no unexpired grant exists. */
+export declare function standingGrantNote(grants: StandingGrant[], now: number): string;

package/dist/native-standing-grants.js

@@ -0,0 +1,226 @@
+import { lstat, mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+const HOUR = 3_600_000, DAY = 24 * HOUR;
+export function capRefusal(grant, stamps, now) {
+    const day = stamps.filter(t => t > now - DAY && t <= now);
+    if (day.length >= grant.caps.perDay)
+        return 'per_day';
+    if (grant.caps.perHour !== undefined && day.filter(t => t > now - HOUR).length >= grant.caps.perHour)
+        return 'per_hour';
+    if (grant.caps.minIntervalSeconds !== undefined && day.some(t => t > now - grant.caps.minIntervalSeconds * 1000))
+        return 'min_interval';
+    return undefined;
+}
+const prune = (usage, now) => {
+    const out = {};
+    for (const [id, stamps] of Object.entries(usage)) {
+        const kept = stamps.filter(t => t > now - DAY).sort((a, b) => a - b).slice(-200);
+        if (kept.length)
+            out[id] = kept;
+    }
+    return out;
+};
+function parseUsage(text) {
+    const value = JSON.parse(text);
+    if (!value || value.schema !== 1 || typeof value.usage !== 'object' || value.usage === null || Array.isArray(value.usage))
+        throw Error('kit_standing_grants_store_invalid');
+    const out = {};
+    for (const [id, stamps] of Object.entries(value.usage)) {
+        if (!/^[a-z0-9][a-z0-9-]{1,47}$/.test(id) || !Array.isArray(stamps) || !stamps.every(t => Number.isFinite(t)))
+            throw Error('kit_standing_grants_store_invalid');
+        out[id] = stamps;
+    }
+    return out;
+}
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+/** Persistent store at `file`, or an in-memory store when `file` is undefined (harness-only tests). */
+export function standingGrantStore(path, options = {}) {
+    const now = options.now ?? Date.now, lockTimeout = options.lockTimeoutMs ?? 3000, stale = options.staleLockMs ?? 30_000;
+    if (!path) {
+        const memory = {};
+        return { now, async usage() { return prune(memory, now()); },
+            async consume(grant) { const t = now(), stamps = memory[grant.id] ?? [], why = capRefusal(grant, stamps, t); if (why)
+                return { ok: false, reason: why }; memory[grant.id] = [...stamps.filter(s => s > t - DAY), t]; return { ok: true }; } };
+    }
+    const file = path, lock = file + '.lock';
+    // In-process serialisation keeps same-process callers from contending on the lock file.
+    let chain = Promise.resolve();
+    const read = async () => {
+        try {
+            const s = await lstat(file);
+            if (!s.isFile() || s.isSymbolicLink())
+                throw Error('kit_standing_grants_store_unsafe');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return {};
+            throw e;
+        }
+        return parseUsage(await readFile(file, 'utf8'));
+    };
+    async function acquire() {
+        const deadline = Date.now() + lockTimeout;
+        await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+        for (;;) {
+            try {
+                const h = await open(lock, 'wx', 0o600);
+                await h.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() }));
+                await h.close();
+                return true;
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    return false;
+            }
+            try {
+                if (Date.now() - (await stat(lock)).mtimeMs > stale)
+                    await unlink(lock).catch(() => { });
+            }
+            catch { }
+            if (Date.now() > deadline)
+                return false;
+            await sleep(15 + Math.random() * 20);
+        }
+    }
+    async function locked(fn, busy) {
+        const run = chain.then(async () => {
+            try {
+                if (!await acquire())
+                    return busy;
+            }
+            catch {
+                return busy;
+            }
+            try {
+                return await fn();
+            }
+            catch {
+                return busy;
+            }
+            finally {
+                await unlink(lock).catch(() => { });
+            }
+        });
+        chain = run;
+        return run;
+    }
+    return {
+        now,
+        async usage() { try {
+            return prune(await read(), now());
+        }
+        catch {
+            return undefined;
+        } },
+        consume(grant) {
+            return locked(async () => {
+                let usage;
+                try {
+                    usage = await read();
+                }
+                catch {
+                    return { ok: false, reason: 'store_unavailable' };
+                }
+                const t = now();
+                usage = prune(usage, t);
+                const why = capRefusal(grant, usage[grant.id] ?? [], t);
+                if (why)
+                    return { ok: false, reason: why };
+                usage[grant.id] = [...(usage[grant.id] ?? []), t];
+                const tmp = file + '.' + randomUUID();
+                try {
+                    await writeFile(tmp, JSON.stringify({ schema: 1, usage }) + '\n', { flag: 'wx', mode: 0o600 });
+                    await rename(tmp, file);
+                }
+                catch {
+                    await unlink(tmp).catch(() => { });
+                    return { ok: false, reason: 'store_unavailable' };
+                }
+                return { ok: true };
+            }, { ok: false, reason: 'store_unavailable' });
+        },
+    };
+}
+const norm = (op) => op.replaceAll('.', '_');
+const globMatch = (pattern, value, ci) => {
+    const re = new RegExp('^' + pattern.split('*').map(p => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', ci ? 'is' : 's');
+    return re.test(value);
+};
+const anyGlob = (patterns, value, ci) => value !== undefined && (Array.isArray(patterns) ? patterns : [patterns]).some(p => globMatch(p, value, ci));
+export const grantExpired = (grant, now) => !(Date.parse(grant.expires) > now);
+/**
+ * Finds the first configured grant (in order) that covers this approval-gated call and still has capacity,
+ * and records its use. Returns undefined when the normal payload approval must run.
+ */
+export async function standingGrantFor(ctx, call) {
+    const { profile, store } = ctx, { name, input } = call;
+    if (!profile.standingGrants.length || name !== 'mcp__tealbrick__tealbrick_call' || typeof input.operation !== 'string' || typeof input.registrationId !== 'string')
+        return undefined;
+    const op = norm(input.operation), registrationId = input.registrationId, child = call.agentId !== undefined;
+    let ref, resolved = false;
+    const resolve = async () => { if (!resolved) {
+        resolved = true;
+        try {
+            ref = await ctx.resolveApp?.(registrationId);
+        }
+        catch {
+            ref = undefined;
+        }
+    } return ref; };
+    const body = JSON.stringify(input.input ?? null).toLowerCase();
+    for (const grant of profile.standingGrants) {
+        if (norm(grant.operation) !== op)
+            continue;
+        if (child && !(call.agentType !== undefined && grant.experts?.includes(call.agentType) && Object.hasOwn(profile.contracts, call.agentType)))
+            continue;
+        const m = grant.match;
+        if (m.registrationId !== undefined && !globMatch(m.registrationId, registrationId, false))
+            continue;
+        if (m.plugin !== undefined || m.action !== undefined) {
+            const r = await resolve();
+            if (!r || r.plugin === undefined || r.action === undefined)
+                continue;
+            if (m.plugin !== undefined && !anyGlob(m.plugin, r.plugin, true))
+                continue;
+            if (m.action !== undefined && !anyGlob(m.action, r.action, true))
+                continue;
+        }
+        if (grant.deny?.inputPattern?.some(p => body.includes(p.toLowerCase()))) {
+            ctx.trace({ event: 'standing_grant.skipped', grantId: grant.id, reason: 'deny_pattern', operation: input.operation, registrationId });
+            continue;
+        }
+        if (grantExpired(grant, store.now())) {
+            ctx.trace({ event: 'standing_grant.exhausted', grantId: grant.id, reason: 'expired', operation: input.operation, registrationId });
+            continue;
+        }
+        const used = await store.consume(grant);
+        if (!used.ok) {
+            ctx.trace({ event: 'standing_grant.exhausted', grantId: grant.id, reason: used.reason, operation: input.operation, registrationId });
+            continue;
+        }
+        return { grant, ...(ref ? { ref } : {}) };
+    }
+    return undefined;
+}
+/** Owner-facing audit view: no deny patterns or inputs, only identifiers, caps, expiry and remaining uses. */
+export async function standingGrantSummary(grants, store) {
+    const usage = await store.usage(), now = store.now();
+    return grants.map(g => {
+        const stamps = (usage?.[g.id] ?? []).filter(t => t > now - DAY && t <= now), hour = stamps.filter(t => t > now - HOUR).length;
+        return { id: g.id, description: g.description, operation: g.operation, match: g.match, experts: [...(g.experts ?? [])], caps: g.caps, expires: g.expires,
+            expired: grantExpired(g, now), ...(usage ? { usedToday: stamps.length, remainingToday: Math.max(0, g.caps.perDay - stamps.length),
+                ...(g.caps.perHour !== undefined ? { remainingThisHour: Math.max(0, g.caps.perHour - hour) } : {}) } : { usage: 'unavailable' }),
+            denyPatterns: g.deny?.inputPattern?.length ?? 0 };
+    });
+}
+/** System-prompt note for the owner session; empty when no unexpired grant exists. */
+export function standingGrantNote(grants, now) {
+    const live = grants.filter(g => !grantExpired(g, now));
+    if (!live.length)
+        return '';
+    const caps = (g) => [`${g.caps.perDay}/day`, ...(g.caps.perHour !== undefined ? [`${g.caps.perHour}/hour`] : []), ...(g.caps.minIntervalSeconds !== undefined ? [`at least ${g.caps.minIntervalSeconds}s apart`] : [])].join(', ');
+    return ['Standing grants: your owner pre-approved these classes of calls; the harness applies them automatically (you do not choose them) within their caps until they expire:',
+        ...live.map(g => `- ${g.id} (${g.operation}): ${g.description} [${caps(g)}; expires ${g.expires}]`),
+        'Anything outside these grants, or beyond their caps, still needs the owner\'s approval of the exact payload. Spending money, contracts or signatures, and first contact with strangers are never covered unless a grant explicitly says so.'].join('\n');
+}

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

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { guidedNativeSetup, nativeSdkConfig } from './native-setup.js';
 import { applyKit, readKit } from './index.js';
-import { loginPortal, portalOrigin } from './onboarding.js';
+import { deviceLabel, loginPortal, portalOrigin } from './onboarding.js';
 import { PortalHttpError } from '@tealbrick/portal';
 import { RuntimeConnector } from '@tealbrick/portal/runtime';
 import { MarketplaceRuntimeConnector } from '@tealbrick/portal/marketplace-runtime';
@@ -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') {
@@ -95,7 +105,7 @@ export async function nativeCommand(args, root) {
         const state = await readKit(root);
         if (!state.native || !state.runtime)
             throw Error('kit_native_setup_required');
-        const login = await loginPortal(portalOrigin(state.runtime.issuer), (url, code) => console.error(`Approve Tealbrick endpoint registration: ${url}\nCode: ${code}`));
+        const login = await loginPortal(portalOrigin(state.runtime.issuer), (url, code) => console.error(`Approve Tealbrick endpoint registration: ${url}\nCode: ${code}`), { label: deviceLabel('native enroll', root) });
         try {
             const result = await enrollNative(root, { url: flags.url, ...(typeof flags.port === 'string' ? { port: Number(flags.port) } : {}) }, login, { verifyEndpoint: !flags['skip-endpoint-check'] });
             console.log(JSON.stringify(result));
@@ -138,7 +148,7 @@ export async function nativeCommand(args, root) {
             flags.delegation = 'disabled';
         }
         const issuer = portalOrigin(flags.issuer ?? 'https://portal.tealbrick.com');
-        const login = await loginPortal(issuer, (url, code) => console.error(`Approve Tealbrick setup: ${url}\nCode: ${code}`));
+        const login = await loginPortal(issuer, (url, code) => console.error(`Approve Tealbrick setup: ${url}\nCode: ${code}`), { label: deviceLabel(`native setup (${flags.harness})`, root) });
         const { select, input } = await import('@inquirer/prompts');
         try {
             console.log(JSON.stringify(await guidedNativeSetup(root, flags, login, { choose: (message, choices) => select({ message, choices }), name: message => input({ message }) })));

package/dist/onboarding.d.ts

@@ -18,10 +18,13 @@ export interface PortalLogin {
 export declare function portalOrigin(value: string): string;
 export declare function agentOrigin(value: string): string;
 /** Device authorization is interactive; user/refresh tokens never enter kit state. */
+/** Label shown in Portal → Connected access: purpose, host and kit folder, so owners can tell devices apart (portal-core#15). */
+export declare function deviceLabel(purpose: string, root?: string, host?: string): string;
 export declare function loginPortal(issuer: string, show: (url: string, code: string) => void, options?: {
     fetch?: typeof fetch;
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
+    label?: string;
 }): Promise<PortalLogin>;
 /** Reuse Portal's owned registration + revision-checked canvas APIs, not a parallel card store. */
 export declare function registerPortalCard(login: PortalLogin, input: {

package/dist/onboarding.js

@@ -1,4 +1,6 @@
 import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { basename } from 'node:path';
 import { PortalClient, PortalHttpError } from '@tealbrick/portal';
 /** Reject URLs that would leak credentials or be silently truncated by registration. */
 export function portalOrigin(value) {
@@ -14,10 +16,15 @@ export function agentOrigin(value) {
     return url.origin;
 }
 /** Device authorization is interactive; user/refresh tokens never enter kit state. */
+/** Label shown in Portal → Connected access: purpose, host and kit folder, so owners can tell devices apart (portal-core#15). */
+export function deviceLabel(purpose, root = process.cwd(), host = hostname()) {
+    const folder = basename(root) || root;
+    return `Teal Brick ${purpose} · ${host.replace(/\.local$/, '')} · ${folder}`.replace(/[\u0000-\u001f]/g, '').slice(0, 120);
+}
 export async function loginPortal(issuer, show, options = {}) {
     issuer = portalOrigin(issuer);
     const client = new PortalClient({ issuer, fetch: options.fetch });
-    const device = await client.startDevice({ deviceId: randomUUID(), deviceLabel: 'Teal Brick package setup' });
+    const device = await client.startDevice({ deviceId: randomUUID(), deviceLabel: options.label ?? deviceLabel('setup') });
     const verification = new URL(device.verification_uri_complete);
     if (verification.origin !== issuer || verification.username || verification.password)
         throw Error('kit_portal_verification_origin_mismatch');

package/dist/runtime-onboarding.js

@@ -1,6 +1,6 @@
 import { password } from '@inquirer/prompts';
 import { createHash } from 'node:crypto';
-import { loginPortal, portalOrigin } from './onboarding.js';
+import { deviceLabel, loginPortal, portalOrigin } from './onboarding.js';
 import { readKit, applyKit } from './index.js';
 function flags(args) { const out = {}; for (let i = 0; i < args.length; i += 2) {
     if (!/^--[a-z]+$/.test(args[i]) || !args[i + 1] || args[i + 1].startsWith('--'))
@@ -37,7 +37,7 @@ finally {
 export async function runtimeOnboarding(command, args, root) {
     const f = flags(args), old = await readKit(root), issuer = portalOrigin(f.issuer ?? old.portal?.issuer ?? 'https://portal.tealbrick.com');
     const workspaceId = required(f, 'workspace'), nodeId = required(f, 'node');
-    const login = await loginPortal(issuer, (url, code) => console.log(`Approve this customer runtime in Portal: ${url}\nCode: ${code}`));
+    const login = await loginPortal(issuer, (url, code) => console.log(`Approve this customer runtime in Portal: ${url}\nCode: ${code}`), { label: deviceLabel(`runtime ${command}`, root) });
     if (!login.workspaces.some(w => w.id === workspaceId))
         throw Error('kit_portal_workspace_required');
     if (command === 'connect') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/kit",
-  "version": "0.3.0-rc.7",
+  "version": "0.3.0-rc.9",
   "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.7",
-    "@tealbrick/avm": "0.3.0-rc.7",
-    "@tealbrick/voice": "0.3.0-rc.7",
-    "@tealbrick/vision": "0.3.0-rc.7",
-    "@tealbrick/deliver": "0.3.0-rc.7",
+    "@tealbrick/portal": "0.3.0-rc.9",
+    "@tealbrick/avm": "0.3.0-rc.9",
+    "@tealbrick/voice": "0.3.0-rc.9",
+    "@tealbrick/vision": "0.3.0-rc.9",
+    "@tealbrick/deliver": "0.3.0-rc.9",
     "@inquirer/prompts": "8.7.2",
     "zod": "^4.0.0"
   },