donobu 5.36.1 → 5.36.2

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

@@ -125,7 +125,16 @@ class FlowsPersistenceDonobuApi {
             params.set('orphaned', query.orphaned ? 'true' : 'false');
         }
         if (query.sortBy) {
-            params.set('sort_by', query.sortBy);
+            switch (query.sortBy) {
+                case 'created_at':
+                    // `donobu-api` only supports `started_at`, but that's essentially
+                    // equivalent to `created_at`
+                    params.set('sort_by', 'started_at');
+                    break;
+                default:
+                    params.set('sort_by', query.sortBy);
+                    break;
+            }
         }
         if (query.sortOrder) {
             params.set('sort_order', query.sortOrder);

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

@@ -2,6 +2,17 @@ import type { EnvPick } from 'env-struct';
 import type { env } from '../../envVars';
 import { PersistencePluginRegistry } from '../PersistencePlugin';
 import type { FlowsPersistence } from './FlowsPersistence';
+/**
+ * A persistence layer paired with the `PERSISTENCE_PRIORITY` key it was
+ * created from. The key is shared across the flows/tests/suites registries:
+ * the same key in each registry refers to the same logical store, which is
+ * how cross-entity foreign keys are kept aligned (e.g. a flow's `testId`
+ * resolves to a test that lives in the same layer).
+ */
+export interface FlowsPersistenceLayer {
+    key: string;
+    persistence: FlowsPersistence;
+}
 export interface FlowsPersistenceRegistry {
     /**
      * Returns the primary persistence layer.
@@ -9,6 +20,17 @@ export interface FlowsPersistenceRegistry {
     get(): Promise<FlowsPersistence>;
     /** Returns a list of all valid persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<FlowsPersistence[]>;
+    /**
+     * Returns all valid layers paired with their `PERSISTENCE_PRIORITY` key.
+     * Used by callers that need to align writes across registries (e.g. write
+     * a flow into the same layer as the test it references).
+     */
+    getEntries(): Promise<FlowsPersistenceLayer[]>;
+    /**
+     * Returns the persistence layer registered under the given
+     * `PERSISTENCE_PRIORITY` key, or undefined if no such layer exists.
+     */
+    getByKey(key: string): Promise<FlowsPersistence | undefined>;
 }
 /**
  * A factory class for creating FlowsPersistence instances. Persistence layers are constructed
@@ -19,7 +41,7 @@ export declare class FlowsPersistenceRegistryImpl implements FlowsPersistenceReg
     /**
      * Creates an instance with pre-built persistence layers.
      */
-    constructor(layers: FlowsPersistence[]);
+    constructor(layers: FlowsPersistenceLayer[]);
     /**
      * Creates an instance by reading environment variables and eagerly constructing
      * all applicable persistence layers.
@@ -31,5 +53,7 @@ export declare class FlowsPersistenceRegistryImpl implements FlowsPersistenceReg
     get(): Promise<FlowsPersistence>;
     /** Returns all persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<FlowsPersistence[]>;
+    getEntries(): Promise<FlowsPersistenceLayer[]>;
+    getByKey(key: string): Promise<FlowsPersistence | undefined>;
 }
 //# sourceMappingURL=FlowsPersistenceRegistry.d.ts.map

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

@@ -32,21 +32,27 @@ class FlowsPersistenceRegistryImpl {
             switch (key) {
                 case 'DONOBU':
                     if (donobuApiKey && donobuApiBaseUrl) {
-                        layers.push(new FlowsPersistenceDonobuApi_1.FlowsPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey));
+                        layers.push({
+                            key,
+                            persistence: new FlowsPersistenceDonobuApi_1.FlowsPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey),
+                        });
                     }
                     break;
                 case 'LOCAL':
-                    layers.push(await FlowsPersistenceSqlite_1.FlowsPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()));
+                    layers.push({
+                        key,
+                        persistence: await FlowsPersistenceSqlite_1.FlowsPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()),
+                    });
                     break;
                 case 'RAM':
-                    layers.push(new FlowsPersistenceVolatile_1.FlowsPersistenceVolatile());
+                    layers.push({ key, persistence: new FlowsPersistenceVolatile_1.FlowsPersistenceVolatile() });
                     break;
                 default: {
                     const plugin = persistencePlugins.get(key);
                     if (plugin) {
                         const impl = await plugin.createFlowsPersistence();
                         if (impl) {
-                            layers.push(impl);
+                            layers.push({ key, persistence: impl });
                         }
                     }
                     break;
@@ -59,12 +65,18 @@ class FlowsPersistenceRegistryImpl {
      * Returns the primary persistence layer.
      */
     async get() {
-        return this.layers[0];
+        return this.layers[0].persistence;
     }
     /** Returns all persistence layers. Guaranteed to be non-empty. */
     async getAll() {
+        return this.layers.map((layer) => layer.persistence);
+    }
+    async getEntries() {
         return this.layers;
     }
+    async getByKey(key) {
+        return this.layers.find((layer) => layer.key === key)?.persistence;
+    }
 }
 exports.FlowsPersistenceRegistryImpl = FlowsPersistenceRegistryImpl;
 //# sourceMappingURL=FlowsPersistenceRegistry.js.map

package/dist/esm/persistence/suites/SuitesPersistenceRegistry.d.ts

@@ -2,17 +2,34 @@ import type { EnvPick } from 'env-struct';
 import type { env } from '../../envVars';
 import { PersistencePluginRegistry } from '../PersistencePlugin';
 import type { SuitesPersistence } from './SuitesPersistence';
+/**
+ * A persistence layer paired with its `PERSISTENCE_PRIORITY` key. See
+ * {@link FlowsPersistenceLayer} for why keys must align across registries.
+ */
+export interface SuitesPersistenceLayer {
+    key: string;
+    persistence: SuitesPersistence;
+}
 export interface SuitesPersistenceRegistry {
     /** Returns the primary persistence layer. */
     get(): Promise<SuitesPersistence>;
     /** Returns all valid persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<SuitesPersistence[]>;
+    /** Returns all valid layers paired with their `PERSISTENCE_PRIORITY` key. */
+    getEntries(): Promise<SuitesPersistenceLayer[]>;
+    /**
+     * Returns the persistence layer registered under the given
+     * `PERSISTENCE_PRIORITY` key, or undefined if no such layer exists.
+     */
+    getByKey(key: string): Promise<SuitesPersistence | undefined>;
 }
 export declare class SuitesPersistenceRegistryImpl implements SuitesPersistenceRegistry {
     private readonly layers;
-    constructor(layers: SuitesPersistence[]);
+    constructor(layers: SuitesPersistenceLayer[]);
     static fromEnvironment(environ: EnvPick<typeof env, 'DONOBU_API_BASE_URL' | 'DONOBU_API_KEY' | 'PERSISTENCE_PRIORITY'>, persistencePlugins?: PersistencePluginRegistry): Promise<SuitesPersistenceRegistryImpl>;
     get(): Promise<SuitesPersistence>;
     getAll(): Promise<SuitesPersistence[]>;
+    getEntries(): Promise<SuitesPersistenceLayer[]>;
+    getByKey(key: string): Promise<SuitesPersistence | undefined>;
 }
 //# sourceMappingURL=SuitesPersistenceRegistry.d.ts.map

package/dist/esm/persistence/suites/SuitesPersistenceRegistry.js

@@ -21,21 +21,27 @@ class SuitesPersistenceRegistryImpl {
             switch (key) {
                 case 'DONOBU':
                     if (donobuApiKey && donobuApiBaseUrl) {
-                        layers.push(new SuitesPersistenceDonobuApi_1.SuitesPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey));
+                        layers.push({
+                            key,
+                            persistence: new SuitesPersistenceDonobuApi_1.SuitesPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey),
+                        });
                     }
                     break;
                 case 'LOCAL':
-                    layers.push(await SuitesPersistenceSqlite_1.SuitesPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()));
+                    layers.push({
+                        key,
+                        persistence: await SuitesPersistenceSqlite_1.SuitesPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()),
+                    });
                     break;
                 case 'RAM':
-                    layers.push(new SuitesPersistenceVolatile_1.SuitesPersistenceVolatile());
+                    layers.push({ key, persistence: new SuitesPersistenceVolatile_1.SuitesPersistenceVolatile() });
                     break;
                 default: {
                     const plugin = persistencePlugins.get(key);
                     if (plugin?.createSuitesPersistence) {
                         const impl = await plugin.createSuitesPersistence();
                         if (impl) {
-                            layers.push(impl);
+                            layers.push({ key, persistence: impl });
                         }
                     }
                     break;
@@ -45,11 +51,17 @@ class SuitesPersistenceRegistryImpl {
         return new SuitesPersistenceRegistryImpl(layers);
     }
     async get() {
-        return this.layers[0];
+        return this.layers[0].persistence;
     }
     async getAll() {
+        return this.layers.map((layer) => layer.persistence);
+    }
+    async getEntries() {
         return this.layers;
     }
+    async getByKey(key) {
+        return this.layers.find((layer) => layer.key === key)?.persistence;
+    }
 }
 exports.SuitesPersistenceRegistryImpl = SuitesPersistenceRegistryImpl;
 //# sourceMappingURL=SuitesPersistenceRegistry.js.map

package/dist/esm/persistence/tests/TestsPersistenceRegistry.d.ts

@@ -3,15 +3,30 @@ import type { env } from '../../envVars';
 import type { FlowsPersistenceRegistry } from '../flows/FlowsPersistenceRegistry';
 import { PersistencePluginRegistry } from '../PersistencePlugin';
 import type { TestsPersistence } from './TestsPersistence';
+/**
+ * A persistence layer paired with its `PERSISTENCE_PRIORITY` key. See
+ * {@link FlowsPersistenceLayer} for why keys must align across registries.
+ */
+export interface TestsPersistenceLayer {
+    key: string;
+    persistence: TestsPersistence;
+}
 export interface TestsPersistenceRegistry {
     /** Returns the primary persistence layer. */
     get(): Promise<TestsPersistence>;
     /** Returns all valid persistence layers. Guaranteed to be non-empty. */
     getAll(): Promise<TestsPersistence[]>;
+    /** Returns all valid layers paired with their `PERSISTENCE_PRIORITY` key. */
+    getEntries(): Promise<TestsPersistenceLayer[]>;
+    /**
+     * Returns the persistence layer registered under the given
+     * `PERSISTENCE_PRIORITY` key, or undefined if no such layer exists.
+     */
+    getByKey(key: string): Promise<TestsPersistence | undefined>;
 }
 export declare class TestsPersistenceRegistryImpl implements TestsPersistenceRegistry {
     private readonly layers;
-    constructor(layers: TestsPersistence[]);
+    constructor(layers: TestsPersistenceLayer[]);
     static fromEnvironment(environ: EnvPick<typeof env, 'DONOBU_API_BASE_URL' | 'DONOBU_API_KEY' | 'PERSISTENCE_PRIORITY'>, 
     /**
      * Flows registry — used by the volatile tests layer to compute
@@ -22,5 +37,7 @@ export declare class TestsPersistenceRegistryImpl implements TestsPersistenceReg
     flowsRegistry?: FlowsPersistenceRegistry, persistencePlugins?: PersistencePluginRegistry): Promise<TestsPersistenceRegistryImpl>;
     get(): Promise<TestsPersistence>;
     getAll(): Promise<TestsPersistence[]>;
+    getEntries(): Promise<TestsPersistenceLayer[]>;
+    getByKey(key: string): Promise<TestsPersistence | undefined>;
 }
 //# sourceMappingURL=TestsPersistenceRegistry.d.ts.map

package/dist/esm/persistence/tests/TestsPersistenceRegistry.js

@@ -28,21 +28,30 @@ class TestsPersistenceRegistryImpl {
             switch (key) {
                 case 'DONOBU':
                     if (donobuApiKey && donobuApiBaseUrl) {
-                        layers.push(new TestsPersistenceDonobuApi_1.TestsPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey));
+                        layers.push({
+                            key,
+                            persistence: new TestsPersistenceDonobuApi_1.TestsPersistenceDonobuApi(donobuApiBaseUrl, donobuApiKey),
+                        });
                     }
                     break;
                 case 'LOCAL':
-                    layers.push(await TestsPersistenceSqlite_1.TestsPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()));
+                    layers.push({
+                        key,
+                        persistence: await TestsPersistenceSqlite_1.TestsPersistenceSqlite.create(await (0, DonobuSqliteDb_1.getDonobuSqliteDatabase)()),
+                    });
                     break;
                 case 'RAM':
-                    layers.push(new TestsPersistenceVolatile_1.TestsPersistenceVolatile(undefined, flowsRegistry ? () => flowsRegistry.get() : undefined));
+                    layers.push({
+                        key,
+                        persistence: new TestsPersistenceVolatile_1.TestsPersistenceVolatile(undefined, flowsRegistry ? () => flowsRegistry.get() : undefined),
+                    });
                     break;
                 default: {
                     const plugin = persistencePlugins.get(key);
                     if (plugin?.createTestsPersistence) {
                         const impl = await plugin.createTestsPersistence();
                         if (impl) {
-                            layers.push(impl);
+                            layers.push({ key, persistence: impl });
                         }
                     }
                     break;
@@ -52,11 +61,17 @@ class TestsPersistenceRegistryImpl {
         return new TestsPersistenceRegistryImpl(layers);
     }
     async get() {
-        return this.layers[0];
+        return this.layers[0].persistence;
     }
     async getAll() {
+        return this.layers.map((layer) => layer.persistence);
+    }
+    async getEntries() {
         return this.layers;
     }
+    async getByKey(key) {
+        return this.layers.find((layer) => layer.key === key)?.persistence;
+    }
 }
 exports.TestsPersistenceRegistryImpl = TestsPersistenceRegistryImpl;
 //# sourceMappingURL=TestsPersistenceRegistry.js.map

package/dist/esm/tools/ScrollPageTool.js

@@ -74,7 +74,7 @@ current page or element, of which may contain relevant information.`, exports.Sc
             return beforeY !== afterY || beforeX !== afterX;
         }, parameters);
         return didScroll
-            ? `Scrolled ${parameters.direction} ${parameters.maxScroll ? ' (max)' : ''}`
+            ? `Scrolled ${parameters.direction} ${parameters.maxScroll ? '(maximum amount scrolled)' : ''} for `
             : `Nothing to scroll ${parameters.direction}`;
     }
 }

package/dist/managers/DonobuFlowsManager.d.ts

@@ -22,6 +22,7 @@ import type { RunConfig } from '../models/RunConfig';
 import type { RunMode } from '../models/RunMode';
 import type { ToolCall } from '../models/ToolCall';
 import type { FlowsPersistenceRegistry } from '../persistence/flows/FlowsPersistenceRegistry';
+import type { TestsPersistenceRegistry } from '../persistence/tests/TestsPersistenceRegistry';
 import type { TargetRuntimePluginRegistry } from '../targets/TargetRuntimePlugin';
 import type { Tool } from '../tools/Tool';
 import type { FlowLogSnapshot } from '../utils/FlowLogBuffer';
@@ -45,17 +46,22 @@ export declare class DonobuFlowsManager {
     private readonly environ;
     private readonly toolRegistry;
     private readonly targetRuntimePlugins;
+    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 FLOW_NAME_MAX_LENGTH = 255;
     private readonly flowRuntime;
     private readonly flowCatalog;
-    constructor(deploymentEnvironment: DonobuDeploymentEnvironment, gptClientFactory: GptClientFactory, gptConfigsManager: GptConfigsManager, agentsManager: AgentsManager, flowsPersistenceRegistry: FlowsPersistenceRegistry, envDataManager: EnvDataManager, controlPanelFactory: ControlPanelFactory, environ: EnvPick<typeof env, '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_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'>, toolRegistry: ToolRegistry, targetRuntimePlugins: TargetRuntimePluginRegistry);
+    constructor(deploymentEnvironment: DonobuDeploymentEnvironment, gptClientFactory: GptClientFactory, gptConfigsManager: GptConfigsManager, agentsManager: AgentsManager, flowsPersistenceRegistry: FlowsPersistenceRegistry, envDataManager: EnvDataManager, controlPanelFactory: ControlPanelFactory, environ: EnvPick<typeof env, '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_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'>, toolRegistry: ToolRegistry, targetRuntimePlugins: TargetRuntimePluginRegistry, testsPersistenceRegistry: TestsPersistenceRegistry);
     /**
      * Create a flow with the given parameters and invoke its `DonobuFlow#run`
      * method, adding it to list of active flows.
      *
+     * If `flowParams.testId` is set, the new flow is persisted to the same
+     * layer as the referenced test so the `flow_metadata.test_id` foreign
+     * key holds. Otherwise the primary layer is used.
+     *
      * @param gptClient If present, will use this as the associated GPT client for
      *          this flow instead of instantiating a new one. If so, the
      *          gptConfigNameOverride field will be ignored.
@@ -168,6 +174,20 @@ export declare class DonobuFlowsManager {
      * {@link BrowserStateNotFoundException} if it is not found.
      */
     getBrowserStorageState(browserStateRef: BrowserStateReference): Promise<BrowserStorageState>;
+    /**
+     * Picks the flows persistence layer to use when creating a new flow.
+     *
+     * - If `testId` is null/undefined: use the primary flows layer.
+     * - If `testId` is set: look up the test's layer key and use the matching
+     *   flows layer. If no flows layer matches the test's key (rare —
+     *   asymmetric registry config), fall back to the primary layer; the FK
+     *   won't hold but the flow is at least persisted.
+     * - If `testId` is set but no test exists with that ID anywhere: fall
+     *   back to the primary layer (the SQLite FK will reject if applicable;
+     *   non-DB layers will accept the dangling reference).
+     */
+    private resolveLayerForFlowCreate;
+    private findTestLayerKey;
     private isLocallyRunning;
 }
 /**

package/dist/managers/DonobuFlowsManager.js

@@ -47,6 +47,7 @@ const BrowserStateNotFoundException_1 = require("../exceptions/BrowserStateNotFo
 const CannotDeleteRunningFlowException_1 = require("../exceptions/CannotDeleteRunningFlowException");
 const FlowNotFoundException_1 = require("../exceptions/FlowNotFoundException");
 const InvalidParamValueException_1 = require("../exceptions/InvalidParamValueException");
+const TestNotFoundException_1 = require("../exceptions/TestNotFoundException");
 const ToolRequiresGptException_1 = require("../exceptions/ToolRequiresGptException");
 const UnknownToolException_1 = require("../exceptions/UnknownToolException");
 const GptConfig_1 = require("../models/GptConfig");
@@ -64,7 +65,7 @@ const FlowRuntime_1 = require("./FlowRuntime");
 const InteractionVisualizer_1 = require("./InteractionVisualizer");
 const ToolManager_1 = require("./ToolManager");
 class DonobuFlowsManager {
-    constructor(deploymentEnvironment, gptClientFactory, gptConfigsManager, agentsManager, flowsPersistenceRegistry, envDataManager, controlPanelFactory, environ, toolRegistry, targetRuntimePlugins) {
+    constructor(deploymentEnvironment, gptClientFactory, gptConfigsManager, agentsManager, flowsPersistenceRegistry, envDataManager, controlPanelFactory, environ, toolRegistry, targetRuntimePlugins, testsPersistenceRegistry) {
         this.deploymentEnvironment = deploymentEnvironment;
         this.gptClientFactory = gptClientFactory;
         this.gptConfigsManager = gptConfigsManager;
@@ -75,6 +76,7 @@ class DonobuFlowsManager {
         this.environ = environ;
         this.toolRegistry = toolRegistry;
         this.targetRuntimePlugins = targetRuntimePlugins;
+        this.testsPersistenceRegistry = testsPersistenceRegistry;
         this.flowRuntime = new FlowRuntime_1.FlowRuntime();
         this.flowCatalog = new FlowCatalog_1.FlowCatalog(this.flowsPersistenceRegistry, this.flowRuntime, this.deploymentEnvironment);
     }
@@ -82,6 +84,10 @@ class DonobuFlowsManager {
      * Create a flow with the given parameters and invoke its `DonobuFlow#run`
      * method, adding it to list of active flows.
      *
+     * If `flowParams.testId` is set, the new flow is persisted to the same
+     * layer as the referenced test so the `flow_metadata.test_id` foreign
+     * key holds. Otherwise the primary layer is used.
+     *
      * @param gptClient If present, will use this as the associated GPT client for
      *          this flow instead of instantiating a new one. If so, the
      *          gptConfigNameOverride field will be ignored.
@@ -179,7 +185,7 @@ class DonobuFlowsManager {
                     ...targetRuntime.getMetadataFields(),
                     provenance: (0, buildProvenance_1.buildProvenance)('DONOBU_STUDIO'),
                 };
-                const flowsPersistence = await this.flowsPersistenceRegistry.get();
+                const flowsPersistence = await this.resolveLayerForFlowCreate(flowParams.testId ?? null);
                 const envData = await this.envDataManager.getByNames(flowMetadata.envVars ?? []);
                 const donobuFlow = new DonobuFlow_1.DonobuFlow(this, envData, flowsPersistence, gptClientData.gptClient, toolManager, interactionVisualizer, toolCallsOnStart, [], [], targetRuntime.inspector, flowMetadata, targetRuntime.controlPanel);
                 await flowsPersistence.setFlowMetadata(flowMetadata);
@@ -652,6 +658,49 @@ class DonobuFlowsManager {
         }
         throw new BrowserStateNotFoundException_1.BrowserStateNotFoundException(flowMetadata.id);
     }
+    /**
+     * Picks the flows persistence layer to use when creating a new flow.
+     *
+     * - If `testId` is null/undefined: use the primary flows layer.
+     * - If `testId` is set: look up the test's layer key and use the matching
+     *   flows layer. If no flows layer matches the test's key (rare —
+     *   asymmetric registry config), fall back to the primary layer; the FK
+     *   won't hold but the flow is at least persisted.
+     * - If `testId` is set but no test exists with that ID anywhere: fall
+     *   back to the primary layer (the SQLite FK will reject if applicable;
+     *   non-DB layers will accept the dangling reference).
+     */
+    async resolveLayerForFlowCreate(testId) {
+        if (!testId) {
+            return this.flowsPersistenceRegistry.get();
+        }
+        let testLayerKey;
+        try {
+            testLayerKey = await this.findTestLayerKey(testId);
+        }
+        catch (error) {
+            if (!(error instanceof TestNotFoundException_1.TestNotFoundException)) {
+                throw error;
+            }
+            return this.flowsPersistenceRegistry.get();
+        }
+        const matched = await this.flowsPersistenceRegistry.getByKey(testLayerKey);
+        return matched ?? (await this.flowsPersistenceRegistry.get());
+    }
+    async findTestLayerKey(testId) {
+        for (const { key, persistence, } of await this.testsPersistenceRegistry.getEntries()) {
+            try {
+                await persistence.getTestById(testId);
+                return key;
+            }
+            catch (error) {
+                if (!(error instanceof TestNotFoundException_1.TestNotFoundException)) {
+                    throw error;
+                }
+            }
+        }
+        throw TestNotFoundException_1.TestNotFoundException.forId(testId);
+    }
     isLocallyRunning() {
         return this.deploymentEnvironment === 'LOCAL';
     }

package/dist/managers/DonobuStack.js

@@ -46,12 +46,12 @@ async function setupDonobuStack(donobuDeploymentEnvironment, controlPanelFactory
     const agentsPersistence = await AgentsPersistenceSqlite_1.AgentsPersistenceSqlite.create(sqliteDb);
     const agentsManager = await AgentsManager_1.AgentsManager.create(agentsPersistence, gptConfigsManager);
     const flowsPersistenceRegistry = await FlowsPersistenceRegistry_1.FlowsPersistenceRegistryImpl.fromEnvironment(environ, persistencePlugins);
-    const envPersistenceFactory = await EnvPersistenceRegistry_1.EnvPersistenceRegistryImpl.fromEnvironment(envPersistenceVolatile ?? null, environ, persistencePlugins);
-    const envDataManager = new EnvDataManager_1.EnvDataManager(envPersistenceFactory);
-    const flowsManager = new DonobuFlowsManager_1.DonobuFlowsManager(donobuDeploymentEnvironment, gptClientFactory, gptConfigsManager, agentsManager, flowsPersistenceRegistry, envDataManager, controlPanelFactory, environ, resolvedToolRegistry, targetRuntimePlugins);
     const testsPersistenceRegistry = await TestsPersistenceRegistry_1.TestsPersistenceRegistryImpl.fromEnvironment(environ, flowsPersistenceRegistry);
-    const testsManager = new TestsManager_1.TestsManager(testsPersistenceRegistry, flowsManager);
     const suitesPersistenceRegistry = await SuitesPersistenceRegistry_1.SuitesPersistenceRegistryImpl.fromEnvironment(environ);
+    const envPersistenceFactory = await EnvPersistenceRegistry_1.EnvPersistenceRegistryImpl.fromEnvironment(envPersistenceVolatile ?? null, environ, persistencePlugins);
+    const envDataManager = new EnvDataManager_1.EnvDataManager(envPersistenceFactory);
+    const flowsManager = new DonobuFlowsManager_1.DonobuFlowsManager(donobuDeploymentEnvironment, gptClientFactory, gptConfigsManager, agentsManager, flowsPersistenceRegistry, envDataManager, controlPanelFactory, environ, resolvedToolRegistry, targetRuntimePlugins, testsPersistenceRegistry);
+    const testsManager = new TestsManager_1.TestsManager(testsPersistenceRegistry, suitesPersistenceRegistry, flowsManager);
     const suitesManager = new SuitesManager_1.SuitesManager(suitesPersistenceRegistry, testsPersistenceRegistry);
     return {
         toolRegistry: resolvedToolRegistry,

package/dist/managers/FederatedPagination.d.ts

@@ -1,31 +1,61 @@
 import type { PaginatedResult } from '../models/PaginatedResult';
+/**
+ * Per-layer pagination state, carried across pages inside the composite
+ * page token. `cursor` is the layer's own opaque page token; `resumeAfterId`
+ * is the id of the last item from this layer kept on the previous page (in
+ * the layer's own order). `exhausted` becomes true once a layer has nothing
+ * more to give and we've already returned everything it contributed.
+ */
+interface SourceState {
+    cursor?: string;
+    resumeAfterId?: string;
+    exhausted: boolean;
+}
 /**
  * Internal state tracked across pages when federating results from multiple
- * persistence layers.
+ * persistence layers. Serialized as base64(JSON(...)) into the composite
+ * page token.
  */
 interface FederatedPaginationState {
-    sourceTokens: Record<number, string>;
-    exhaustedSources: number[];
-    cursorTimestamp: number | null;
+    sources: SourceState[];
 }
 export declare function createCompositePageToken(state: FederatedPaginationState): string;
 export declare function parseCompositePageToken(token?: string): FederatedPaginationState;
 /**
- * Federate a paginated listing across multiple persistence layers.
+ * Federate a paginated listing across multiple persistence layers
+ * (resume-by-id).
+ *
+ * Each layer holds an opaque cursor and an optional `resumeAfterId`. On
+ * each page request, federation fetches from each non-exhausted layer
+ * (advancing through batches as needed until it has at least `limit`
+ * candidates per layer), stable-sorts the merged contributions with the
+ * caller's `comparator`, and trims to `limit`. For each layer, the
+ * **last kept item in that layer's order** becomes the new
+ * `resumeAfterId`, with `cursor` set to the layer-token used to fetch
+ * that item's batch. Layers whose contribution is wholly dropped by the
+ * trim retain their pre-call state so their items remain reachable on
+ * later pages.
  *
- * Each layer is queried with up to 2× the requested limit, results are merged,
- * sorted by the provided comparator, and trimmed to the requested limit.
- * A composite page token tracks per-source pagination state.
+ * **Critical contract: the comparator must NOT tiebreak by id.** Ties
+ * on the sort key must return 0 from `comparator`. `Array.sort` is
+ * stable since ES2019, and federation feeds the merge in
+ * `[layer0..., layer1..., ...]` insertion order, so ties resolve by
+ * `(layerIndex, layer-internal position)` — exactly the property that
+ * keeps each layer's kept items as a *prefix* of its own order, which
+ * is what makes a single `resumeAfterId` representable. An id
+ * tiebreaker would silently break this and lose items.
  *
- * @param layers    The persistence layers to query.
- * @param query     The query object (must have `limit`, `pageToken`).
- * @param fetcher   Function that queries a single layer.
- * @param comparator Sort comparator for merging results across layers.
+ * **Layer contract.** Layers must return the same items in the same
+ * order for the same `(query, pageToken)` pair across calls. Their
+ * internal ordering does not need to match federation's tiebreaker —
+ * just be deterministic.
  */
 export declare function federatedList<TQuery extends {
     limit?: number;
     pageToken?: string;
-}, TItem>(layers: {
+}, TItem extends {
+    id: string;
+}>(layers: {
     getItems: (query: TQuery) => Promise<PaginatedResult<TItem>>;
 }[], query: TQuery, comparator: (a: TItem, b: TItem) => number): Promise<PaginatedResult<TItem>>;
 export {};