@reticlehq/server 3.9.0 → 3.10.0

package/dist/language/flows/affected-tools.d.ts

@@ -1,4 +1,4 @@
-import type { ToolDef } from '../../surface/tools/tool-kit.js';
+import { type ToolDef } from '../../surface/tools/tool-kit.js';
 /**
  * `reticle_affected` — which saved flows must re-verify for a set of changed files.
  *

package/dist/language/flows/affected-tools.js

@@ -1,10 +1,40 @@
 import { z } from 'zod';
-import { ReticleTool } from '@reticlehq/core';
-import { loadNamedFlows, resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
-import { projectDirFor } from '../../memory/project/session-root.js';
-import { sessionRoot, sessionProjectId } from '../../memory/project/session-root.js';
+import { asString, ReticleTool } from '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
+import { namedFlowsForSession } from './flow-store-for-session.js';
 import { affectedSavedFlows } from './change/flow-sources.js';
 import { RECORD_A_FLOW } from './suite/coverage.js';
+/**
+ * Why the answer is empty, when that needs saying.
+ *
+ * Several situations produced the same empty answer: no files changed, no flows saved, and a git
+ * ref that resolved to nothing. Only the first means "nothing to re-verify". The others mean the
+ * question could not be answered, and re-running nothing on that basis is how a regression ships.
+ */
+function emptyAnswerReason(facts) {
+    const { changed, since, fileCount, flowCount, changedCount, unmatchedRoot } = facts;
+    // No folder declares this project, so nothing here is about a checkout (#1550).
+    if (unmatchedRoot !== undefined) {
+        return `no flows here: no folder on disk declares this project, so its evidence goes to ${unmatchedRoot}. Run \`reticle init\` in the app's folder, or lease the tab from there.`;
+    }
+    // A git failure OUTRANKS every other explanation: the others describe a question that was
+    // answered, and this one is a question that was not. Reporting "nothing changed" over a mistyped
+    // ref or a shallow clone is how a regression ships past the tool meant to catch it.
+    if (true === changed.failed) {
+        return `could not read the diff for \`${String(since)}\`, so NOTHING was compared and this result proves nothing: ${changed.reason ?? 'git failed'}`;
+    }
+    if (0 === flowCount) {
+        return `no saved flows exist yet, so nothing COULD be affected. ${RECORD_A_FLOW}`;
+    }
+    if (0 !== changedCount) {
+        return undefined;
+    }
+    if (since === undefined && 0 === fileCount) {
+        return 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref';
+    }
+    return 'nothing changed against that input, so no saved flow needs re-verifying';
+}
 /**
  * `reticle_affected` — which saved flows must re-verify for a set of changed files.
  *
@@ -27,6 +57,7 @@ export const AFFECTED_TOOLS = [
         description: 'Which saved flows must re-verify for a set of changed files. Pass the files you edited (and/or `since` for a git ref to diff against). Returns { changedFiles, affected, unknownProvenance } — `affected` is what to re-run, and `unknownProvenance` are flows included only because Reticle cannot tell which sources they cover, so they are re-verified by default rather than silently skipped.',
         example: { files: ['src/App.tsx'] },
         inputSchema: {
+            ...sessionIdShape,
             files: z
                 .array(z.string())
                 .optional()
@@ -46,34 +77,22 @@ export const AFFECTED_TOOLS = [
                 ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
             const since = 'string' === typeof args['since'] ? args['since'] : undefined;
-            // Same address as verify_change, resolved the same way. `deps.reticleRoot` is NOT the project
-            // directory this line used to claim it was — it is the daemon's `.reticle` subdirectory, in
-            // whichever tree the MCP host was started in. `undefined` here resolves the single connected
-            // session, which is the same rule the flow lookup below already follows.
-            const changed = await resolveChangedFiles(files, since, projectDirFor(deps, undefined));
+            // The project of the tab being driven, not the folder the daemon started in (#1550). The flows
+            // come from the store `flows` replays from, so a flow named here can be replayed by that name
+            // (#1996). `git diff` runs in the project directory that holds that store.
+            const { flows, projectDir, unmatchedRoot } = await namedFlowsForSession(deps, asString(args['sessionId']));
+            // A bucket of evidence is not a tree, so a `since` has nothing to diff against.
+            const changed = await resolveChangedFiles(files, unmatchedRoot === undefined ? since : undefined, projectDir);
             const changedFiles = changed.files;
-            // No `sessionId` on this tool's surface, and it does not need one: passing `undefined`
-            // resolves the single connected session, and falls back exactly as before when it cannot.
-            // Adding an argument here would be a surface change to fix an addressing bug.
-            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, undefined), sessionProjectId(deps, undefined));
             const result = affectedSavedFlows(flows, changedFiles);
-            // Three different situations produced the same empty answer: no files changed, no flows saved,
-            // and a git ref that resolved to nothing. Only the first means "nothing to re-verify"; the
-            // others mean the question could not be answered, and re-running nothing on that basis is how a
-            // regression ships. Say which one it is.
-            const why = 
-            // A git failure OUTRANKS every other explanation: the others describe a question that was
-            // answered, and this one is a question that was not. Reporting "nothing changed" over a
-            // mistyped ref or a shallow clone is how a regression ships past the tool meant to catch it.
-            changed.failed
-                ? `could not read the diff for \`${String(since)}\`, so NOTHING was compared and this result proves nothing: ${changed.reason ?? 'git failed'}`
-                : 0 === flows.length
-                    ? `no saved flows exist yet, so nothing COULD be affected. ${RECORD_A_FLOW}`
-                    : 0 === changedFiles.length
-                        ? since === undefined && 0 === files.length
-                            ? 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref'
-                            : 'nothing changed against that input, so no saved flow needs re-verifying'
-                        : undefined;
+            const why = emptyAnswerReason({
+                changed,
+                since,
+                fileCount: files.length,
+                flowCount: flows.length,
+                changedCount: changedFiles.length,
+                unmatchedRoot,
+            });
             return {
                 changedFiles,
                 ...result,

package/dist/language/flows/change/git-changed.d.ts

@@ -17,7 +17,8 @@ export interface ChangedFiles {
 }
 /**
  * Files changed since a git ref (`git diff --name-only <ref>`), so `reticle gate --since main` works
- * from the real diff instead of hand-listed files.
+ * from the real diff instead of hand-listed files. Files under Reticle's own directory are left
+ * out: a replay writes them, and they are not a change to the app's code.
  *
  * Never throws, and never pretends. The CLI gate may still degrade to "no changes" and pass rather
  * than crash CI — that reasoning was right and is unchanged — but it now has to opt into doing so by

package/dist/language/flows/change/git-changed.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { ReticleDir } from '@reticlehq/core';
 const run = promisify(execFile);
 /** Parse `git diff --name-only` output into a clean file list. Pure; exported for testing. */
 export function parseGitFiles(output) {
@@ -19,9 +20,22 @@ export function parseGitFiles(output) {
 function refIsOptionLike(ref) {
     return ref.startsWith('-');
 }
+/**
+ * True when a diff path sits under Reticle's own project directory.
+ *
+ * A replay writes intent, impact and episode files into that directory. Those writes are
+ * Reticle's output, not a change to the app's code. A flow with no source stamps reads any
+ * change as "affected", so counting them marked flows the gate had just proved as uncovered
+ * (#2050). The directory can sit below the repo root, so any path segment counts. `git diff`
+ * prints paths with `/` on every platform.
+ */
+function isReticleOwnPath(path) {
+    return path.split('/').includes(ReticleDir.ROOT);
+}
 /**
  * Files changed since a git ref (`git diff --name-only <ref>`), so `reticle gate --since main` works
- * from the real diff instead of hand-listed files.
+ * from the real diff instead of hand-listed files. Files under Reticle's own directory are left
+ * out: a replay writes them, and they are not a change to the app's code.
  *
  * Never throws, and never pretends. The CLI gate may still degrade to "no changes" and pass rather
  * than crash CI — that reasoning was right and is unchanged — but it now has to opt into doing so by
@@ -38,7 +52,10 @@ export async function changedFilesSince(ref, cwd) {
     }
     try {
         const { stdout } = await run('git', ['diff', '--name-only', ref], { cwd });
-        return { files: parseGitFiles(stdout), failed: false };
+        return {
+            files: parseGitFiles(stdout).filter((file) => !isReticleOwnPath(file)),
+            failed: false,
+        };
     }
     catch (error) {
         return {

package/dist/language/flows/fields/flow-secret-field.d.ts

@@ -41,7 +41,7 @@ export declare const SECRET_FIELD_ARG = "secretField";
  * rules must not be able to drift. It used to sit in `replay.ts`, one import away from the sentence
  * saying it had to stay together.
  */
-export declare const secretEnvKey: (field: string) => string;
+export declare function secretEnvKey(field: string): string;
 /** The schema of that argument, shared by every tool that replays a flow. */
 export { CALL_SECRETS_ARG };
 export declare const callSecretsArg: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -59,16 +59,4 @@ export interface UnsuppliedSecret {
     field: string;
     envKey: string;
 }
-/**
- * Every credential this flow will replay as the literal placeholder.
- *
- * Checked BEFORE a step runs, because the alternative is what shipped: the placeholder is typed
- * into the password box, sign-in fails, and the flow reports that an element further down the
- * journey has gone missing -- a `drift` verdict naming a component nobody touched, with an
- * invitation to update a flow that was correct.
- *
- * The emptiness rule matches `replayActionArgs` exactly: it substitutes only for a value of
- * non-zero length, so an empty variable leaves the placeholder and must count as unsupplied here.
- * Two different answers to "is this supplied" is how the gate would pass and the replay still fail.
- */
 export declare function unsuppliedSecrets(flow: FlowFile, env: Record<string, string | undefined>): UnsuppliedSecret[];

package/dist/language/flows/fields/flow-secret-field.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import { AnchorKind } from '@reticlehq/core';
 import { CALL_SECRETS_ARG, callSecrets } from '../../../surface/tools/tool-kit.js';
@@ -14,12 +15,15 @@ import { CALL_SECRETS_ARG, callSecrets } from '../../../surface/tools/tool-kit.j
  * to find the env var because the runner passed a role or a label instead.
  */
 export function anchorFieldName(anchor) {
-    if (AnchorKind.TESTID === anchor.kind)
+    if (AnchorKind.TESTID === anchor.kind) {
         return anchor.value;
-    if (AnchorKind.ROLE === anchor.kind)
+    }
+    if (AnchorKind.ROLE === anchor.kind) {
         return anchor.name;
-    if (AnchorKind.SIGNAL === anchor.kind)
+    }
+    if (AnchorKind.SIGNAL === anchor.kind) {
         return anchor.name;
+    }
     return undefined;
 }
 /**
@@ -39,6 +43,16 @@ export const SECRET_NAME_ARG = 'secret';
 export const SECRET_FIELD_ARG = 'secretField';
 /** The prefix every secret's variable carries. */
 const SECRET_ENV_PREFIX = 'RETICLE_SECRET_';
+/** Any character outside ASCII. */
+const NON_ASCII = /[^\p{ASCII}]/u;
+/** The word in the variable of a field whose name is not ASCII. */
+const NON_ASCII_FIELD = 'FIELD';
+const NON_ASCII_DIGEST_LENGTH = 8;
+/**
+ * The variable name an ASCII field gets. Up to 3.9.0 a non-ASCII field got this name too, and a
+ * flow saved then still names it.
+ */
+const asciiSecretEnvKey = (field) => `${SECRET_ENV_PREFIX}${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
 /**
  * The environment variable that supplies one redacted field.
  *
@@ -51,7 +65,16 @@ const SECRET_ENV_PREFIX = 'RETICLE_SECRET_';
  * rules must not be able to drift. It used to sit in `replay.ts`, one import away from the sentence
  * saying it had to stay together.
  */
-export const secretEnvKey = (field) => `${SECRET_ENV_PREFIX}${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+export function secretEnvKey(field) {
+    if (!NON_ASCII.test(field)) {
+        return asciiSecretEnvKey(field);
+    }
+    // A name in another script has no ASCII letters to keep: "Пароль" and "Гасло" both became
+    // `RETICLE_SECRET__`, so one field's value was typed into the other. A short hash of the name
+    // keeps each field's variable distinct and the same on every machine.
+    const digest = createHash('sha256').update(field.normalize('NFC').toLowerCase()).digest('hex');
+    return `${SECRET_ENV_PREFIX}${NON_ASCII_FIELD}_${digest.slice(0, NON_ASCII_DIGEST_LENGTH).toUpperCase()}`;
+}
 /** The schema of that argument, shared by every tool that replays a flow. */
 export { CALL_SECRETS_ARG };
 export const callSecretsArg = z
@@ -64,30 +87,35 @@ export const callSecretsArg = z
  */
 export function secretValue(envKey, env) {
     for (const [key, value] of Object.entries(callSecrets() ?? {})) {
-        if (envKey === (key.startsWith(SECRET_ENV_PREFIX) ? key : secretEnvKey(key)))
+        if (envKey === (key.startsWith(SECRET_ENV_PREFIX) ? key : secretEnvKey(key))) {
             return value;
+        }
     }
     return env[envKey];
 }
 const SECRET_OCCURRENCE = /^(?:[2-9]|[1-9][0-9]+)$/;
 /** The field's own saved variable name, or its original key for legacy and invalid metadata. */
 export function secretKeyForFill(args, field) {
-    if (args?.['value'] !== REDACTED_FILL)
+    if (args?.['value'] !== REDACTED_FILL) {
         return undefined;
+    }
     const named = args[SECRET_NAME_ARG];
     const base = secretEnvKey(field);
-    // A flow can supply this field's occurrence, never an unrelated environment variable.
-    return 'string' === typeof named &&
-        named.startsWith(`${base}_`) &&
-        SECRET_OCCURRENCE.test(named.slice(base.length + 1))
-        ? named
-        : base;
+    // A flow can supply this field's occurrence, never an unrelated environment variable. The name
+    // an earlier version gave a non-ASCII field is still this field's.
+    if ('string' !== typeof named) {
+        return base;
+    }
+    const own = (key) => named === key ||
+        (named.startsWith(`${key}_`) && SECRET_OCCURRENCE.test(named.slice(key.length + 1)));
+    return own(base) || own(asciiSecretEnvKey(field)) ? named : base;
 }
 function* secretSteps(steps) {
     for (const step of steps) {
         yield step;
-        if (step.steps !== undefined)
+        if (step.steps !== undefined) {
             yield* secretSteps(step.steps);
+        }
     }
 }
 /** Allocate recorded fills' names while preserving legacy placeholders and existing suffixes. */
@@ -96,14 +124,17 @@ export function withDistinctSecretKeys(flow) {
     const used = new Set();
     for (const step of secretSteps(flow.steps)) {
         const field = anchorFieldName(step.anchor);
-        if (field === undefined)
+        if (field === undefined) {
             continue;
+        }
         const key = secretKeyForFill(step.args, field);
-        if (key === undefined)
+        if (key === undefined) {
             continue;
+        }
         reserved.add(key);
-        if (key !== secretEnvKey(field) || step.args?.[SECRET_NAME_ARG] === undefined)
+        if (key !== secretEnvKey(field) || step.args?.[SECRET_NAME_ARG] === undefined) {
             used.add(key);
+        }
     }
     const assign = (step) => {
         let out = step;
@@ -119,8 +150,9 @@ export function withDistinctSecretKeys(flow) {
                 occurrence += 1;
             }
             used.add(key);
-            if (key !== base)
+            if (key !== base) {
                 out = { ...step, args: { ...step.args, [SECRET_NAME_ARG]: key } };
+            }
         }
         return step.steps === undefined ? out : { ...out, steps: step.steps.map(assign) };
     };
@@ -138,23 +170,47 @@ export function withDistinctSecretKeys(flow) {
  * non-zero length, so an empty variable leaves the placeholder and must count as unsupplied here.
  * Two different answers to "is this supplied" is how the gate would pass and the replay still fail.
  */
+function* flattenAll(steps) {
+    for (const step of steps) {
+        yield step;
+        yield* flattenAll(step.steps ?? []);
+    }
+}
 export function unsuppliedSecrets(flow, env) {
     const out = [];
     const seen = new Set();
     for (const step of secretSteps(flow.steps ?? [])) {
         const field = anchorFieldName(step.anchor);
-        if (field === undefined)
+        if (field === undefined) {
             continue;
+        }
         const envKey = secretKeyForFill(step.args, field);
-        if (envKey === undefined)
+        if (envKey === undefined) {
             continue;
+        }
         const supplied = secretValue(envKey, env);
-        if (supplied !== undefined && supplied.length > 0)
+        if (supplied !== undefined && supplied.length > 0) {
             continue;
-        if (seen.has(envKey))
+        }
+        if (seen.has(envKey)) {
             continue;
+        }
         seen.add(envKey);
         out.push({ field, envKey });
     }
+    // A request step that acts as another account needs that account's session.
+    for (const step of flattenAll(flow.steps ?? [])) {
+        const account = step.request?.as;
+        if (account === undefined) {
+            continue;
+        }
+        const envKey = secretEnvKey(account);
+        const supplied = secretValue(envKey, env);
+        if ((supplied !== undefined && supplied.length > 0) || seen.has(envKey)) {
+            continue;
+        }
+        seen.add(envKey);
+        out.push({ field: account, envKey });
+    }
     return out;
 }

package/dist/language/flows/flow-anchor.d.ts

@@ -1,4 +1,4 @@
-import { AnchorKind, type Drift, type FlowAnchor, type QueryEmptyHint } from '@reticlehq/core';
+import { AnchorKind, type CommandResult, type Drift, type FlowAnchor, type QueryEmptyHint } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 /**
  * Finding a step's anchor again, and saying legibly why it could not be found.
@@ -33,6 +33,29 @@ export declare function nearestTestid(missing: string, present: string[]): strin
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
 /** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
 export declare function testidDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
+/**
+ * How an anchor is ADDRESSED — the sentence that names it, and the label a result row carries.
+ *
+ * Two different strings, and neither can be derived from the other: `value` is a raw testid for one
+ * anchor kind and a human-readable label for the others, so one sentence cannot name both. Calling a
+ * role anchor `testid "button "View result""` sends the reader to edit a locator that does not exist
+ * on that step, which is the same misdirection the drift reason exists to remove.
+ *
+ * Derived from the anchor rather than passed in by the caller. The first version of the role fix took
+ * a `described` argument and wrote `ambiguousAnchorDrift(label, n, \`role anchor ${label}\`)` — the
+ * same string twice, so the `anchor` field and the sentence could drift apart with nothing to catch
+ * it, and the next anchor kind would have had to remember the convention on its own.
+ */
+/**
+ * How a role anchor reads in a message: `button "View result"`, or for a control with no accessible
+ * name, `button (no accessible name, #2 of 3)` — never `button "undefined"`.
+ */
+export declare function roleAnchorLabel(anchor: {
+    role: string;
+    name?: string | undefined;
+    nth?: number | undefined;
+    of?: number | undefined;
+}): string;
 /**
  * What the stale-ref retry found when it ran the locator again.
  *
@@ -106,10 +129,28 @@ export declare function queryOnce(session: FlowReplaySession, queryArgs: Record<
     refs: string[];
     hint?: QueryEmptyHint;
 }>;
-export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep, now?: () => number): Promise<{
+export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep, now?: () => number, read?: (result: CommandResult) => {
+    refs: string[];
+    hint?: QueryEmptyHint;
+}): Promise<{
     refs: string[];
     hint?: QueryEmptyHint;
 }>;
+/**
+ * Several queries for one control, pooled: each attempt runs every query and joins the refs, so
+ * the settle budget is spent once, not once for each query. A role anchor with `alsoRoles` uses it.
+ */
+export declare function resolveAnyQuery(session: FlowReplaySession, queries: readonly Record<string, unknown>[], sleep: Sleep, now?: () => number, read?: (result: CommandResult) => {
+    refs: string[];
+    hint?: QueryEmptyHint;
+}): Promise<{
+    refs: string[];
+    hint?: QueryEmptyHint;
+}>;
+/** `resolveQuery`'s reader for a nameless role anchor: only the matches with no accessible name. */
+export declare function readNamelessQuery(result: CommandResult): {
+    refs: string[];
+};
 /** Re-resolve a testid anchor. */
 export declare function resolveTestid(session: FlowReplaySession, value: string, sleep: Sleep): Promise<{
     refs: string[];
@@ -125,3 +166,20 @@ export declare function anchorLabel(anchor: FlowAnchor): string;
 export declare function componentQueryArgs(anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.COMPONENT;
 }>): Record<string, unknown>;
+/** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
+export declare function roleQueryArgs(anchor: Extract<FlowAnchor, {
+    kind: typeof AnchorKind.ROLE;
+}>): Record<string, unknown>;
+/**
+ * Resolve a role anchor. ONE function for the first look and the re-resolve after a stale ref: the
+ * re-resolve used to count every control of the role, so a nameless anchor's position came back
+ * ambiguous on a working page.
+ *
+ * A nameless anchor's position counts only the nameless controls of its role (an icon-only edit
+ * button is the 2nd nameless button of its row, not the 5th button), so it reads only those.
+ */
+export declare function resolveRoleAnchor(session: FlowReplaySession, anchor: Extract<FlowAnchor, {
+    kind: typeof AnchorKind.ROLE;
+}>, sleep: Sleep): Promise<{
+    refs: string[];
+}>;