@reticlehq/server 2.12.0 → 2.13.0

package/dist/flows/flow-tools.js

@@ -5,6 +5,7 @@ import { FlowErrorCode, RecordedSaveError, ReplayStatus, } from '@reticlehq/core
 import { recordSuiteFlakes } from './suite-flakes.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { workerCountSchema } from '../tools/numeric-bounds.js';
 import { log } from '../log.js';
 import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { mapWithConcurrency, resolveConcurrency } from './parallel-suite.js';
@@ -14,14 +15,15 @@ import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { buildSuiteVerdict } from './decision.js';
 import { classifyFlowAssertions } from './flow-classify.js';
 import { isValidFlowName, flowPath } from '../project/reticle-dir.js';
-import { FlowStore } from './flows.js';
+import {} from './flows.js';
+import { flowsForSession } from './flow-store-for-session.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun } from '../runs/verification-sync.js';
 import { runServerVerify } from './server-verify.js';
 import { healFlow } from './heal-run.js';
 export { replayNamedFlow } from './flow-replay-run.js';
 /**
- * Best-effort mirror of a just-saved flow to Reticle Cloud (only when logged in — both cloud env vars
+ * Best-effort mirror of a just-saved flow to Reticle (only when logged in — both cloud env vars
  * set). Fire-and-forget: resolves the config, POSTs via the platform fetch, and logs the outcome. Any
  * failure is swallowed so a network hiccup never affects the local save.
  */
@@ -68,24 +70,6 @@ export function leaseFailureReplay(name, error) {
 }
 /** Stand-in path for a flow whose name fails the path-segment guard — never a real join. */
 const INVALID_FLOW_NAME_PATH = '(invalid flow name — not a usable path)';
-/**
- * The flow store a SESSION's artifacts belong in, and the root it resolved to.
- *
- * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
- * daemon happens to have been started in the project it is driving. When a resolver is wired and it
- * names a different project, the write has to go there instead — so the store is rebound for this
- * call. Rebinding is cheap: a FlowStore is a filesystem port, a root and a clock.
- *
- * Returns `deps.flows` unchanged when nothing is wired or the roots already agree, so the common
- * case allocates nothing and behaves exactly as before.
- */
-function flowsForSession(deps, projectId) {
-    const resolved = deps.artifactRootFor?.(projectId);
-    if (resolved === undefined || resolved.root === deps.reticleRoot) {
-        return { flows: deps.flows, root: deps.reticleRoot };
-    }
-    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
-}
 /**
  * How a save reports that nobody said what the flow is for.
  *
@@ -108,7 +92,11 @@ export const FLOW_TOOLS = [
                 .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
-                .describe('Name for the flow file (saved to .reticle/flows/<flowName>.json). Use again in reticle_flow{action:"load"} / reticle_flow_replay.'),
+                .describe('Which RECORDING to save — the name reticle_record{start} was called with. This is a lookup key, not the filename: pass `saveAs` to choose that.'),
+            saveAs: z
+                .string()
+                .optional()
+                .describe('Name for the flow file (.reticle/flows/<saveAs>.json), and the name reticle_flow{action:"load"} / reticle_flow_replay take. Omit to reuse the recording name.'),
             intent: z
                 .string()
                 .optional()
@@ -147,12 +135,40 @@ export const FLOW_TOOLS = [
             const name = asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '';
             const program = deps.recordings.getCompiled(name);
             if (program === undefined) {
+                /*
+                 * Name what DOES exist.
+                 *
+                 * `flowName` here is the RECORDING's name, while every other flow tool reads it as the name
+                 * to save AS — so recording `default` and saving as `sign-in` looks obviously right and
+                 * answers "no compiled recording by that name". The old message then said "record one
+                 * first", which is advice to repeat the step that just succeeded. Cost a real investigation
+                 * before the names were compared.
+                 */
+                const held = deps.recordings.compiled();
                 return Promise.resolve({
-                    error: flowErrorMessage(FlowErrorCode.NO_RECORDING),
+                    error: 0 === held.length
+                        ? flowErrorMessage(FlowErrorCode.NO_RECORDING)
+                        : `no recording named '${name}'. This is the name the RECORDING was made under, not ` +
+                            `the name to save it as — stopped and ready to save: ${held.map((n) => `'${n}'`).join(', ')}.`,
                     code: FlowErrorCode.NO_RECORDING,
                 });
             }
+            // The name to save AS, which is not the name looked up above.
+            //
+            // `flowName` selects the recording; a recording is named at `record{start}`, often `default`
+            // or whatever the drive began as. Every other flow tool reads a flow name as the thing you
+            // load and replay, so a caller naming their flow at save time had no way to do it and had to
+            // `mv` the file on disk. The error message below already had to explain this ambiguity; that
+            // it needed explaining is the bug (#698).
+            const saveAs = asString(args['saveAs']);
+            if (saveAs !== undefined && !isValidFlowName(saveAs)) {
+                return Promise.resolve({
+                    error: `'${saveAs}' is not a usable flow name — it becomes a filename under .reticle/flows/.`,
+                    code: FlowErrorCode.INVALID_NAME,
+                });
+            }
             // fold any structured annotations (expect/dynamic/success/intent) onto the saved flow.
+            // Keyed by the RECORDING name: annotations were left against the recording, not the file.
             const success = deps.annotations.success(name);
             // The inline argument wins over an annotation left from an earlier call: it is the more recent
             // statement, and it is the one the author just typed.
@@ -170,7 +186,8 @@ export const FLOW_TOOLS = [
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
             const { flows, root } = flowsForSession(deps, projectId);
-            return flows.save(program, annotations, projectId).then(async (res) => {
+            const toSave = saveAs === undefined ? program : { ...program, name: saveAs };
+            return flows.save(toSave, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
                 deps.annotations.clear(name);
@@ -211,7 +228,10 @@ export const FLOW_TOOLS = [
         // received string") — caught driving the live demo.
         handler: (deps, args) => {
             const projectId = sessionProjectId(deps, asString(args['sessionId']));
-            return deps.flows.list(projectId).then((names) => ({
+            // The APP's flows, not the daemon's. Listing where the daemon was launched is what showed a
+            // React dashboard a HUD full of Electron and Tauri flows from an unrelated checkout.
+            const { flows: store, root } = flowsForSession(deps, projectId);
+            return store.list(projectId).then((names) => ({
                 // `list` deliberately returns invalid names so they are reported rather than silently
                 // dropped — but the declared outputSchema requires `path` on EVERY entry, and omitting it made
                 // a strict MCP client reject the whole listing (the agent then sees no flows at all, which is
@@ -219,7 +239,7 @@ export const FLOW_TOOLS = [
                 // gets an explanatory marker instead of a joined filesystem path, which is what must never
                 // happen for a traversal-shaped name.
                 flows: names.map((name) => isValidFlowName(name)
-                    ? { name, path: flowPath(deps.reticleRoot, name, projectId) }
+                    ? { name, path: flowPath(root, name, projectId) }
                     : { name, path: INVALID_FLOW_NAME_PATH }),
             }));
         },
@@ -368,8 +388,7 @@ export const FLOW_TOOLS = [
                 .array(z.string())
                 .optional()
                 .describe('Flow names to verify. Omit to verify every saved flow.'),
-            parallel: z
-                .number()
+            parallel: workerCountSchema
                 .optional()
                 .describe('Run this many flows at once, each in its own isolated leased browser context (needs the browser pool). Clamped to the pool capacity and the flow count. Omit for the sequential single-tab run.'),
             sessionId: z
@@ -398,7 +417,7 @@ export const FLOW_TOOLS = [
             const projectId = sessionProjectId(deps, sessionId);
             const requested = Array.isArray(args['names'])
                 ? args['names'].filter((n) => 'string' === typeof n)
-                : await deps.flows.list(projectId);
+                : await flowsForSession(deps, projectId).flows.list(projectId);
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
             const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
@@ -435,7 +454,9 @@ export const FLOW_TOOLS = [
                 const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
                     const name = requested[i] ?? '';
                     const replay = o.ok && o.value !== undefined ? o.value.replay : leaseFailureReplay(name, o.error);
-                    const loaded = await deps.flows.load(name, projectId).catch(() => null);
+                    const loaded = await flowsForSession(deps, projectId)
+                        .flows.load(name, projectId)
+                        .catch(() => null);
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
@@ -459,7 +480,9 @@ export const FLOW_TOOLS = [
             for (const flowName of requested) {
                 const start = deps.now();
                 const replay = await replayNamedFlow(deps, { flowName, sessionId });
-                const loaded = await deps.flows.load(flowName, projectId).catch(() => null);
+                const loaded = await flowsForSession(deps, projectId)
+                    .flows.load(flowName, projectId)
+                    .catch(() => null);
                 const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                 runs.push(flow === undefined ? { replay } : { replay, flow });
                 timed.push({ replay, durationMs: deps.now() - start });
@@ -538,10 +561,13 @@ export const FLOW_TOOLS = [
             const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);
             if (emptyRecorded !== undefined)
                 return emptyRecorded;
-            const res = await deps.flows.saveFlow(flow, session.projectId);
+            // Resolved like every other path now. This save used to go to the daemon's root while the
+            // recorded-flow save resolved per session, so where a flow landed depended on which tool wrote
+            // it — and the pair that disagreed were the two ways to save the same thing.
+            const res = await flowsForSession(deps, session.projectId).flows.saveFlow(flow, session.projectId);
             if (!res.ok)
                 return { error: flowErrorMessage(res.code), code: res.code };
-            // If logged into Reticle Cloud, mirror the saved flow to the team's regression suite. Best-effort
+            // If logged in to Reticle, mirror the saved flow to the team's regression suite. Best-effort
             // and non-blocking: the flow is already on disk, so a sync failure never fails the save.
             void syncSavedFlowToCloud(deps, flow, session.projectId);
             // Return the SaveSummary as-is ({ name, stepCount, degraded, empty }) — the outputSchema

package/dist/flows/flows.d.ts

@@ -19,6 +19,14 @@ export declare function anchorForStep(args: Record<string, unknown>): {
     anchor: FlowAnchor;
     degraded: boolean;
 };
+/**
+ * What a redacted fill value is replaced WITH.
+ *
+ * Replaced, never dropped. Replay still needs a step there, and a flow that silently loses its
+ * password step drifts at sign-in forever with no explanation of why. The placeholder also tells a
+ * reader what to do: the value belongs in the environment, not in a file they are about to commit.
+ */
+export declare const REDACTED_FILL = "<redacted: supply at replay>";
 /**
  * Pure: map one normalized RecordedStep → FlowStep with a semantic anchor (+ degraded marker).
  * A ref-only (stable:false) step is recorded with a best-effort anchor and degraded:true —