@tealbrick/kit 0.2.7 → 0.3.0-rc.10

package/dist/native-setup.js

@@ -0,0 +1,122 @@
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, lstat, readFile, writeFile, rename, unlink, realpath } from 'node:fs/promises';
+import { PortalHttpError } from '@tealbrick/portal';
+import { readKit } from './index.js';
+import { selectNativeIdentity, harnessLabels } from './native-selection.js';
+import { setupNative } from './native.js';
+export function nativeSdkConfig(harness, root, options = {}) {
+    if (harness === 'codex' && !options.codexDelegationDisabled)
+        throw Error('kit_native_codex_delegation_opt_in_required');
+    const server = { command: process.execPath, args: [fileURLToPath(new URL('./cli.js', import.meta.url)), 'native', 'mcp', '--root', resolve(root)] };
+    return harness === 'codex' ? { config: { features: { multi_agent: false, multi_agent_v2: false }, mcp_servers: { tealbrick: server } } } : harness === 'langchain' ? { servers: { tealbrick: server } } : { settings: { hooks: { PreToolUse: [{ matcher: 'mcp__tealbrick__.*', hooks: [{ type: 'command', command: process.execPath, args: [fileURLToPath(new URL('./native-child-guard.js', import.meta.url))] }] }] } }, mcpServers: { tealbrick: server } };
+}
+/** Private setup journal stores only identity intent, never account/runtime credentials. */
+export async function guidedNativeSetup(root, flags, login, prompts) {
+    root = await realpath(root);
+    const dir = join(root, '.tealbrick');
+    try {
+        if ((await lstat(dir)).isSymbolicLink())
+            throw Error('kit_symlink_path');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const paths = ['native-setup.json', 'native-setup.lock', 'native-sdk.json'].map(name => join(dir, name));
+    for (const path of paths) {
+        try {
+            if ((await lstat(path)).isSymbolicLink())
+                throw Error('kit_symlink_path');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+    const [journalPath, lockPath, configPath] = paths;
+    try {
+        await writeFile(lockPath, String(process.pid), { flag: 'wx', mode: 0o600 });
+    }
+    catch (e) {
+        if (e.code === 'EEXIST')
+            throw Error('kit_native_setup_locked');
+        throw e;
+    }
+    try {
+        const harness = flags.harness;
+        if (harness === 'codex' && flags.delegation !== 'disabled')
+            throw Error('kit_native_codex_delegation_opt_in_required');
+        if (!Object.hasOwn(harnessLabels, harness))
+            throw Error('kit_native_harness_required');
+        const old = await readKit(root);
+        if (old.runtime && (old.runtime.issuer !== login.issuer || old.runtime.org !== login.org) || old.native && old.native.harness !== harness)
+            throw Error('kit_runtime_existing_binding_mismatch');
+        if (old.portal || old.voice || old.vision || old.deliver !== undefined || old.avm || old.routines || old.selfEvolution || old.runtime && !old.native)
+            throw Error('kit_native_eve_configuration_conflict');
+        let journal;
+        try {
+            journal = JSON.parse(await readFile(journalPath, 'utf8'));
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        const stamp = { issuer: login.issuer, org: login.org, userId: login.userId, harness };
+        if (journal && JSON.stringify(journal.stamp) !== JSON.stringify(stamp))
+            throw Error('kit_native_setup_account_mismatch');
+        let request = journal?.status !== 'rejected' ? journal?.request : undefined;
+        let resuming = !!request;
+        let selectionFlags = { ...flags };
+        if (request) {
+            // A prior POST may already have created the identity. Reconcile that exact key first.
+            const mismatched = (flags.agent && request.agent.id !== flags.agent) || (flags['create-agent'] && request.agent.mode === 'create' && request.agent.name !== flags['create-agent'].trim()) || (flags.workspace && request.workspace.id !== flags.workspace) || (flags['create-workspace'] && request.workspace.name !== flags['create-workspace'].trim());
+            if (mismatched)
+                throw Error('kit_native_setup_pending_intent_mismatch');
+        }
+        const saveJournal = async (status) => { const tmp = journalPath + '.' + randomUUID(); await writeFile(tmp, JSON.stringify({ version: 1, stamp, request, status }) + '\n', { flag: 'wx', mode: 0o600 }); await rename(tmp, journalPath); };
+        let prepared;
+        for (let attempt = 0;; attempt++) {
+            if (!request) {
+                const chosen = await selectNativeIdentity(root, selectionFlags, login, prompts);
+                const agent = 'id' in chosen.agent ? { mode: 'attach', id: chosen.agent.id, harness: harnessLabels[harness] } : { mode: 'create', name: chosen.agent.name, harness: harnessLabels[harness] };
+                if (old.runtime && (!('id' in chosen.workspace) || chosen.workspace.id !== old.runtime.workspaceId || !('id' in chosen.agent) || chosen.agent.id !== old.runtime.agentId))
+                    throw Error('kit_runtime_existing_binding_mismatch');
+                request = { workspace: chosen.workspace, agent, idempotencyKey: randomUUID() };
+                await saveJournal('pending');
+            }
+            try {
+                prepared = await login.client.request('/api/runtime/setup', request);
+                break;
+            }
+            catch (error) {
+                // This exact Portal error occurs before workspace/agent mutation. Other failures
+                // retain the pending request, including timeouts, lost responses and HTTP 5xx.
+                if (!(error instanceof PortalHttpError) || error.status !== 409 || error.code !== 'agent_name_exists_select_existing' || attempt >= 3 || request.agent.mode !== 'create')
+                    throw error;
+                await saveJournal('rejected');
+                resuming = false;
+                selectionFlags = { harness, ...(request.workspace.id ? { workspace: request.workspace.id } : { 'create-workspace': request.workspace.name }), 'create-agent': request.agent.name };
+                request = undefined;
+            }
+        }
+        if (!prepared.workspace?.id || !prepared.agent?.id || !prepared.nodeId || prepared.agent.harness !== harnessLabels[harness])
+            throw Error('kit_native_setup_response_invalid');
+        if (resuming && ((flags['create-agent'] && prepared.agent.name !== flags['create-agent'].trim()) || (flags['agent-name'] && prepared.agent.name !== flags['agent-name']) || (flags['workspace-name'] && prepared.workspace.name !== flags['workspace-name'])))
+            throw Error('kit_native_setup_pending_intent_mismatch');
+        if (flags.node && flags.node !== prepared.nodeId)
+            throw Error('kit_owned_agent_card_required');
+        await saveJournal('prepared');
+        const authenticated = { ...login, workspaces: [...login.workspaces.filter(w => w.id !== prepared.workspace.id), prepared.workspace] };
+        const result = await setupNative(root, { harness, workspaceId: prepared.workspace.id, nodeId: prepared.nodeId, agentId: prepared.agent.id }, authenticated);
+        const tmp = configPath + '.' + randomUUID();
+        await writeFile(tmp, JSON.stringify(nativeSdkConfig(harness, root, { codexDelegationDisabled: flags.delegation === 'disabled' }), null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        await rename(tmp, configPath);
+        return { ...result, workspaceId: prepared.workspace.id, nodeId: prepared.nodeId, configPath };
+    }
+    finally {
+        await unlink(lockPath);
+    }
+}

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

@@ -0,0 +1,42 @@
+import { guidedNativeSetup, nativeSdkConfig } from './native-setup.js';
+import { type PortalLogin } from './onboarding.js';
+import { type KnowledgeOperation } from '@tealbrick/portal/runtime';
+import { MarketplaceRuntimeConnector } from '@tealbrick/portal/marketplace-runtime';
+declare const harnesses: {
+    readonly claude: "Claude Agent SDK";
+    readonly codex: "Codex";
+    readonly langchain: "LangChain";
+};
+export type NativeHarness = keyof typeof harnesses;
+/** Enroll an existing, accurately labelled owned card. Registration belongs to Portal. */
+export declare function setupNative(root: string, input: {
+    harness: NativeHarness;
+    workspaceId: string;
+    nodeId: string;
+    agentId: string;
+}, login: PortalLogin): Promise<{
+    connected: boolean;
+    agentId: string;
+    connectionId: string;
+    harness: "claude" | "codex" | "langchain";
+}>;
+/** A fresh connector per invocation rechecks Portal and local activation. No authorization cache
+ * survives MCP reconnect, local deactivation or a request boundary. No session is created here. */
+export declare function nativeConnector(): {
+    marketplace: () => Promise<MarketplaceRuntimeConnector | undefined>;
+    capabilities: () => Promise<{
+        revision: string;
+        expiresAt: number;
+        apps: {
+            registrationId: string;
+            appId: "knowledge";
+            actions: import("@tealbrick/portal/runtime").CrudAction[];
+            available: boolean;
+            operations: KnowledgeOperation[];
+        }[];
+    }>;
+    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 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 };