@agent-native/core 0.175.0 → 0.175.1

package/dist/file-upload/builder.js

@@ -36,13 +36,13 @@ async function assertOk(res, label) {
         throw new Error(`${label} (${res.status}): ${body || res.statusText}`);
     }
 }
-async function uploadLargeFileViaSignedUrl(input, privateKey, bareMimeType, bytes) {
+async function uploadLargeFileViaSignedUrl(input, authorization, bareMimeType, bytes) {
     const name = input.filename ?? "upload";
     const mb = (bytes.byteLength / (1024 * 1024)).toFixed(1);
     console.log(`[builder-upload] large-file path: ${name} ${mb}MB ${bareMimeType}`);
     // Step 1 — request a signed URL.
     console.log(`[builder-upload] step 1: requesting signed URL`);
-    const { uploadUrl, assetId, requiredHeaders } = await requestBuilderSignedUrl(privateKey, name, bareMimeType, bytes.byteLength);
+    const { uploadUrl, assetId, requiredHeaders } = await requestBuilderSignedUrl(authorization, name, bareMimeType, bytes.byteLength);
     console.log(`[builder-upload] step 1 ok: assetId=${assetId}`);
     // Step 2 — PUT bytes directly to GCS. Only requiredHeaders; no Authorization
     // (signed URL carries its own auth — extra signed headers break the signature).
@@ -56,20 +56,20 @@ async function uploadLargeFileViaSignedUrl(input, privateKey, bareMimeType, byte
     console.log(`[builder-upload] step 2 ok [${assetId}]: GCS ${step2Res.status} etag=${step2Res.headers.get("etag") ?? "none"}`);
     // Step 3 — register the asset and get the CDN URL.
     console.log(`[builder-upload] step 3: registering asset - ${assetId}, ${input.filename}`);
-    const { url, id } = await completeBuilderUpload(privateKey, assetId, input.filename, {
+    const { url, id } = await completeBuilderUpload(authorization, assetId, input.filename, {
         stableUrl: input.stableUrl,
         recordAsset: input.recordAsset,
     });
     console.log(`[builder-upload] done [${assetId}]: ${url}`);
     return { url, id, provider: "builder" };
 }
-async function requestBuilderSignedUrl(privateKey, filename, mimeType, size, resumable = false) {
+async function requestBuilderSignedUrl(authorization, filename, mimeType, size, resumable = false) {
     const host = builderUploadHost();
     const url = new URL("/api/v1/upload/signed-url", host);
     const res = await fetchWithTimeout(url.toString(), {
         method: "POST",
         headers: {
-            Authorization: `Bearer ${privateKey}`,
+            Authorization: authorization,
             "Content-Type": "application/json",
         },
         body: JSON.stringify({
@@ -90,7 +90,7 @@ async function requestBuilderSignedUrl(privateKey, filename, mimeType, size, res
         requiredHeaders: json.requiredHeaders,
     };
 }
-async function completeBuilderUpload(privateKey, assetId, filename, options) {
+async function completeBuilderUpload(authorization, assetId, filename, options) {
     const host = builderUploadHost();
     const url = new URL("/api/v1/upload/complete", host);
     if (options?.stableUrl) {
@@ -100,7 +100,7 @@ async function completeBuilderUpload(privateKey, assetId, filename, options) {
     const res = await fetchWithTimeout(url.toString(), {
         method: "POST",
         headers: {
-            Authorization: `Bearer ${privateKey}`,
+            Authorization: authorization,
             "Content-Type": "application/json",
         },
         body: JSON.stringify({
@@ -144,10 +144,22 @@ async function uploadSmallFile(url, init) {
     const statusText = response?.statusText ?? "no response";
     throw new Error(`Builder.io upload failed (${status}): ${lastErrorBody || statusText}`);
 }
+/**
+ * Builder gates every `/api/v1/upload/*` endpoint on `builder:assets:write`.
+ * Legacy `bpk-` keys skip that check, which is why uploads kept working for
+ * older connections while OAuth-only ones could not upload at all.
+ */
+async function assetAuthorization() {
+    const [{ resolveBuilderApiAuthorization }, { BUILDER_ASSETS_WRITE_SCOPE }] = await Promise.all([
+        import("../server/builder-api-auth.js"),
+        import("../server/builder-oauth.js"),
+    ]);
+    return resolveBuilderApiAuthorization(BUILDER_ASSETS_WRITE_SCOPE);
+}
 /**
  * Built-in Builder.io file upload provider.
- * Uses the same BUILDER_PRIVATE_KEY as the browser/background-agent flows,
- * so connecting Builder once (via the sidebar "Connect Builder" action)
+ * Uses the same Builder connection as the browser/background-agent flows, so
+ * connecting Builder once (via the sidebar "Connect Builder" action)
  * automatically enables file uploads.
  *
  * Upload API: https://www.builder.io/c/docs/upload-api
@@ -158,11 +170,7 @@ export const builderFileUploadProvider = {
     isConfigured: () => !!process.env.BUILDER_PRIVATE_KEY,
     upload: async (input) => {
         const { data, filename, mimeType } = input;
-        const { resolveBuilderPrivateKey } = await import("../server/credential-provider.js");
-        const privateKey = await resolveBuilderPrivateKey();
-        if (!privateKey) {
-            throw new Error("BUILDER_PRIVATE_KEY is not set");
-        }
+        const authorization = await assetAuthorization();
         // Strip any media-type parameters (e.g. `;codecs=avc1,opus` from
         // MediaRecorder blobs) — Builder's upload API parses the body as raw
         // binary only when Content-Type is a bare MIME type. A parameterized
@@ -175,7 +183,7 @@ export const builderFileUploadProvider = {
         const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
         const mb = (bytes.byteLength / (1024 * 1024)).toFixed(1);
         if (shouldUseSignedUrlUpload(bytes, bareMimeType)) {
-            return uploadLargeFileViaSignedUrl(input, privateKey, bareMimeType, bytes);
+            return uploadLargeFileViaSignedUrl(input, authorization, bareMimeType, bytes);
         }
         console.log(`[builder-upload] small-file path: ${filename ?? "upload"} ${mb}MB ${bareMimeType}`);
         const url = new URL("/api/v1/upload", builderUploadHost());
@@ -188,7 +196,7 @@ export const builderFileUploadProvider = {
         const response = await uploadSmallFile(url, {
             method: "POST",
             headers: {
-                Authorization: `Bearer ${privateKey}`,
+                Authorization: authorization,
                 "Content-Type": bareMimeType,
             },
             body: makeBody(bytes, bareMimeType),
@@ -225,12 +233,9 @@ export const builderFileUploadProvider = {
     },
     resumable: {
         async startSession(filename, mimeType, maxBytes) {
-            const { resolveBuilderPrivateKey } = await import("../server/credential-provider.js");
-            const privateKey = await resolveBuilderPrivateKey();
-            if (!privateKey)
-                throw new Error("BUILDER_PRIVATE_KEY is not set");
+            const authorization = await assetAuthorization();
             console.log(`[builder-resumable] starting session: ${filename} ${mimeType} ${maxBytes} bytes`);
-            const { uploadUrl, assetId, requiredHeaders } = await requestBuilderSignedUrl(privateKey, filename, mimeType, maxBytes, true);
+            const { uploadUrl, assetId, requiredHeaders } = await requestBuilderSignedUrl(authorization, filename, mimeType, maxBytes, true);
             console.log(`[builder-resumable] session step 1 ok: assetId=${assetId}`);
             const initHeaders = {
                 "Content-Type": mimeType,
@@ -305,13 +310,10 @@ export const builderFileUploadProvider = {
                 : new Error("GCS PUT failed after retries");
         },
         async completeSession(session, filename, options) {
-            const { resolveBuilderPrivateKey } = await import("../server/credential-provider.js");
-            const privateKey = await resolveBuilderPrivateKey();
-            if (!privateKey)
-                throw new Error("BUILDER_PRIVATE_KEY is not set");
+            const authorization = await assetAuthorization();
             const assetId = session.meta.assetId;
             console.log(`[builder-resumable] completing upload: assetId=${assetId}`);
-            const { url } = await completeBuilderUpload(privateKey, assetId, filename, {
+            const { url } = await completeBuilderUpload(authorization, assetId, filename, {
                 stableUrl: options?.stableUrl || session.meta.stableUrl === true,
                 recordAsset: options?.recordAsset ??
                     (session.meta.recordAsset === false ? false : undefined),

package/dist/file-upload/registry.js

@@ -44,8 +44,10 @@ export async function getActiveFileUploadProviderForRequest() {
         return builderFileUploadProvider;
     }
     try {
-        const { resolveHasBuilderPrivateKey } = await import("../server/credential-provider.js");
-        if (await resolveHasBuilderPrivateKey()) {
+        // Either Builder credential kind counts. Checking only the private key
+        // reported every OAuth-only connection as having no upload provider.
+        const { hasBuilderApiCredentialCustody } = await import("../server/builder-api-auth.js");
+        if (await hasBuilderApiCredentialCustody()) {
             return builderFileUploadProvider;
         }
     }
@@ -79,17 +81,18 @@ export async function uploadFile(input) {
     // via runWithRequestContext — actions always have one via action-routes.ts).
     // Two separate try-catch blocks ensure a real upload failure is never
     // silently swallowed as a "no credentials" case.
-    let builderKey = null;
+    let hasBuilderCredential = false;
     try {
-        const { resolveBuilderPrivateKey } = await import("../server/credential-provider.js");
-        builderKey = await resolveBuilderPrivateKey();
+        const { hasBuilderApiCredentialCustody } = await import("../server/builder-api-auth.js");
+        hasBuilderCredential = await hasBuilderApiCredentialCustody();
     }
     catch (err) {
-        // DB unavailable or credential store not ready — can't resolve key.
-        // Return an unavailable-provider state below; never fall back to SQL.
+        // DB unavailable or credential store not ready — can't resolve a
+        // credential. Return an unavailable-provider state below; never fall back
+        // to SQL.
         console.warn("[agent-native] Builder credential check failed:", err instanceof Error ? err.message : String(err));
     }
-    if (builderKey) {
+    if (hasBuilderCredential) {
         // Credentials confirmed — attempt the upload. Real errors (network,
         // API, rate-limit) propagate to the caller; do NOT catch them here.
         return await builderFileUploadProvider.upload(input);

package/dist/mcp/screen-memory-stdio.d.ts

@@ -137,13 +137,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -159,7 +159,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -175,6 +174,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -190,7 +190,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             minutes: {
                 type: string;
                 description: string;
@@ -200,6 +199,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -216,7 +216,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -235,6 +234,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             };
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -250,7 +250,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
@@ -264,6 +263,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
                 description: string;
             };
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             includeMicrophone?: undefined;
@@ -314,13 +314,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt: {
                 type: string;
                 description: string;
@@ -349,13 +349,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;

package/dist/notifications/routes.d.ts

@@ -16,18 +16,18 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error?: undefined;
     ok?: undefined;
 } | {
-    count?: undefined;
     updated: number;
     error?: undefined;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     error: string;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     error?: undefined;
     ok: boolean;
+    count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
     error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -34,10 +34,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/builder-api-auth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Authorization for Builder.io REST asset calls (`/api/v1/upload/*`).
+ *
+ * Two credential kinds reach those endpoints and they are not interchangeable:
+ * a legacy `bpk-` private key bypasses Builder's OAuth scope middleware
+ * entirely, while an OAuth access token is checked against the scopes its
+ * grant was issued with. New Builder connections store only an OAuth grant, so
+ * a caller that knows about private keys alone cannot upload for them at all.
+ */
+/**
+ * Resolve the `Authorization` header for a Builder asset API call.
+ *
+ * OAuth wins whenever the request's owner has a grant. An unusable grant
+ * throws rather than falling back to a private key: falling back would let a
+ * deploy-level or stale `bpk-` key act for a user who never authorized it.
+ *
+ * @param requiredScope OAuth scope the endpoint enforces. Omit for endpoints
+ * with no scope gate.
+ */
+export declare function resolveBuilderApiAuthorization(requiredScope?: string): Promise<string>;
+/**
+ * Whether Builder.io can authenticate an asset call for this request — an
+ * OAuth grant, or a legacy private key.
+ *
+ * Storage gates and provider selection use this. It intentionally does not
+ * verify the grant is usable: answering `false` for a connected user whose
+ * grant needs re-authorizing would report storage as unconfigured and send
+ * them to set up something they already have, instead of letting the upload
+ * path say what is actually wrong.
+ */
+export declare function hasBuilderApiCredentialCustody(): Promise<boolean>;

package/dist/server/builder-api-auth.js

@@ -0,0 +1,62 @@
+/**
+ * Authorization for Builder.io REST asset calls (`/api/v1/upload/*`).
+ *
+ * Two credential kinds reach those endpoints and they are not interchangeable:
+ * a legacy `bpk-` private key bypasses Builder's OAuth scope middleware
+ * entirely, while an OAuth access token is checked against the scopes its
+ * grant was issued with. New Builder connections store only an OAuth grant, so
+ * a caller that knows about private keys alone cannot upload for them at all.
+ */
+import { getBuilderOAuthSession, hasBuilderOAuthSession, } from "./builder-oauth.js";
+import { resolveBuilderPrivateKey } from "./credential-provider.js";
+import { getRequestOrgId, getRequestUserEmail } from "./request-context.js";
+/**
+ * Resolve the `Authorization` header for a Builder asset API call.
+ *
+ * OAuth wins whenever the request's owner has a grant. An unusable grant
+ * throws rather than falling back to a private key: falling back would let a
+ * deploy-level or stale `bpk-` key act for a user who never authorized it.
+ *
+ * @param requiredScope OAuth scope the endpoint enforces. Omit for endpoints
+ * with no scope gate.
+ */
+export async function resolveBuilderApiAuthorization(requiredScope) {
+    const ownerEmail = getRequestUserEmail();
+    // Bind to the request's organization, not the user's currently active one:
+    // the grant is org-scoped, and a recording that finalizes after the user
+    // switched org must still authorize against the org it belongs to. The
+    // legacy private-key path already resolves this way.
+    const orgId = getRequestOrgId();
+    if (ownerEmail && (await hasBuilderOAuthSession(ownerEmail, orgId))) {
+        const session = await getBuilderOAuthSession(ownerEmail, orgId);
+        if (!session) {
+            throw new Error("Builder.io access expired. Re-authorize Builder.io in Settings to continue.");
+        }
+        if (requiredScope && !session.scopes.includes(requiredScope)) {
+            throw new Error(`Builder.io access needs re-authorizing to grant ${requiredScope}. Open Settings and authorize Builder.io again.`);
+        }
+        return `Bearer ${session.accessToken}`;
+    }
+    const privateKey = await resolveBuilderPrivateKey();
+    if (!privateKey)
+        throw new Error("Builder.io is not connected.");
+    return `Bearer ${privateKey}`;
+}
+/**
+ * Whether Builder.io can authenticate an asset call for this request — an
+ * OAuth grant, or a legacy private key.
+ *
+ * Storage gates and provider selection use this. It intentionally does not
+ * verify the grant is usable: answering `false` for a connected user whose
+ * grant needs re-authorizing would report storage as unconfigured and send
+ * them to set up something they already have, instead of letting the upload
+ * path say what is actually wrong.
+ */
+export async function hasBuilderApiCredentialCustody() {
+    const ownerEmail = getRequestUserEmail();
+    if (ownerEmail &&
+        (await hasBuilderOAuthSession(ownerEmail, getRequestOrgId()))) {
+        return true;
+    }
+    return !!(await resolveBuilderPrivateKey());
+}

package/dist/server/builder-oauth.d.ts

@@ -1,7 +1,9 @@
 export declare const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
 export declare const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
 export declare const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
-export declare const BUILDER_OAUTH_SCOPES: readonly ["builder:ai:invoke"];
+/** Enforced by Builder's `/api/v1/upload/*` endpoints; without it, no uploads. */
+export declare const BUILDER_ASSETS_WRITE_SCOPE = "builder:assets:write";
+export declare const BUILDER_OAUTH_SCOPES: readonly ["builder:ai:invoke", "builder:assets:write"];
 export type BuilderOAuthPendingFlow = {
     codeVerifier: string;
     clientInformation: unknown;
@@ -32,8 +34,8 @@ export declare function finishBuilderOAuthAuthorization(input: {
     pending: BuilderOAuthPendingFlow;
 }): Promise<void>;
 export declare function markBuilderOAuthReconnectRequired(ownerEmail: string): Promise<void>;
-export declare function getBuilderOAuthSession(ownerEmail: string): Promise<BuilderOAuthSession | null>;
-export declare function hasBuilderOAuthSession(ownerEmail: string): Promise<boolean>;
+export declare function getBuilderOAuthSession(ownerEmail: string, orgId?: string | null): Promise<BuilderOAuthSession | null>;
+export declare function hasBuilderOAuthSession(ownerEmail: string, orgId?: string | null): Promise<boolean>;
 export declare function resolveBuilderOAuthRequestAccess(input: {
     ownerEmail: string;
     requiredScope: string;

package/dist/server/builder-oauth.js

@@ -5,7 +5,12 @@ import { resolveOrgIdForEmail } from "../org/context.js";
 export const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
 export const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
 export const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
-export const BUILDER_OAUTH_SCOPES = [BUILDER_OAUTH_SCOPE];
+/** Enforced by Builder's `/api/v1/upload/*` endpoints; without it, no uploads. */
+export const BUILDER_ASSETS_WRITE_SCOPE = "builder:assets:write";
+export const BUILDER_OAUTH_SCOPES = [
+    BUILDER_OAUTH_SCOPE,
+    BUILDER_ASSETS_WRITE_SCOPE,
+];
 // Folded with the owner so each owner gets their own (provider, account_id)
 // row; a bare shared key would let only the first connector hold a grant.
 const BUILDER_OAUTH_KEY = "builder-general-resource-v1";
@@ -26,12 +31,17 @@ function normalizeOwnerEmail(ownerEmail) {
 }
 // Read paths use this: a caller with no org simply has no Builder session, so
 // engine detection and status checks get null instead of an exception.
-async function resolveOwnerOptions(ownerEmail) {
+//
+// An explicit orgId wins over the user's active org. The grant is org-scoped,
+// so work that carries its own organization — a recording finalizing after the
+// user switched active org, a background run — must authorize against that org
+// rather than whichever one the user happens to be looking at now.
+async function resolveOwnerOptions(ownerEmail, orgId) {
     const email = normalizeOwnerEmail(ownerEmail);
-    const orgId = await resolveOrgIdForEmail(email);
-    if (!orgId)
+    const resolvedOrgId = orgId?.trim() || (await resolveOrgIdForEmail(email));
+    if (!resolvedOrgId)
         return null;
-    return orgOwnerOptions(orgId);
+    return orgOwnerOptions(resolvedOrgId);
 }
 // Write paths use this: storing a Builder credential without an org is a broken
 // invariant, so a missing org fails loudly rather than silently dropping it.
@@ -54,10 +64,28 @@ function builderOAuthKey(orgId) {
     const digest = createHash("sha256").update(orgId).digest("hex");
     return `${BUILDER_OAUTH_KEY}:o:${digest}`;
 }
+/**
+ * RFC 6749 §5.1 lets a token response omit `scope` when the grant matches what
+ * was requested. Record what this flow asked for, so a stored credential always
+ * states its own scopes: inferring them later cannot tell a new two-scope grant
+ * from a pre-change AI-only one, and either guess is wrong for the other.
+ */
+function withRecordedScopes(credentials) {
+    if (typeof credentials.tokens.scope === "string")
+        return credentials;
+    return {
+        ...credentials,
+        tokens: { ...credentials.tokens, scope: BUILDER_OAUTH_SCOPES.join(" ") },
+    };
+}
+// Builder's token endpoint always sets `scope`, and `withRecordedScopes` backs
+// that up for anything this flow stores, so an absent claim can only be a grant
+// predating both. Those were AI-only and must not be credited with an upload
+// scope the user never consented to.
 function scopesFrom(credentials) {
     const declared = credentials.tokens.scope;
     if (typeof declared !== "string")
-        return [...BUILDER_OAUTH_SCOPES];
+        return [BUILDER_OAUTH_SCOPE];
     return declared.split(/\s+/).filter(Boolean);
 }
 function resourceUrlsMatch(left, right) {
@@ -92,7 +120,7 @@ export async function startBuilderOAuthAuthorization(input) {
         serverUrl: BUILDER_OAUTH_RESOURCE,
         redirectUrl: input.redirectUri,
         state: input.state,
-        scope: BUILDER_OAUTH_SCOPE,
+        scope: BUILDER_OAUTH_SCOPES.join(" "),
         resourceMetadataUrl: BUILDER_OAUTH_PROTECTED_RESOURCE_METADATA,
     });
     return {
@@ -124,7 +152,7 @@ export async function finishBuilderOAuthAuthorization(input) {
         ...(input.orgId
             ? orgOwnerOptions(input.orgId)
             : await ownerOptions(input.ownerEmail)),
-        credentials: result.credentials,
+        credentials: withRecordedScopes(result.credentials),
     });
 }
 export async function markBuilderOAuthReconnectRequired(ownerEmail) {
@@ -133,8 +161,8 @@ export async function markBuilderOAuthReconnectRequired(ownerEmail) {
         return;
     await markMcpOAuthReconnectRequired(options);
 }
-export async function getBuilderOAuthSession(ownerEmail) {
-    const options = await resolveOwnerOptions(ownerEmail);
+export async function getBuilderOAuthSession(ownerEmail, orgId) {
+    const options = await resolveOwnerOptions(ownerEmail, orgId);
     if (!options)
         return null;
     // Delegates refresh single-flight and reconnect latching to the shared
@@ -152,8 +180,8 @@ export async function getBuilderOAuthSession(ownerEmail) {
         scopes: scopesFrom(credentials),
     };
 }
-export async function hasBuilderOAuthSession(ownerEmail) {
-    const options = await resolveOwnerOptions(ownerEmail);
+export async function hasBuilderOAuthSession(ownerEmail, orgId) {
+    const options = await resolveOwnerOptions(ownerEmail, orgId);
     if (!options)
         return false;
     const stored = await getOAuthTokens("mcp", options.key, `${options.scope}:${options.scopeId}`);

package/dist/server/core-routes-plugin.js

@@ -2747,8 +2747,11 @@ export function createCoreRoutesPlugin(options = {}) {
                     const active = await getActiveFileUploadProviderForRequest();
                     let builderConfigured = !!process.env.BUILDER_PRIVATE_KEY;
                     try {
-                        const { resolveBuilderPrivateKey } = await import("./credential-provider.js");
-                        builderConfigured = await resolveBuilderPrivateKey().then((k) => !!k);
+                        // Must match what provider selection asks, or this reports
+                        // storage as unconfigured for an OAuth-only connection whose
+                        // uploads actually work.
+                        const { hasBuilderApiCredentialCustody } = await import("./builder-api-auth.js");
+                        builderConfigured = await hasBuilderApiCredentialCustody();
                     }
                     catch {
                         // fall back to env check above