donobu 5.37.1 → 5.38.1

package/dist/esm/exceptions/FlowIdCollisionException.d.ts

@@ -0,0 +1,6 @@
+import { DonobuException } from './DonobuException';
+export declare class FlowIdCollisionException extends DonobuException {
+    private constructor();
+    static forId(flowId: string): FlowIdCollisionException;
+}
+//# sourceMappingURL=FlowIdCollisionException.d.ts.map

package/dist/esm/exceptions/FlowIdCollisionException.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowIdCollisionException = void 0;
+const DonobuException_1 = require("./DonobuException");
+class FlowIdCollisionException extends DonobuException_1.DonobuException {
+    constructor(message) {
+        super(message, undefined, 409);
+    }
+    static forId(flowId) {
+        return new FlowIdCollisionException(`A flow with ID '${flowId}' already exists. Client-supplied flow IDs must be unique.`);
+    }
+}
+exports.FlowIdCollisionException = FlowIdCollisionException;
+//# sourceMappingURL=FlowIdCollisionException.js.map

package/dist/esm/main.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod/v4';
 export { AnthropicGptClient } from './clients/AnthropicGptClient';
 export { DonobuGptClient } from './clients/DonobuGptClient';
 export { fixAssertFields, GoogleGenerativeAiGptClient, } from './clients/GoogleGenerativeAiGptClient';
@@ -8,6 +9,7 @@ export { VercelAiGptClient } from './clients/VercelAiGptClient';
 export { runGenerateSiteTests } from './codegen/runGenerateSiteTests';
 export { env } from './envVars';
 export * from './exceptions/DonobuException';
+export * from './exceptions/FlowIdCollisionException';
 export * from './exceptions/FlowNotFoundException';
 export * from './exceptions/GptApiKeysNotSetupException';
 export * from './exceptions/GptPlatformAuthenticationFailedException';
@@ -77,8 +79,51 @@ export * from './utils/TargetUtils';
  * Starts a Donobu API server at the given port. The server assumes that the
  * Playwright browsers have been installed.
  */
-export declare function startDonobuServer({ port, controlPanelHost, }?: {
+export declare function startDonobuServer({ port, controlPanelHost, environ, }?: {
     port?: number | undefined;
     controlPanelHost?: import("./models/ControlPanel").ControlPanelFactory | undefined;
+    environ?: import("env-struct").Env<{
+        BASE64_GPT_CONFIG: z.ZodOptional<z.ZodString>;
+        BROWSERBASE_API_KEY: z.ZodOptional<z.ZodString>;
+        BROWSERBASE_PROJECT_ID: z.ZodOptional<z.ZodString>;
+        DONOBU_DEPLOYMENT_ENVIRONMENT: z.ZodOptional<z.ZodEnum<{
+            LOCAL: "LOCAL";
+            DONOBU_HOSTED_MULTI_TENANT: "DONOBU_HOSTED_MULTI_TENANT";
+            DONOBU_HOSTED_SINGLE_TENANT: "DONOBU_HOSTED_SINGLE_TENANT";
+        }>>;
+        DONOBU_API_BASE_URL: z.ZodDefault<z.ZodString>;
+        ANTHROPIC_API_KEY: z.ZodOptional<z.ZodString>;
+        ANTHROPIC_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        GOOGLE_GENERATIVE_AI_API_KEY: z.ZodOptional<z.ZodString>;
+        GOOGLE_GENERATIVE_AI_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        OLLAMA_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        OLLAMA_API_URL: z.ZodOptional<z.ZodString>;
+        OPENAI_API_KEY: z.ZodOptional<z.ZodString>;
+        OPENAI_API_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        PERSISTENCE_PRIORITY: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        AWS_BEDROCK_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        AWS_ACCESS_KEY_ID: z.ZodOptional<z.ZodString>;
+        AWS_SECRET_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+        DONOBU_API_KEY: z.ZodOptional<z.ZodString>;
+    }, {
+        BASE64_GPT_CONFIG?: string | undefined;
+        BROWSERBASE_API_KEY?: string | undefined;
+        BROWSERBASE_PROJECT_ID?: string | undefined;
+        DONOBU_DEPLOYMENT_ENVIRONMENT?: "LOCAL" | "DONOBU_HOSTED_MULTI_TENANT" | "DONOBU_HOSTED_SINGLE_TENANT" | undefined;
+        DONOBU_API_BASE_URL: string;
+        ANTHROPIC_API_KEY?: string | undefined;
+        ANTHROPIC_MODEL_NAME?: string | undefined;
+        GOOGLE_GENERATIVE_AI_API_KEY?: string | undefined;
+        GOOGLE_GENERATIVE_AI_MODEL_NAME?: string | undefined;
+        OLLAMA_MODEL_NAME?: string | undefined;
+        OLLAMA_API_URL?: string | undefined;
+        OPENAI_API_KEY?: string | undefined;
+        OPENAI_API_MODEL_NAME?: string | undefined;
+        PERSISTENCE_PRIORITY: string[];
+        AWS_BEDROCK_MODEL_NAME?: string | undefined;
+        AWS_ACCESS_KEY_ID?: string | undefined;
+        AWS_SECRET_ACCESS_KEY?: string | undefined;
+        DONOBU_API_KEY?: string | undefined;
+    }> | undefined;
 }): Promise<void>;
 //# sourceMappingURL=main.d.ts.map

package/dist/esm/main.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "runGenerateSiteTests", { enumerable: true, get:
 var envVars_2 = require("./envVars");
 Object.defineProperty(exports, "env", { enumerable: true, get: function () { return envVars_2.env; } });
 __exportStar(require("./exceptions/DonobuException"), exports);
+__exportStar(require("./exceptions/FlowIdCollisionException"), exports);
 __exportStar(require("./exceptions/FlowNotFoundException"), exports);
 __exportStar(require("./exceptions/GptApiKeysNotSetupException"), exports);
 __exportStar(require("./exceptions/GptPlatformAuthenticationFailedException"), exports);
@@ -112,9 +113,9 @@ const DEFAULT_PORT = 31000;
  * Starts a Donobu API server at the given port. The server assumes that the
  * Playwright browsers have been installed.
  */
-async function startDonobuServer({ port = DEFAULT_PORT, controlPanelHost = ControlPanel_1.NoOpControlPanelFactory, } = {}) {
+async function startDonobuServer({ port = DEFAULT_PORT, controlPanelHost = ControlPanel_1.NoOpControlPanelFactory, environ = envVars_1.env.pick('ANTHROPIC_API_KEY', 'ANTHROPIC_MODEL_NAME', 'AWS_ACCESS_KEY_ID', 'AWS_BEDROCK_MODEL_NAME', 'AWS_SECRET_ACCESS_KEY', 'BASE64_GPT_CONFIG', 'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID', 'DONOBU_DEPLOYMENT_ENVIRONMENT', 'DONOBU_API_BASE_URL', 'DONOBU_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY', 'GOOGLE_GENERATIVE_AI_MODEL_NAME', 'OLLAMA_API_URL', 'OLLAMA_MODEL_NAME', 'OPENAI_API_KEY', 'OPENAI_API_MODEL_NAME', 'PERSISTENCE_PRIORITY'), } = {}) {
     try {
-        const adminController = await AdminApiController_1.AdminApiController.create(envVars_1.env.data.DONOBU_DEPLOYMENT_ENVIRONMENT ?? 'LOCAL', controlPanelHost, envVars_1.env);
+        const adminController = await AdminApiController_1.AdminApiController.create(environ.data.DONOBU_DEPLOYMENT_ENVIRONMENT ?? 'LOCAL', controlPanelHost, environ);
         adminController.start(port);
         Logger_1.appLogger.info(`Donobu API server available on http://localhost:${port}`);
         // Keep the process running until a process signal is detected.

package/dist/esm/managers/DonobuFlowsManager.d.ts

@@ -186,6 +186,12 @@ export declare class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    private assertFlowIdAvailable;
     private resolveLayerForFlowCreate;
     private findTestLayerKey;
     private isLocallyRunning;

package/dist/esm/managers/DonobuFlowsManager.js

@@ -45,6 +45,7 @@ const CodeGenerator_1 = require("../codegen/CodeGenerator");
 const ActiveFlowNotFoundException_1 = require("../exceptions/ActiveFlowNotFoundException");
 const BrowserStateNotFoundException_1 = require("../exceptions/BrowserStateNotFoundException");
 const CannotDeleteRunningFlowException_1 = require("../exceptions/CannotDeleteRunningFlowException");
+const FlowIdCollisionException_1 = require("../exceptions/FlowIdCollisionException");
 const FlowNotFoundException_1 = require("../exceptions/FlowNotFoundException");
 const InvalidParamValueException_1 = require("../exceptions/InvalidParamValueException");
 const TestNotFoundException_1 = require("../exceptions/TestNotFoundException");
@@ -96,7 +97,10 @@ class DonobuFlowsManager {
      *          related parameters are will be ignored.
      */
     async createFlow(flowParams, gptClient, browserContextOverride) {
-        const flowId = (0, crypto_1.randomUUID)();
+        if (flowParams.id) {
+            await this.assertFlowIdAvailable(flowParams.id);
+        }
+        const flowId = flowParams.id ?? (0, crypto_1.randomUUID)();
         const logBuffer = new FlowLogBuffer_1.FlowLogBuffer();
         return Logger_1.loggingContext.run({ flowId, logBuffer }, async () => {
             const messageDuration = flowParams.defaultMessageDuration ??
@@ -670,6 +674,27 @@ class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    async assertFlowIdAvailable(flowId) {
+        for (const persistence of await this.flowsPersistenceRegistry.getAll()) {
+            try {
+                await persistence.getFlowMetadataById(flowId);
+                throw FlowIdCollisionException_1.FlowIdCollisionException.forId(flowId);
+            }
+            catch (error) {
+                if (error instanceof FlowIdCollisionException_1.FlowIdCollisionException) {
+                    throw error;
+                }
+                if (!(error instanceof FlowNotFoundException_1.FlowNotFoundException)) {
+                    throw error;
+                }
+            }
+        }
+    }
     async resolveLayerForFlowCreate(testId) {
         if (!testId) {
             return this.flowsPersistenceRegistry.get();

package/dist/esm/models/CreateDonobuFlow.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 export declare const CreateDonobuFlowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
     target: z.ZodString;
     web: z.ZodOptional<z.ZodObject<{
         browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/esm/models/CreateDonobuFlow.js

@@ -7,7 +7,21 @@ const FlowMetadata_1 = require("./FlowMetadata");
 const ProposedToolCall_1 = require("./ProposedToolCall");
 const RunMode_1 = require("./RunMode");
 exports.CreateDonobuFlowSchema = v4_1.z
-    .object({
+    .looseObject({
+    id: v4_1.z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[a-zA-Z0-9._:-]+$/)
+        .optional()
+        .describe(`⚠️ ADVANCED — DO NOT USE unless you have a specific reason.
+Pre-assigned flow ID. Useful only when the caller must know the ID before
+flow creation completes (e.g. orchestrators that pre-allocate IDs to track
+an in-flight execution). The SDK does a best-effort collision check against
+the persistence layer and throws FlowIdCollisionException if the ID already
+exists, but concurrent calls with the same ID are RACY: there is no locking,
+so two callers can both pass the check and create dueling rows. If you do
+not need this, omit it and let the SDK mint an ID.`),
     target: v4_1.z
         .string()
         .describe('The target type: "web", "mobile", or a plugin-provided target.'),
@@ -69,6 +83,5 @@ is not defined or unresolvable, the default flow agent configuration will be use
         .optional()
         .describe('The ID of the test that this flow is associated with. Only optional to support legacy flow creation scenarios.'),
 })
-    .passthrough()
     .describe('This is the expected payload for a request to create a new Donobu flow');
 //# sourceMappingURL=CreateDonobuFlow.js.map

package/dist/esm/tools/TriggerDonobuFlowTool.d.ts

@@ -4,6 +4,7 @@ import type { ToolCallResult } from '../models/ToolCallResult';
 import { Tool } from './Tool';
 export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -151,6 +152,7 @@ export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const TriggerDonobuFlowGptSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/exceptions/FlowIdCollisionException.d.ts

@@ -0,0 +1,6 @@
+import { DonobuException } from './DonobuException';
+export declare class FlowIdCollisionException extends DonobuException {
+    private constructor();
+    static forId(flowId: string): FlowIdCollisionException;
+}
+//# sourceMappingURL=FlowIdCollisionException.d.ts.map

package/dist/exceptions/FlowIdCollisionException.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowIdCollisionException = void 0;
+const DonobuException_1 = require("./DonobuException");
+class FlowIdCollisionException extends DonobuException_1.DonobuException {
+    constructor(message) {
+        super(message, undefined, 409);
+    }
+    static forId(flowId) {
+        return new FlowIdCollisionException(`A flow with ID '${flowId}' already exists. Client-supplied flow IDs must be unique.`);
+    }
+}
+exports.FlowIdCollisionException = FlowIdCollisionException;
+//# sourceMappingURL=FlowIdCollisionException.js.map

package/dist/main.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod/v4';
 export { AnthropicGptClient } from './clients/AnthropicGptClient';
 export { DonobuGptClient } from './clients/DonobuGptClient';
 export { fixAssertFields, GoogleGenerativeAiGptClient, } from './clients/GoogleGenerativeAiGptClient';
@@ -8,6 +9,7 @@ export { VercelAiGptClient } from './clients/VercelAiGptClient';
 export { runGenerateSiteTests } from './codegen/runGenerateSiteTests';
 export { env } from './envVars';
 export * from './exceptions/DonobuException';
+export * from './exceptions/FlowIdCollisionException';
 export * from './exceptions/FlowNotFoundException';
 export * from './exceptions/GptApiKeysNotSetupException';
 export * from './exceptions/GptPlatformAuthenticationFailedException';
@@ -77,8 +79,51 @@ export * from './utils/TargetUtils';
  * Starts a Donobu API server at the given port. The server assumes that the
  * Playwright browsers have been installed.
  */
-export declare function startDonobuServer({ port, controlPanelHost, }?: {
+export declare function startDonobuServer({ port, controlPanelHost, environ, }?: {
     port?: number | undefined;
     controlPanelHost?: import("./models/ControlPanel").ControlPanelFactory | undefined;
+    environ?: import("env-struct").Env<{
+        BASE64_GPT_CONFIG: z.ZodOptional<z.ZodString>;
+        BROWSERBASE_API_KEY: z.ZodOptional<z.ZodString>;
+        BROWSERBASE_PROJECT_ID: z.ZodOptional<z.ZodString>;
+        DONOBU_DEPLOYMENT_ENVIRONMENT: z.ZodOptional<z.ZodEnum<{
+            LOCAL: "LOCAL";
+            DONOBU_HOSTED_MULTI_TENANT: "DONOBU_HOSTED_MULTI_TENANT";
+            DONOBU_HOSTED_SINGLE_TENANT: "DONOBU_HOSTED_SINGLE_TENANT";
+        }>>;
+        DONOBU_API_BASE_URL: z.ZodDefault<z.ZodString>;
+        ANTHROPIC_API_KEY: z.ZodOptional<z.ZodString>;
+        ANTHROPIC_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        GOOGLE_GENERATIVE_AI_API_KEY: z.ZodOptional<z.ZodString>;
+        GOOGLE_GENERATIVE_AI_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        OLLAMA_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        OLLAMA_API_URL: z.ZodOptional<z.ZodString>;
+        OPENAI_API_KEY: z.ZodOptional<z.ZodString>;
+        OPENAI_API_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        PERSISTENCE_PRIORITY: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        AWS_BEDROCK_MODEL_NAME: z.ZodOptional<z.ZodString>;
+        AWS_ACCESS_KEY_ID: z.ZodOptional<z.ZodString>;
+        AWS_SECRET_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+        DONOBU_API_KEY: z.ZodOptional<z.ZodString>;
+    }, {
+        BASE64_GPT_CONFIG?: string | undefined;
+        BROWSERBASE_API_KEY?: string | undefined;
+        BROWSERBASE_PROJECT_ID?: string | undefined;
+        DONOBU_DEPLOYMENT_ENVIRONMENT?: "LOCAL" | "DONOBU_HOSTED_MULTI_TENANT" | "DONOBU_HOSTED_SINGLE_TENANT" | undefined;
+        DONOBU_API_BASE_URL: string;
+        ANTHROPIC_API_KEY?: string | undefined;
+        ANTHROPIC_MODEL_NAME?: string | undefined;
+        GOOGLE_GENERATIVE_AI_API_KEY?: string | undefined;
+        GOOGLE_GENERATIVE_AI_MODEL_NAME?: string | undefined;
+        OLLAMA_MODEL_NAME?: string | undefined;
+        OLLAMA_API_URL?: string | undefined;
+        OPENAI_API_KEY?: string | undefined;
+        OPENAI_API_MODEL_NAME?: string | undefined;
+        PERSISTENCE_PRIORITY: string[];
+        AWS_BEDROCK_MODEL_NAME?: string | undefined;
+        AWS_ACCESS_KEY_ID?: string | undefined;
+        AWS_SECRET_ACCESS_KEY?: string | undefined;
+        DONOBU_API_KEY?: string | undefined;
+    }> | undefined;
 }): Promise<void>;
 //# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -44,6 +44,7 @@ Object.defineProperty(exports, "runGenerateSiteTests", { enumerable: true, get:
 var envVars_2 = require("./envVars");
 Object.defineProperty(exports, "env", { enumerable: true, get: function () { return envVars_2.env; } });
 __exportStar(require("./exceptions/DonobuException"), exports);
+__exportStar(require("./exceptions/FlowIdCollisionException"), exports);
 __exportStar(require("./exceptions/FlowNotFoundException"), exports);
 __exportStar(require("./exceptions/GptApiKeysNotSetupException"), exports);
 __exportStar(require("./exceptions/GptPlatformAuthenticationFailedException"), exports);
@@ -112,9 +113,9 @@ const DEFAULT_PORT = 31000;
  * Starts a Donobu API server at the given port. The server assumes that the
  * Playwright browsers have been installed.
  */
-async function startDonobuServer({ port = DEFAULT_PORT, controlPanelHost = ControlPanel_1.NoOpControlPanelFactory, } = {}) {
+async function startDonobuServer({ port = DEFAULT_PORT, controlPanelHost = ControlPanel_1.NoOpControlPanelFactory, environ = envVars_1.env.pick('ANTHROPIC_API_KEY', 'ANTHROPIC_MODEL_NAME', 'AWS_ACCESS_KEY_ID', 'AWS_BEDROCK_MODEL_NAME', 'AWS_SECRET_ACCESS_KEY', 'BASE64_GPT_CONFIG', 'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID', 'DONOBU_DEPLOYMENT_ENVIRONMENT', 'DONOBU_API_BASE_URL', 'DONOBU_API_KEY', 'GOOGLE_GENERATIVE_AI_API_KEY', 'GOOGLE_GENERATIVE_AI_MODEL_NAME', 'OLLAMA_API_URL', 'OLLAMA_MODEL_NAME', 'OPENAI_API_KEY', 'OPENAI_API_MODEL_NAME', 'PERSISTENCE_PRIORITY'), } = {}) {
     try {
-        const adminController = await AdminApiController_1.AdminApiController.create(envVars_1.env.data.DONOBU_DEPLOYMENT_ENVIRONMENT ?? 'LOCAL', controlPanelHost, envVars_1.env);
+        const adminController = await AdminApiController_1.AdminApiController.create(environ.data.DONOBU_DEPLOYMENT_ENVIRONMENT ?? 'LOCAL', controlPanelHost, environ);
         adminController.start(port);
         Logger_1.appLogger.info(`Donobu API server available on http://localhost:${port}`);
         // Keep the process running until a process signal is detected.

package/dist/managers/DonobuFlowsManager.d.ts

@@ -186,6 +186,12 @@ export declare class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    private assertFlowIdAvailable;
     private resolveLayerForFlowCreate;
     private findTestLayerKey;
     private isLocallyRunning;

package/dist/managers/DonobuFlowsManager.js

@@ -45,6 +45,7 @@ const CodeGenerator_1 = require("../codegen/CodeGenerator");
 const ActiveFlowNotFoundException_1 = require("../exceptions/ActiveFlowNotFoundException");
 const BrowserStateNotFoundException_1 = require("../exceptions/BrowserStateNotFoundException");
 const CannotDeleteRunningFlowException_1 = require("../exceptions/CannotDeleteRunningFlowException");
+const FlowIdCollisionException_1 = require("../exceptions/FlowIdCollisionException");
 const FlowNotFoundException_1 = require("../exceptions/FlowNotFoundException");
 const InvalidParamValueException_1 = require("../exceptions/InvalidParamValueException");
 const TestNotFoundException_1 = require("../exceptions/TestNotFoundException");
@@ -96,7 +97,10 @@ class DonobuFlowsManager {
      *          related parameters are will be ignored.
      */
     async createFlow(flowParams, gptClient, browserContextOverride) {
-        const flowId = (0, crypto_1.randomUUID)();
+        if (flowParams.id) {
+            await this.assertFlowIdAvailable(flowParams.id);
+        }
+        const flowId = flowParams.id ?? (0, crypto_1.randomUUID)();
         const logBuffer = new FlowLogBuffer_1.FlowLogBuffer();
         return Logger_1.loggingContext.run({ flowId, logBuffer }, async () => {
             const messageDuration = flowParams.defaultMessageDuration ??
@@ -670,6 +674,27 @@ class DonobuFlowsManager {
      *   back to the primary layer (the SQLite FK will reject if applicable;
      *   non-DB layers will accept the dangling reference).
      */
+    /**
+     * Best-effort check that no flow with the given ID exists in any persistence
+     * layer. Throws {@link FlowIdCollisionException} on hit. Note: this is RACY
+     * — concurrent callers with the same ID can both pass the check.
+     */
+    async assertFlowIdAvailable(flowId) {
+        for (const persistence of await this.flowsPersistenceRegistry.getAll()) {
+            try {
+                await persistence.getFlowMetadataById(flowId);
+                throw FlowIdCollisionException_1.FlowIdCollisionException.forId(flowId);
+            }
+            catch (error) {
+                if (error instanceof FlowIdCollisionException_1.FlowIdCollisionException) {
+                    throw error;
+                }
+                if (!(error instanceof FlowNotFoundException_1.FlowNotFoundException)) {
+                    throw error;
+                }
+            }
+        }
+    }
     async resolveLayerForFlowCreate(testId) {
         if (!testId) {
             return this.flowsPersistenceRegistry.get();

package/dist/models/CreateDonobuFlow.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 export declare const CreateDonobuFlowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
     target: z.ZodString;
     web: z.ZodOptional<z.ZodObject<{
         browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/models/CreateDonobuFlow.js

@@ -7,7 +7,21 @@ const FlowMetadata_1 = require("./FlowMetadata");
 const ProposedToolCall_1 = require("./ProposedToolCall");
 const RunMode_1 = require("./RunMode");
 exports.CreateDonobuFlowSchema = v4_1.z
-    .object({
+    .looseObject({
+    id: v4_1.z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[a-zA-Z0-9._:-]+$/)
+        .optional()
+        .describe(`⚠️ ADVANCED — DO NOT USE unless you have a specific reason.
+Pre-assigned flow ID. Useful only when the caller must know the ID before
+flow creation completes (e.g. orchestrators that pre-allocate IDs to track
+an in-flight execution). The SDK does a best-effort collision check against
+the persistence layer and throws FlowIdCollisionException if the ID already
+exists, but concurrent calls with the same ID are RACY: there is no locking,
+so two callers can both pass the check and create dueling rows. If you do
+not need this, omit it and let the SDK mint an ID.`),
     target: v4_1.z
         .string()
         .describe('The target type: "web", "mobile", or a plugin-provided target.'),
@@ -69,6 +83,5 @@ is not defined or unresolvable, the default flow agent configuration will be use
         .optional()
         .describe('The ID of the test that this flow is associated with. Only optional to support legacy flow creation scenarios.'),
 })
-    .passthrough()
     .describe('This is the expected payload for a request to create a new Donobu flow');
 //# sourceMappingURL=CreateDonobuFlow.js.map

package/dist/tools/TriggerDonobuFlowTool.d.ts

@@ -4,6 +4,7 @@ import type { ToolCallResult } from '../models/ToolCallResult';
 import { Tool } from './Tool';
 export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -151,6 +152,7 @@ export declare const TriggerDonobuFlowCoreSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const TriggerDonobuFlowGptSchema: z.ZodObject<{
     donobuFlowParameters: z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
         target: z.ZodString;
         web: z.ZodOptional<z.ZodObject<{
             browser: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.37.1",
+  "version": "5.38.1",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",