donobu 5.61.3 → 5.62.0

package/dist/cli/donobu-cli.js

@@ -66,6 +66,7 @@ const healRerunGate_1 = require("../lib/test/healRerunGate");
 const donobuTestStack_1 = require("../lib/test/utils/donobuTestStack");
 const triageTestFailure_1 = require("../lib/test/utils/triageTestFailure");
 const fileUploadWorkerRegistry_1 = require("../persistence/files/fileUploadWorkerRegistry");
+const FlowsPersistence_1 = require("../persistence/flows/FlowsPersistence");
 const FlowsPersistenceDonobuApi_1 = require("../persistence/flows/FlowsPersistenceDonobuApi");
 const FlowsPersistenceRegistry_1 = require("../persistence/flows/FlowsPersistenceRegistry");
 const merge_1 = require("../reporter/merge");
@@ -1292,7 +1293,7 @@ async function postProcessTriageRun(context, originalPlaywrightArgs, reportPath)
                 const donobu = await (0, donobuTestStack_1.getOrCreateDonobuStack)();
                 const persistence = await donobu.flowsPersistenceRegistry.get();
                 const planBuffer = Buffer.from(persistedJson, 'utf8');
-                const fileId = 'treatment-plan.json';
+                const fileId = FlowsPersistence_1.WELL_KNOWN_FILE_IDS.treatmentPlan;
                 await persistence.setFlowFile(flowId, fileId, planBuffer);
                 Logger_1.appLogger.info(`Persisted treatment plan for "${testLabel}" as "${fileId}" to Donobu stack (flow: ${flowId}).`);
             }

package/dist/esm/cli/donobu-cli.js

@@ -66,6 +66,7 @@ const healRerunGate_1 = require("../lib/test/healRerunGate");
 const donobuTestStack_1 = require("../lib/test/utils/donobuTestStack");
 const triageTestFailure_1 = require("../lib/test/utils/triageTestFailure");
 const fileUploadWorkerRegistry_1 = require("../persistence/files/fileUploadWorkerRegistry");
+const FlowsPersistence_1 = require("../persistence/flows/FlowsPersistence");
 const FlowsPersistenceDonobuApi_1 = require("../persistence/flows/FlowsPersistenceDonobuApi");
 const FlowsPersistenceRegistry_1 = require("../persistence/flows/FlowsPersistenceRegistry");
 const merge_1 = require("../reporter/merge");
@@ -1292,7 +1293,7 @@ async function postProcessTriageRun(context, originalPlaywrightArgs, reportPath)
                 const donobu = await (0, donobuTestStack_1.getOrCreateDonobuStack)();
                 const persistence = await donobu.flowsPersistenceRegistry.get();
                 const planBuffer = Buffer.from(persistedJson, 'utf8');
-                const fileId = 'treatment-plan.json';
+                const fileId = FlowsPersistence_1.WELL_KNOWN_FILE_IDS.treatmentPlan;
                 await persistence.setFlowFile(flowId, fileId, planBuffer);
                 Logger_1.appLogger.info(`Persisted treatment plan for "${testLabel}" as "${fileId}" to Donobu stack (flow: ${flowId}).`);
             }

package/dist/esm/lib/test/testExtension.js

@@ -31,6 +31,7 @@ const v4_1 = require("zod/v4");
 const envVars_1 = require("../../envVars");
 const DonobuFlowsManager_1 = require("../../managers/DonobuFlowsManager");
 const fileUploadWorkerRegistry_1 = require("../../persistence/files/fileUploadWorkerRegistry");
+const FlowsPersistence_1 = require("../../persistence/flows/FlowsPersistence");
 const ansi_1 = require("../../utils/ansi");
 const BrowserUtils_1 = require("../../utils/BrowserUtils");
 const buildProvenance_1 = require("../../utils/buildProvenance");
@@ -958,7 +959,7 @@ async function captureAndPersistFinalState(page, testInfo) {
     try {
         const screenshot = await (0, triageTestFailure_1.captureLivePageScreenshot)(page);
         if (screenshot) {
-            await persistence.setFlowFile(flowId, triageTestFailure_1.TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot, screenshot);
+            await persistence.setFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.triage.finalStateScreenshot, screenshot);
         }
     }
     catch (error) {
@@ -991,11 +992,11 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
         // assertion errors with snippets/diffs) so the website can render the
         // report's summary row + error section. Playwright's TestInfoError already
         // carries the code `snippet`, so no source-file access is needed.
-        await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, 'donobu-test-result.json', buildDonobuTestResult(testInfo));
+        await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.donobuTestResult, buildDonobuTestResult(testInfo));
         // Persist captured flow logs so they are available in the Donobu UI,
         // mirroring what DonobuFlowsManager does for Studio-launched flows.
         if (logBuffer) {
-            await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, 'logs.json', logBuffer.snapshot());
+            await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.logs, logBuffer.snapshot());
         }
         // Attach step-level screenshots from the flow's tool call history.
         // These enable the HTML report to show a visual timeline of what the

package/dist/esm/lib/test/utils/triageTestFailure.d.ts

@@ -409,13 +409,6 @@ declare const TRIAGE_PERSISTENCE_FILE_IDS: {
     readonly evidence: "triage-evidence.json";
     readonly failureScreenshot: "triage-failure-screenshot.png";
     readonly baselineScreenshot: "triage-baseline-screenshot.png";
-    /**
-     * Live screenshot of a flow's final visual state, captured at teardown while
-     * the page is still open. Persisted on successful runs so that a *later*
-     * failing run can use it as a true final-state baseline — symmetric with the
-     * failure screenshot, which is also a live end-of-test capture. Keyed per
-     * flow, like browser state.
-     */
     readonly finalStateScreenshot: "triage-final-state-screenshot.png";
 };
 /**

package/dist/esm/lib/test/utils/triageTestFailure.js

@@ -49,6 +49,7 @@ const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const typescript_1 = __importDefault(require("typescript"));
 const v4_1 = require("zod/v4");
+const FlowsPersistence_1 = require("../../../persistence/flows/FlowsPersistence");
 const AnalyzePageTextTool_1 = require("../../../tools/AnalyzePageTextTool");
 const MarkObjectiveCompleteTool_1 = require("../../../tools/MarkObjectiveCompleteTool");
 const MarkObjectiveNotCompletableTool_1 = require("../../../tools/MarkObjectiveNotCompletableTool");
@@ -329,19 +330,7 @@ const MAX_SERIALIZED_STRING_LENGTH = 10000;
 const MAX_TOOL_CALL_PARAMETERS_LENGTH = 500;
 const MAX_TOOL_CALLS_TO_INCLUDE = 12;
 const TRIAGE_EVIDENCE_SCHEMA_VERSION = 2;
-const TRIAGE_PERSISTENCE_FILE_IDS = {
-    evidence: 'triage-evidence.json',
-    failureScreenshot: 'triage-failure-screenshot.png',
-    baselineScreenshot: 'triage-baseline-screenshot.png',
-    /**
-     * Live screenshot of a flow's final visual state, captured at teardown while
-     * the page is still open. Persisted on successful runs so that a *later*
-     * failing run can use it as a true final-state baseline — symmetric with the
-     * failure screenshot, which is also a live end-of-test capture. Keyed per
-     * flow, like browser state.
-     */
-    finalStateScreenshot: 'triage-final-state-screenshot.png',
-};
+const TRIAGE_PERSISTENCE_FILE_IDS = FlowsPersistence_1.WELL_KNOWN_FILE_IDS.triage;
 exports.TRIAGE_PERSISTENCE_FILE_IDS = TRIAGE_PERSISTENCE_FILE_IDS;
 /**
  * Ensures text blobs captured from tool calls or error messages fit within storage

package/dist/esm/main.d.ts

@@ -61,7 +61,7 @@ export type * from './models/ToolTemplateDataSource';
 export type { VideoSegment } from './models/VideoSegment';
 export type { EnvPersistence } from './persistence/env/EnvPersistence';
 export { type FileUploadAggregateStatus, type FileUploadPlatformStatus, getFileUploadAggregateStatus, shutdownFileUploadWorkers, } from './persistence/files/fileUploadWorkerRegistry';
-export type { FlowsPersistence } from './persistence/flows/FlowsPersistence';
+export { type FlowsPersistence, WELL_KNOWN_FILE_IDS, } from './persistence/flows/FlowsPersistence';
 export { type PersistencePlugin, PersistencePluginRegistry, } from './persistence/PersistencePlugin';
 export type { SuitesPersistence } from './persistence/suites/SuitesPersistence';
 export type { TestsPersistence } from './persistence/tests/TestsPersistence';

package/dist/esm/main.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TargetRuntimePluginRegistry = exports.PersistencePluginRegistry = exports.shutdownFileUploadWorkers = exports.getFileUploadAggregateStatus = exports.createDefaultToolRegistry = exports.ToolManager = exports.buildToolInterpolationDataSource = exports.PluginLoader = exports.InteractionVisualizer = exports.setupDonobuStack = exports.prepareToolCallsForRerun = exports.DonobuFlowsManager = exports.distillAllowedEnvVariableNames = exports.DonobuFlow = exports.AdminApiController = exports.env = exports.VercelAiGptClient = exports.OpenAiGptClient = exports.GptClientPluginRegistry = exports.GptClient = exports.GoogleGenerativeAiGptClient = exports.fixAssertFields = exports.DonobuGptClient = exports.AnthropicGptClient = void 0;
+exports.TargetRuntimePluginRegistry = exports.PersistencePluginRegistry = exports.WELL_KNOWN_FILE_IDS = exports.shutdownFileUploadWorkers = exports.getFileUploadAggregateStatus = exports.createDefaultToolRegistry = exports.ToolManager = exports.buildToolInterpolationDataSource = exports.PluginLoader = exports.InteractionVisualizer = exports.setupDonobuStack = exports.prepareToolCallsForRerun = exports.DonobuFlowsManager = exports.distillAllowedEnvVariableNames = exports.DonobuFlow = exports.AdminApiController = exports.env = exports.VercelAiGptClient = exports.OpenAiGptClient = exports.GptClientPluginRegistry = exports.GptClient = exports.GoogleGenerativeAiGptClient = exports.fixAssertFields = exports.DonobuGptClient = exports.AnthropicGptClient = void 0;
 exports.startDonobuServer = startDonobuServer;
 const commander_1 = require("commander");
 const v4_1 = require("zod/v4");
@@ -94,6 +94,8 @@ __exportStar(require("./models/ToolSchema"), exports);
 var fileUploadWorkerRegistry_1 = require("./persistence/files/fileUploadWorkerRegistry");
 Object.defineProperty(exports, "getFileUploadAggregateStatus", { enumerable: true, get: function () { return fileUploadWorkerRegistry_1.getFileUploadAggregateStatus; } });
 Object.defineProperty(exports, "shutdownFileUploadWorkers", { enumerable: true, get: function () { return fileUploadWorkerRegistry_1.shutdownFileUploadWorkers; } });
+var FlowsPersistence_1 = require("./persistence/flows/FlowsPersistence");
+Object.defineProperty(exports, "WELL_KNOWN_FILE_IDS", { enumerable: true, get: function () { return FlowsPersistence_1.WELL_KNOWN_FILE_IDS; } });
 var PersistencePlugin_1 = require("./persistence/PersistencePlugin");
 Object.defineProperty(exports, "PersistencePluginRegistry", { enumerable: true, get: function () { return PersistencePlugin_1.PersistencePluginRegistry; } });
 var TargetRuntimePlugin_1 = require("./targets/TargetRuntimePlugin");

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

@@ -49,7 +49,7 @@ export declare class DonobuFlowsManager {
     private readonly testsPersistenceRegistry;
     static readonly DEFAULT_MESSAGE_DURATION = 2247;
     static readonly DEFAULT_MAX_TOOL_CALLS = 50;
-    static readonly DEFAULT_BROWSER_STATE_FILENAME = "browserstate.json";
+    static readonly DEFAULT_BROWSER_STATE_FILENAME: "browserstate.json";
     static readonly FLOW_NAME_MAX_LENGTH = 1024;
     private readonly flowRuntime;
     private readonly flowCatalog;

package/dist/esm/managers/DonobuFlowsManager.js

@@ -55,6 +55,7 @@ const UnknownToolException_1 = require("../exceptions/UnknownToolException");
 const CreateDonobuFlow_1 = require("../models/CreateDonobuFlow");
 const GptConfig_1 = require("../models/GptConfig");
 const MetadataVersion_1 = require("../models/MetadataVersion");
+const FlowsPersistence_1 = require("../persistence/flows/FlowsPersistence");
 const resolveTargetRuntime_1 = require("../targets/resolveTargetRuntime");
 const CustomToolRunnerTool_1 = require("../tools/CustomToolRunnerTool");
 const buildProvenance_1 = require("../utils/buildProvenance");
@@ -218,7 +219,7 @@ class DonobuFlowsManager {
                     }
                     try {
                         const snapshot = logBuffer.snapshot();
-                        await flowsPersistence.setFlowFile(donobuFlow.metadata.id, 'logs.json', Buffer.from(JSON.stringify(snapshot)));
+                        await flowsPersistence.setFlowFile(donobuFlow.metadata.id, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.logs, Buffer.from(JSON.stringify(snapshot)));
                     }
                     catch (error) {
                         Logger_1.appLogger.error('Failed to persist flow logs:', error);
@@ -254,7 +255,7 @@ class DonobuFlowsManager {
         }
         // Otherwise, read the persisted snapshot.
         const persistence = await this.flowsPersistenceRegistry.get();
-        const file = await persistence.getFlowFile(flowId, 'logs.json');
+        const file = await persistence.getFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.logs);
         if (file) {
             return JSON.parse(file.toString('utf8'));
         }
@@ -757,7 +758,7 @@ DonobuFlowsManager.DEFAULT_MESSAGE_DURATION = 2247;
 // If you change this value, also consider changing the frontend default
 // value in createFlowDefaults in flow-types.ts.
 DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS = 50;
-DonobuFlowsManager.DEFAULT_BROWSER_STATE_FILENAME = 'browserstate.json';
+DonobuFlowsManager.DEFAULT_BROWSER_STATE_FILENAME = FlowsPersistence_1.WELL_KNOWN_FILE_IDS.browserState;
 // Re-exported from models/CreateDonobuFlow so existing callers can keep using
 // DonobuFlowsManager.FLOW_NAME_MAX_LENGTH. The source of truth (and the
 // rationale for keeping it in sync with the donobu-api gateway) lives there.

package/dist/esm/persistence/flows/FlowsPersistence.d.ts

@@ -4,6 +4,39 @@ import type { FlowMetadata, FlowsQuery } from '../../models/FlowMetadata';
 import type { PaginatedResult } from '../../models/PaginatedResult';
 import type { ToolCall } from '../../models/ToolCall';
 import type { VideoSegment } from '../../models/VideoSegment';
+/**
+ * Well-known per-flow persistence filenames reserved by Donobu.
+ *
+ * These names are storage contracts. Avoid reusing them for ad hoc tool
+ * artifacts.
+ */
+export declare const WELL_KNOWN_FILE_IDS: {
+    /** Full flow video backing {@link FlowsPersistence.setVideo}. */
+    readonly video: "video.webm";
+    /** Browser storage state backing {@link FlowsPersistence.setBrowserState}. */
+    readonly browserState: "browserstate.json";
+    /** Structured flow log snapshot consumed by the Studio flow log view. */
+    readonly logs: "logs.json";
+    /** Playwright test result summary consumed by the Donobu HTML report. */
+    readonly donobuTestResult: "donobu-test-result.json";
+    /** Generated remediation plan consumed by Studio and admin tooling. */
+    readonly treatmentPlan: "treatment-plan.json";
+    /** Failure-triage artifacts persisted alongside a test flow. */
+    readonly triage: {
+        /** Serialized GPT triage evidence and heuristic assessment. */
+        readonly evidence: "triage-evidence.json";
+        /** Screenshot from the failed run's final page state. */
+        readonly failureScreenshot: "triage-failure-screenshot.png";
+        /** Screenshot from the latest successful baseline run. */
+        readonly baselineScreenshot: "triage-baseline-screenshot.png";
+        /**
+         * Live final-state screenshot captured at test teardown. Successful runs
+         * provide the baseline for later failures; failed runs provide the current
+         * failure screenshot.
+         */
+        readonly finalStateScreenshot: "triage-final-state-screenshot.png";
+    };
+};
 /**
  * Interface for persisting data relating to DonobuFlow runs.
  */

package/dist/esm/persistence/flows/FlowsPersistence.js

@@ -1,3 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WELL_KNOWN_FILE_IDS = void 0;
+/**
+ * Well-known per-flow persistence filenames reserved by Donobu.
+ *
+ * These names are storage contracts. Avoid reusing them for ad hoc tool
+ * artifacts.
+ */
+exports.WELL_KNOWN_FILE_IDS = {
+    /** Full flow video backing {@link FlowsPersistence.setVideo}. */
+    video: 'video.webm',
+    /** Browser storage state backing {@link FlowsPersistence.setBrowserState}. */
+    browserState: 'browserstate.json',
+    /** Structured flow log snapshot consumed by the Studio flow log view. */
+    logs: 'logs.json',
+    /** Playwright test result summary consumed by the Donobu HTML report. */
+    donobuTestResult: 'donobu-test-result.json',
+    /** Generated remediation plan consumed by Studio and admin tooling. */
+    treatmentPlan: 'treatment-plan.json',
+    /** Failure-triage artifacts persisted alongside a test flow. */
+    triage: {
+        /** Serialized GPT triage evidence and heuristic assessment. */
+        evidence: 'triage-evidence.json',
+        /** Screenshot from the failed run's final page state. */
+        failureScreenshot: 'triage-failure-screenshot.png',
+        /** Screenshot from the latest successful baseline run. */
+        baselineScreenshot: 'triage-baseline-screenshot.png',
+        /**
+         * Live final-state screenshot captured at test teardown. Successful runs
+         * provide the baseline for later failures; failed runs provide the current
+         * failure screenshot.
+         */
+        finalStateScreenshot: 'triage-final-state-screenshot.png',
+    },
+};
 //# sourceMappingURL=FlowsPersistence.js.map

package/dist/esm/persistence/flows/FlowsPersistenceDonobuApi.d.ts

@@ -5,7 +5,7 @@ import type { PaginatedResult } from '../../models/PaginatedResult';
 import type { ToolCall } from '../../models/ToolCall';
 import type { VideoSegment } from '../../models/VideoSegment';
 import { FileUploadCache } from '../files/FileUploadCache';
-import type { FlowsPersistence } from './FlowsPersistence';
+import { type FlowsPersistence } from './FlowsPersistence';
 /**
  * A {@link FlowsPersistence} implementation that persists flow data via the
  * Donobu API.  The API stores the SDK's data models as opaque JSON blobs,

package/dist/esm/persistence/flows/FlowsPersistenceDonobuApi.js

@@ -14,8 +14,8 @@ const MiscUtils_1 = require("../../utils/MiscUtils");
 const FileUploadCache_1 = require("../files/FileUploadCache");
 const FileUploadWorker_1 = require("../files/FileUploadWorker");
 const fileUploadWorkerRegistry_1 = require("../files/fileUploadWorkerRegistry");
+const FlowsPersistence_1 = require("./FlowsPersistence");
 const PLATFORM_LABEL = 'donobu';
-const VIDEO_FILE_ID = 'video.webm';
 /**
  * A {@link FlowsPersistence} implementation that persists flow data via the
  * Donobu API.  The API stores the SDK's data models as opaque JSON blobs,
@@ -205,10 +205,10 @@ class FlowsPersistenceDonobuApi {
     }
     // -- Screenshots ---------------------------------------------------
     async setVideo(flowId, bytes) {
-        await this.setFlowFile(flowId, VIDEO_FILE_ID, bytes);
+        await this.setFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video, bytes);
     }
     async getVideoSegment(flowId, startOffset, length) {
-        const videoBuffer = await this.getFlowFile(flowId, VIDEO_FILE_ID);
+        const videoBuffer = await this.getFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video);
         if (!videoBuffer) {
             return null;
         }

package/dist/esm/persistence/flows/FlowsPersistenceSqlite.d.ts

@@ -5,15 +5,13 @@ import type { FlowMetadata, FlowsQuery } from '../../models/FlowMetadata';
 import type { PaginatedResult } from '../../models/PaginatedResult';
 import type { ToolCall } from '../../models/ToolCall';
 import type { VideoSegment } from '../../models/VideoSegment';
-import type { FlowsPersistence } from './FlowsPersistence';
+import { type FlowsPersistence } from './FlowsPersistence';
 /**
  * A persistence implementation that uses SQLite for all data storage, including binary files.
  */
 export declare class FlowsPersistenceSqlite implements FlowsPersistence {
     private readonly db;
     private static readonly VIDEO_MIME_TYPE;
-    private static readonly BROWSER_STATE_FILE_ID;
-    private static readonly VIDEO_FILE_ID;
     private constructor();
     static create(db: Database.Database): Promise<FlowsPersistenceSqlite>;
     setEnvironmentDatum(key: string, value: string): Promise<void>;

package/dist/esm/persistence/flows/FlowsPersistenceSqlite.js

@@ -7,6 +7,7 @@ const AiQuery_1 = require("../../models/AiQuery");
 const BrowserStorageState_1 = require("../../models/BrowserStorageState");
 const MiscUtils_1 = require("../../utils/MiscUtils");
 const normalizeFlowMetadata_1 = require("../normalizeFlowMetadata");
+const FlowsPersistence_1 = require("./FlowsPersistence");
 /**
  * A persistence implementation that uses SQLite for all data storage, including binary files.
  */
@@ -221,13 +222,13 @@ class FlowsPersistenceSqlite {
     async setVideo(flowId, bytes) {
         // Ensure flow exists.
         await this.getFlowMetadataById(flowId);
-        const binaryId = `${flowId}-${FlowsPersistenceSqlite.VIDEO_FILE_ID}`;
+        const binaryId = `${flowId}-${FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video}`;
         const stmt = this.db.prepare('INSERT OR REPLACE INTO binary_files (id, flow_id, file_id, mime_type, content) VALUES (?, ?, ?, ?, ?)');
-        stmt.run(binaryId, flowId, FlowsPersistenceSqlite.VIDEO_FILE_ID, FlowsPersistenceSqlite.VIDEO_MIME_TYPE, bytes);
+        stmt.run(binaryId, flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video, FlowsPersistenceSqlite.VIDEO_MIME_TYPE, bytes);
     }
     async getVideoSegment(flowId, startOffset, length) {
         const stmt = this.db.prepare('SELECT content FROM binary_files WHERE flow_id = ? AND file_id = ?');
-        const row = stmt.get(flowId, FlowsPersistenceSqlite.VIDEO_FILE_ID);
+        const row = stmt.get(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video);
         if (!row) {
             return null;
         }
@@ -261,10 +262,10 @@ class FlowsPersistenceSqlite {
     }
     async setBrowserState(flowId, browserState) {
         const serializedBrowserState = Buffer.from(JSON.stringify(browserState), 'utf-8');
-        await this.setFlowFile(flowId, FlowsPersistenceSqlite.BROWSER_STATE_FILE_ID, serializedBrowserState);
+        await this.setFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.browserState, serializedBrowserState);
     }
     async getBrowserState(flowId) {
-        const browserStateRaw = await this.getFlowFile(flowId, FlowsPersistenceSqlite.BROWSER_STATE_FILE_ID);
+        const browserStateRaw = await this.getFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.browserState);
         if (browserStateRaw) {
             return BrowserStorageState_1.BrowserStorageStateSchema.parse(JSON.parse(browserStateRaw.toString('utf-8')));
         }
@@ -284,6 +285,4 @@ class FlowsPersistenceSqlite {
 }
 exports.FlowsPersistenceSqlite = FlowsPersistenceSqlite;
 FlowsPersistenceSqlite.VIDEO_MIME_TYPE = 'video/webm';
-FlowsPersistenceSqlite.BROWSER_STATE_FILE_ID = 'browserstate.json';
-FlowsPersistenceSqlite.VIDEO_FILE_ID = 'video.webm';
 //# sourceMappingURL=FlowsPersistenceSqlite.js.map

package/dist/lib/test/testExtension.js

@@ -31,6 +31,7 @@ const v4_1 = require("zod/v4");
 const envVars_1 = require("../../envVars");
 const DonobuFlowsManager_1 = require("../../managers/DonobuFlowsManager");
 const fileUploadWorkerRegistry_1 = require("../../persistence/files/fileUploadWorkerRegistry");
+const FlowsPersistence_1 = require("../../persistence/flows/FlowsPersistence");
 const ansi_1 = require("../../utils/ansi");
 const BrowserUtils_1 = require("../../utils/BrowserUtils");
 const buildProvenance_1 = require("../../utils/buildProvenance");
@@ -958,7 +959,7 @@ async function captureAndPersistFinalState(page, testInfo) {
     try {
         const screenshot = await (0, triageTestFailure_1.captureLivePageScreenshot)(page);
         if (screenshot) {
-            await persistence.setFlowFile(flowId, triageTestFailure_1.TRIAGE_PERSISTENCE_FILE_IDS.finalStateScreenshot, screenshot);
+            await persistence.setFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.triage.finalStateScreenshot, screenshot);
         }
     }
     catch (error) {
@@ -991,11 +992,11 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
         // assertion errors with snippets/diffs) so the website can render the
         // report's summary row + error section. Playwright's TestInfoError already
         // carries the code `snippet`, so no source-file access is needed.
-        await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, 'donobu-test-result.json', buildDonobuTestResult(testInfo));
+        await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.donobuTestResult, buildDonobuTestResult(testInfo));
         // Persist captured flow logs so they are available in the Donobu UI,
         // mirroring what DonobuFlowsManager does for Studio-launched flows.
         if (logBuffer) {
-            await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, 'logs.json', logBuffer.snapshot());
+            await persistFlowJson(sharedState.persistence, sharedState.donobuFlowMetadata.id, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.logs, logBuffer.snapshot());
         }
         // Attach step-level screenshots from the flow's tool call history.
         // These enable the HTML report to show a visual timeline of what the

package/dist/lib/test/utils/triageTestFailure.d.ts

@@ -409,13 +409,6 @@ declare const TRIAGE_PERSISTENCE_FILE_IDS: {
     readonly evidence: "triage-evidence.json";
     readonly failureScreenshot: "triage-failure-screenshot.png";
     readonly baselineScreenshot: "triage-baseline-screenshot.png";
-    /**
-     * Live screenshot of a flow's final visual state, captured at teardown while
-     * the page is still open. Persisted on successful runs so that a *later*
-     * failing run can use it as a true final-state baseline — symmetric with the
-     * failure screenshot, which is also a live end-of-test capture. Keyed per
-     * flow, like browser state.
-     */
     readonly finalStateScreenshot: "triage-final-state-screenshot.png";
 };
 /**

package/dist/lib/test/utils/triageTestFailure.js

@@ -49,6 +49,7 @@ const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const typescript_1 = __importDefault(require("typescript"));
 const v4_1 = require("zod/v4");
+const FlowsPersistence_1 = require("../../../persistence/flows/FlowsPersistence");
 const AnalyzePageTextTool_1 = require("../../../tools/AnalyzePageTextTool");
 const MarkObjectiveCompleteTool_1 = require("../../../tools/MarkObjectiveCompleteTool");
 const MarkObjectiveNotCompletableTool_1 = require("../../../tools/MarkObjectiveNotCompletableTool");
@@ -329,19 +330,7 @@ const MAX_SERIALIZED_STRING_LENGTH = 10000;
 const MAX_TOOL_CALL_PARAMETERS_LENGTH = 500;
 const MAX_TOOL_CALLS_TO_INCLUDE = 12;
 const TRIAGE_EVIDENCE_SCHEMA_VERSION = 2;
-const TRIAGE_PERSISTENCE_FILE_IDS = {
-    evidence: 'triage-evidence.json',
-    failureScreenshot: 'triage-failure-screenshot.png',
-    baselineScreenshot: 'triage-baseline-screenshot.png',
-    /**
-     * Live screenshot of a flow's final visual state, captured at teardown while
-     * the page is still open. Persisted on successful runs so that a *later*
-     * failing run can use it as a true final-state baseline — symmetric with the
-     * failure screenshot, which is also a live end-of-test capture. Keyed per
-     * flow, like browser state.
-     */
-    finalStateScreenshot: 'triage-final-state-screenshot.png',
-};
+const TRIAGE_PERSISTENCE_FILE_IDS = FlowsPersistence_1.WELL_KNOWN_FILE_IDS.triage;
 exports.TRIAGE_PERSISTENCE_FILE_IDS = TRIAGE_PERSISTENCE_FILE_IDS;
 /**
  * Ensures text blobs captured from tool calls or error messages fit within storage

package/dist/main.d.ts

@@ -61,7 +61,7 @@ export type * from './models/ToolTemplateDataSource';
 export type { VideoSegment } from './models/VideoSegment';
 export type { EnvPersistence } from './persistence/env/EnvPersistence';
 export { type FileUploadAggregateStatus, type FileUploadPlatformStatus, getFileUploadAggregateStatus, shutdownFileUploadWorkers, } from './persistence/files/fileUploadWorkerRegistry';
-export type { FlowsPersistence } from './persistence/flows/FlowsPersistence';
+export { type FlowsPersistence, WELL_KNOWN_FILE_IDS, } from './persistence/flows/FlowsPersistence';
 export { type PersistencePlugin, PersistencePluginRegistry, } from './persistence/PersistencePlugin';
 export type { SuitesPersistence } from './persistence/suites/SuitesPersistence';
 export type { TestsPersistence } from './persistence/tests/TestsPersistence';

package/dist/main.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TargetRuntimePluginRegistry = exports.PersistencePluginRegistry = exports.shutdownFileUploadWorkers = exports.getFileUploadAggregateStatus = exports.createDefaultToolRegistry = exports.ToolManager = exports.buildToolInterpolationDataSource = exports.PluginLoader = exports.InteractionVisualizer = exports.setupDonobuStack = exports.prepareToolCallsForRerun = exports.DonobuFlowsManager = exports.distillAllowedEnvVariableNames = exports.DonobuFlow = exports.AdminApiController = exports.env = exports.VercelAiGptClient = exports.OpenAiGptClient = exports.GptClientPluginRegistry = exports.GptClient = exports.GoogleGenerativeAiGptClient = exports.fixAssertFields = exports.DonobuGptClient = exports.AnthropicGptClient = void 0;
+exports.TargetRuntimePluginRegistry = exports.PersistencePluginRegistry = exports.WELL_KNOWN_FILE_IDS = exports.shutdownFileUploadWorkers = exports.getFileUploadAggregateStatus = exports.createDefaultToolRegistry = exports.ToolManager = exports.buildToolInterpolationDataSource = exports.PluginLoader = exports.InteractionVisualizer = exports.setupDonobuStack = exports.prepareToolCallsForRerun = exports.DonobuFlowsManager = exports.distillAllowedEnvVariableNames = exports.DonobuFlow = exports.AdminApiController = exports.env = exports.VercelAiGptClient = exports.OpenAiGptClient = exports.GptClientPluginRegistry = exports.GptClient = exports.GoogleGenerativeAiGptClient = exports.fixAssertFields = exports.DonobuGptClient = exports.AnthropicGptClient = void 0;
 exports.startDonobuServer = startDonobuServer;
 const commander_1 = require("commander");
 const v4_1 = require("zod/v4");
@@ -94,6 +94,8 @@ __exportStar(require("./models/ToolSchema"), exports);
 var fileUploadWorkerRegistry_1 = require("./persistence/files/fileUploadWorkerRegistry");
 Object.defineProperty(exports, "getFileUploadAggregateStatus", { enumerable: true, get: function () { return fileUploadWorkerRegistry_1.getFileUploadAggregateStatus; } });
 Object.defineProperty(exports, "shutdownFileUploadWorkers", { enumerable: true, get: function () { return fileUploadWorkerRegistry_1.shutdownFileUploadWorkers; } });
+var FlowsPersistence_1 = require("./persistence/flows/FlowsPersistence");
+Object.defineProperty(exports, "WELL_KNOWN_FILE_IDS", { enumerable: true, get: function () { return FlowsPersistence_1.WELL_KNOWN_FILE_IDS; } });
 var PersistencePlugin_1 = require("./persistence/PersistencePlugin");
 Object.defineProperty(exports, "PersistencePluginRegistry", { enumerable: true, get: function () { return PersistencePlugin_1.PersistencePluginRegistry; } });
 var TargetRuntimePlugin_1 = require("./targets/TargetRuntimePlugin");

package/dist/managers/DonobuFlowsManager.d.ts

@@ -49,7 +49,7 @@ export declare class DonobuFlowsManager {
     private readonly testsPersistenceRegistry;
     static readonly DEFAULT_MESSAGE_DURATION = 2247;
     static readonly DEFAULT_MAX_TOOL_CALLS = 50;
-    static readonly DEFAULT_BROWSER_STATE_FILENAME = "browserstate.json";
+    static readonly DEFAULT_BROWSER_STATE_FILENAME: "browserstate.json";
     static readonly FLOW_NAME_MAX_LENGTH = 1024;
     private readonly flowRuntime;
     private readonly flowCatalog;

package/dist/managers/DonobuFlowsManager.js

@@ -55,6 +55,7 @@ const UnknownToolException_1 = require("../exceptions/UnknownToolException");
 const CreateDonobuFlow_1 = require("../models/CreateDonobuFlow");
 const GptConfig_1 = require("../models/GptConfig");
 const MetadataVersion_1 = require("../models/MetadataVersion");
+const FlowsPersistence_1 = require("../persistence/flows/FlowsPersistence");
 const resolveTargetRuntime_1 = require("../targets/resolveTargetRuntime");
 const CustomToolRunnerTool_1 = require("../tools/CustomToolRunnerTool");
 const buildProvenance_1 = require("../utils/buildProvenance");
@@ -218,7 +219,7 @@ class DonobuFlowsManager {
                     }
                     try {
                         const snapshot = logBuffer.snapshot();
-                        await flowsPersistence.setFlowFile(donobuFlow.metadata.id, 'logs.json', Buffer.from(JSON.stringify(snapshot)));
+                        await flowsPersistence.setFlowFile(donobuFlow.metadata.id, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.logs, Buffer.from(JSON.stringify(snapshot)));
                     }
                     catch (error) {
                         Logger_1.appLogger.error('Failed to persist flow logs:', error);
@@ -254,7 +255,7 @@ class DonobuFlowsManager {
         }
         // Otherwise, read the persisted snapshot.
         const persistence = await this.flowsPersistenceRegistry.get();
-        const file = await persistence.getFlowFile(flowId, 'logs.json');
+        const file = await persistence.getFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.logs);
         if (file) {
             return JSON.parse(file.toString('utf8'));
         }
@@ -757,7 +758,7 @@ DonobuFlowsManager.DEFAULT_MESSAGE_DURATION = 2247;
 // If you change this value, also consider changing the frontend default
 // value in createFlowDefaults in flow-types.ts.
 DonobuFlowsManager.DEFAULT_MAX_TOOL_CALLS = 50;
-DonobuFlowsManager.DEFAULT_BROWSER_STATE_FILENAME = 'browserstate.json';
+DonobuFlowsManager.DEFAULT_BROWSER_STATE_FILENAME = FlowsPersistence_1.WELL_KNOWN_FILE_IDS.browserState;
 // Re-exported from models/CreateDonobuFlow so existing callers can keep using
 // DonobuFlowsManager.FLOW_NAME_MAX_LENGTH. The source of truth (and the
 // rationale for keeping it in sync with the donobu-api gateway) lives there.

package/dist/persistence/flows/FlowsPersistence.d.ts

@@ -4,6 +4,39 @@ import type { FlowMetadata, FlowsQuery } from '../../models/FlowMetadata';
 import type { PaginatedResult } from '../../models/PaginatedResult';
 import type { ToolCall } from '../../models/ToolCall';
 import type { VideoSegment } from '../../models/VideoSegment';
+/**
+ * Well-known per-flow persistence filenames reserved by Donobu.
+ *
+ * These names are storage contracts. Avoid reusing them for ad hoc tool
+ * artifacts.
+ */
+export declare const WELL_KNOWN_FILE_IDS: {
+    /** Full flow video backing {@link FlowsPersistence.setVideo}. */
+    readonly video: "video.webm";
+    /** Browser storage state backing {@link FlowsPersistence.setBrowserState}. */
+    readonly browserState: "browserstate.json";
+    /** Structured flow log snapshot consumed by the Studio flow log view. */
+    readonly logs: "logs.json";
+    /** Playwright test result summary consumed by the Donobu HTML report. */
+    readonly donobuTestResult: "donobu-test-result.json";
+    /** Generated remediation plan consumed by Studio and admin tooling. */
+    readonly treatmentPlan: "treatment-plan.json";
+    /** Failure-triage artifacts persisted alongside a test flow. */
+    readonly triage: {
+        /** Serialized GPT triage evidence and heuristic assessment. */
+        readonly evidence: "triage-evidence.json";
+        /** Screenshot from the failed run's final page state. */
+        readonly failureScreenshot: "triage-failure-screenshot.png";
+        /** Screenshot from the latest successful baseline run. */
+        readonly baselineScreenshot: "triage-baseline-screenshot.png";
+        /**
+         * Live final-state screenshot captured at test teardown. Successful runs
+         * provide the baseline for later failures; failed runs provide the current
+         * failure screenshot.
+         */
+        readonly finalStateScreenshot: "triage-final-state-screenshot.png";
+    };
+};
 /**
  * Interface for persisting data relating to DonobuFlow runs.
  */

package/dist/persistence/flows/FlowsPersistence.js

@@ -1,3 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WELL_KNOWN_FILE_IDS = void 0;
+/**
+ * Well-known per-flow persistence filenames reserved by Donobu.
+ *
+ * These names are storage contracts. Avoid reusing them for ad hoc tool
+ * artifacts.
+ */
+exports.WELL_KNOWN_FILE_IDS = {
+    /** Full flow video backing {@link FlowsPersistence.setVideo}. */
+    video: 'video.webm',
+    /** Browser storage state backing {@link FlowsPersistence.setBrowserState}. */
+    browserState: 'browserstate.json',
+    /** Structured flow log snapshot consumed by the Studio flow log view. */
+    logs: 'logs.json',
+    /** Playwright test result summary consumed by the Donobu HTML report. */
+    donobuTestResult: 'donobu-test-result.json',
+    /** Generated remediation plan consumed by Studio and admin tooling. */
+    treatmentPlan: 'treatment-plan.json',
+    /** Failure-triage artifacts persisted alongside a test flow. */
+    triage: {
+        /** Serialized GPT triage evidence and heuristic assessment. */
+        evidence: 'triage-evidence.json',
+        /** Screenshot from the failed run's final page state. */
+        failureScreenshot: 'triage-failure-screenshot.png',
+        /** Screenshot from the latest successful baseline run. */
+        baselineScreenshot: 'triage-baseline-screenshot.png',
+        /**
+         * Live final-state screenshot captured at test teardown. Successful runs
+         * provide the baseline for later failures; failed runs provide the current
+         * failure screenshot.
+         */
+        finalStateScreenshot: 'triage-final-state-screenshot.png',
+    },
+};
 //# sourceMappingURL=FlowsPersistence.js.map

package/dist/persistence/flows/FlowsPersistenceDonobuApi.d.ts

@@ -5,7 +5,7 @@ import type { PaginatedResult } from '../../models/PaginatedResult';
 import type { ToolCall } from '../../models/ToolCall';
 import type { VideoSegment } from '../../models/VideoSegment';
 import { FileUploadCache } from '../files/FileUploadCache';
-import type { FlowsPersistence } from './FlowsPersistence';
+import { type FlowsPersistence } from './FlowsPersistence';
 /**
  * A {@link FlowsPersistence} implementation that persists flow data via the
  * Donobu API.  The API stores the SDK's data models as opaque JSON blobs,

package/dist/persistence/flows/FlowsPersistenceDonobuApi.js

@@ -14,8 +14,8 @@ const MiscUtils_1 = require("../../utils/MiscUtils");
 const FileUploadCache_1 = require("../files/FileUploadCache");
 const FileUploadWorker_1 = require("../files/FileUploadWorker");
 const fileUploadWorkerRegistry_1 = require("../files/fileUploadWorkerRegistry");
+const FlowsPersistence_1 = require("./FlowsPersistence");
 const PLATFORM_LABEL = 'donobu';
-const VIDEO_FILE_ID = 'video.webm';
 /**
  * A {@link FlowsPersistence} implementation that persists flow data via the
  * Donobu API.  The API stores the SDK's data models as opaque JSON blobs,
@@ -205,10 +205,10 @@ class FlowsPersistenceDonobuApi {
     }
     // -- Screenshots ---------------------------------------------------
     async setVideo(flowId, bytes) {
-        await this.setFlowFile(flowId, VIDEO_FILE_ID, bytes);
+        await this.setFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video, bytes);
     }
     async getVideoSegment(flowId, startOffset, length) {
-        const videoBuffer = await this.getFlowFile(flowId, VIDEO_FILE_ID);
+        const videoBuffer = await this.getFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video);
         if (!videoBuffer) {
             return null;
         }

package/dist/persistence/flows/FlowsPersistenceSqlite.d.ts

@@ -5,15 +5,13 @@ import type { FlowMetadata, FlowsQuery } from '../../models/FlowMetadata';
 import type { PaginatedResult } from '../../models/PaginatedResult';
 import type { ToolCall } from '../../models/ToolCall';
 import type { VideoSegment } from '../../models/VideoSegment';
-import type { FlowsPersistence } from './FlowsPersistence';
+import { type FlowsPersistence } from './FlowsPersistence';
 /**
  * A persistence implementation that uses SQLite for all data storage, including binary files.
  */
 export declare class FlowsPersistenceSqlite implements FlowsPersistence {
     private readonly db;
     private static readonly VIDEO_MIME_TYPE;
-    private static readonly BROWSER_STATE_FILE_ID;
-    private static readonly VIDEO_FILE_ID;
     private constructor();
     static create(db: Database.Database): Promise<FlowsPersistenceSqlite>;
     setEnvironmentDatum(key: string, value: string): Promise<void>;

package/dist/persistence/flows/FlowsPersistenceSqlite.js

@@ -7,6 +7,7 @@ const AiQuery_1 = require("../../models/AiQuery");
 const BrowserStorageState_1 = require("../../models/BrowserStorageState");
 const MiscUtils_1 = require("../../utils/MiscUtils");
 const normalizeFlowMetadata_1 = require("../normalizeFlowMetadata");
+const FlowsPersistence_1 = require("./FlowsPersistence");
 /**
  * A persistence implementation that uses SQLite for all data storage, including binary files.
  */
@@ -221,13 +222,13 @@ class FlowsPersistenceSqlite {
     async setVideo(flowId, bytes) {
         // Ensure flow exists.
         await this.getFlowMetadataById(flowId);
-        const binaryId = `${flowId}-${FlowsPersistenceSqlite.VIDEO_FILE_ID}`;
+        const binaryId = `${flowId}-${FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video}`;
         const stmt = this.db.prepare('INSERT OR REPLACE INTO binary_files (id, flow_id, file_id, mime_type, content) VALUES (?, ?, ?, ?, ?)');
-        stmt.run(binaryId, flowId, FlowsPersistenceSqlite.VIDEO_FILE_ID, FlowsPersistenceSqlite.VIDEO_MIME_TYPE, bytes);
+        stmt.run(binaryId, flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video, FlowsPersistenceSqlite.VIDEO_MIME_TYPE, bytes);
     }
     async getVideoSegment(flowId, startOffset, length) {
         const stmt = this.db.prepare('SELECT content FROM binary_files WHERE flow_id = ? AND file_id = ?');
-        const row = stmt.get(flowId, FlowsPersistenceSqlite.VIDEO_FILE_ID);
+        const row = stmt.get(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.video);
         if (!row) {
             return null;
         }
@@ -261,10 +262,10 @@ class FlowsPersistenceSqlite {
     }
     async setBrowserState(flowId, browserState) {
         const serializedBrowserState = Buffer.from(JSON.stringify(browserState), 'utf-8');
-        await this.setFlowFile(flowId, FlowsPersistenceSqlite.BROWSER_STATE_FILE_ID, serializedBrowserState);
+        await this.setFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.browserState, serializedBrowserState);
     }
     async getBrowserState(flowId) {
-        const browserStateRaw = await this.getFlowFile(flowId, FlowsPersistenceSqlite.BROWSER_STATE_FILE_ID);
+        const browserStateRaw = await this.getFlowFile(flowId, FlowsPersistence_1.WELL_KNOWN_FILE_IDS.browserState);
         if (browserStateRaw) {
             return BrowserStorageState_1.BrowserStorageStateSchema.parse(JSON.parse(browserStateRaw.toString('utf-8')));
         }
@@ -284,6 +285,4 @@ class FlowsPersistenceSqlite {
 }
 exports.FlowsPersistenceSqlite = FlowsPersistenceSqlite;
 FlowsPersistenceSqlite.VIDEO_MIME_TYPE = 'video/webm';
-FlowsPersistenceSqlite.BROWSER_STATE_FILE_ID = 'browserstate.json';
-FlowsPersistenceSqlite.VIDEO_FILE_ID = 'video.webm';
 //# sourceMappingURL=FlowsPersistenceSqlite.js.map

package/package.json

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