@vendoai/vendo 0.4.0

package/dist/auth-presets/supabase.js

@@ -0,0 +1,229 @@
+import { supabasePreset, verifyHs256 } from "@vendoai/actions/presets";
+import { environment } from "../wire/shared.js";
+import { actAsClaimsFromUser, bearerToken, claimString, composeHostAuthPreset, lazyActAs, lazyModule, loginRedirect, makeUserResolver, requestCookies, resolvePresetSecret, } from "./identity.js";
+const MISSING_VERIFIER_MESSAGE = "supabase() has no way to verify sessions: set SUPABASE_JWT_SECRET (the project's legacy JWT signing secret — verifies HS256 access tokens offline; the same one supabasePreset mints with, never the anon key) and/or SUPABASE_URL (the project URL — ES256 logins verify against its GoTrue JWKS at /auth/v1/.well-known/jwks.json), or pass supabase({ secret }) / supabase({ jwks }).";
+/** Same optional-dependency strategy as auth0's jose: ES256 login tokens
+    (Supabase's newer signing keys) verify against GoTrue's JWKS through jose,
+    an optional peerDependency loaded lazily on first use. HS256-only hosts
+    never hit this path and need nothing installed. */
+const MISSING_JOSE_MESSAGE = "supabase() verifies ES256 Supabase session tokens through jose, which is not installed. Install it next to your Supabase setup: npm install jose";
+const loadJose = lazyModule(() => import("jose").then((module) => module), MISSING_JOSE_MESSAGE);
+/** jose's remote JWKS resolvers cache fetched keys per instance — keep one per
+    URL so verification never refetches per request (auth0's pattern). */
+const jwksByUrl = new Map();
+function remoteJwks(jose, url) {
+    let jwks = jwksByUrl.get(url);
+    if (jwks === undefined) {
+        jwks = jose.createRemoteJWKSet(new URL(url));
+        jwksByUrl.set(url, jwks);
+    }
+    return jwks;
+}
+/** Supabase's auth cookie: `sb-<project-ref>-auth-token`, optionally chunked
+    across `.0`, `.1`, ... suffixes by @supabase/ssr. */
+const SUPABASE_AUTH_COOKIE = /^(sb-.+-auth-token)(?:\.(\d+))?$/;
+/** A compact JWS: three non-empty base64url segments. */
+const RAW_JWT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+function decodeBase64Url(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value) || value.length % 4 === 1)
+        return undefined;
+    const padding = "=".repeat((4 - (value.length % 4)) % 4);
+    try {
+        const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + padding);
+        return new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0)));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Extract the access token from a reassembled cookie value. Four shapes ship
+    in the wild: @supabase/ssr's `base64-` + base64url(JSON session), the
+    legacy plain-JSON session object / `[access_token, ...]` array, and the
+    raw access token itself (hand-rolled hosts, the old auth-helpers). */
+function accessTokenFrom(value) {
+    if (RAW_JWT.test(value))
+        return value;
+    const raw = value.startsWith("base64-") ? decodeBase64Url(value.slice("base64-".length)) : value;
+    if (raw === undefined)
+        return undefined;
+    let session;
+    try {
+        session = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (Array.isArray(session)) {
+        const token = session[0];
+        return typeof token === "string" && token.length > 0 ? token : undefined;
+    }
+    if (session !== null && typeof session === "object") {
+        const token = session.access_token;
+        return typeof token === "string" && token.length > 0 ? token : undefined;
+    }
+    return undefined;
+}
+/** The session token off a plain Request, per Supabase's own conventions:
+    `Authorization: Bearer <access token>` (how Supabase clients call the API —
+    and what the actAs half mints), else the `sb-*-auth-token` cookie with its
+    chunks reassembled in order. */
+function sessionTokenFrom(request) {
+    const fromHeader = bearerToken(request);
+    if (fromHeader !== undefined)
+        return fromHeader;
+    const chunks = new Map();
+    for (const [name, value] of requestCookies(request)) {
+        const match = SUPABASE_AUTH_COOKIE.exec(name);
+        if (match === null)
+            continue;
+        const base = match[1];
+        const parts = chunks.get(base) ?? [];
+        parts.push({ index: match[2] === undefined ? 0 : Number(match[2]), value });
+        chunks.set(base, parts);
+    }
+    for (const parts of chunks.values()) {
+        const joined = parts.sort((left, right) => left.index - right.index).map((part) => part.value).join("");
+        const token = accessTokenFrom(joined);
+        if (token !== undefined)
+            return token;
+    }
+    return undefined;
+}
+/** The token's protected-header `alg`, decoded without verification — only to
+    route the token to the verifier that can possibly accept it. */
+function tokenAlg(token) {
+    const header = decodeBase64Url(token.split(".")[0] ?? "");
+    if (header === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(header);
+        return parsed !== null && typeof parsed === "object" && typeof parsed.alg === "string"
+            ? parsed.alg
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** GoTrue's JWKS URL: the `jwks` option (thunks resolved per call), else
+    SUPABASE_URL's well-known path. */
+function jwksUrlFrom(jwks) {
+    const resolved = typeof jwks === "function" ? jwks() : jwks;
+    if (resolved !== undefined)
+        return resolved.toString();
+    const projectUrl = environment("SUPABASE_URL");
+    if (projectUrl === undefined)
+        return undefined;
+    try {
+        return new URL("/auth/v1/.well-known/jwks.json", projectUrl).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Supabase's claims→user defaults: identity lives in `user_metadata`
+    (name/full_name) with the email as a top-level claim. */
+function supabaseUser(claims) {
+    const metadata = claims["user_metadata"];
+    const metadataClaims = metadata !== null && typeof metadata === "object" && !Array.isArray(metadata)
+        ? metadata
+        : {};
+    const email = claimString(claims, "email");
+    const display = claimString(metadataClaims, "name")
+        ?? claimString(metadataClaims, "full_name")
+        ?? claimString(claims, "name")
+        ?? email;
+    return {
+        ...(display === undefined ? {} : { display }),
+        ...(email === undefined ? {} : { email }),
+    };
+}
+/**
+ * 09-vendo §2.1 — the Supabase Auth host-identity preset. Zero-argument in
+ * the standard case: it reads Supabase's own env, the session resolves off a
+ * plain Request per Supabase's own formats (Authorization: Bearer, or the
+ * `sb-*-auth-token` cookie — @supabase/ssr's `base64-`/chunked shape, the
+ * legacy JSON shapes, and the raw access token), and display derives from
+ * user_metadata.name/full_name/email. The optional subject→user resolver has
+ * the same semantics as authJs (null = subject unknown → decline/null).
+ *
+ * Session verification is Supabase's documented HYBRID (the same one a
+ * project with JWT signing keys needs), routed by the token's own `alg`:
+ *
+ * 1. HS256 first — the project's legacy JWT secret (SUPABASE_JWT_SECRET or
+ *    `secret`), verified OFFLINE through the SAME shared `verifyHs256` the
+ *    minting half targets: no network, no optional SDK, and every actAs-minted
+ *    away token stays verifiable with no Supabase stack running.
+ * 2. ES256 fallback — what `supabase start` ≥ v2.71 and hosted projects on
+ *    the new key system sign interactive logins with, verified against
+ *    GoTrue's JWKS (SUPABASE_URL → /auth/v1/.well-known/jwks.json, or the
+ *    `jwks` option) through a lazily-imported jose (optional peer, cached
+ *    remote key set per URL).
+ *
+ * Both paths enforce Supabase's `authenticated` audience, which is also what
+ * keeps the project's API keys (anon/service_role — HS256 JWTs under the same
+ * secret, but without that audience) from ever counting as a signed-in user.
+ * Tokens neither path can verify resolve to null (no session); construction
+ * with NEITHER a secret NOR a JWKS source fails loud, naming both.
+ *
+ * The actAs half IS the shipped `@vendoai/actions/presets` supabasePreset —
+ * one minting story (04 §2.1), configured from these same options. Tokens
+ * mint (and verify) under Supabase's `authenticated` audience convention.
+ */
+export function supabase(options = {}) {
+    const { secret, user, jwks } = options;
+    const sessionClaims = async (request) => {
+        const token = sessionTokenFrom(request);
+        if (token === undefined)
+            return null;
+        const jwtSecret = secret === undefined && environment("SUPABASE_JWT_SECRET") === undefined
+            ? undefined
+            : await resolvePresetSecret(secret, "SUPABASE_JWT_SECRET", MISSING_VERIFIER_MESSAGE);
+        const jwksUrl = jwksUrlFrom(jwks);
+        if (jwtSecret === undefined && jwksUrl === undefined) {
+            throw new Error(MISSING_VERIFIER_MESSAGE);
+        }
+        const alg = tokenAlg(token);
+        // HS256 first: offline, no network — and the only path a JWKS could never
+        // serve. ES256 is the fallback for logins under the newer signing keys.
+        if (alg === "HS256" && jwtSecret !== undefined) {
+            try {
+                return (await verifyHs256(token, jwtSecret, { audience: "authenticated" })).payload;
+            }
+            catch {
+                return null; // unverifiable/expired/foreign token = no session
+            }
+        }
+        if (alg === "ES256" && jwksUrl !== undefined) {
+            const jose = await loadJose();
+            try {
+                const { payload } = await jose.jwtVerify(token, remoteJwks(jose, jwksUrl), {
+                    audience: "authenticated",
+                    algorithms: ["ES256"],
+                });
+                return payload;
+            }
+            catch {
+                return null; // unverifiable/expired/foreign token = no session
+            }
+        }
+        return null; // an alg (or config) neither verifier serves = no session
+    };
+    return composeHostAuthPreset({
+        sessionClaims,
+        resolveUser: makeUserResolver(user, supabaseUser),
+        // Away + MCP execution: the shipped Supabase minting preset (04 §2.1),
+        // fed the same secret and identity this preset resolves sessions with —
+        // user identity rides the token as Supabase's own claim shape.
+        actAs: lazyActAs(() => supabasePreset({
+            ...(secret === undefined ? {} : { secret }),
+            ...(user === undefined ? {} : {
+                claims: actAsClaimsFromUser(user, (resolved) => ({
+                    ...(resolved.email === undefined ? {} : { email: resolved.email }),
+                    ...(resolved.display === undefined ? {} : { user_metadata: { name: resolved.display } }),
+                })),
+            }),
+        })),
+        login: (request, returnTo) => loginRedirect(request, returnTo),
+    });
+}

package/dist/byo-approvals.d.ts

@@ -0,0 +1,37 @@
+import { type ApprovalRequest, type Principal, type StoreAdapter, type ToolOutcome, type ToolRegistry } from "@vendoai/core";
+import type { VendoGuard } from "@vendoai/guard";
+/** The wire's answer to `GET /approvals/:id` — the frozen
+ *  `VendoApprovalEmbedState` vocabulary, plus what each state needs to render:
+ *  the full request while pending (the consent card shows real inputs), the
+ *  executed outcome after resume. */
+export type ByoApprovalResolution = {
+    state: "pending";
+    request: ApprovalRequest;
+} | {
+    state: "executed";
+    outcome: ToolOutcome;
+} | {
+    state: "declined";
+} | {
+    state: "expired";
+};
+export interface ByoApprovals {
+    /** The guard-bound registry with approval parking — the registry the BYO
+     *  tool pack executes through. Same decisions, same audit; the only
+     *  addition is the parked record behind a `pending-approval` outcome. */
+    registry: ToolRegistry;
+    /** Resolve one approval's state for its owner; not-found for unknown or
+     *  foreign ids (indistinguishable on purpose). */
+    read(approvalId: string, principal: Principal): Promise<ByoApprovalResolution>;
+    /** Deny every parked call idle past `ttlMs` through the existing
+     *  abandonment path. No-op when `ttlMs` is 0 or negative. */
+    sweepExpired(ttlMs: number, now?: number): Promise<void>;
+}
+export interface ByoApprovalsConfig {
+    guard: VendoGuard;
+    /** The guard-bound registry (the SAME binding chat, apps, and automations
+     *  execute through) — both the parked call and its resume dispatch ride it. */
+    tools: ToolRegistry;
+    store: StoreAdapter;
+}
+export declare function createByoApprovals({ guard, tools, store }: ByoApprovalsConfig): ByoApprovals;

package/dist/byo-approvals.js

@@ -0,0 +1,189 @@
+import { VendoError, } from "@vendoai/core";
+/**
+ * Existing-agents Lane B — parked guarded calls with NO Vendo thread and NO app.
+ *
+ * A `vendo_*` pack tool executing in a BYO agent loop returns the
+ * `vendo/approval-ref@1` envelope the instant the guard answers
+ * `pending-approval` — no throw, no block. But nothing in the host's loop ever
+ * re-dispatches the call: the thread resume path (`data-vendo-approval` stream
+ * parts) needs Vendo's conversation, and the apps runtime's `ParkedAction`
+ * pins an `appId` and lives with the app. This seam is the venue-neutral
+ * third venue, riding the same three existing mechanisms end to end:
+ *
+ * - PARK: the {@link ByoApprovals.registry} decorator records the EXACT call
+ *   (guard-minted id, tool, args) plus its `RunContext` when a guarded execute
+ *   returns `pending-approval` — the same shape as `ParkedAction`, minus the
+ *   app pin.
+ * - RESUME: an umbrella-level `guard.onApprovalDecision` subscriber (the SAME
+ *   seam the apps runtime and automations ride) re-dispatches the parked call
+ *   byte-for-byte through the guard-bound registry on approve — the guard's
+ *   one-shot approved replay pins subject, call id, args hash, descriptor
+ *   hash, venue, presence, and appId, so the stored ctx is reused verbatim.
+ *   Deny clears the record and never executes (fail closed).
+ * - EXPIRE: {@link ByoApprovals.sweepExpired} denies parked calls older than
+ *   the TTL through the existing abandonment path (`guard.abandonApprovals`
+ *   semantics: deny + clear, idempotent) — a new trigger, not new semantics.
+ *
+ * The resume outcome persists keyed by approvalId so the wire can answer
+ * "what happened to apr_x?" for `<VendoApprovalEmbed>` — in-thread that answer
+ * rides the thread stream; there is no thread here.
+ */
+const PARKED_COLLECTION = "vendo_parked_call";
+const OUTCOME_COLLECTION = "vendo_parked_call_outcome";
+function now() {
+    return new Date().toISOString();
+}
+function cloneJson(value) {
+    return globalThis.structuredClone(value);
+}
+async function listAll(store) {
+    const records = [];
+    let cursor;
+    do {
+        const page = await store.list({ ...(cursor === undefined ? {} : { cursor }) });
+        records.push(...page.records);
+        if (page.cursor === undefined || page.cursor === cursor)
+            break;
+        cursor = page.cursor;
+    } while (cursor !== undefined);
+    return records;
+}
+export function createByoApprovals({ guard, tools, store }) {
+    const parked = store.records(PARKED_COLLECTION);
+    const outcomes = store.records(OUTCOME_COLLECTION);
+    const putParked = async (record) => {
+        await parked.put({
+            id: record.approvalId,
+            data: record,
+            refs: { subject: record.owner, approval: record.approvalId },
+        });
+    };
+    const putOutcome = async (record) => {
+        await outcomes.put({
+            id: record.approvalId,
+            data: record,
+            refs: { subject: record.owner, state: record.state },
+        });
+    };
+    // RESUME — the decision subscriber. `decide` fires callbacks exactly once
+    // per approval (the pending→decided transition has a single atomic winner)
+    // and awaits them, so the outcome row has one writer and lands before the
+    // decide call returns to the wire.
+    guard.onApprovalDecision(async (approvalId, approved) => {
+        const record = await parked.get(approvalId);
+        if (record === null)
+            return;
+        const data = record.data;
+        try {
+            if (approved) {
+                // Byte-for-byte re-dispatch: the one-shot approved replay executes it;
+                // the guard binding folds a downstream throw into an error outcome.
+                const outcome = await tools.execute(data.call, data.ctx);
+                await putOutcome({ approvalId, owner: data.owner, state: "executed", outcome, at: now() });
+            }
+            else {
+                await putOutcome({
+                    approvalId,
+                    owner: data.owner,
+                    state: data.expiring === true ? "expired" : "declined",
+                    at: now(),
+                });
+            }
+        }
+        finally {
+            // Cleared either way: approve ran it, deny fails closed. A parked record
+            // exists exactly while its approval is undecided.
+            await parked.delete(approvalId);
+        }
+    });
+    // EXPIRE — abandonApprovals is the guard's idempotent deny wrapper (already-
+    // decided and unknown ids already hold the state abandonment wants). Older
+    // Guard implementations may omit the optional method; the fallback applies
+    // the same semantics through the plain decide path.
+    const abandon = async (approvalId, ctx) => {
+        if (guard.abandonApprovals !== undefined) {
+            await guard.abandonApprovals([approvalId], ctx);
+            return;
+        }
+        try {
+            await guard.approvals.decide(approvalId, { approve: false }, ctx.principal);
+        }
+        catch (error) {
+            if (error instanceof VendoError && (error.code === "conflict" || error.code === "not-found"))
+                return;
+            throw error;
+        }
+    };
+    return {
+        registry: {
+            descriptors: () => tools.descriptors(),
+            async execute(call, ctx) {
+                const outcome = await tools.execute(call, ctx);
+                if (outcome.status === "pending-approval") {
+                    // PARK — written right before the pack tool returns the
+                    // vendo/approval-ref@1 envelope to the foreign loop. The request
+                    // snapshot keeps `read` answering "pending" through the resume
+                    // window, after the decision has already left the guard's queue.
+                    const requests = await guard.approvals.pending(ctx.principal);
+                    const request = requests.find((candidate) => candidate.id === outcome.approvalId);
+                    await putParked({
+                        approvalId: outcome.approvalId,
+                        owner: ctx.principal.subject,
+                        call: cloneJson(call),
+                        ctx: cloneJson(ctx),
+                        parkedAt: now(),
+                        ...(request === undefined ? {} : { request: cloneJson(request) }),
+                    });
+                }
+                return outcome;
+            },
+        },
+        async read(approvalId, principal) {
+            const record = await outcomes.get(approvalId);
+            if (record !== null) {
+                const data = record.data;
+                if (data.owner === principal.subject) {
+                    if (data.state === "executed" && data.outcome !== undefined) {
+                        return { state: "executed", outcome: data.outcome };
+                    }
+                    if (data.state === "declined" || data.state === "expired") {
+                        return { state: data.state };
+                    }
+                }
+            }
+            const pending = await guard.approvals.pending(principal);
+            const request = pending.find((candidate) => candidate.id === approvalId);
+            if (request !== undefined)
+                return { state: "pending", request };
+            // Mid-resume window: the decision already left the guard's pending queue
+            // but the subscriber has not written the outcome row yet. The parked
+            // record exists exactly until that write, so serve its request snapshot
+            // as still-pending rather than a terminal not-found (which the embed
+            // renders as expired and stops polling).
+            const stillParked = await parked.get(approvalId);
+            if (stillParked !== null) {
+                const data = stillParked.data;
+                if (data.owner === principal.subject && data.request !== undefined) {
+                    return { state: "pending", request: data.request };
+                }
+            }
+            throw new VendoError("not-found", `Approval ${approvalId} was not found`);
+        },
+        async sweepExpired(ttlMs, at = Date.now()) {
+            if (ttlMs <= 0)
+                return;
+            for (const record of await listAll(parked)) {
+                const data = record.data;
+                const parkedAt = Date.parse(data.parkedAt);
+                if (Number.isFinite(parkedAt) && parkedAt + ttlMs > at)
+                    continue;
+                // Mark first, so the deny lands as "expired" — the subscriber is the
+                // outcome's single writer and reads the flag when the decision fires.
+                // A concurrent user approve that wins the atomic decide still executes
+                // and records "executed"; this abandon then no-ops (conflict).
+                await putParked({ ...data, expiring: true });
+                await abandon(data.approvalId, data.ctx);
+            }
+        },
+    };
+}

package/dist/capability-misses.d.ts

@@ -0,0 +1,38 @@
+import { type CapabilityMissEvent, type RiskLabel, type ToolDescriptor } from "@vendoai/core";
+import { type TelemetryConfig } from "@vendoai/telemetry";
+export interface CapabilitySurfaceSnapshot {
+    hash: string;
+    tools: Array<{
+        name: string;
+        risk: RiskLabel;
+    }>;
+}
+interface AppendOptions {
+    dataDir?: string;
+}
+type AppendMiss = (event: CapabilityMissEvent) => Promise<void>;
+interface CaptureOptions {
+    dataDir?: string;
+    env?: Record<string, string | undefined>;
+    telemetryHome?: string;
+    telemetryConfig?: Pick<TelemetryConfig, "anonymousId" | "optedOut">;
+    surface: Promise<CapabilitySurfaceSnapshot>;
+    append?: AppendMiss;
+    fetchImpl?: typeof fetch;
+    batchSize?: number;
+    queueLimit?: number;
+    batchDelayMs?: number;
+    requestTimeoutMs?: number;
+    retryDelaysMs?: readonly number[];
+}
+export interface CapabilityMissCapture {
+    /** Stable host-installation identity, shared with telemetry by contract. */
+    hostId: string;
+    record(event: CapabilityMissEvent): void;
+    /** Drain hook for tests and orderly host shutdown; agent turns never await it. */
+    flush(): Promise<void>;
+}
+export declare function appendCapabilityMiss(event: CapabilityMissEvent, options?: AppendOptions): Promise<void>;
+export declare function capabilitySurfaceSnapshot(descriptors: ToolDescriptor[]): CapabilitySurfaceSnapshot;
+export declare function createCapabilityMissCapture(options: CaptureOptions): CapabilityMissCapture;
+export {};

package/dist/capability-misses.js

@@ -0,0 +1,172 @@
+import { canonicalJson, sha256Hex, } from "@vendoai/core";
+import { envOptOut, loadConfig } from "@vendoai/telemetry";
+import { cloudFetch } from "./cli/cloud/client.js";
+const DEFAULT_DATA_DIR = ".vendo/data";
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_QUEUE_LIMIT = 1_000;
+const DEFAULT_BATCH_DELAY_MS = 250;
+const DEFAULT_REQUEST_TIMEOUT_MS = 1_500;
+const DEFAULT_RETRY_DELAYS_MS = [250, 1_000];
+function runtimeEnv() {
+    return typeof process === "undefined" ? {} : process.env;
+}
+function nodeFs() {
+    const proc = globalThis.process;
+    const fs = proc?.getBuiltinModule?.("node:fs");
+    if (!fs)
+        throw new Error("Capability-miss local persistence requires the Node filesystem");
+    return fs;
+}
+export async function appendCapabilityMiss(event, options = {}) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    const fs = nodeFs();
+    await fs.promises.mkdir(dataDir, { recursive: true });
+    // appendFile opens with O_APPEND. Each event is serialized into one write so
+    // concurrent processes cannot race a read/modify/write cycle.
+    await fs.promises.appendFile(`${dataDir.replace(/[\\/]$/, "")}/misses.jsonl`, `${JSON.stringify(event)}\n`, { encoding: "utf8", flag: "a" });
+}
+export function capabilitySurfaceSnapshot(descriptors) {
+    const tools = descriptors
+        .map(({ name, risk }) => ({ name, risk }))
+        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    const canonical = canonicalJson({ format: "vendo/tools@1", tools });
+    return { hash: `sha256:${sha256Hex(canonical)}`, tools };
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        unrefTimer(timer);
+    });
+}
+function unrefTimer(timer) {
+    if (typeof timer === "object" && timer !== null && "unref" in timer) {
+        timer.unref?.();
+    }
+}
+function validUploadResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const response = value;
+    return Number.isInteger(response.accepted) && Number.isInteger(response.duplicates);
+}
+function createMissUploader(options) {
+    const queue = [];
+    let timer;
+    let active;
+    const send = async (events) => {
+        for (let attempt = 0; attempt <= options.retryDelaysMs.length; attempt += 1) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), options.requestTimeoutMs);
+            unrefTimer(timeout);
+            try {
+                const surface = await options.surface;
+                const response = await cloudFetch("/api/v1/misses", {
+                    auth: "key",
+                    apiKey: options.apiKey,
+                    env: options.env,
+                    fetchImpl: options.fetchImpl,
+                    signal: controller.signal,
+                    body: { surface, events },
+                });
+                if (!validUploadResponse(response))
+                    throw new Error("Invalid capability-miss upload response");
+                return;
+            }
+            catch {
+                const retryDelay = options.retryDelaysMs[attempt];
+                if (retryDelay === undefined)
+                    return;
+                await delay(retryDelay);
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+    };
+    const drain = async () => {
+        while (queue.length > 0) {
+            const batch = queue.splice(0, options.batchSize);
+            await send(batch);
+        }
+    };
+    const flush = async () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (active) {
+            await active;
+            if (queue.length === 0)
+                return;
+        }
+        active = drain().finally(() => {
+            active = undefined;
+        });
+        await active;
+    };
+    const schedule = () => {
+        if (timer !== undefined || active !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void flush().catch(() => undefined);
+        }, options.batchDelayMs);
+        unrefTimer(timer);
+    };
+    return {
+        enqueue(event) {
+            if (queue.length >= options.queueLimit)
+                return;
+            queue.push(event);
+            if (queue.length >= options.batchSize)
+                void flush().catch(() => undefined);
+            else
+                schedule();
+        },
+        flush,
+    };
+}
+export function createCapabilityMissCapture(options) {
+    const env = options.env ?? runtimeEnv();
+    const telemetryConfig = options.telemetryConfig
+        ?? loadConfig(options.telemetryHome, env);
+    const apiKey = env.VENDO_API_KEY?.trim();
+    let uploader;
+    if (apiKey) {
+        // Contract (01-core §17): upload is gated by the key plus envOptOut only.
+        // The persisted telemetry opt-out and the NODE_ENV fail-close are
+        // product-telemetry-only; a non-empty VENDO_API_KEY is the host's opt-in.
+        if (!envOptOut(env)) {
+            uploader = createMissUploader({
+                apiKey,
+                env,
+                surface: options.surface,
+                fetchImpl: options.fetchImpl,
+                batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+                queueLimit: options.queueLimit ?? DEFAULT_QUEUE_LIMIT,
+                batchDelayMs: options.batchDelayMs ?? DEFAULT_BATCH_DELAY_MS,
+                requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+                retryDelaysMs: options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
+            });
+        }
+    }
+    const append = options.append
+        ?? ((event) => appendCapabilityMiss(event, { dataDir: options.dataDir }));
+    const pendingLocal = new Set();
+    return {
+        hostId: telemetryConfig.anonymousId,
+        record(event) {
+            const local = Promise.resolve()
+                .then(() => append(event))
+                .catch(() => undefined)
+                .finally(() => pendingLocal.delete(local));
+            pendingLocal.add(local);
+            uploader?.enqueue(event);
+        },
+        async flush() {
+            while (pendingLocal.size > 0)
+                await Promise.all([...pendingLocal]);
+            await uploader?.flush();
+        },
+    };
+}