@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.84af65cd215b6ca1

package/dist/ai-service/agent/tools/apis/test-api.js

@@ -0,0 +1,742 @@
+import { isEmpty } from "lodash-es";
+import { z } from "zod";
+import { AiEntityType, AiPermissionType, } from "@superblocksteam/library-shared/types";
+import { DATABASE_LIFECYCLE_MANAGED_BY, LanguagePluginID, } from "@superblocksteam/shared";
+import { normalizeIntegrationWritePolicyForEnforcement } from "../../../../migration/integration-write-policy.js";
+import { safeJsonParse, safeJsonStringify, } from "../../../../util/log-sanitizer.js";
+import { getErrorMeta, getLogger, getPrefixedLogger, } from "../../../../util/logger.js";
+import { readPersistedChecklist } from "../../../checklist/persisted-checklist-store.js";
+import { callPeer } from "../../../util/call-peer.js";
+import { ORCHESTRATOR_PEER_RPC_TIMEOUT_MS } from "../../../util/rpc-timeout.js";
+import { createToolFactory, PermissionLevel, ToolCategory, ToolExecutionError, } from "../../tools2/types.js";
+import { codeBlock } from "../../tools2/utils.js";
+import { MAX_QUERY_RESPONSE_TOKENS, truncateToTokens, } from "../integrations/internal.js";
+import { isManagedAppDatabaseIntegration } from "../integrations/managed-app-database.js";
+import { containsMutations, extractIntegrationIdsFromSource, extractMutations, } from "./analysis.js";
+import { runApiValidationPipeline } from "./api-validation-orchestrator.js";
+import { safeSampleJson } from "./sample-json.js";
+import { resolveSdkApiEntryPoint, resolveSdkApiEntry } from "./sdk-registry.js";
+async function resolveSdkApiSourcePath(apiName, services, clark) {
+    return resolveSdkApiEntryPoint(apiName, {
+        readFile: (relativePath) => services.appShell.readFile(relativePath),
+        pathExists: (relativePath) => services.appShell.pathExists(relativePath),
+    }, clark?.context.sdkApiRegistryEntryPoints);
+}
+async function resolveSdkApiRegistryEntry(apiName, services) {
+    return resolveSdkApiEntry(apiName, {
+        readFile: (relativePath) => services.appShell.readFile(relativePath),
+        pathExists: (relativePath) => services.appShell.pathExists(relativePath),
+    });
+}
+/**
+ * Execute an SDK API via the editor socket (aiExecuteSdkApi).
+ * Runs a TypeScript typecheck first to catch errors before execution.
+ */
+async function executeSdkApi({ apiName, inputs, clark, services, logger, }) {
+    const apiTsPath = await resolveSdkApiSourcePath(apiName, services, clark);
+    if (!apiTsPath) {
+        throw new Error(`No registry entryPoint found for API "${apiName}". Add it to server/apis/index.ts before testing.`);
+    }
+    // Run TypeScript check before execution to catch type errors
+    logger.info(`Starting TypeScript check for API file: ${apiTsPath}`);
+    try {
+        const typecheckErrors = await services.appShell.runTypecheck(clark.context.abortController?.signal);
+        logger.info(`TypeScript check completed. Has errors: ${!!typecheckErrors}, error file count: ${typecheckErrors ? Object.keys(typecheckErrors).length : 0}`);
+        if (typecheckErrors) {
+            const apiErrors = [];
+            for (const [filePath, errors] of Object.entries(typecheckErrors)) {
+                if (filePath.includes(apiTsPath) || filePath.endsWith(apiTsPath)) {
+                    apiErrors.push(...errors);
+                }
+            }
+            if (apiErrors.length > 0) {
+                const errorPreview = apiErrors.slice(0, 5).join("\n");
+                const moreErrors = apiErrors.length > 5
+                    ? `\n... and ${apiErrors.length - 5} more error(s)`
+                    : "";
+                logger.error(`Blocking execution due to TypeScript errors`);
+                throw new Error(`TypeScript errors in API "${apiName}" must be fixed before testing:\n\n${errorPreview}${moreErrors}\n\nFix these type errors and try again.`);
+            }
+        }
+        logger.info(`TypeScript check passed for ${apiName}`);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.includes("TypeScript errors in API")) {
+            throw error;
+        }
+        logger.warn(`TypeScript check failed, proceeding with execution: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    logger.info(`Executing SDK API ${apiName} with inputs:`, safeJsonStringify(inputs));
+    const editorClient = clark.context.peer;
+    if (!editorClient) {
+        throw new Error("No editor client available");
+    }
+    // Resolve entry point and export name from the registry so execution
+    // works even when browser-side discovery hasn't run yet (e.g. Clark
+    // just created the API files and no UI is rendered).
+    const registryEntry = await resolveSdkApiRegistryEntry(apiName, services);
+    // Extract integration IDs from the API source so the UI handler can
+    // run the auth preflight even when the Redux store hasn't registered
+    // this API yet (APPS-3288).
+    let integrationIds;
+    try {
+        const apiSource = await services.appShell.readFile(apiTsPath);
+        const ids = extractIntegrationIdsFromSource(apiSource);
+        if (ids.length > 0) {
+            integrationIds = ids;
+        }
+    }
+    catch {
+        logger.warn(`Failed to extract integration IDs from ${apiTsPath}, auth preflight will rely on Redux store`);
+    }
+    try {
+        const result = await callPeer(editorClient, () => editorClient.call.aiExecuteSdkApi({
+            apiName,
+            input: inputs ?? {},
+            entryPoint: registryEntry?.entryPoint ?? apiTsPath,
+            exportName: registryEntry?.exportName,
+            integrationIds,
+        }), ORCHESTRATOR_PEER_RPC_TIMEOUT_MS, "aiExecuteSdkApi");
+        logger.info(`aiExecuteSdkApi returned for ${apiName}: success=${result.success}, hasOutput=${!!result.output}, hasError=${!!result.error}`);
+        if (result.success === undefined) {
+            logger.error(`aiExecuteSdkApi returned malformed result (no success field) for ${apiName}`);
+            return {
+                message: `API ${apiName} execution returned unexpected result format. This may indicate the API file failed to load or has syntax errors. Check the browser console for details.`,
+                result: {
+                    success: false,
+                    systemError: "Malformed response from API execution",
+                    rawResult: result,
+                },
+                apiName,
+            };
+        }
+        if (result.success === false) {
+            logger.warn(`SDK API execution returned error for ${apiName}: ${result.error?.message ?? "Unknown error"}`);
+            clark.context.apiTestingState ??= {
+                untested: new Set(),
+                failed: new Set(),
+                passed: new Set(),
+                denied: new Set(),
+            };
+            clark.context.apiTestingState.failed.add(apiName);
+            clark.context.apiTestingState.passed.delete(apiName);
+            const errorSummary = result.error?.message ?? "";
+            return {
+                message: `API ${apiName} FAILED with unhandled errors. Do NOT show a success message to the user - investigate and fix the error.
+
+Error summary:
+${errorSummary || "No specific error details available."}`,
+                result: {
+                    success: false,
+                    error: result.error,
+                },
+                apiName,
+            };
+        }
+        // Limit output size for SDK APIs (same token cap as YAML step outputs).
+        // The UI (getToolOutput) and model (toModelOutput) apply further limits.
+        const truncated = truncateToTokens(result.output, MAX_QUERY_RESPONSE_TOKENS);
+        const outputs = safeJsonParse(truncated.result) ?? truncated.result;
+        logger.info(`API ${apiName} executed successfully, output truncated=${truncated.truncated}`);
+        clark.context.apiTestingState ??= {
+            untested: new Set(),
+            failed: new Set(),
+            passed: new Set(),
+            denied: new Set(),
+        };
+        clark.context.apiTestingState.passed.add(apiName);
+        clark.context.apiTestingState.failed.delete(apiName);
+        return {
+            message: `API ${apiName} executed without throwing exceptions. This does NOT guarantee the outputs are correct - verify the data before showing success to the user.
+If the API is meant to be run off a useEffect, call build_reloadFile to reload the appropriate file to propagate the changes to the UI.`,
+            result: {
+                success: true,
+                outputs,
+                ...(truncated.truncated && { isPartial: true }),
+            },
+            apiName,
+        };
+    }
+    catch (error) {
+        const errorMeta = getErrorMeta(error);
+        logger.warn(`API execution failed for ${apiName}:`, errorMeta);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            message: `API execution failed for ${apiName}. The error details are included in the result below - analyze them to understand and fix the issue.
+
+Error: ${errorMessage}`,
+            result: {
+                success: false,
+                systemError: errorMessage,
+            },
+            apiName,
+        };
+    }
+}
+/**
+ * Execute a YAML API via the validation pipeline.
+ */
+async function executeYamlApi({ apiName, inputs, omitStepOutputs, timeout, clark, services, logger, }) {
+    try {
+        const result = (await runApiValidationPipeline({
+            clark,
+            services,
+            identifier: apiName,
+            inputs,
+            options: {
+                omitStepOutputs,
+                timeout,
+            },
+        })).executionResult;
+        if (!result) {
+            logger.error("BUG! No execution result returned by api validation pipeline");
+            throw new Error("No API execution result received, please try again");
+        }
+        if (!result.success) {
+            logger.warn(`api execution returned errors for ${apiName}:`, result);
+            clark.context.apiTestingState ??= {
+                untested: new Set(),
+                failed: new Set(),
+                passed: new Set(),
+                denied: new Set(),
+            };
+            clark.context.apiTestingState.failed.add(apiName);
+            clark.context.apiTestingState.passed.delete(apiName);
+            const errors = result.errors ?? [];
+            const errorSummary = errors
+                .map((e) => {
+                const parts = [e.message];
+                if (e.suggestion) {
+                    parts.push(`Suggestion: ${e.suggestion}`);
+                }
+                return parts.join("\n");
+            })
+                .join("\n\n");
+            return {
+                message: `API ${apiName} FAILED with unhandled errors. Do NOT show a success message to the user - investigate and fix the error.
+
+Error summary:
+${errorSummary || "No specific error details available."}`,
+                result,
+                apiName,
+            };
+        }
+        const outputSample = safeSampleJson(result.outputs);
+        let stepOutputs = result.stepOutputs;
+        if (stepOutputs) {
+            stepOutputs = { ...result.stepOutputs };
+            for (const [key, value] of Object.entries(stepOutputs)) {
+                const stepOutputSample = safeSampleJson(value.output);
+                stepOutputs[key] = {
+                    ...value,
+                    output: stepOutputSample,
+                };
+            }
+        }
+        clark.context.apiTestingState ??= {
+            untested: new Set(),
+            failed: new Set(),
+            passed: new Set(),
+            denied: new Set(),
+        };
+        clark.context.apiTestingState.passed.add(apiName);
+        clark.context.apiTestingState.failed.delete(apiName);
+        return {
+            message: `API ${apiName} executed without throwing exceptions. This does NOT guarantee the outputs are correct - verify the data before showing success to the user.
+If the API is meant to be run off a useEffect, call build_reloadFile to reload the appropriate file to propagate the changes to the UI.`,
+            result: {
+                ...result,
+                outputs: outputSample,
+                stepOutputs,
+            },
+            apiName,
+        };
+    }
+    catch (error) {
+        logger.warn(`API execution failed for ${apiName}:`, getErrorMeta(error));
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            message: `API execution failed for ${apiName}. The error details are included in the result below - analyze them to understand and fix the issue.
+
+Error: ${errorMessage}`,
+            result: {
+                success: false,
+                systemError: errorMessage,
+            },
+            apiName,
+        };
+    }
+}
+/**
+ * Read the API source file using the appropriate path for the current mode.
+ * When a pre-resolved `RegistryEntry` is provided (SDK mode), its `entryPoint`
+ * is used directly — avoiding a redundant registry read.
+ * Non-SDK mode reads from the YAML-based `apis/<apiName>.ts` path.
+ */
+async function readApiSource(apiName, services, registryEntry) {
+    if (services.features.sdkApiEnabled) {
+        const sdkPath = registryEntry?.entryPoint;
+        if (!sdkPath) {
+            throw new Error(`No SDK registry entry point found for API "${apiName}"`);
+        }
+        return await services.appShell.readFile(sdkPath);
+    }
+    return await services.appShell.readFile(`apis/${apiName}.ts`);
+}
+async function assertReferencedLifecycleIntegrationsReady(apiName, services, logger) {
+    let apiSourceContent;
+    try {
+        const registryEntry = services.features.sdkApiEnabled
+            ? await resolveSdkApiRegistryEntry(apiName, services)
+            : undefined;
+        apiSourceContent = await readApiSource(apiName, services, registryEntry);
+    }
+    catch (error) {
+        logger.warn(`Failed to inspect API source before execution; lifecycle integration readiness could not be checked before testApi dispatch. If the API uses a still-provisioning database integration, execution may fail with a database connection error instead of a structured readiness error. TODO(ENG-3537): add server-side lifecycle integration readiness enforcement. ${error instanceof Error ? error.message : String(error)}`);
+        return;
+    }
+    const pendingIntegration = extractIntegrationIdsFromSource(apiSourceContent)
+        .filter((id) => !LANGUAGE_PLUGIN_IDS.has(id))
+        .map((id) => services.integrationStore.getHeader(id))
+        .find((integration) => integration?.lifecycleState && integration.lifecycleState !== "ready");
+    if (!pendingIntegration) {
+        return;
+    }
+    throw new Error(`Cannot test API "${apiName}" yet because integration "${pendingIntegration.name}" is not ready (state: ${pendingIntegration.lifecycleState}). Wait for the database provisioning to finish, then call testApi again.`);
+}
+const LANGUAGE_PLUGIN_IDS = new Set(Object.values(LanguagePluginID));
+const API_MIGRATION_ORIGINS = new Set(["2.0-upgrade", "seed_api"]);
+/**
+ * Returns true while migration is still in progress from the user's
+ * perspective. Keep honoring modal write-policy through the "ready to
+ * complete" state (no pending API rows) and stop only once checklist marks
+ * migration completed. This avoids dropping back to per-API prompts before
+ * the user actually finishes migration.
+ */
+async function isMigrationTranslating(services) {
+    if (!services.appRootDirPath) {
+        return false;
+    }
+    const checklist = await readPersistedChecklist(services.appRootDirPath);
+    if (!checklist) {
+        return false;
+    }
+    if (checklist.overallStatus === "completed") {
+        return false;
+    }
+    const hasApiMigrationItems = checklist.items.some((item) => API_MIGRATION_ORIGINS.has(item.origin));
+    if (!hasApiMigrationItems) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Resolve the v2 → v3 pre-migration write-policy decision for this API.
+ *
+ * The pre-migration modal lets the user mark each integration as
+ * `allow` / `deny`. We collapse those per-integration choices into
+ * a single decision for this API:
+ *
+ * - `"allow"`  → every data integration this API touches is allow AND the
+ *                app-level policy contains no "deny" entries → skip the
+ *                per-API prompt and execute. The whole-app deny check is a
+ *                defense-in-depth guard against `extractIntegrationIdsFromSource`
+ *                missing a reference shape; see comment at the call site.
+ * - `"deny"`   → at least one data integration is deny → block the test
+ *                entirely; the user already said no in the modal and
+ *                must not be re-prompted per API (regression: was being
+ *                asked on every testApi call after picking deny).
+ * - `null`     → no migration in progress, no policy persisted, parse
+ *                failure, or a mixed policy (some allow, some without an
+ *                explicit entry) → fall through to the existing per-API
+ *                PROMPT behavior.
+ *
+ * Inline JS/TS code is not a data integration and never appears in the
+ * policy map; language-runtime ids are filtered out so a mixed API
+ * (e.g. postgres + javascript) isn't gated on `javascript` having no
+ * policy entry.
+ */
+async function getMigrationPolicyDecision(services, apiSourceContent) {
+    // Only honor the persisted policy while the migration is actively
+    // translating. After completion (or if migration-state.json is stale or
+    // injected without a matching checklist), fall through to PROMPT so the
+    // user explicitly approves each test.
+    if (!(await isMigrationTranslating(services)))
+        return null;
+    let raw;
+    try {
+        raw = await services.appShell.readFile("scratch/migration-state.json");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const rawPolicy = parsed.integrationWritePolicy;
+    if (!rawPolicy || typeof rawPolicy !== "object")
+        return null;
+    const policy = normalizeIntegrationWritePolicyForEnforcement(rawPolicy);
+    let integrationIds;
+    try {
+        integrationIds = extractIntegrationIdsFromSource(apiSourceContent);
+    }
+    catch {
+        return null;
+    }
+    const dataIntegrationIds = integrationIds.filter((id) => !LANGUAGE_PLUGIN_IDS.has(id));
+    if (dataIntegrationIds.length === 0)
+        return null;
+    // Deny wins over allow: a single deny is enough to block, matching
+    // the modal's per-integration semantics ("deny" = never test APIs that
+    // touch this integration).
+    if (dataIntegrationIds.some((id) => policy[id] === "deny")) {
+        return "deny";
+    }
+    if (dataIntegrationIds.every((id) => policy[id] === "allow")) {
+        // Defense-in-depth: only auto-allow when the entire app-level policy is
+        // free of "deny" entries. `extractIntegrationIdsFromSource` is best-effort
+        // (regex + AST walk over the SDK API source); if it misses a reference
+        // shape — spread args, re-exported integration wiring, dynamically-built
+        // constructor calls — a denied integration could be omitted from
+        // `dataIntegrationIds` and slip past the per-API check above. Falling
+        // through to PROMPT in that case re-asks the user instead of silently
+        // executing a write the user previously denied at the modal.
+        const policyHasDeny = Object.values(policy).some((p) => p === "deny");
+        if (!policyHasDeny)
+            return "allow";
+    }
+    return null;
+}
+/**
+ * Collects integration IDs attributed to mutation sites. Shared by the
+ * ALLOW/PROMPT gate and getRequiredPermissions so both views of the policy
+ * cannot drift.
+ */
+function resolveMutatingIntegrationIds(mutations) {
+    const mutatingIntegrationIds = [
+        ...new Set(mutations
+            .map((mutation) => mutation.integrationId)
+            .filter((id) => typeof id === "string" && id.length > 0)),
+    ];
+    const hasIdLessMutation = mutations.some((mutation) => typeof mutation.integrationId !== "string" ||
+        mutation.integrationId.length === 0);
+    return { hasIdLessMutation, mutatingIntegrationIds };
+}
+function logManagedWriteAutoAllow({ apiName, mutatingIntegrationIds, services, }) {
+    const allowSignals = mutatingIntegrationIds.map((id) => {
+        const header = services.integrationStore?.getHeader(id);
+        const signal = header?.managedBy === DATABASE_LIFECYCLE_MANAGED_BY
+            ? "managed_by"
+            : "lifecycle_state";
+        return `${id}:${signal}`;
+    });
+    const logger = getLogger();
+    const message = "[testApi] Auto-allowing write test for managed app database integrations";
+    const attributes = {
+        "clark.testapi.permission_decision": "allow_managed_app_database",
+        "clark.testapi.mutating_integration_count": mutatingIntegrationIds.length,
+        ...(apiName ? { "clark.testapi.api_name": apiName } : {}),
+        // Bounded, low-cardinality: id:signal pairs only (no source / headers).
+        "clark.testapi.allow_signals": allowSignals.join(","),
+    };
+    if (logger.infoStructured) {
+        logger.infoStructured(message, attributes);
+    }
+    else {
+        logger.info(message, attributes);
+    }
+}
+/**
+ * Returns true when every mutation site in this API is attributed to a
+ * managed app-database integration. Writes against the provisioned app DB
+ * are always on Clark-managed sandbox data, so testApi should not ask for
+ * write approval.
+ *
+ * Auto-allow requires:
+ * - managed-native-db.enabled (kill switch)
+ * - every mutation site has an integrationId (no unverified write sites)
+ * - every such ID resolves to a managed app-database header
+ *
+ * There is intentionally no fallback to "all referenced integrations" —
+ * a co-located managed read must not smuggle an ID-less external write.
+ */
+function areAllMutatingIntegrationsManaged(mutations, services, apiName) {
+    if (services.features.managedNativeDbEnabled !== true)
+        return false;
+    if (!services.integrationStore)
+        return false;
+    if (mutations.length === 0)
+        return false;
+    const { hasIdLessMutation, mutatingIntegrationIds } = resolveMutatingIntegrationIds(mutations);
+    // Any unattributed mutation site (or zero attributed IDs) → prompt.
+    if (hasIdLessMutation || mutatingIntegrationIds.length === 0) {
+        return false;
+    }
+    const allManaged = mutatingIntegrationIds.every((id) => {
+        const header = services.integrationStore.getHeader(id);
+        return header != null && isManagedAppDatabaseIntegration(header);
+    });
+    if (allManaged) {
+        logManagedWriteAutoAllow({ apiName, mutatingIntegrationIds, services });
+    }
+    return allManaged;
+}
+/**
+ * WRITE permission entity IDs for non-managed mutating integrations.
+ * When some mutation sites lack an ID, also consider other data integrations
+ * referenced in the source so entity-keyed escalation still has something to
+ * attach to (checkTestApiPermissions already returns PROMPT in that case).
+ */
+function resolveNonManagedWritePermissionIds(apiSourceContent, mutations, services) {
+    const { hasIdLessMutation, mutatingIntegrationIds } = resolveMutatingIntegrationIds(mutations);
+    let candidateIds = mutatingIntegrationIds;
+    if (hasIdLessMutation) {
+        let referencedIds = [];
+        try {
+            referencedIds = extractIntegrationIdsFromSource(apiSourceContent).filter((id) => !LANGUAGE_PLUGIN_IDS.has(id));
+        }
+        catch {
+            referencedIds = [];
+        }
+        candidateIds = [...new Set([...mutatingIntegrationIds, ...referencedIds])];
+    }
+    // Kill switch: when managed-native-db is off, do not drop managed IDs from
+    // WRITE entities — they must still prompt / escalate like any other write.
+    if (services.features.managedNativeDbEnabled !== true) {
+        return candidateIds;
+    }
+    return candidateIds.filter((id) => {
+        const header = services.integrationStore?.getHeader(id);
+        return header == null || !isManagedAppDatabaseIntegration(header);
+    });
+}
+/**
+ * Validates testApi inputs before permission check.
+ * Throws if validation fails (e.g., mutations detected but no description provided).
+ */
+const validateTestApiInput = (input = {}, mutations = []) => {
+    const hasMutations = mutations?.length > 0;
+    const description = input?.description;
+    const apiName = input?.apiName;
+    if (hasMutations && (!description || description.trim().length === 0)) {
+        const mutationsPreview = mutations
+            .slice(0, 3)
+            .map((m, idx) => {
+            const detail = m.details.length > 60 ? `${m.details.slice(0, 60)}...` : m.details;
+            return `  ${idx + 1}. ${m.type} "${m.name}": ${detail}`;
+        })
+            .join("\n");
+        throw new Error(`
+The API "${apiName}" contains ${mutations.length} mutation(s) that will modify data, but no description was provided.
+
+Mutations detected:
+${mutationsPreview}
+
+You MUST provide a 'description' parameter that explains in plain English what data will be modified and why.
+
+Example call:
+testApi({
+apiName: "${apiName}",
+inputs: {...},
+description: "Creates a users table with columns for id, name, email, and created_at timestamp"
+})`.trim());
+    }
+};
+export const checkTestApiPermissions = async (services, input, _clark) => {
+    // we are building our initial set of tools, we don't have any permissions yet
+    if (!input || isEmpty(input)) {
+        return PermissionLevel.PROMPT;
+    }
+    if (!input.apiName) {
+        throw new ToolExecutionError("API name is required", {
+            toolName: "testApi",
+            input: input ?? {},
+            context: {},
+            severity: "warn",
+        });
+    }
+    let mutations = [];
+    let apiSourceContent;
+    let exportName;
+    try {
+        const registryEntry = services.features.sdkApiEnabled
+            ? await resolveSdkApiRegistryEntry(input.apiName, services)
+            : undefined;
+        apiSourceContent = await readApiSource(input.apiName, services, registryEntry);
+        exportName = registryEntry
+            ? (registryEntry.exportName ?? "default")
+            : undefined;
+        mutations = extractMutations(apiSourceContent, exportName);
+    }
+    catch (error) {
+        getLogger().info(`[testApi] Failed to resolve or read API source, fall back to PROMPT: ${input.apiName}`, error instanceof Error ? error.message : String(error));
+        validateTestApiInput(input, mutations);
+        return PermissionLevel.PROMPT;
+    }
+    if (mutations.length > 0) {
+        validateTestApiInput(input, mutations);
+        // During a v2 → v3 migration the user already opted into testing on a
+        // per-integration basis via the pre-migration write-policy modal.
+        // Honor that decision instead of re-prompting for each API:
+        //  - all "allow"  → execute without prompting
+        //  - any "deny"   → block; user already said no in the modal and must
+        //                   not be re-prompted per API
+        //  - otherwise    → fall through to the standard PROMPT path
+        if (apiSourceContent) {
+            if (areAllMutatingIntegrationsManaged(mutations, services, input.apiName)) {
+                return PermissionLevel.ALLOW;
+            }
+            const decision = await getMigrationPolicyDecision(services, apiSourceContent);
+            if (decision === "allow")
+                return PermissionLevel.ALLOW;
+            if (decision === "deny")
+                return PermissionLevel.BLOCK;
+        }
+        return PermissionLevel.PROMPT;
+    }
+    return PermissionLevel.ALLOW;
+};
+export const testApiToolFactory = createToolFactory("testApi", ({ clark, services, }) => {
+    return {
+        category: ToolCategory.DEBUG,
+        timeoutMs: 300_000, // 5 minutes — API executions involve LLM/network calls that regularly exceed 60s
+        // For SDK APIs, we skip the output limit but will truncate the output we send to the LLM in toModelOutput
+        skipOutputLimit: (_output) => !!services.features.sdkApiEnabled,
+        description: `
+Execute an API to test its behavior. This triggers the API through the normal UI execution path,
+so the execution will be visible in the application UI with full trace details.
+
+Use this tool to verify that an API works correctly after building it.
+
+The tool will generate smart default inputs for any bindings the API uses:
+- Component values (e.g., Input1.value) will use mock data based on component type
+- State variables will use empty objects/arrays
+- Global context values are automatically available
+
+CRITICAL: If the API contains mutations (SQL INSERT/UPDATE/DELETE, HTTP POST/PUT/PATCH/DELETE, DynamoDB mutations, Salesforce CRUD operations, etc.),
+you MUST provide the 'description' parameter with a clear, plain-English explanation of:
+  - What data will be created/modified/deleted
+  - Which resources are affected
+  - The business purpose of the operation
+
+The description will be shown to the user in an approval prompt, so it must be clear and easy to understand for technical and non-technical users. You can return Markdown.
+`,
+        inputSchema: z.object({
+            apiName: z.string().describe("The name of the API to test"),
+            inputs: z
+                .record(z.string(), z.any())
+                .describe("Test input values for the API bindings. A key must be provided for each input the API expects."),
+            description: z
+                .string()
+                .optional()
+                .describe("Plain-English explanation of what this API does, especially any side-effects."),
+            omitStepOutputs: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("If true, step outputs will be omitted from the execution result."),
+            timeout: z
+                .number()
+                .optional()
+                .describe("Timeout in milliseconds. If exceeded, the API execution is cancelled. Defaults to 500 seconds."),
+        }),
+        getActionName: () => ({
+            future: "Test API",
+            present: "Testing API",
+            past: "Tested API",
+        }),
+        formatInput: (params) => {
+            const { apiName, inputs, description } = params;
+            return {
+                targets: [apiName],
+                details: description ??
+                    (inputs ? codeBlock(safeJsonStringify(inputs, 2)) : undefined),
+                summary: `Ok if I test ${apiName}?`,
+            };
+        },
+        onCall: (_params) => {
+            // No-op: We intentionally do NOT modify untested/denied here.
+            // The API stays in `untested` until we get a definitive response:
+            // - If user approves (or no permission needed): execute() removes from untested
+            // - If user denies: handleToolPermission removes from untested and adds to denied
+            // This ensures build_debug correctly reports untested APIs while waiting for user response.
+        },
+        getRequiredPermissions: async (params) => {
+            const { apiName } = params;
+            if (!apiName) {
+                return [];
+            }
+            try {
+                const registryEntry = services.features.sdkApiEnabled
+                    ? await resolveSdkApiRegistryEntry(apiName, services)
+                    : undefined;
+                const apiSourceContent = await readApiSource(apiName, services, registryEntry);
+                const hasWrites = containsMutations(apiSourceContent, registryEntry ? (registryEntry.exportName ?? "default") : undefined);
+                if (!hasWrites) {
+                    return [];
+                }
+                const mutations = extractMutations(apiSourceContent, registryEntry ? (registryEntry.exportName ?? "default") : undefined);
+                // Managed app-database mutations always target Clark sandbox data —
+                // no approval needed. Mixed APIs still require WRITE only for the
+                // non-managed mutating integrations.
+                if (areAllMutatingIntegrationsManaged(mutations, services, apiName)) {
+                    return [];
+                }
+                // Keep registry WRITE escalation aligned with the migration modal's
+                // up-front write-policy. When policy allows this API, do not emit
+                // WRITE permissions here, otherwise ToolRegistry will re-escalate
+                // ALLOW -> PROMPT and ignore the user's choice.
+                const migrationDecision = await getMigrationPolicyDecision(services, apiSourceContent);
+                if (migrationDecision === "allow") {
+                    return [];
+                }
+                return resolveNonManagedWritePermissionIds(apiSourceContent, mutations, services).map((id) => ({
+                    entityType: AiEntityType.INTEGRATION,
+                    entityId: id,
+                    permissionType: AiPermissionType.WRITE,
+                }));
+            }
+            catch {
+                // Source read failed — return empty so the registry's
+                // shouldPromptForEntities (which returns true for []) prompts the user.
+                return [];
+            }
+        },
+        execute: async ({ apiName, inputs, omitStepOutputs, timeout }) => {
+            const logger = getPrefixedLogger(`[testApi-${apiName}]`);
+            logger.info(`Executing API ${apiName} with inputs:`, safeJsonStringify(inputs));
+            await assertReferencedLifecycleIntegrationsReady(apiName, services, logger);
+            clark.context.apiTestingState?.untested.delete(apiName);
+            // User approved execution — remove from denied so future file
+            // edits can re-mark the API as untested if needed.
+            clark.context.apiTestingState?.denied.delete(apiName);
+            if (services.features.sdkApiEnabled) {
+                return executeSdkApi({ apiName, inputs, clark, services, logger });
+            }
+            return executeYamlApi({
+                apiName,
+                inputs,
+                omitStepOutputs,
+                timeout,
+                clark,
+                services,
+                logger,
+            });
+        },
+        getSummary: (_input, output) => {
+            // Explicitly check for true - undefined/null means failure
+            const success = output.result?.success === true;
+            const status = success ? "Success" : "Failed";
+            return {
+                output: status,
+            };
+        },
+    };
+});
+//# sourceMappingURL=test-api.js.map