@agent-native/core 0.145.8 → 0.146.1

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,9 +75,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    message?: undefined;
+    id?: undefined;
     deleted?: undefined;
-    found?: undefined;
     providers: {
         id: string;
         label: string;
@@ -89,21 +88,21 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }[];
     count: number;
     provider?: undefined;
+    found?: undefined;
     registered?: undefined;
-    id?: undefined;
     label?: undefined;
-} | {
     message?: undefined;
+} | {
+    id?: undefined;
     deleted?: undefined;
     providers?: undefined;
     count?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
-    id?: undefined;
     label?: undefined;
-} | {
     message?: undefined;
+} | {
     deleted?: undefined;
     providers?: undefined;
     count?: undefined;
@@ -112,22 +111,23 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-} | {
     message?: undefined;
-    found?: undefined;
+} | {
     providers?: undefined;
     count?: undefined;
     provider?: undefined;
+    found?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
+    message?: undefined;
 } | {
     deleted?: undefined;
-    found?: undefined;
     providers?: undefined;
     count?: undefined;
     provider?: undefined;
+    found?: undefined;
     registered: boolean;
     id: string;
     label: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,10 +311,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        deleted?: undefined;
         id?: undefined;
         provider?: undefined;
-        found?: undefined;
+        deleted?: undefined;
         message?: undefined;
         providers: {
             id: string;
@@ -326,12 +325,13 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
+        found?: undefined;
         registered?: undefined;
         label?: undefined;
     } | {
-        deleted?: undefined;
-        count?: undefined;
         id?: undefined;
+        count?: undefined;
+        deleted?: undefined;
         message?: undefined;
         providers?: undefined;
         found: boolean;
@@ -339,9 +339,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         registered?: undefined;
         label?: undefined;
     } | {
-        deleted?: undefined;
         count?: undefined;
         provider?: undefined;
+        deleted?: undefined;
         message?: undefined;
         providers?: undefined;
         found: boolean;
@@ -351,19 +351,19 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
     } | {
         count?: undefined;
         provider?: undefined;
-        found?: undefined;
         message?: undefined;
         providers?: undefined;
+        found?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
     } | {
-        deleted?: undefined;
         count?: undefined;
         provider?: undefined;
-        found?: undefined;
+        deleted?: undefined;
         providers?: undefined;
+        found?: undefined;
         registered: boolean;
         id: string;
         label: string;

package/dist/provider-api/corpus-jobs.d.ts

@@ -73,7 +73,6 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     offset?: unknown;
     limit?: unknown;
 }, {
-    deleted?: undefined;
     jobs: {
         id: string;
         name: string;
@@ -84,6 +83,7 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
         updatedAt: string;
     }[];
     total: number;
+    deleted?: undefined;
     jobId?: undefined;
 } | {
     jobs?: undefined;
@@ -91,9 +91,9 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     deleted: boolean;
     jobId: string;
 } | {
-    deleted?: undefined;
     jobs?: undefined;
     total?: undefined;
+    deleted?: undefined;
     jobId?: undefined;
     hits: Record<string, unknown>[];
     offset: number;

package/dist/scripts/docs/search.js

@@ -127,12 +127,13 @@ async function loadAgentBundleDocs() {
                 body: bundle.workspaceAgentsMd,
             });
         }
-        if (bundle.agentsMd?.trim()) {
+        const runtimeAgentsMd = bundle.runtimeAgentsMd ?? bundle.agentsMd;
+        if (runtimeAgentsMd?.trim()) {
             docs.push({
                 slug: "agents-template",
                 title: "Template AGENTS.md",
                 description: "Full bundled template/app agent instructions.",
-                body: bundle.agentsMd,
+                body: runtimeAgentsMd,
             });
         }
         // Only runtime-visible skills are searchable/readable here — `scope: dev`

package/dist/server/agent-chat/prompt-resources.js

@@ -631,13 +631,14 @@ export async function loadResourcesForPrompt(owner, compact = false, selfAppId,
             });
             addSection(block, "required");
         }
-        // 2. Template AGENTS.md — always included (critical template instructions).
-        if (bundle.agentsMd.trim()) {
+        // 2. Runtime instruction file — always included when configured.
+        const runtimeAgentsMd = bundle.runtimeAgentsMd ?? bundle.agentsMd;
+        if (runtimeAgentsMd.trim()) {
             const block = promptResourceBlock({
                 name: "AGENTS.md",
                 scope: "template",
                 path: "AGENTS.md",
-                content: bundle.agentsMd,
+                content: runtimeAgentsMd,
                 maxChars: promptResourceMaxChars,
                 readHint: 'Use docs-search --slug "agents-template" to read the full template AGENTS.md.',
             });

package/dist/server/agents-bundle.d.ts

@@ -15,7 +15,8 @@
  *   2. Filesystem fallback — `process.cwd()/AGENTS.md` +
  *      `process.cwd()/.agents/skills/` (or legacy `.agent/skills/`). Only reliable in local dev and Node
  *      production (`agent-native start`); not on Netlify/Vercel/CF at runtime.
- *   3. Empty bundle — everything silently returns empty strings.
+ *   3. Configuration and filesystem failures propagate so a broken bundle is
+ *      visible instead of being mistaken for an app with no instructions.
  *
  * Result is cached in module scope so it's only computed once per cold start.
  */
@@ -68,8 +69,15 @@ export interface Skill {
     files: Record<string, string>;
 }
 export interface AgentsBundle {
-    /** Contents of the template's AGENTS.md (empty string if missing). */
+    /**
+     * Legacy alias for the runtime instruction file. Empty when an explicitly
+     * configured runtime file is missing.
+     */
     agentsMd: string;
+    /** Contents of the runtime agent's selected instruction file. */
+    runtimeAgentsMd: string;
+    /** Contents of the development agent's selected instruction file. */
+    developmentAgentsMd: string;
     /**
      * Contents of the workspace core's AGENTS.md, if the app is inside an
      * enterprise monorepo with a `workspaceCore` configured. Empty string
@@ -86,6 +94,14 @@ export interface AgentsBundle {
      */
     skills: Record<string, Skill>;
 }
+export interface AgentsBundleReadOptions {
+    instructions?: AgentNativeInstructionsConfig;
+}
+export interface AgentInstructionPaths {
+    runtime: string;
+    development: string;
+}
+export declare function resolveAgentInstructionPaths(instructions?: AgentNativeInstructionsConfig): AgentInstructionPaths;
 export declare function normalizeSkillScope(raw: string | undefined): SkillScope;
 /**
  * Parse the YAML frontmatter at the top of a skill file.
@@ -97,6 +113,7 @@ export declare function normalizeSkillScope(raw: string | undefined): SkillScope
  *   - Literal scalar: `description: |\n  multi\n  line` → "multi\nline"
  */
 export declare function parseSkillFrontmatter(content: string): Partial<SkillMeta>;
+import type { AgentNativeInstructionsConfig } from "../config.js";
 /**
  * Paths to a workspace-core's agent resources, for merging into a template's
  * bundle. All fields optional — pass null for any missing piece.
@@ -117,7 +134,7 @@ export interface WorkspaceAgentsSource {
  *
  * Synchronous — the Vite plugin's load hook calls it inline during the build.
  */
-export declare function readAgentsBundleFromFs(cwd: string, workspaceSource?: WorkspaceAgentsSource | null): AgentsBundle;
+export declare function readAgentsBundleFromFs(cwd: string, workspaceSource?: WorkspaceAgentsSource | null, options?: AgentsBundleReadOptions): AgentsBundle;
 /**
  * Load the agents bundle. Returns a cached result on subsequent calls.
  * Tries the virtual module first (works everywhere, including edge), then

package/dist/server/agents-bundle.js

@@ -15,12 +15,19 @@
  *   2. Filesystem fallback — `process.cwd()/AGENTS.md` +
  *      `process.cwd()/.agents/skills/` (or legacy `.agent/skills/`). Only reliable in local dev and Node
  *      production (`agent-native start`); not on Netlify/Vercel/CF at runtime.
- *   3. Empty bundle — everything silently returns empty strings.
+ *   3. Configuration and filesystem failures propagate so a broken bundle is
+ *      visible instead of being mistaken for an app with no instructions.
  *
  * Result is cached in module scope so it's only computed once per cold start.
  */
 export const DEFAULT_SKILL_SCOPE = "both";
-const EMPTY = { agentsMd: "", workspaceAgentsMd: "", skills: {} };
+const DEFAULT_AGENT_INSTRUCTIONS_PATH = "AGENTS.md";
+export function resolveAgentInstructionPaths(instructions) {
+    return {
+        runtime: instructions?.runtime ?? DEFAULT_AGENT_INSTRUCTIONS_PATH,
+        development: instructions?.development ?? DEFAULT_AGENT_INSTRUCTIONS_PATH,
+    };
+}
 let cached = null;
 /**
  * Coerce a raw frontmatter `scope` value into a known `SkillScope`. Unknown,
@@ -125,6 +132,23 @@ const READABLE_SUBFILE_EXTENSIONS = new Set([".md", ".txt", ".json"]);
  */
 const MAX_SUBFILE_BYTES = 64 * 1024;
 const MAX_SKILL_FILES_BYTES = 256 * 1024;
+function readInstructionFile(cwd, relativePath) {
+    const normalizedPath = relativePath.replaceAll("\\", "/");
+    const root = fs.realpathSync(path.resolve(cwd));
+    const absolutePath = path.resolve(root, normalizedPath);
+    if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`Agent instruction path must stay inside the app root: ${relativePath}`);
+    }
+    if (!fs.existsSync(absolutePath))
+        return "";
+    const realPath = fs.realpathSync(absolutePath);
+    if (realPath !== root && !realPath.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`Agent instruction path must stay inside the app root: ${relativePath}`);
+    }
+    if (!fs.statSync(realPath).isFile())
+        return "";
+    return fs.readFileSync(realPath, "utf-8");
+}
 /**
  * Read one skills directory into a `Record<string, Skill>`. Extracted so
  * both the template and workspace-core paths can reuse it. `dirPrefix` is
@@ -214,15 +238,10 @@ function readSkillsDir(skillsDir, rootForRelative, out, skipExistingNames) {
  *
  * Synchronous — the Vite plugin's load hook calls it inline during the build.
  */
-export function readAgentsBundleFromFs(cwd, workspaceSource = null) {
-    let agentsMd = "";
-    try {
-        const agentsMdPath = path.join(cwd, "AGENTS.md");
-        if (fs.existsSync(agentsMdPath)) {
-            agentsMd = fs.readFileSync(agentsMdPath, "utf-8");
-        }
-    }
-    catch { }
+export function readAgentsBundleFromFs(cwd, workspaceSource = null, options = {}) {
+    const instructionPaths = resolveAgentInstructionPaths(options.instructions);
+    const runtimeAgentsMd = readInstructionFile(cwd, instructionPaths.runtime);
+    const developmentAgentsMd = readInstructionFile(cwd, instructionPaths.development);
     let workspaceAgentsMd = "";
     if (workspaceSource?.agentsMdPath) {
         try {
@@ -249,7 +268,15 @@ export function readAgentsBundleFromFs(cwd, workspaceSource = null) {
         }
         catch { }
     }
-    return { agentsMd, workspaceAgentsMd, skills };
+    return {
+        // Keep the old field useful for callers that only know about the runtime
+        // bundle. Audience-aware consumers should use the explicit fields.
+        agentsMd: runtimeAgentsMd,
+        runtimeAgentsMd,
+        developmentAgentsMd,
+        workspaceAgentsMd,
+        skills,
+    };
 }
 /**
  * Load the agents bundle. Returns a cached result on subsequent calls.
@@ -279,29 +306,29 @@ export async function loadAgentsBundle() {
     }
     // 2. Filesystem fallback — works in dev / Node prod. If a workspace core
     //    is present in the ancestor chain, merge its skills + AGENTS.md in.
+    let workspaceSource = null;
     try {
-        let workspaceSource = null;
-        try {
-            const { getWorkspaceCoreExports } = await import("../deploy/workspace-core.js");
-            const ws = await getWorkspaceCoreExports(process.cwd());
-            if (ws) {
-                workspaceSource = {
-                    skillsDir: ws.skillsDir,
-                    agentsMdPath: ws.agentsMdPath,
-                    rootDir: ws.packageDir,
-                };
-            }
-        }
-        catch {
-            // workspace-core discovery isn't available (e.g. edge runtime).
+        const { getWorkspaceCoreExports } = await import("../deploy/workspace-core.js");
+        const ws = await getWorkspaceCoreExports(process.cwd());
+        if (ws) {
+            workspaceSource = {
+                skillsDir: ws.skillsDir,
+                agentsMdPath: ws.agentsMdPath,
+                rootDir: ws.packageDir,
+            };
         }
-        cached = readAgentsBundleFromFs(process.cwd(), workspaceSource);
-        return cached;
+        // coercion-ok: workspace-core discovery is optional in edge runtimes.
     }
     catch {
-        cached = EMPTY;
-        return cached;
+        // workspace-core discovery isn't available (e.g. edge runtime).
     }
+    const { createAgentNativeConfigContext, loadResolvedAgentNativeConfig } = await import("../vite/agent-native-config-loader.js");
+    const production = process.env.NODE_ENV === "production";
+    const config = await loadResolvedAgentNativeConfig(process.cwd(), createAgentNativeConfigContext(production ? "build" : "serve", production ? "production" : "development"));
+    cached = readAgentsBundleFromFs(process.cwd(), workspaceSource, {
+        instructions: config.instructions,
+    });
+    return cached;
 }
 /**
  * Generate the `<skills>` block to inject into the system prompt.

package/dist/server/better-auth-instance.js

@@ -16,7 +16,7 @@ import { pgTable, text as pgText, timestamp as pgTimestamp, boolean as pgBoolean
 import { sqliteTable, text as sqliteText, integer as sqliteInteger, } from "drizzle-orm/sqlite-core";
 import { TEMPLATES } from "../cli/templates-meta.js";
 import { getDbExec, isPostgres } from "../db/client.js";
-import { getDialect, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolOptions, attachNeonPoolErrorLogger, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "../db/client.js";
+import { getDialect, getDatabaseUrl, getDatabaseAuthToken, closePgliteClients, getPgliteClient, isPgliteUrl, loadPgliteDrizzle, pgPoolOptions, neonPoolOptions, guardNeonPool, sharedDbPool, onSharedDbPoolsClosed, onSharedDbPoolReplaced, } from "../db/client.js";
 import { CORE_RESET_PASSWORD_EMAIL_ID, CORE_VERIFY_SIGNUP_EMAIL_ID, } from "../email-catalog/system-emails.js";
 import { saveOAuthTokens } from "../oauth-tokens/store.js";
 import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
@@ -1151,7 +1151,7 @@ async function buildDatabaseConfig(dialect) {
             // connections reached" across concurrent serverless instances.
             resetAuthOnPoolClose("neon", url);
             _neonAuthPool = sharedDbPool("neon", url, () => new Pool({ connectionString: url, ...neonPoolOptions() }));
-            attachNeonPoolErrorLogger(_neonAuthPool, "db/neon-auth");
+            guardNeonPool(_neonAuthPool, url, "db/neon-auth");
             const { drizzle } = await import("drizzle-orm/neon-serverless");
             const db = drizzle(buildResilientNeonPool(_neonAuthPool), {
                 schema: pgAuthSchema,

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

@@ -328,6 +328,40 @@ export interface RunBuilderAgentResult {
     url: string;
     status: string;
 }
+export interface BuilderProjectLookupArgs {
+    repoUrl: string;
+}
+export interface BuilderProjectResult {
+    projectId: string;
+    name: string;
+    repoUrl: string;
+    browserUrl: string;
+    created: boolean;
+}
+/**
+ * Find an existing Builder project connected to a repository. Dispatch uses
+ * this before provisioning so a first app request cannot create a duplicate
+ * workspace project when the project id has not been saved yet.
+ */
+export declare function findBuilderProjectForRepo(args: BuilderProjectLookupArgs): Promise<BuilderProjectResult | null>;
+/**
+ * Create a Builder project connected to a repository through the public
+ * projects API. This is the server-side bridge used by Dispatch; online
+ * Claude and ChatGPT hosts do not need a separate Builder CMS MCP connector.
+ */
+export declare function createBuilderProject(args: {
+    name: string;
+    repoUrl: string;
+}): Promise<BuilderProjectResult>;
+/**
+ * Reuse a connected Builder project or create it once when Dispatch is first
+ * used for a workspace. The lookup and create calls intentionally stay in
+ * this shared server helper so all callers use the same authenticated path.
+ */
+export declare function ensureBuilderProject(args: {
+    name: string;
+    repoUrl: string;
+}): Promise<BuilderProjectResult>;
 /**
  * POST a prompt to the Builder agents-run API. The Builder agent runs in a
  * cloud sandbox and writes code to a branch; the returned URL opens that

package/dist/server/builder-browser.js

@@ -1283,6 +1283,185 @@ function normalizeBuilderApiString(value, fieldName) {
     }
     return trimmed;
 }
+function normalizeBuilderProjectString(value, fieldName) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Builder project response returned a blank ${fieldName}`);
+    }
+    const trimmed = value.trim();
+    if (/[\u0000-\u001f\u007f]/.test(trimmed)) {
+        throw new Error(`Builder project response returned a malformed ${fieldName}`);
+    }
+    return trimmed;
+}
+function normalizeBuilderRepoUrl(value) {
+    const trimmed = value.trim();
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new Error("Builder project repository URL is malformed");
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error("Builder project repository URL must use HTTP or HTTPS");
+    }
+    return trimmed;
+}
+function comparableBuilderRepoUrl(value) {
+    try {
+        const parsed = new URL(value);
+        const pathname = parsed.pathname.replace(/\/+$/, "").replace(/\.git$/, "");
+        return `${parsed.hostname.toLowerCase()}${pathname.toLowerCase()}`;
+    }
+    catch {
+        return value
+            .trim()
+            .replace(/\/+$/, "")
+            .replace(/\.git$/, "")
+            .toLowerCase();
+    }
+}
+function builderProjectBrowserUrl(projectId) {
+    return `${getBuilderAppHost().replace(/\/$/, "")}/app/projects/${encodeURIComponent(projectId)}`;
+}
+function builderProjectFromRecord(value, fallbackRepoUrl, created) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const projectId = typeof record.id === "string" && record.id.trim() ? record.id.trim() : null;
+    if (!projectId)
+        return null;
+    const name = typeof record.name === "string" && record.name.trim()
+        ? record.name.trim()
+        : "Agent-Native Workspace";
+    const repoUrl = typeof record.repoUrl === "string" && record.repoUrl.trim()
+        ? record.repoUrl.trim()
+        : fallbackRepoUrl;
+    if (!repoUrl)
+        return null;
+    return {
+        projectId: normalizeBuilderProjectString(projectId, "project id"),
+        name: normalizeBuilderProjectString(name, "project name"),
+        repoUrl: normalizeBuilderRepoUrl(repoUrl),
+        browserUrl: builderProjectBrowserUrl(projectId),
+        created,
+    };
+}
+async function resolveBuilderApiCredentials() {
+    const { resolveBuilderCredentials } = await import("./credential-provider.js");
+    const creds = await resolveBuilderCredentials();
+    if (!creds.privateKey || !creds.publicKey) {
+        throw new Error("Builder keys are not configured");
+    }
+    return {
+        ...creds,
+        privateKey: creds.privateKey,
+        publicKey: creds.publicKey,
+    };
+}
+async function readBuilderApiObject(response, operation) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (error) {
+        throw new Error("Builder " +
+            operation +
+            " returned an invalid JSON response (" +
+            response.status +
+            ")", { cause: error });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Builder " +
+            operation +
+            " returned an invalid JSON response (" +
+            response.status +
+            ")");
+    }
+    return parsed;
+}
+function builderApiErrorMessage(parsed, fallback) {
+    if (typeof parsed.error === "string" && parsed.error.trim()) {
+        return parsed.error.trim();
+    }
+    if (typeof parsed.message === "string" && parsed.message.trim()) {
+        return parsed.message.trim();
+    }
+    return fallback;
+}
+/**
+ * Find an existing Builder project connected to a repository. Dispatch uses
+ * this before provisioning so a first app request cannot create a duplicate
+ * workspace project when the project id has not been saved yet.
+ */
+export async function findBuilderProjectForRepo(args) {
+    const repoUrl = normalizeBuilderRepoUrl(args.repoUrl);
+    const creds = await resolveBuilderApiCredentials();
+    const url = new URL("/projects", getBuilderApiHost());
+    url.searchParams.set("apiKey", creds.publicKey);
+    url.searchParams.set("includeHidden", "true");
+    const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${creds.privateKey}` },
+    });
+    const parsed = await readBuilderApiObject(response, "project lookup");
+    if (!response.ok) {
+        throw new Error(builderApiErrorMessage(parsed, `Builder project lookup failed (${response.status})`));
+    }
+    if (!Array.isArray(parsed.projects)) {
+        throw new Error("Builder project lookup returned no projects list");
+    }
+    const comparableRepoUrl = comparableBuilderRepoUrl(repoUrl);
+    for (const project of parsed.projects) {
+        const normalized = builderProjectFromRecord(project, null, false);
+        if (normalized &&
+            comparableBuilderRepoUrl(normalized.repoUrl) === comparableRepoUrl) {
+            return normalized;
+        }
+    }
+    return null;
+}
+/**
+ * Create a Builder project connected to a repository through the public
+ * projects API. This is the server-side bridge used by Dispatch; online
+ * Claude and ChatGPT hosts do not need a separate Builder CMS MCP connector.
+ */
+export async function createBuilderProject(args) {
+    const name = normalizeBuilderProjectString(args.name, "project name");
+    const repoUrl = normalizeBuilderRepoUrl(args.repoUrl);
+    const creds = await resolveBuilderApiCredentials();
+    const url = new URL("/projects/create", getBuilderApiHost());
+    url.searchParams.set("apiKey", creds.publicKey);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${creds.privateKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            source: { kind: "repo", repoUrl },
+            name,
+        }),
+    });
+    const parsed = await readBuilderApiObject(response, "project creation");
+    if (!response.ok) {
+        throw new Error(builderApiErrorMessage(parsed, `Builder project creation failed (${response.status})`));
+    }
+    const project = builderProjectFromRecord(parsed.project, repoUrl, true);
+    if (!project) {
+        throw new Error("Builder project creation returned no project id");
+    }
+    return project;
+}
+/**
+ * Reuse a connected Builder project or create it once when Dispatch is first
+ * used for a workspace. The lookup and create calls intentionally stay in
+ * this shared server helper so all callers use the same authenticated path.
+ */
+export async function ensureBuilderProject(args) {
+    const existing = await findBuilderProjectForRepo({ repoUrl: args.repoUrl });
+    return existing ?? createBuilderProject(args);
+}
 function normalizeBuilderBranchUrl(value) {
     const urlString = normalizeBuilderApiString(value, "url");
     let parsed;

package/dist/server/core-routes-plugin.d.ts

@@ -288,6 +288,11 @@ interface LegacyCoreRouteInitSettings {
 }
 type CoreRouteSettingReader = (key: string) => Promise<Record<string, unknown> | null>;
 export declare function readLegacyCoreRouteInitSettings(readSetting?: CoreRouteSettingReader): Promise<LegacyCoreRouteInitSettings>;
+/**
+ * Production release jobs own schema setup. Request functions must not spend
+ * their cold-start budget on legacy cleanup or best-effort table warmups.
+ */
+export declare function shouldRunCoreRouteBootDatabaseWork(env?: NodeJS.ProcessEnv): boolean;
 export declare function createCoreRoutesPlugin(options?: CoreRoutesPluginOptions): NitroPluginDef;
 /**
  * Default core routes plugin — mount with no configuration needed.