@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/agent/tools/databases/dev-database-tasks.js

@@ -0,0 +1,1172 @@
+import { z } from "zod";
+import { DATABASE_LIFECYCLE_MANAGED_BY, sanitizeLifecycleProviderDiagnostics, } from "@superblocksteam/shared";
+import { getLogger } from "../../../../util/logger.js";
+import { DevDatabaseClientError } from "../../../dev-database-client.js";
+import { mentionSafeTagName as toMentionSafeCharset } from "../../../integrations/mention-safe-tag-name.js";
+import { scrubSecrets, stripUnsafeChars } from "../../../types.js";
+import { PermissionLevel, ToolCategory } from "../../tools2/types.js";
+import { declaresDestructiveChange } from "./destructive-migration-prompt.js";
+export {};
+// Master parity: the only user-controlled requirement fields are
+// `logicalName` and (optionally) `migrationDirectory`. Engine, extensions,
+// sizing, replicaCount, version, and the editor-mode profile are
+// platform-controlled — the server resolves them from the org's
+// lifecycle policy, so exposing them on the LLM surface would let Clark
+// invent values the platform later overrides.
+const databaseRequirementSchema = z.object({
+    logicalName: z
+        .string()
+        .min(1)
+        .describe("The app-local database name. Becomes the lifecycle integration's display name. When wiring SDK APIs, derive a valid lowercase snake_case integrations map key from this name (replace non-alphanumeric with _, prefix db_ if empty/digit-leading/reserved; disambiguate collisions). Examples: 'pokemon_tracker' → pokemon_tracker; 'Orders DB' → orders_db. Do not use a generic key like 'db'."),
+    migrationDirectory: z
+        .string()
+        .optional()
+        .describe("Repo-relative path to the directory holding the app's SQL migrations. Set this explicitly when provisionDatabase should enable startApplyDevDatabaseMigrations; `db/migrations/` is the recommended convention. Files inside must match `<digits>_<description>.sql` (e.g. `0001_init.sql`, `0002_add_users.sql`); the leading digits are the sort key and the runner applies them in lexicographic order against the in-DB ledger. Migrations run in authoring and on production deploys — put seed/INSERT rows here only when deployed apps will always need that data; for authoring-only test/demo data insert at runtime against the integration instead of a .sql seed migration."),
+});
+const provisionInputSchema = z.object({
+    requirement: databaseRequirementSchema,
+});
+const provisionHandleSchema = z.object({
+    bindingKey: z.string().min(1),
+    engine: z.string().optional(),
+    integrationId: z.string().optional(),
+    lifecycleState: z.string().optional(),
+    logicalName: z.string().optional(),
+    // Datatag (Profile.key) this task is tracking. Set when ensure fans out.
+    profile: z.string().min(1).optional(),
+    // Correlates to the server-side lifecycle_request row for oncall/debug
+    // (mirrors ApplyMigrationsHandle). Persisted on the task handle so
+    // classified failures still carry a durable request id even when the
+    // user-facing error string omits it.
+    requestId: z.string().min(1).optional(),
+    requirement: databaseRequirementSchema,
+    // Watch tasks this fan-out started for the other datatags. Clark waits on
+    // the primary task only, so the primary reports success only once these are
+    // done — the migrate step that follows skips datatags that are not ready.
+    siblingTaskIds: z.array(z.string().min(1)).optional(),
+    // Total editor datatags this ensure covered (including this task). Used
+    // by the kickoff tool title to show "N tags".
+    tagCount: z.number().int().positive().optional(),
+    // Sibling watches set this so poll uses migrationState (not lifecycleState)
+    // after ensure already left the binding ready.
+    watchKind: z.enum(["provision", "migration"]).optional(),
+});
+/** Poll-only sibling for a fanned-out ensure/migrate target (no second kickoff). */
+const watchProvisionInputSchema = z.object({
+    bindingKey: z.string().min(1),
+    logicalName: z.string().min(1),
+    profile: z.string().min(1),
+    requestId: z.string().min(1).optional(),
+    initialFailed: z.boolean().optional(),
+    initialError: z.string().optional(),
+    // provision: complete when lifecycleState is terminal.
+    // migration: complete when migrationState is migrated/failed (binding may
+    // already be ready from ensure).
+    watchKind: z.enum(["provision", "migration"]).optional(),
+});
+export const watchDevDatabaseProvisionTaskMetadata = {
+    category: ToolCategory.DATA,
+    defaultPermission: PermissionLevel.ALLOW,
+    description: "Internal: poll lifecycle progress for one fanned-out datatag binding. Not for direct LLM use.",
+    externalHandleSchema: provisionHandleSchema,
+    inputSchema: watchProvisionInputSchema,
+    name: "watchDevDatabaseProvision",
+    pollSchedule: { factor: 1.5, initialMs: 2_000, maxMs: 30_000 },
+};
+// Clark must not pin migrate to a provision-primary bindingKey. The server
+// fans out migrate_schema across every eligible editor Environments datatag
+// (ENG-3469). The only LLM-facing fields are the three that describe a
+// deletion; filling any of them is what puts the apply behind a confirmation
+// card. There is no acknowledgement flag: the acknowledgement the server wants
+// is issued by this client only after the user answers that card, so Clark
+// cannot authorize its own destructive apply.
+const applyMigrationsInputSchema = z.object({
+    destructiveChangeDetails: z
+        .string()
+        .optional()
+        .describe("What the migrations about to run will delete, written for the person approving (for example: 'The 0004_drop_orders.sql migration deletes the orders table, including the 1,200 orders in it.'). Name the tables, columns, and rows in plain words - no SQL, no file paths the reader cannot act on. One short line per migration file. Shown on the confirmation card under 'What changes'."),
+    destructiveChangeReason: z
+        .string()
+        .optional()
+        .describe("One short sentence saying why the deletion is needed, written for the person approving (for example: 'Orders now live in the purchases table this app just built.'). Shown on the confirmation card under 'Why'."),
+    destructiveChangeSummary: z
+        .string()
+        .optional()
+        .describe("The deletion as a short phrase that completes the question 'Ok if I ...?' - for example 'delete the orders table and the 1,200 rows in it' or 'make 3 changes that delete data'. No leading 'Ok if I', no trailing question mark, and do not mention the database (the card says which one). Shown as the confirmation card's headline, so it is the one line the user is guaranteed to read."),
+});
+const applyMigrationsHandleSchema = z.object({
+    bindingKey: z.string().min(1).optional(),
+    // Captured at start() so entityTag can still be built if a later
+    // poll/migrated envelope omits logicalName (optional on the response).
+    logicalName: z.string().optional(),
+    requestId: z.string().min(1),
+    siblingTaskIds: z.array(z.string().min(1)).optional(),
+});
+/**
+ * Module-scoped metadata for the provision-dev-database background task.
+ *
+ * Split out from the live TaskType (which needs per-session closure
+ * deps for `start`/`poll`) so the LLM-facing `provisionDatabase`
+ * ToolFactory can be built at module load with `defineBackgroundTaskFactory`
+ * while the executable type is registered per-session in the TaskStore.
+ * Both surfaces share `name`/`description`/`inputSchema` here, so they
+ * cannot drift.
+ */
+export const provisionDevDatabaseTaskMetadata = {
+    category: ToolCategory.DATA,
+    // ALLOW: createDevDb is idempotent when the requested logical database
+    // matches the existing app+profile binding. A differently named database
+    // is rejected because an application supports only one App Database.
+    defaultPermission: PermissionLevel.ALLOW,
+    // Substance mirrors master's `createDevDb`: App Database binding
+    // (Aurora or RDS depending on the Superblocks environment — never
+    // hard-code either product; APPS-5377), returns lifecycle progress.
+    // Engine/extensions and the editor-mode profile are
+    // platform-controlled, so they're not in the input. BG wrapping
+    // (taskId, don't waitForTask, check first) is the only behavioral
+    // delta from master.
+    description: "Create the application's dev App Database binding, or reuse it when the same logical database was already provisioned, as a BACKGROUND TASK. Only one App Database per application is supported; never reinterpret a request for another database as a request to add tables or migrations to the existing database. Clark provisions a cloud Postgres database (Amazon Aurora or Amazon RDS depending on the Superblocks environment — do NOT assume either product) and returns lifecycle progress. Returns a taskId IMMEDIATELY while provisioning runs in the background; the user already sees live progress in the chat's background-tasks indicator. " +
+        "DO NOT call waitForTask right after this — that defeats the whole point of a background task and blocks your turn for minutes while the database spins up. Instead: keep working on whatever does NOT depend on the database (scaffold the UI, draft API code that will use the binding, write SQL migration files, plan next steps). When you reach a step that genuinely cannot proceed without the connection details, FIRST call checkTask({ taskId }) — it returns instantly. Only fall back to waitForTask if checkTask still reports state='running' AND you literally have no other useful work to do. " +
+        'On completion the result includes bindingKey, integrationId, entityTag, lifecycleState, connectionMetadata, and providerLabel. App Database bindings use IAM authentication. Use providerLabel when naming the cloud product in user-facing chat (e.g. "Amazon Aurora" or "App Database"); NEVER invent "RDS" or "Aurora" when providerLabel is absent or says "App Database" — Aurora still uses the AWS RDS API and *.rds.amazonaws.com hostnames. Use integrationId only for tool inputs or generated source code such as postgres(...). MUST NEVER paste bare integrationId UUIDs or phrases like "Integration ID is …" in user-facing chat — when referring to this managed database for the user, paste entityTag (e.g. @OrdersDB[id=…]) so the UI shows a name sticker. When declaring the integration in an SDK API, derive a valid lowercase snake_case integrations map key from requirement.logicalName (normalize non-alphanumeric to _, prefix db_ if needed, disambiguate collisions; e.g. pokemon_tracker → pokemon_tracker: postgres(POKEMON_TRACKER), Orders DB → orders_db) so code and TraceView match the database name — never a generic key like db. This task ONLY creates the database server + an integration; it does NOT apply SQL migrations — query attempts will fail with `relation "X" does not exist` until you call startApplyDevDatabaseMigrations. Cancellation only stops local polling; the underlying cloud provisioning continues on the server.',
+    externalHandleSchema: provisionHandleSchema,
+    inputSchema: provisionInputSchema,
+    name: "provisionDatabase",
+    pollSchedule: { factor: 1.5, initialMs: 2_000, maxMs: 30_000 },
+};
+/**
+ * Module-scoped metadata for the apply-dev-database-migrations background
+ * task. See `provisionDevDatabaseTaskMetadata` for the rationale.
+ */
+export const applyDevDatabaseMigrationsTaskMetadata = {
+    category: ToolCategory.DATA,
+    // ALLOW for additive migrations. An apply Clark says deletes something
+    // escalates to a confirmation card via getRequiredPermissions (see the tool
+    // factory), and an apply that declares nothing is refused by the server when
+    // it turns out to contain destructive SQL.
+    //
+    // Be precise about the guarantee: the acknowledgment is one boolean for the
+    // whole apply, not per statement. It says "a person approved this call", not
+    // "every deletion in it was described". A partial declaration - Clark spots
+    // one DROP and misses another in the same apply - still authorizes both, and
+    // the card only describes what Clark wrote. Closing that needs the server to
+    // hand back a token over its findings and the retry to send it back; the
+    // guidance below leans on Clark covering every flagged statement until then.
+    defaultPermission: PermissionLevel.ALLOW,
+    // Substance mirrors master's `applyMigrations`: SQL files come from the
+    // binding's `migrationDirectory` set on provisionDatabase (no implicit
+    // default — older copy claimed `db/migrations/` would be loaded
+    // automatically, which is a lie when provisionDatabase didn't set
+    // one). BG wrapping (taskId, don't waitForTask, check first) is the
+    // only behavioral delta from master.
+    description: "Run the application's working-state SQL migrations against every eligible editor datatag binding for this application's App Databases as a BACKGROUND TASK. Returns a taskId IMMEDIATELY; the user already sees live progress in the chat's background-tasks indicator. " +
+        "DO NOT call waitForTask right after this — that defeats the whole point of a background task and blocks your turn while migrations run. Instead: keep working on anything that does not need migrations to have landed yet (UI scaffolding, additional API code, the next migration file). When you reach a step that genuinely needs migrationState='migrated' (for example, executing a SELECT against the new tables), FIRST call checkTask({ taskId }) — it returns instantly. Only fall back to waitForTask if checkTask still reports state='running' AND there is nothing else useful to do. " +
+        "REQUIRED after provisionDatabase if any application tables need to exist — provisioning only creates an empty App Database. Reads SQL files from each binding's migrationDirectory set on provisionDatabase and applies any not yet recorded in the in-DB migration ledger; if provisionDatabase did not set a migrationDirectory, no SQL files are loaded. Seed/INSERT rows belong in migrations only when deployed apps will always need that data; for authoring-only test/demo data insert at runtime against the integration instead of a .sql seed file. Re-firing is safe; already-applied versions are skipped. The terminal result includes migrationState='migrated' on success. " +
+        "If any migration this apply will run deletes something (DROP TABLE/DATABASE/SCHEMA, TRUNCATE, DROP COLUMN), say so on THIS call by filling destructiveChangeSummary, destructiveChangeDetails, and destructiveChangeReason. Those three are the plain-language copy on the confirmation card, so write them for a non-technical builder and cover every deleting statement - the user sees your copy and nothing else, so anything you leave out gets deleted without them knowing. Filling them pauses this call, shows the card, and resumes the same call automatically if the user approves; you do not need to ask in chat, set any acknowledgement, or call this tool again. If you do not declare it and the server returns errorCode DESTRUCTIVE_MIGRATION_ACK_REQUIRED, nothing has run: call again with those three fields filled in. Never run the migration another way (for example raw SQL) or tell the user to drop objects manually.",
+    externalHandleSchema: applyMigrationsHandleSchema,
+    inputSchema: applyMigrationsInputSchema,
+    name: "startApplyDevDatabaseMigrations",
+    pollSchedule: { factor: 1.5, initialMs: 1_000, maxMs: 10_000 },
+};
+const TERMINAL_LIFECYCLE_STATES = new Set([
+    "ready",
+    "failed",
+    "cancelled",
+]);
+/** Max length for code/message/requestId/providerLabel in agent-facing
+ *  lifecycle fields. Matches `SAFE_INTERP_MAX_LEN` in build-install-packages.ts
+ *  so a multi-KB provider string cannot crowd out the rest of agent context. */
+const LIFECYCLE_FAILURE_FIELD_MAX_LEN = 100;
+const LIFECYCLE_PROVIDER_DIAGNOSTICS_DETAIL_MAX_LEN = 512;
+function sanitizeLifecycleFailureText(value, maxLength) {
+    // Defense-in-depth for LLM-facing task fields: server already redacts
+    // credential material, but worker messages / labels can still carry
+    // newlines / backticks that would otherwise reach agent context verbatim.
+    const scrubbed = stripUnsafeChars(scrubSecrets(value)).trim();
+    return scrubbed.length > maxLength
+        ? `${scrubbed.slice(0, maxLength - 1).trimEnd()}…`
+        : scrubbed;
+}
+function sanitizeLifecycleFailureField(value) {
+    const scrubbed = stripUnsafeChars(scrubSecrets(value)).trim();
+    return scrubbed.length > LIFECYCLE_FAILURE_FIELD_MAX_LEN
+        ? `${scrubbed.slice(0, LIFECYCLE_FAILURE_FIELD_MAX_LEN)}…`
+        : scrubbed;
+}
+function sanitizeProviderDiagnostics(diagnostics) {
+    return (sanitizeLifecycleProviderDiagnostics(diagnostics) ?? []).map((diagnostic) => {
+        if (diagnostic.provider === "aws") {
+            return {
+                errorCode: sanitizeLifecycleFailureField(diagnostic.errorCode),
+                nextAction: diagnostic.nextAction,
+                operation: sanitizeLifecycleFailureField(diagnostic.operation),
+                phase: diagnostic.phase,
+                provider: diagnostic.provider,
+                ...(diagnostic.requestId
+                    ? {
+                        requestId: sanitizeLifecycleFailureField(diagnostic.requestId),
+                    }
+                    : {}),
+                retryable: diagnostic.retryable,
+                service: sanitizeLifecycleFailureField(diagnostic.service),
+            };
+        }
+        return {
+            nextAction: diagnostic.nextAction,
+            phase: diagnostic.phase,
+            provider: diagnostic.provider,
+            retryable: diagnostic.retryable,
+            sqlState: sanitizeLifecycleFailureField(diagnostic.sqlState),
+        };
+    });
+}
+const DEFAULT_PROVIDER_LABEL = "App Database";
+/**
+ * APPS-5377: Clark historically assumed "Amazon RDS" because tool copy
+ * hard-coded it. Aurora Serverless still uses the RDS API and
+ * `*.rds.amazonaws.com` hostnames (including Multi-AZ cluster writers
+ * that share the `*.cluster-*` DNS pattern with Aurora), so hostname
+ * sniffing replaces one confident mislabel with another.
+ *
+ * Keep the generic `App Database` label unless the backend explicitly
+ * supplies `providerLabel` / `provider_label` on the lifecycle response
+ * or connectionMetadata.
+ */
+export function inferManagedDatabaseProviderLabel(connectionMetadata) {
+    // Prefer an explicit backend hint if present (future / passthrough).
+    const explicit = connectionMetadata?.providerLabel ?? connectionMetadata?.provider_label;
+    if (typeof explicit === "string" && explicit.trim()) {
+        return {
+            providerLabel: explicit.trim(),
+            source: "connectionMetadata",
+        };
+    }
+    return { providerLabel: DEFAULT_PROVIDER_LABEL, source: "default" };
+}
+function sanitizeProviderLabel(value) {
+    const scrubbed = sanitizeLifecycleFailureField(value);
+    return scrubbed.length > 0 ? scrubbed : DEFAULT_PROVIDER_LABEL;
+}
+function withProviderLabel(response) {
+    if (response.providerLabel) {
+        const providerLabel = sanitizeProviderLabel(response.providerLabel);
+        getLogger().debug({
+            bindingKey: response.bindingKey,
+            requestId: response.requestId,
+            providerLabel,
+            source: "server",
+        }, "[devDatabase] using server-provided providerLabel");
+        return providerLabel === response.providerLabel
+            ? response
+            : { ...response, providerLabel };
+    }
+    const { providerLabel: inferredLabel, source } = inferManagedDatabaseProviderLabel(response.connectionMetadata);
+    const providerLabel = sanitizeProviderLabel(inferredLabel);
+    getLogger().debug({
+        bindingKey: response.bindingKey,
+        requestId: response.requestId,
+        providerLabel,
+        source,
+    }, source === "connectionMetadata"
+        ? "[devDatabase] using providerLabel from connectionMetadata"
+        : "[devDatabase] using generic providerLabel (prefer server field when available)");
+    return {
+        ...response,
+        providerLabel,
+    };
+}
+function toToolError(error) {
+    if (error instanceof DevDatabaseClientError) {
+        return new Error(`${error.code}: ${error.message}`);
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+// Plain-language, action-first copy for the chat checklist row (clamped,
+// no LLM in the loop). Keep free of internal tool/OPA jargon — builders
+// are the audience, not oncall (ENG-4712 / Wylie review on #20678).
+// Tables are split by action so shared codes (e.g. backend_locked) do not
+// say "Database setup…" / "retry the provisioning task" on migrate fails.
+const LIFECYCLE_FAILURE_USER_MESSAGE = {
+    "dev database provisioning": {
+        backend_locked: "Database setup is briefly busy. Try again in a moment.",
+        callback_failed: "Database setup didn't finish reporting status. Try again.",
+        credential_resolution_failed: "Database setup couldn't access required credentials. Contact your admin, then try again.",
+        migration_failed: "A database schema update failed. Check your migration SQL, then try again.",
+        policy_blocked: "Your organization blocked this database operation. Contact your admin.",
+        terraform_failed: "Cloud database setup failed. Check cloud credentials with your admin, then try again.",
+        unsupported_provider_capability: "This database operation isn't supported in your environment. Contact your admin.",
+    },
+    "applying migrations": {
+        backend_locked: "Database schema update is briefly busy. Try again in a moment.",
+        callback_failed: "Database schema update didn't finish reporting status. Try again.",
+        credential_resolution_failed: "Database schema update couldn't access required credentials. Contact your admin, then try again.",
+        migration_failed: "A database schema update failed. Check your migration SQL, then try again.",
+        policy_blocked: "Your organization blocked this database operation. Contact your admin.",
+        terraform_failed: "Cloud database setup failed. Check cloud credentials with your admin, then try again.",
+        unsupported_provider_capability: "This database operation isn't supported in your environment. Contact your admin.",
+    },
+};
+// Agent/oncall next-step hints (checkTask/waitForTask `detail` only).
+// Only codes the worker already redacts/sanitizes before shipping to the
+// control plane — never raw terraform/provider stderr (see ENG-4712).
+const LIFECYCLE_FAILURE_AGENT_GUIDANCE = {
+    "dev database provisioning": {
+        backend_locked: "This is usually transient; retry the provisioning task.",
+        callback_failed: "The agent failed to report a terminal result; retry, and check the database-lifecycle worker if it persists.",
+        credential_resolution_failed: "Credentials could not be resolved for the worker; verify secrets configuration, then retry.",
+        migration_failed: "A schema migration failed during provisioning; inspect the migration SQL, fix it, then retry the provisioning task.",
+        policy_blocked: "An organization policy blocked this operation; adjust policy or agent capability coverage, then retry.",
+        terraform_failed: "Infrastructure provisioning failed on the agent; verify OPA/database-lifecycle worker setup and cloud credentials, then retry.",
+        unsupported_provider_capability: "The agent does not support this database operation; update OPA lifecycle configuration, then retry.",
+    },
+    "applying migrations": {
+        backend_locked: "This is usually transient; retry startApplyDevDatabaseMigrations.",
+        callback_failed: "The agent failed to report a terminal result; retry startApplyDevDatabaseMigrations, and check the database-lifecycle worker if it persists.",
+        credential_resolution_failed: "Credentials could not be resolved for the worker; verify secrets configuration, then retry startApplyDevDatabaseMigrations.",
+        migration_failed: "A schema migration failed; inspect the migration SQL, fix it, then retry startApplyDevDatabaseMigrations.",
+        policy_blocked: "An organization policy blocked this operation; adjust policy or agent capability coverage, then retry.",
+        terraform_failed: "Infrastructure provisioning failed on the agent; verify OPA/database-lifecycle worker setup and cloud credentials, then retry.",
+        unsupported_provider_capability: "The agent does not support this database operation; update OPA lifecycle configuration, then retry.",
+    },
+};
+function formatProviderDiagnostics(diagnostics) {
+    if (!diagnostics?.length) {
+        return undefined;
+    }
+    const details = sanitizeProviderDiagnostics(diagnostics).flatMap((diagnostic) => {
+        const phase = sanitizeLifecycleFailureField(diagnostic.phase);
+        if (diagnostic.provider === "aws") {
+            const service = sanitizeLifecycleFailureField(diagnostic.service.toUpperCase());
+            const operation = sanitizeLifecycleFailureField(diagnostic.operation);
+            const errorCode = sanitizeLifecycleFailureField(diagnostic.errorCode);
+            if (!service || !operation || !errorCode) {
+                return [];
+            }
+            const requestId = diagnostic.requestId
+                ? sanitizeLifecycleFailureField(diagnostic.requestId)
+                : "";
+            return [
+                `${service} ${operation} failed with ${errorCode}${requestId ? ` (request ${requestId})` : ""} during ${phase}`,
+            ];
+        }
+        const sqlState = sanitizeLifecycleFailureField(diagnostic.sqlState);
+        return sqlState
+            ? [`PostgreSQL failed with SQLSTATE ${sqlState} during ${phase}`]
+            : [];
+    });
+    return details.length > 0
+        ? sanitizeLifecycleFailureText(`Provider diagnostics: ${details.join("; ")}`, LIFECYCLE_PROVIDER_DIAGNOSTICS_DETAIL_MAX_LEN)
+        : undefined;
+}
+function formatLifecycleTaskFailure(action, response, 
+// Durable id from the persisted task handle when progress omits it
+// (Scout / Bugbot: ProvisionHandle.requestId must be read, not only written).
+fallbackRequestId) {
+    const code = response.errorCode
+        ? sanitizeLifecycleFailureField(response.errorCode)
+        : "";
+    const message = response.errorMessage
+        ? sanitizeLifecycleFailureField(response.errorMessage)
+        : "";
+    const rawRequestId = response.requestId || fallbackRequestId || "";
+    const requestId = rawRequestId
+        ? sanitizeLifecycleFailureField(rawRequestId)
+        : "";
+    const requestSuffix = requestId ? `, request ${requestId}` : "";
+    // Prefer the classified reason the server already surfaces. Always keep
+    // requestId in `detail` when present so oncall can correlate to the
+    // lifecycle_request row (Scout review on #20678).
+    let detail;
+    if (code && message) {
+        detail = `${action} failed (${code}${requestSuffix}): ${message}`;
+    }
+    else if (message) {
+        detail = requestId
+            ? `${action} failed (request ${requestId}): ${message}`
+            : `${action} failed: ${message}`;
+    }
+    else if (code) {
+        detail = `${action} failed (${code}${requestSuffix})`;
+    }
+    else if (requestId) {
+        detail = `${action} failed (request ${requestId})`;
+    }
+    else {
+        detail = `${action} failed`;
+    }
+    const providerDiagnostics = formatProviderDiagnostics(response.errorDiagnostics);
+    if (providerDiagnostics) {
+        detail = `${detail}. ${providerDiagnostics}`;
+    }
+    const agentGuidance = code
+        ? LIFECYCLE_FAILURE_AGENT_GUIDANCE[action][code]
+        : undefined;
+    if (agentGuidance) {
+        detail = `${detail}. ${agentGuidance}`;
+    }
+    const userDefault = action === "applying migrations"
+        ? "A database schema update failed. Try again, or contact support if it keeps happening."
+        : "Database setup failed. Try again, or contact support if it keeps happening.";
+    const error = (code ? LIFECYCLE_FAILURE_USER_MESSAGE[action][code] : undefined) ??
+        userDefault;
+    return { error, detail };
+}
+/**
+ * Keep only characters the chat mention parser accepts inside `@Name[id=…]`
+ * (letters, numbers, `_` `.` `-` `$`, and interior spaces). Scrub secrets /
+ * unsafe chars and cap length like sibling lifecycle fields so a long
+ * `logicalName` cannot inflate completed task results fed back to the model.
+ * Punctuation such as `()`, `/`, brackets, or apostrophes would otherwise
+ * prevent a match and leave the raw `[id=<uuid>]` visible in assistant text.
+ * Display name still comes from entity lookup by id when the tag resolves.
+ */
+export function mentionSafeTagName(name) {
+    const scrubbed = stripUnsafeChars(scrubSecrets(name)).trim();
+    const sanitized = toMentionSafeCharset(scrubbed);
+    const capped = sanitized.length > LIFECYCLE_FAILURE_FIELD_MAX_LEN
+        ? sanitized.slice(0, LIFECYCLE_FAILURE_FIELD_MAX_LEN).trimEnd()
+        : sanitized;
+    return capped || "entity";
+}
+/**
+ * Attach `@logicalName[id=integrationId]` for user-facing chat stickers.
+ * Uses a parser-safe label derived from logicalName. Keeps integrationId
+ * available for codegen.
+ */
+function withEntityTag(response, fallbackLogicalName) {
+    if (response.entityTag) {
+        return response;
+    }
+    const name = response.logicalName ?? fallbackLogicalName;
+    if (!response.integrationId || !name) {
+        if (response.integrationId && !name) {
+            getLogger().warn("[devDatabase] cannot attach entityTag: response missing logicalName and no fallback provided; chat may only have bare integrationId");
+        }
+        return response;
+    }
+    return {
+        ...response,
+        entityTag: `@${mentionSafeTagName(name)}[id=${response.integrationId}]`,
+    };
+}
+/** A completed task hands its whole result to the LLM, so per-datatag error text
+ *  needs the same scrubbing a top-level failure gets. Partial success is the
+ *  common case here: the task completes while some datatags carry provider
+ *  errors. */
+function withSanitizedTargets(response) {
+    const { errorDiagnostics, ...responseWithoutDiagnostics } = response;
+    const sanitizedResponseDiagnostics = sanitizeProviderDiagnostics(errorDiagnostics);
+    if (!response.targets || response.targets.length === 0) {
+        return {
+            ...responseWithoutDiagnostics,
+            ...(sanitizedResponseDiagnostics.length > 0
+                ? { errorDiagnostics: sanitizedResponseDiagnostics }
+                : {}),
+        };
+    }
+    return {
+        ...responseWithoutDiagnostics,
+        ...(sanitizedResponseDiagnostics.length > 0
+            ? { errorDiagnostics: sanitizedResponseDiagnostics }
+            : {}),
+        targets: response.targets.map((target) => {
+            const { errorDiagnostics: targetDiagnostics, ...targetWithoutDiagnostics } = target;
+            const sanitizedTargetDiagnostics = sanitizeProviderDiagnostics(targetDiagnostics);
+            return {
+                ...targetWithoutDiagnostics,
+                ...(target.errorCode
+                    ? { errorCode: sanitizeLifecycleFailureField(target.errorCode) }
+                    : {}),
+                ...(sanitizedTargetDiagnostics.length > 0
+                    ? { errorDiagnostics: sanitizedTargetDiagnostics }
+                    : {}),
+                ...(target.errorMessage
+                    ? { errorMessage: sanitizeLifecycleFailureField(target.errorMessage) }
+                    : {}),
+            };
+        }),
+    };
+}
+const REGISTERING_CONNECTION_MESSAGE = "Database provisioned; registering the connection";
+/**
+ * When the server says runtime config is not ready yet, keep the task running
+ * so Clark does not treat a vacant `{}` projection as executable (ENG-5285).
+ * Older servers omit the fields — preserve prior complete-on-ready behavior,
+ * except the migrate-then-project case (ready + migration still pending).
+ */
+function awaitingRuntimeConfiguration(response) {
+    if (response.runtimeConfigurationReady !== false) {
+        return false;
+    }
+    if (typeof response.expectsRuntimeConfiguration === "boolean") {
+        return response.expectsRuntimeConfiguration;
+    }
+    // Compat for servers that only send runtimeConfigurationReady: projection
+    // was historically deferred until migrate, so pending migration may complete.
+    return response.migrationState !== "pending";
+}
+function enrichCompletedResponse(response, fallbackLogicalName) {
+    return withEntityTag(withProviderLabel(withSanitizedTargets(response)), fallbackLogicalName);
+}
+function lifecycleStatusFor(response, fallbackRequestId, fallbackLogicalName) {
+    switch (response.lifecycleState) {
+        case "ready":
+            if (awaitingRuntimeConfiguration(response)) {
+                return {
+                    state: "running",
+                    message: REGISTERING_CONNECTION_MESSAGE,
+                };
+            }
+            return {
+                state: "completed",
+                result: enrichCompletedResponse(response, fallbackLogicalName),
+            };
+        case "failed": {
+            const { error, detail } = formatLifecycleTaskFailure("dev database provisioning", response, fallbackRequestId);
+            return { state: "failed", error, detail };
+        }
+        case "cancelled":
+            return { state: "cancelled" };
+        default:
+            // pending / provisioning / migrating / retiring — still working.
+            return { state: "running", message: response.lifecycleState };
+    }
+}
+function migrationStatusFor(response, fallbackRequestId, fallbackLogicalName) {
+    switch (response.migrationState) {
+        case "migrated":
+            if (awaitingRuntimeConfiguration(response)) {
+                return {
+                    state: "running",
+                    message: REGISTERING_CONNECTION_MESSAGE,
+                };
+            }
+            return {
+                state: "completed",
+                result: enrichCompletedResponse(response, fallbackLogicalName),
+            };
+        case "failed": {
+            const { error, detail } = formatLifecycleTaskFailure("applying migrations", response, fallbackRequestId);
+            return { state: "failed", error, detail };
+        }
+        case "pending":
+        default:
+            return { state: "running", message: response.migrationState };
+    }
+}
+function isPreconditionFailure(response) {
+    return ("ok" in response && response.ok === false && !("bindingKey" in response));
+}
+const DEFAULT_MIGRATION_TASK_LABEL = "the database schema update";
+const MAX_MIGRATION_FILENAMES_IN_TASK_LABEL = 3;
+/**
+ * Deterministic next step for Clark when the server blocks a destructive
+ * migration it did not declare. This is the backstop, not the main path: when
+ * Clark fills the `destructiveChange*` fields the confirmation card is raised
+ * before anything reaches the server, and no block happens.
+ *
+ * Kept out of the length-capped `error` field (see the precondition branch
+ * below): `error` is clamped to LIFECYCLE_FAILURE_FIELD_MAX_LEN, so the
+ * instruction and the list of blocked statements would truncate and Clark
+ * would improvise (for example try to run the DROP as raw SQL, or tell the
+ * user to drop the object by hand). `detail` is not clamped, so the whole
+ * instruction reaches the model verbatim.
+ *
+ * Clark writes the user-facing copy because it is the only party holding both
+ * the migration SQL and the conversation that asked for it; the statements the
+ * server flagged are appended below so the copy can account for all of them.
+ */
+const DESTRUCTIVE_MIGRATION_ACK_AGENT_GUIDANCE = "Nothing ran: these migrations delete something, and you did not say so on " +
+    "the call. Call startApplyDevDatabaseMigrations again with " +
+    "destructiveChangeSummary, destructiveChangeDetails, and " +
+    "destructiveChangeReason filled in: plain-language copy, written for a " +
+    "non-technical builder, saying what each flagged statement deletes and why " +
+    "it is needed. Read the migration files if you need to before writing it. " +
+    "Cover every statement listed below - the user sees only your copy, so " +
+    "anything you leave out is deleted without them knowing. If the list ends " +
+    "with a count of statements it did not show, say that total on the card and " +
+    "describe the rest in aggregate (how many files, what kinds of deletion) " +
+    "rather than writing as though the ones you can see are all of them. That " +
+    "call shows the user a confirmation card and resumes by itself when they " +
+    "approve, so there is no acknowledgement flag to set and nothing to ask in " +
+    "chat. Do not run the SQL another way and do not ask the user to drop " +
+    "objects manually.";
+const MAX_FLAGGED_STATEMENTS_IN_AGENT_DETAIL = 25;
+/**
+ * The blocked statements, for the uncapped `detail` field. Each field is
+ * sanitized on its own so a hostile filename cannot smuggle newlines or
+ * backticks into agent context, and the list is bounded so a migration set
+ * with hundreds of drops cannot crowd out the instruction above it.
+ */
+function flaggedStatementsForAgent(findings) {
+    if (findings.length === 0) {
+        return "";
+    }
+    const listed = findings
+        .slice(0, MAX_FLAGGED_STATEMENTS_IN_AGENT_DETAIL)
+        .map((finding) => `${sanitizeLifecycleFailureField(finding.fileName)} (${sanitizeLifecycleFailureField(finding.kind)})`)
+        .join("; ");
+    const hidden = findings.length - MAX_FLAGGED_STATEMENTS_IN_AGENT_DETAIL;
+    if (hidden <= 0) {
+        return ` Statements the server flagged (${findings.length} total): ${listed}.`;
+    }
+    // The total goes first: Clark is told to cover every statement, and without
+    // the total it cannot tell that the list it can see is a subset, so it would
+    // write copy that reads as complete while N deletions go undescribed.
+    return (` Statements the server flagged (${findings.length} total, first ` +
+        `${MAX_FLAGGED_STATEMENTS_IN_AGENT_DETAIL} shown): ${listed}; and ` +
+        `${hidden} more not shown here.`);
+}
+const SINGLE_APP_DATABASE_PRECONDITION_AGENT_GUIDANCE = "This application already has an App Database, and only one App Database " +
+    "per application is supported. Explain that limit to the user. Do not add " +
+    "tables, migrations, or schema to the existing database as a substitute for " +
+    "creating another database. Only modify the existing database if the user " +
+    "explicitly asks to.";
+function isSingleAppDatabasePreconditionFailure(response) {
+    return /already has (?:a )?(?:dev |app )?database|only one (?:dev |app )?database per application/i.test(response.errorMessage ?? "");
+}
+function migrationTaskLabel(response) {
+    if (response.migrationState === "failed") {
+        return DEFAULT_MIGRATION_TASK_LABEL;
+    }
+    const migrations = response.dispatchPayload?.migrations;
+    if (migrations === undefined) {
+        return response.migrationState === "migrated"
+            ? "Database migrations already up to date"
+            : DEFAULT_MIGRATION_TASK_LABEL;
+    }
+    if (migrations.length === 0) {
+        return "No database migration files to apply";
+    }
+    // The dispatch always carries every SQL file in the migration directory,
+    // because the worker replays them against its own ledger. Name only the ones
+    // this run adds, so a row for a one-file change does not read like the whole
+    // schema is being rebuilt. Servers that don't report the added files leave us
+    // no way to tell them apart, so fall back to naming the whole set.
+    const applying = response.newMigrationFilenames ??
+        migrations.map(({ filename }) => filename);
+    // An empty added-set is an estimate, not the worker's ledger, and this label
+    // is set once and never revisited. Naming nothing is honest; asserting the
+    // schema is current would stay on screen even if the run then failed.
+    if (applying.length === 0) {
+        return DEFAULT_MIGRATION_TASK_LABEL;
+    }
+    const filenames = applying
+        .slice(0, MAX_MIGRATION_FILENAMES_IN_TASK_LABEL)
+        .map((filename) => sanitizeLifecycleFailureField(filename));
+    if (filenames.some((filename) => filename.length === 0)) {
+        return DEFAULT_MIGRATION_TASK_LABEL;
+    }
+    const remaining = Math.max(0, applying.length - MAX_MIGRATION_FILENAMES_IN_TASK_LABEL);
+    return `Database migrations: ${filenames.join(", ")}${remaining > 0 ? ` (+${remaining} more)` : ""}`;
+}
+function updateProvisionHandleFromResponse(handle, response) {
+    handle.engine = response.engine;
+    handle.integrationId = response.integrationId;
+    handle.lifecycleState = response.lifecycleState;
+    // Poll envelopes may omit logicalName; keep the name captured at task /
+    // watch start so entityTag can still be attached on completion.
+    if (response.logicalName) {
+        handle.logicalName = response.logicalName;
+    }
+    if (response.requestId) {
+        handle.requestId = response.requestId;
+    }
+}
+/**
+ * Build the per-Clark dev-database task types. Closes over the
+ * applicationId + the client factory so the resulting `TaskType`s have
+ * everything they need without touching Clark internals on every call.
+ *
+ * Called once per AiService when the TaskStore is constructed.
+ */
+function provisionLabel(logicalName, profile) {
+    return profile
+        ? `a new database (${logicalName} · ${profile})`
+        : `a new database (${logicalName})`;
+}
+function fanOutTargetsFromResponse(response) {
+    if (response.targets && response.targets.length > 0) {
+        return response.targets;
+    }
+    return [
+        {
+            bindingKey: response.bindingKey,
+            lifecycleState: response.lifecycleState,
+            migrationState: response.migrationState,
+            ok: response.lifecycleState !== "failed" && !response.errorCode,
+            profile: "default",
+            requestId: response.requestId,
+        },
+    ];
+}
+async function spawnSiblingWatchTasks(deps, { logicalName, primaryBindingKey, signal, targets, toolOpts, watchKind = "provision", }) {
+    const taskStore = deps.getTaskStore?.();
+    if (!taskStore) {
+        return [];
+    }
+    const startedTaskIds = [];
+    const ownerUserId = deps.getCurrentOwnerId?.();
+    const siblings = targets.filter((target) => target.bindingKey !== primaryBindingKey);
+    // Spawning is sequential and each start is awaited, so a cancel can land
+    // between siblings or while one is in flight. Stop at the next boundary and
+    // retire the watches this kickoff already created: their parent is gone, so
+    // nobody would consume them and they would keep polling on their own.
+    const stopIfCancelled = async () => {
+        if (signal?.aborted !== true) {
+            return;
+        }
+        await Promise.allSettled(startedTaskIds.map((taskId) => taskStore.cancel(taskId)));
+        signal.throwIfAborted();
+    };
+    for (const target of siblings) {
+        await stopIfCancelled();
+        try {
+            const rawInitialError = !target.ok
+                ? (target.errorMessage ??
+                    target.errorCode ??
+                    (watchKind === "migration"
+                        ? "datatag migration failed"
+                        : "datatag provision failed"))
+                : undefined;
+            const started = await taskStore.start(watchDevDatabaseProvisionTaskMetadata.name, {
+                bindingKey: target.bindingKey,
+                logicalName,
+                profile: target.profile,
+                watchKind,
+                ...(target.requestId ? { requestId: target.requestId } : {}),
+                ...(rawInitialError
+                    ? {
+                        initialFailed: true,
+                        initialError: sanitizeLifecycleFailureField(rawInitialError),
+                    }
+                    : {}),
+            }, toolOpts, ownerUserId !== undefined ? { ownerUserId } : undefined);
+            startedTaskIds.push(started.taskId);
+        }
+        catch (error) {
+            getLogger().warn({ err: error, profile: target.profile }, "[devDatabase] failed to start sibling watch task for fanned-out datatag");
+            // Do not let the primary task report completion without this datatag in
+            // siblingTaskIds. That would make Clark proceed to migrations while the
+            // unobserved binding may still be provisioning.
+            throw error;
+        }
+        await stopIfCancelled();
+    }
+    return startedTaskIds;
+}
+function stillWorkingSiblingCount(deps, siblingTaskIds) {
+    if (!siblingTaskIds || siblingTaskIds.length === 0) {
+        return 0;
+    }
+    const taskStore = deps.getTaskStore?.();
+    if (!taskStore) {
+        return 0;
+    }
+    return siblingTaskIds.filter((taskId) => taskStore.get(taskId)?.state === "running").length;
+}
+/** Clark waits on the kickoff task only. Reporting success there while another
+ *  datatag is still working lets the migrate step that follows run against a
+ *  datatag that is not ready yet, which silently skips it. */
+function heldForSiblings(deps, status, siblingTaskIds) {
+    if (status.state !== "completed") {
+        return status;
+    }
+    const working = stillWorkingSiblingCount(deps, siblingTaskIds);
+    if (working === 0) {
+        return status;
+    }
+    return {
+        state: "running",
+        message: `waiting for ${working} more ${working === 1 ? "datatag" : "datatags"}`,
+    };
+}
+export function createDevDatabaseTaskTypes(deps) {
+    const watchDevDatabaseProvisionTaskType = {
+        ...watchDevDatabaseProvisionTaskMetadata,
+        start: async (input) => {
+            const watchKind = input.watchKind ?? "provision";
+            const label = watchKind === "migration"
+                ? `the database schema update (${input.logicalName} · ${input.profile})`
+                : provisionLabel(input.logicalName, input.profile);
+            const handle = {
+                bindingKey: input.bindingKey,
+                logicalName: input.logicalName,
+                profile: input.profile,
+                requirement: { logicalName: input.logicalName },
+                watchKind,
+                ...(input.requestId ? { requestId: input.requestId } : {}),
+            };
+            if (input.initialFailed) {
+                return {
+                    externalHandle: handle,
+                    initialStatus: {
+                        state: "failed",
+                        error: input.initialError ??
+                            (watchKind === "migration"
+                                ? "datatag migration failed"
+                                : "datatag provision failed"),
+                    },
+                    label,
+                };
+            }
+            return {
+                externalHandle: handle,
+                initialStatus: { state: "running", message: "pending" },
+                label,
+            };
+        },
+        poll: async (handle) => {
+            let response;
+            try {
+                // Progress query accepts exactly one locator — requestId XOR
+                // bindingKey. Sibling watches keep both on the handle for labeling /
+                // cancel, so prefer the request when present.
+                response = await deps
+                    .getClient()
+                    .pollProgress(handle.requestId
+                    ? { requestId: handle.requestId }
+                    : { bindingKey: handle.bindingKey });
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+            updateProvisionHandleFromResponse(handle, response);
+            const fallbackLogicalName = handle.logicalName ?? handle.requirement.logicalName;
+            if (handle.watchKind === "migration") {
+                if (TERMINAL_LIFECYCLE_STATES.has(response.lifecycleState) &&
+                    response.lifecycleState !== "ready") {
+                    return lifecycleStatusFor(response, handle.requestId, fallbackLogicalName);
+                }
+                return migrationStatusFor(response, handle.requestId, fallbackLogicalName);
+            }
+            return lifecycleStatusFor(response, handle.requestId, fallbackLogicalName);
+        },
+    };
+    const provisionDevDatabaseTaskType = {
+        ...provisionDevDatabaseTaskMetadata,
+        pendingLabel: (input) => provisionLabel(input.requirement.logicalName),
+        start: async (input, toolOpts, signal) => {
+            let response;
+            try {
+                // Client never sends a profile — the server resolves editor
+                // Environments targets and fans out ensure across every eligible
+                // datatag (ENG-3469).
+                response = await deps.getClient().createDevDb({
+                    applicationId: deps.applicationId,
+                    requirement: input.requirement,
+                });
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+            signal?.throwIfAborted();
+            // The application already has a database (typically under a
+            // different name — only one dev database per application is
+            // supported), or another precondition blocks provisioning. Surface
+            // the actionable server message as a soft failure so Clark can tell
+            // the user to reuse the existing database, instead of throwing an
+            // opaque "did not include lifecycle state" error. Mirrors the
+            // applyMigrations precondition branch below.
+            if (isPreconditionFailure(response)) {
+                const detail = isSingleAppDatabasePreconditionFailure(response)
+                    ? SINGLE_APP_DATABASE_PRECONDITION_AGENT_GUIDANCE
+                    : undefined;
+                return {
+                    externalHandle: {
+                        bindingKey: "precondition-failure",
+                        requirement: input.requirement,
+                    },
+                    initialStatus: {
+                        state: "failed",
+                        error: sanitizeLifecycleFailureField(response.errorMessage ??
+                            response.errorCode ??
+                            "createDevDb precondition failed"),
+                        ...(detail ? { detail } : {}),
+                    },
+                    label: provisionLabel(input.requirement.logicalName),
+                };
+            }
+            const targets = fanOutTargetsFromResponse(response);
+            const primaryProfile = targets.find((target) => target.bindingKey === response.bindingKey)
+                ?.profile ?? targets[0]?.profile;
+            const tagCount = targets.length;
+            const label = provisionLabel(input.requirement.logicalName, tagCount > 1 ? primaryProfile : undefined);
+            const handle = {
+                bindingKey: response.bindingKey,
+                requirement: input.requirement,
+                ...(primaryProfile && primaryProfile !== "default"
+                    ? { profile: primaryProfile }
+                    : {}),
+                ...(tagCount > 1 ? { tagCount } : {}),
+            };
+            updateProvisionHandleFromResponse(handle, response);
+            if (tagCount > 1) {
+                const siblingTaskIds = await spawnSiblingWatchTasks(deps, {
+                    logicalName: input.requirement.logicalName,
+                    primaryBindingKey: response.bindingKey,
+                    signal,
+                    targets,
+                    toolOpts,
+                });
+                if (siblingTaskIds.length > 0) {
+                    handle.siblingTaskIds = siblingTaskIds;
+                }
+            }
+            // Synchronous terminal short-circuit. The poll loop is skipped by
+            // TaskStore when initialStatus is non-running.
+            if (TERMINAL_LIFECYCLE_STATES.has(response.lifecycleState)) {
+                return {
+                    externalHandle: handle,
+                    initialStatus: heldForSiblings(deps, lifecycleStatusFor(response, undefined, input.requirement.logicalName), handle.siblingTaskIds),
+                    label,
+                };
+            }
+            return {
+                externalHandle: handle,
+                initialStatus: {
+                    state: "running",
+                    message: tagCount > 1
+                        ? `${response.lifecycleState}; ${tagCount} tags`
+                        : response.lifecycleState,
+                },
+                label,
+            };
+        },
+        poll: async (handle) => {
+            let response;
+            try {
+                response = await deps.getClient().pollProgress({
+                    bindingKey: handle.bindingKey,
+                });
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+            updateProvisionHandleFromResponse(handle, response);
+            return heldForSiblings(deps, lifecycleStatusFor(response, handle.requestId, handle.logicalName ?? handle.requirement.logicalName), handle.siblingTaskIds);
+        },
+    };
+    const applyDevDatabaseMigrationsTaskType = {
+        ...applyDevDatabaseMigrationsTaskMetadata,
+        // Kickoff uploads the working directory and then asks the server what
+        // needs applying, so there is nothing to name yet. `start` swaps in the
+        // filenames once it knows them.
+        pendingLabel: () => DEFAULT_MIGRATION_TASK_LABEL,
+        start: async (input, toolOpts, signal) => {
+            try {
+                await deps.ensureFilesSynced?.();
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+            signal?.throwIfAborted();
+            let response;
+            try {
+                // Never pass bindingKey — server fans out migrate_schema across
+                // every eligible editor Environments datatag. Passing the
+                // provision-primary key left siblings provisioned but without
+                // projected integration configs (migrations never ran there).
+                // The acknowledgment rides on Clark's declaration, and a declared
+                // apply only reaches this line after the registry showed the user a
+                // confirmation card and they approved it (see the tool factory in
+                // dev-database-tools.ts). So "declared" here means "a person said
+                // yes to this exact call", which is what the server is asking for.
+                response = await deps.getClient().applyMigrations({
+                    applicationId: deps.applicationId,
+                    ...(declaresDestructiveChange({
+                        details: input.destructiveChangeDetails,
+                        reason: input.destructiveChangeReason,
+                        summary: input.destructiveChangeSummary,
+                    })
+                        ? { acknowledgeDestructive: true }
+                        : {}),
+                });
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+            signal?.throwIfAborted();
+            if (isPreconditionFailure(response)) {
+                const baseError = sanitizeLifecycleFailureField(response.errorMessage ??
+                    response.errorCode ??
+                    "applyMigrations precondition failed");
+                const isDestructiveAck = response.errorCode === "DESTRUCTIVE_MIGRATION_ACK_REQUIRED";
+                const blockedFindings = isDestructiveAck && Array.isArray(response.findings)
+                    ? response.findings
+                    : [];
+                return {
+                    externalHandle: {
+                        requestId: "precondition-failure",
+                    },
+                    initialStatus: {
+                        state: "failed",
+                        error: baseError,
+                        // The instruction and the blocked statements both go in `detail`,
+                        // not `error`: `error` is clamped, so either would truncate.
+                        // `detail` reaches Clark verbatim, so it reliably calls again with
+                        // copy covering every statement — which is what raises the
+                        // confirmation card — instead of improvising a bypass.
+                        ...(isDestructiveAck
+                            ? {
+                                detail: `${DESTRUCTIVE_MIGRATION_ACK_AGENT_GUIDANCE}${flaggedStatementsForAgent(blockedFindings)}`,
+                            }
+                            : {}),
+                    },
+                    label: DEFAULT_MIGRATION_TASK_LABEL,
+                };
+            }
+            const label = migrationTaskLabel(response);
+            const handle = {
+                bindingKey: response.bindingKey,
+                logicalName: response.logicalName,
+                requestId: response.requestId,
+            };
+            const targets = fanOutTargetsFromResponse(response);
+            const tagCount = targets.length;
+            if (tagCount > 1) {
+                const siblingTaskIds = await spawnSiblingWatchTasks(deps, {
+                    logicalName: response.logicalName ?? "database",
+                    primaryBindingKey: response.bindingKey,
+                    signal,
+                    targets,
+                    toolOpts,
+                    watchKind: "migration",
+                });
+                if (siblingTaskIds.length > 0) {
+                    handle.siblingTaskIds = siblingTaskIds;
+                }
+            }
+            // Migrations sometimes finish synchronously (no SQL to apply). Still
+            // route through migrationStatusFor so a vacant projection keeps the
+            // task running until runtimeConfigurationReady (ENG-5285).
+            if (response.migrationState === "migrated" ||
+                response.migrationState === "failed") {
+                return {
+                    externalHandle: handle,
+                    initialStatus: heldForSiblings(deps, migrationStatusFor(response, handle.requestId, handle.logicalName), handle.siblingTaskIds),
+                    label,
+                };
+            }
+            return {
+                externalHandle: handle,
+                initialStatus: {
+                    state: "running",
+                    message: tagCount > 1
+                        ? `${response.migrationState}; ${tagCount} tags`
+                        : response.migrationState,
+                },
+                label,
+            };
+        },
+        poll: async (handle) => {
+            let response;
+            try {
+                response = await deps.getClient().pollProgress({
+                    requestId: handle.requestId,
+                });
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+            if (response.logicalName) {
+                handle.logicalName = response.logicalName;
+            }
+            // If the underlying lifecycle went terminal (failed/cancelled)
+            // while migrations are still pending, surface the lifecycle
+            // failure instead of spinning forever on migrationState.
+            if (TERMINAL_LIFECYCLE_STATES.has(response.lifecycleState) &&
+                response.lifecycleState !== "ready") {
+                return lifecycleStatusFor(response, handle.requestId, handle.logicalName);
+            }
+            return heldForSiblings(deps, migrationStatusFor(response, handle.requestId, handle.logicalName), handle.siblingTaskIds);
+        },
+    };
+    return {
+        applyDevDatabaseMigrationsTaskType,
+        provisionDevDatabaseTaskType,
+        watchDevDatabaseProvisionTaskType,
+    };
+}
+/**
+ * Prime Clark's in-memory IntegrationStore from any dev-database response
+ * that includes an `integrationId`.
+ *
+ * Extracted from the legacy `dev-database.ts` so the background-task
+ * listener wired in ai-service/index.ts can reuse the exact same
+ * semantics (fall back to the caller-supplied `logicalName` when the
+ * response omits it). The
+ * fallback's `engine` field is optional because the LLM-facing tool
+ * input does not carry an engine — engine is platform-controlled and
+ * only surfaces on the server response.
+ *
+ * Returning the registry to a consistent state when the response shape
+ * is incomplete is intentional: the IntegrationStore will be re-primed
+ * by the next `searchIntegrations` round-trip if we no-op here.
+ */
+export function primeIntegrationStoreFromResponse(integrationStore, response, context, fallback) {
+    if (!response.integrationId) {
+        return;
+    }
+    const name = response.logicalName ?? fallback?.logicalName;
+    const type = response.engine ?? fallback?.engine;
+    if (!name || !type) {
+        getLogger().warn({ context, integrationId: response.integrationId }, "[devDatabase] cannot prime integration-store cache: response missing logicalName/engine and no fallback provided; searchIntegrations may miss the integration until next refetch");
+        return;
+    }
+    try {
+        integrationStore.registerIntegration({
+            displayName: name,
+            id: response.integrationId,
+            lifecycleState: response.lifecycleState,
+            managedBy: DATABASE_LIFECYCLE_MANAGED_BY,
+            name,
+            type,
+        });
+    }
+    catch (err) {
+        getLogger().warn({ context, err, integrationId: response.integrationId }, "[devDatabase] failed to prime integration-store cache; searchIntegrations may miss the integration until next refetch");
+    }
+}
+/**
+ * Subscribe to the TaskStore so every successful `provisionDevDatabase`
+ * or `applyDevDatabaseMigrations` terminal status primes Clark's
+ * IntegrationStore cache with the freshly-created lifecycle integration.
+ *
+ * This is the background-task replacement for the inline
+ * `primeIntegrationStoreFromResponse` calls the legacy blocking
+ * `createDevDb` / `applyMigrations` / `getDevDbProgress` tools used to
+ * make. It runs once per Clark session — wired alongside the TaskStore
+ * construction in `ai-service/index.ts`.
+ *
+ * Returns the unsubscribe function from `taskStore.onStatus` so the
+ * caller can dispose this listener on FSM teardown.
+ */
+export function wireDevDatabaseIntegrationPriming(taskStore, integrationStore) {
+    return taskStore.onStatus((_taskId, status, task) => {
+        if (task.taskType !== provisionDevDatabaseTaskMetadata.name &&
+            task.taskType !== applyDevDatabaseMigrationsTaskMetadata.name &&
+            task.taskType !== watchDevDatabaseProvisionTaskMetadata.name) {
+            return;
+        }
+        const isProvisionLike = task.taskType === provisionDevDatabaseTaskMetadata.name ||
+            task.taskType === watchDevDatabaseProvisionTaskMetadata.name;
+        const result = status.state === "completed"
+            ? status.result
+            : isProvisionLike
+                ? task.externalHandle
+                : undefined;
+        if (!result || typeof result !== "object")
+            return;
+        // The provision handle carries the user-supplied requirement so the
+        // server can omit `logicalName` on the ready envelope without
+        // breaking IntegrationStore priming. Engine is platform-controlled
+        // and only surfaces on the response itself, so it's not on the
+        // requirement. The migrations handle does NOT carry the
+        // requirement; we rely on the ready response to supply both
+        // `logicalName` and `engine` (the legacy applyMigrations path also
+        // did not have access to the original requirement).
+        const provisionHandle = task.externalHandle;
+        primeIntegrationStoreFromResponse(integrationStore, result, task.taskType, provisionHandle?.requirement);
+    });
+}
+//# sourceMappingURL=dev-database-tasks.js.map