donobu 5.60.8 → 5.61.0

package/dist/esm/utils/AdvancedSelectorGenerator.d.ts

@@ -0,0 +1,106 @@
+import type { ElementHandle } from 'playwright';
+import { z } from 'zod/v4';
+import type { ElementSelector } from '../models/ElementSelector';
+import type { GptMessage } from '../models/GptMessage';
+import type { ToolCallContext } from '../models/ToolCallContext';
+/**
+ * The model's decision for advancing a generated selector: the SAME candidate
+ * list, in the same order and count, each rewritten so env-derived substrings are
+ * expressed as `{{$.env.NAME}}` (optionally with a `| filter`) placeholders, or
+ * returned unchanged. The deterministic core ({@link advanceSelectorCandidates})
+ * validates and applies it.
+ */
+export declare const AdvancedSelectorDecisionSchema: z.ZodObject<{
+    element: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type AdvancedSelectorDecision = z.infer<typeof AdvancedSelectorDecisionSchema>;
+/**
+ * The model's synthesized selector: one that locates the target by anchoring on
+ * nearby env-derived text (e.g. a card's title), or null if it can't. Validated
+ * against the live page before being accepted.
+ */
+export declare const SynthesizedSelectorSchema: z.ZodObject<{
+    selector: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The slice of {@link ToolCallContext} this routine needs: the env data and the
+ * action's references (to know what was baked in), plus the GPT client and flow
+ * metadata to run + account for the one model call. Callers pass their
+ * `ToolCallContext` directly.
+ */
+export type AdvancedSelectorContext = Pick<ToolCallContext, 'gptClient' | 'metadata' | 'envData' | 'rawParameters'>;
+/** A referenced env var and the forms of its value that appear in the candidates. */
+type BakedEnvForm = {
+    name: string;
+    value: string;
+    forms: Array<{
+        filter: string | null;
+        form: string;
+    }>;
+};
+/**
+ * Turn the element the agent acted on into the best *replayable* selector:
+ * generate raw candidates from the DOM, then (only for env-parameterized actions
+ * whose value got baked in) re-parameterize and prune them so the cached selector
+ * reflects the action's semantic intent rather than incidental DOM position.
+ *
+ * The DOM read and the model call are the only impurities and live here; the
+ * decision logic is delegated to the pure helpers below. Never returns null — it
+ * falls back to the raw generated selector whenever there is nothing to advance
+ * or the model's rewrite can't be validated.
+ */
+export declare function generateAdvancedSelectors(target: ElementHandle<HTMLElement | SVGElement>, context: AdvancedSelectorContext): Promise<ElementSelector>;
+/**
+ * For each referenced env var, the distinct forms of its value (verbatim or via a
+ * transform — e.g. "contact" / "Contact" / "/contact") that actually appear in
+ * the generated candidates. PURE.
+ */
+export declare function computeBakedEnvForms(candidates: string[], envData: Record<string, string>, referencedEnvVars: string[]): BakedEnvForm[];
+/**
+ * Build the model prompt: deterministic `form -> placeholder` hints (with the
+ * `| filter` to use for each transformed form) plus the candidate list. PURE.
+ */
+export declare function buildAdvancedSelectorRequest(candidates: string[], baked: BakedEnvForm[]): GptMessage[];
+/**
+ * Build the synthesis prompt: the target's neighborhood HTML (with the target
+ * marked) and the env values in play. PURE.
+ */
+export declare function buildSynthesisRequest(neighborhoodHtml: string, envMapping: string, markerAttribute: string): GptMessage[];
+/**
+ * Apply the model's decision and prune the result. PURE:
+ *
+ * 1. **Validate + templatize.** A rewrite is accepted only if interpolating it
+ *    with the current env values reproduces the exact original candidate — so the
+ *    model is bound to placeholder substitution; any other edit is rejected and
+ *    that candidate keeps its literal. A wrong-shaped decision is ignored wholesale.
+ * 2. **Elide.** Once a candidate tracks an env value, drop any purely-positional
+ *    candidate that does not: for a data-driven action, position is a coincidence
+ *    of the recorded data and would mislocate when the value (or order) changes.
+ *
+ * Never returns empty — falls back to the raw candidates if pruning would remove
+ * everything (and elision never fires unless a semantic, env-bearing candidate
+ * survives to take over).
+ */
+export declare function advanceSelectorCandidates(rawCandidates: string[], envData: Record<string, string>, decision: AdvancedSelectorDecision): string[];
+/**
+ * Once a candidate tracks an env value, drop purely-positional candidates that
+ * don't — for a data-driven action, position is a coincidence of the recorded
+ * data and would mislocate when the value (or order) changes. Returns the input
+ * unchanged when nothing is env-bearing (no semantic anchor to take over) or when
+ * pruning would remove everything. PURE.
+ */
+export declare function pruneCoincidentalPositional(candidates: string[]): string[];
+/** A selector that carries an env reference (so it tracks the value at replay). */
+export declare function isEnvBearingSelector(selector: string): boolean;
+/**
+ * Heuristic for a selector that locates an element *purely by DOM position* — an
+ * `:nth-*` pseudo, an XPath numeric index `[N]`, or a bare combinator chain — with
+ * no meaningful anchor (id, class, attribute, or text predicate). PURE.
+ *
+ * The "meaningful anchor" guard is what keeps a text/attribute selector that also
+ * happens to carry an index (e.g. `(.//a[normalize-space(.)='X'])[2]`) from being
+ * treated as positional.
+ */
+export declare function isPurelyPositionalSelector(selector: string): boolean;
+export {};
+//# sourceMappingURL=AdvancedSelectorGenerator.d.ts.map

package/dist/esm/utils/AdvancedSelectorGenerator.js

@@ -0,0 +1,396 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SynthesizedSelectorSchema = exports.AdvancedSelectorDecisionSchema = void 0;
+exports.generateAdvancedSelectors = generateAdvancedSelectors;
+exports.computeBakedEnvForms = computeBakedEnvForms;
+exports.buildAdvancedSelectorRequest = buildAdvancedSelectorRequest;
+exports.buildSynthesisRequest = buildSynthesisRequest;
+exports.advanceSelectorCandidates = advanceSelectorCandidates;
+exports.pruneCoincidentalPositional = pruneCoincidentalPositional;
+exports.isEnvBearingSelector = isEnvBearingSelector;
+exports.isPurelyPositionalSelector = isPurelyPositionalSelector;
+const v4_1 = require("zod/v4");
+const Logger_1 = require("./Logger");
+const MiscUtils_1 = require("./MiscUtils");
+const PlaywrightUtils_1 = require("./PlaywrightUtils");
+const TemplateInterpolator_1 = require("./TemplateInterpolator");
+/**
+ * Cap on generated selector candidates kept as failovers. Mirrors the failover
+ * cap used by the deterministic locator path (`ReplayableInteraction`); kept here
+ * because this module owns the generation step.
+ */
+const MAX_REPLAY_SELECTOR_CANDIDATES = 3;
+/** Temporary attribute marking the target so the model knows which element to anchor to. */
+const SYNTH_TARGET_MARKER = 'data-donobu-synth-target';
+/** Cap on the neighborhood HTML sent to the model for synthesis. */
+const MAX_NEIGHBORHOOD_HTML = 4000;
+/**
+ * The model's decision for advancing a generated selector: the SAME candidate
+ * list, in the same order and count, each rewritten so env-derived substrings are
+ * expressed as `{{$.env.NAME}}` (optionally with a `| filter`) placeholders, or
+ * returned unchanged. The deterministic core ({@link advanceSelectorCandidates})
+ * validates and applies it.
+ */
+exports.AdvancedSelectorDecisionSchema = v4_1.z.object({
+    element: v4_1.z
+        .array(v4_1.z.string())
+        .describe('The selector candidates from the input, in the SAME order and count, ' +
+        'with each substring that came from an env var replaced by its ' +
+        '{{$.env.NAME}} placeholder (use the | filter form for a transformed ' +
+        'substring). Structural or coincidental matches are left untouched. No ' +
+        'other edits.'),
+});
+/**
+ * The model's synthesized selector: one that locates the target by anchoring on
+ * nearby env-derived text (e.g. a card's title), or null if it can't. Validated
+ * against the live page before being accepted.
+ */
+exports.SynthesizedSelectorSchema = v4_1.z.object({
+    selector: v4_1.z
+        .string()
+        .nullable()
+        .describe('A single CSS or XPath selector that UNIQUELY locates the marked target ' +
+        'element by anchoring on its env-derived nearby text (as a ' +
+        '{{$.env.NAME}} placeholder, optionally with a | filter). Do NOT use the ' +
+        'temporary marker attribute. Null if no reliable anchor exists.'),
+});
+/**
+ * Turn the element the agent acted on into the best *replayable* selector:
+ * generate raw candidates from the DOM, then (only for env-parameterized actions
+ * whose value got baked in) re-parameterize and prune them so the cached selector
+ * reflects the action's semantic intent rather than incidental DOM position.
+ *
+ * The DOM read and the model call are the only impurities and live here; the
+ * decision logic is delegated to the pure helpers below. Never returns null — it
+ * falls back to the raw generated selector whenever there is nothing to advance
+ * or the model's rewrite can't be validated.
+ */
+async function generateAdvancedSelectors(target, context) {
+    const element = (await PlaywrightUtils_1.PlaywrightUtils.generateSelectors(target)).slice(0, MAX_REPLAY_SELECTOR_CANDIDATES);
+    const frame = await deriveFrameSelector(target);
+    const raw = { element, frame };
+    if (element.length === 0) {
+        return raw;
+    }
+    // Env vars referenced by this action — in its own (raw, un-interpolated)
+    // parameters or in the overall objective (e.g. a click targeting
+    // "{{$.env.NAV}}", where the reference lives in the objective, not the params).
+    const referencedEnvVars = [
+        JSON.stringify(context.rawParameters ?? {}),
+        context.metadata.overallObjective ?? '',
+    ].flatMap((source) => (0, TemplateInterpolator_1.extractEnvVarReferences)(source));
+    const gptClient = context.gptClient;
+    // Only data-driven actions need advancing, and either path needs the model.
+    if (referencedEnvVars.length === 0 || !gptClient) {
+        return raw;
+    }
+    // Case A — the referenced value was baked into the target's OWN selectors (its
+    // text, an attribute, an href). Re-parameterize those and prune coincidental
+    // positional siblings.
+    const baked = computeBakedEnvForms(element, context.envData, referencedEnvVars);
+    if (baked.length > 0) {
+        let decision;
+        try {
+            const outcome = await gptClient.getStructuredOutput(buildAdvancedSelectorRequest(element, baked), exports.AdvancedSelectorDecisionSchema);
+            MiscUtils_1.MiscUtils.updateTokenCounts(outcome, context.metadata);
+            decision = outcome.output;
+        }
+        catch (error) {
+            Logger_1.appLogger.warn('Advanced selector model call failed; keeping the generated selector.', error);
+            return raw;
+        }
+        const advancedElement = advanceSelectorCandidates(element, context.envData, decision);
+        if (JSON.stringify(advancedElement) !== JSON.stringify(element)) {
+            Logger_1.appLogger.info(`Advanced replay selector: ${JSON.stringify(element)} -> ${JSON.stringify(advancedElement)}`);
+        }
+        return { element: advancedElement, frame };
+    }
+    // Case B — the value is NOT in the target's own selectors (the target is
+    // identified only by position), but may live in a nearby element (a title or
+    // label). Try to synthesize a selector that anchors on that text instead.
+    const synthesized = await synthesizeAnchoredSelector(target, context, referencedEnvVars);
+    if (synthesized) {
+        const advancedElement = pruneCoincidentalPositional([
+            synthesized,
+            ...element,
+        ]);
+        Logger_1.appLogger.info(`Synthesized anchored replay selector: ${synthesized} (failover: ${JSON.stringify(advancedElement.slice(1))})`);
+        return { element: advancedElement, frame };
+    }
+    return raw;
+}
+/**
+ * For each referenced env var, the distinct forms of its value (verbatim or via a
+ * transform — e.g. "contact" / "Contact" / "/contact") that actually appear in
+ * the generated candidates. PURE.
+ */
+function computeBakedEnvForms(candidates, envData, referencedEnvVars) {
+    const referenced = new Set(referencedEnvVars);
+    return Object.entries(envData)
+        .filter(([name]) => referenced.has(name))
+        .map(([name, value]) => ({
+        name,
+        value,
+        forms: (0, TemplateInterpolator_1.envValueForms)(value).filter((candidateForm) => candidates.some((candidate) => candidate.includes(candidateForm.form))),
+    }))
+        .filter((entry) => entry.forms.length > 0);
+}
+/**
+ * Build the model prompt: deterministic `form -> placeholder` hints (with the
+ * `| filter` to use for each transformed form) plus the candidate list. PURE.
+ */
+function buildAdvancedSelectorRequest(candidates, baked) {
+    const envHints = baked
+        .map((entry) => {
+        const formLines = entry.forms
+            .map((candidateForm) => {
+            const placeholder = candidateForm.filter
+                ? `{{$.env.${entry.name} | ${candidateForm.filter}}}`
+                : `{{$.env.${entry.name}}}`;
+            return `      - the substring ${JSON.stringify(candidateForm.form)} -> ${placeholder}`;
+        })
+            .join('\n');
+        return `  - ${entry.name} = ${JSON.stringify(entry.value)}\n${formLines}`;
+    })
+        .join('\n');
+    return [
+        {
+            type: 'system',
+            text: `You re-parameterize auto-generated browser element selectors so that
+cached automation stays correct when environment variable values change.
+
+You are given a prioritized list of selector candidates generated from a live DOM
+element. Some may contain a substring that came from an environment variable —
+either the value verbatim, or a deterministic transform of it (e.g. a tab text
+"Contact" from the value "contact", or an href "/some-tab" from "Some Tab").
+
+For each env var below, the exact substring form(s) that appear in the candidates
+are listed, each with the placeholder to use for it. Replace each such substring
+with its placeholder (use the \`| filter\` form when the substring is a transformed
+form). Use judgment: only replace a substring that is genuinely the env-derived
+data, not a coincidental structural token (e.g. a CSS tag like \`body\`, an
+attribute name). When in doubt, LEAVE IT UNCHANGED. Never add, remove, reorder, or
+otherwise alter a selector beyond substituting placeholders. Return the SAME
+candidates, in the SAME order and count.
+
+Env vars and the substring forms they take in these selectors:
+${envHints}`,
+        },
+        {
+            type: 'user',
+            items: [{ type: 'text', text: JSON.stringify(candidates, null, 2) }],
+        },
+    ];
+}
+/**
+ * Build the synthesis prompt: the target's neighborhood HTML (with the target
+ * marked) and the env values in play. PURE.
+ */
+function buildSynthesisRequest(neighborhoodHtml, envMapping, markerAttribute) {
+    return [
+        {
+            type: 'system',
+            text: `You write ONE robust selector that locates a specific target element by
+anchoring on nearby text that came from an environment variable.
+
+The target element is marked with the attribute \`${markerAttribute}\` in the HTML
+below. Return a single CSS or XPath selector that UNIQUELY locates that element —
+but do NOT use \`${markerAttribute}\` (it is temporary and gone at replay).
+Instead, anchor on the env-derived text near it (e.g. a sibling/ancestor title or
+label), written as a {{$.env.NAME}} placeholder (use the \`| filter\` form when the
+on-page text is a transformed form of the value). Prefer an XPath that finds the
+container by its env-derived text and then descends to the target. If you cannot
+build a reliable, unique anchor, return null.
+
+Env vars in play:
+${envMapping}`,
+        },
+        {
+            type: 'user',
+            items: [{ type: 'text', text: neighborhoodHtml }],
+        },
+    ];
+}
+/**
+ * Apply the model's decision and prune the result. PURE:
+ *
+ * 1. **Validate + templatize.** A rewrite is accepted only if interpolating it
+ *    with the current env values reproduces the exact original candidate — so the
+ *    model is bound to placeholder substitution; any other edit is rejected and
+ *    that candidate keeps its literal. A wrong-shaped decision is ignored wholesale.
+ * 2. **Elide.** Once a candidate tracks an env value, drop any purely-positional
+ *    candidate that does not: for a data-driven action, position is a coincidence
+ *    of the recorded data and would mislocate when the value (or order) changes.
+ *
+ * Never returns empty — falls back to the raw candidates if pruning would remove
+ * everything (and elision never fires unless a semantic, env-bearing candidate
+ * survives to take over).
+ */
+function advanceSelectorCandidates(rawCandidates, envData, decision) {
+    const rewrites = decision?.element;
+    if (!Array.isArray(rewrites) || rewrites.length !== rawCandidates.length) {
+        Logger_1.appLogger.warn(`Advanced selector decision shape mismatch (${rewrites?.length ?? 'none'} vs ${rawCandidates.length}); keeping the generated selector.`);
+        return rawCandidates;
+    }
+    const dataSource = { env: envData, vars: {}, calls: [] };
+    const templatized = rawCandidates.map((raw, index) => {
+        const rewrite = rewrites[index];
+        return typeof rewrite === 'string' &&
+            (0, TemplateInterpolator_1.interpolateString)(rewrite, dataSource) === raw
+            ? rewrite
+            : raw;
+    });
+    return pruneCoincidentalPositional(templatized);
+}
+/**
+ * Once a candidate tracks an env value, drop purely-positional candidates that
+ * don't — for a data-driven action, position is a coincidence of the recorded
+ * data and would mislocate when the value (or order) changes. Returns the input
+ * unchanged when nothing is env-bearing (no semantic anchor to take over) or when
+ * pruning would remove everything. PURE.
+ */
+function pruneCoincidentalPositional(candidates) {
+    if (!candidates.some(isEnvBearingSelector)) {
+        return candidates;
+    }
+    const pruned = candidates.filter((candidate) => isEnvBearingSelector(candidate) || !isPurelyPositionalSelector(candidate));
+    return pruned.length > 0 ? pruned : candidates;
+}
+/** A selector that carries an env reference (so it tracks the value at replay). */
+function isEnvBearingSelector(selector) {
+    return selector.includes('{{$.env.');
+}
+/**
+ * Heuristic for a selector that locates an element *purely by DOM position* — an
+ * `:nth-*` pseudo, an XPath numeric index `[N]`, or a bare combinator chain — with
+ * no meaningful anchor (id, class, attribute, or text predicate). PURE.
+ *
+ * The "meaningful anchor" guard is what keeps a text/attribute selector that also
+ * happens to carry an index (e.g. `(.//a[normalize-space(.)='X'])[2]`) from being
+ * treated as positional.
+ */
+function isPurelyPositionalSelector(selector) {
+    const hasMeaningfulAnchor = /#[\w-]/.test(selector) || // css id (not a bare '#')
+        /\.[a-zA-Z][\w-]*/.test(selector) || // css class (dot + identifier, not xpath './/')
+        /@[a-zA-Z_-]+/.test(selector) || // xpath attribute axis
+        /\[[a-zA-Z][\w-]*\s*[*^$~|]?=/.test(selector) || // css attribute selector
+        /normalize-space|text\(\)|contains\(/.test(selector); // text predicate
+    if (hasMeaningfulAnchor) {
+        return false;
+    }
+    return (/:nth-(child|of-type|last-child|last-of-type)\b/.test(selector) ||
+        /\[\d+\]/.test(selector) ||
+        /[>+~]/.test(selector));
+}
+/**
+ * Synthesize a selector that locates the target by anchoring on env-derived text
+ * in a NEARBY element (e.g. a card's title) — for the case where the target's own
+ * selectors are purely positional. Captures the target's smallest ancestor whose
+ * text contains an env value form, asks the model to write a value-anchored
+ * selector, then validates it against the live (pre-interaction) page: it is
+ * accepted only if, interpolated with the current env values, it uniquely resolves
+ * back to the target element. Returns null when there is nothing to anchor on, the
+ * model declines, or validation fails.
+ */
+async function synthesizeAnchoredSelector(target, context, referencedEnvVars) {
+    const gptClient = context.gptClient;
+    if (!gptClient) {
+        return null;
+    }
+    // Every form (verbatim + transforms) of each referenced value, for locating the
+    // value in the surrounding DOM text.
+    const valueForms = referencedEnvVars.flatMap((name) => {
+        const value = context.envData[name];
+        return value ? (0, TemplateInterpolator_1.envValueForms)(value).map((entry) => entry.form) : [];
+    });
+    if (valueForms.length === 0) {
+        return null;
+    }
+    // Capture the nearest ancestor whose text contains an env value form, with the
+    // target temporarily marked so the model knows which element to anchor to.
+    let neighborhoodHtml = null;
+    try {
+        await target.evaluate((el, marker) => el.setAttribute(marker, ''), SYNTH_TARGET_MARKER);
+        neighborhoodHtml = await target.evaluate((el, forms) => {
+            let node = el.parentElement;
+            while (node) {
+                const text = node.textContent ?? '';
+                if (forms.some((form) => form.length > 0 && text.includes(form))) {
+                    return node.outerHTML;
+                }
+                node = node.parentElement;
+            }
+            return null;
+        }, valueForms);
+    }
+    catch (error) {
+        Logger_1.appLogger.warn('Failed to capture neighborhood for selector synthesis.', error);
+        return null;
+    }
+    finally {
+        await target
+            .evaluate((el, marker) => el.removeAttribute(marker), SYNTH_TARGET_MARKER)
+            .catch(() => undefined);
+    }
+    if (!neighborhoodHtml) {
+        return null; // the value isn't near the target — nothing to anchor on
+    }
+    const html = neighborhoodHtml.length > MAX_NEIGHBORHOOD_HTML
+        ? `${neighborhoodHtml.slice(0, MAX_NEIGHBORHOOD_HTML)}…`
+        : neighborhoodHtml;
+    const envMapping = referencedEnvVars
+        .filter((name) => context.envData[name])
+        .map((name) => `  - {{$.env.${name}}} = ${JSON.stringify(context.envData[name])}`)
+        .join('\n');
+    let synthesized;
+    try {
+        const outcome = await gptClient.getStructuredOutput(buildSynthesisRequest(html, envMapping, SYNTH_TARGET_MARKER), exports.SynthesizedSelectorSchema);
+        MiscUtils_1.MiscUtils.updateTokenCounts(outcome, context.metadata);
+        synthesized = outcome.output.selector;
+    }
+    catch (error) {
+        Logger_1.appLogger.warn('Selector synthesis model call failed.', error);
+        return null;
+    }
+    if (!synthesized || !isEnvBearingSelector(synthesized)) {
+        return null; // model declined, or produced a non-parameterized selector
+    }
+    // Validate against the live page: interpolate with current env values and
+    // confirm the result uniquely resolves to the target element.
+    const interpolated = (0, TemplateInterpolator_1.interpolateString)(synthesized, {
+        env: context.envData,
+        vars: {},
+        calls: [],
+    });
+    const resolvesToTarget = await selectorUniquelyResolvesToTarget(target, interpolated).catch(() => false);
+    if (!resolvesToTarget) {
+        Logger_1.appLogger.warn(`Synthesized selector rejected (did not uniquely resolve to the target): ${synthesized}`);
+        return null;
+    }
+    return synthesized;
+}
+/** True when `selector` resolves to exactly one element and it is `target`. */
+async function selectorUniquelyResolvesToTarget(target, selector) {
+    const frame = await target.ownerFrame();
+    if (!frame) {
+        return false;
+    }
+    const locator = frame.locator(PlaywrightUtils_1.PlaywrightUtils.normalizeSelector(selector));
+    if ((await locator.count()) !== 1) {
+        return false;
+    }
+    return locator
+        .first()
+        .evaluate((element, other) => element === other, target);
+}
+async function deriveFrameSelector(target) {
+    const frame = await target.ownerFrame();
+    // No owning frame, or a top-level frame (no parent) -> no frame selector.
+    if (!frame?.parentFrame()) {
+        return null;
+    }
+    const frameElement = await frame.frameElement();
+    const selectors = await PlaywrightUtils_1.PlaywrightUtils.generateSelectors(frameElement);
+    return selectors[0] ?? null;
+}
+//# sourceMappingURL=AdvancedSelectorGenerator.js.map

package/dist/esm/utils/EnvVarSensitivity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Heuristic for whether an environment variable should be treated as a secret.
+ *
+ * ⚠️ MUST stay in sync with the frontend copy at
+ * `frontend/src/app/settings/environment/page.tsx` (`SENSITIVE_NAME_PATTERNS`,
+ * `SENSITIVE_VALUE_PREFIXES`, `isSensitive`). The two cannot share runtime code:
+ * `donobu` is only a *devDependency* of the frontend, and the settings page is a
+ * browser (`'use client'`) component, so there is no shared runtime module — this
+ * is a deliberate duplicate.
+ *
+ * Why keeping them identical matters: the frontend uses this to mask values in
+ * the settings UI; the backend uses it to decide which values may be shown to the
+ * AI and which must be redacted from AI-visible output. If the two drift, a value
+ * shown masked in the UI could still leak to the AI (or, conversely, a value the
+ * user sees in plaintext could be needlessly withheld). If you change the
+ * patterns here, change them there too.
+ */
+export declare const SENSITIVE_ENV_NAME_PATTERNS: RegExp;
+export declare const SENSITIVE_ENV_VALUE_PREFIXES: string[];
+/**
+ * Returns true when an env var looks sensitive — either its name matches a known
+ * secret-ish pattern or its value carries a known secret token prefix. See the
+ * sync warning above.
+ */
+export declare function isSensitiveEnvVar(name: string, value: string): boolean;
+/**
+ * Redacts the resolved values of *sensitive* env vars from a string the AI will
+ * see (e.g. a tool result that interpolated `{{$.env.X}}` and echoes it back).
+ * Each occurrence of a sensitive value is replaced with a `[redacted:NAME]`
+ * marker, so the agent learns the reference exists but never the secret itself.
+ *
+ * Non-sensitive values are left intact — consistent with their being shown in the
+ * settings UI and usable by the agent. Empty values are skipped to avoid
+ * pathological whole-string matches.
+ */
+export declare function redactSensitiveEnvValues(text: string, envData: Record<string, string>): string;
+//# sourceMappingURL=EnvVarSensitivity.d.ts.map

package/dist/esm/utils/EnvVarSensitivity.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SENSITIVE_ENV_VALUE_PREFIXES = exports.SENSITIVE_ENV_NAME_PATTERNS = void 0;
+exports.isSensitiveEnvVar = isSensitiveEnvVar;
+exports.redactSensitiveEnvValues = redactSensitiveEnvValues;
+/**
+ * Heuristic for whether an environment variable should be treated as a secret.
+ *
+ * ⚠️ MUST stay in sync with the frontend copy at
+ * `frontend/src/app/settings/environment/page.tsx` (`SENSITIVE_NAME_PATTERNS`,
+ * `SENSITIVE_VALUE_PREFIXES`, `isSensitive`). The two cannot share runtime code:
+ * `donobu` is only a *devDependency* of the frontend, and the settings page is a
+ * browser (`'use client'`) component, so there is no shared runtime module — this
+ * is a deliberate duplicate.
+ *
+ * Why keeping them identical matters: the frontend uses this to mask values in
+ * the settings UI; the backend uses it to decide which values may be shown to the
+ * AI and which must be redacted from AI-visible output. If the two drift, a value
+ * shown masked in the UI could still leak to the AI (or, conversely, a value the
+ * user sees in plaintext could be needlessly withheld). If you change the
+ * patterns here, change them there too.
+ */
+exports.SENSITIVE_ENV_NAME_PATTERNS = /KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL/i;
+exports.SENSITIVE_ENV_VALUE_PREFIXES = [
+    'sk-',
+    'ghp_',
+    'gho_',
+    'glpat-',
+    'xoxb-',
+    'xoxp-',
+];
+/**
+ * Returns true when an env var looks sensitive — either its name matches a known
+ * secret-ish pattern or its value carries a known secret token prefix. See the
+ * sync warning above.
+ */
+function isSensitiveEnvVar(name, value) {
+    return (exports.SENSITIVE_ENV_NAME_PATTERNS.test(name) ||
+        exports.SENSITIVE_ENV_VALUE_PREFIXES.some((prefix) => value.startsWith(prefix)));
+}
+/**
+ * Redacts the resolved values of *sensitive* env vars from a string the AI will
+ * see (e.g. a tool result that interpolated `{{$.env.X}}` and echoes it back).
+ * Each occurrence of a sensitive value is replaced with a `[redacted:NAME]`
+ * marker, so the agent learns the reference exists but never the secret itself.
+ *
+ * Non-sensitive values are left intact — consistent with their being shown in the
+ * settings UI and usable by the agent. Empty values are skipped to avoid
+ * pathological whole-string matches.
+ */
+function redactSensitiveEnvValues(text, envData) {
+    let redacted = text;
+    for (const [name, value] of Object.entries(envData)) {
+        // Skip empty values, and values too long to possibly be a substring — a cheap
+        // guard since env values in this system can be very large (up to ~1MB).
+        if (value &&
+            value.length <= redacted.length &&
+            isSensitiveEnvVar(name, value)) {
+            redacted = redacted.split(value).join(`[redacted:${name}]`);
+        }
+    }
+    return redacted;
+}
+//# sourceMappingURL=EnvVarSensitivity.js.map

package/dist/esm/utils/TemplateInterpolator.d.ts

@@ -2,6 +2,56 @@
  * Regular expression to match template JSON-path expressions inside of {{...}}
  */
 export declare const TEMPLATE_DATA_PATTERN: RegExp;
+/**
+ * Allow-listed, pure string transforms usable as `{{ <path> | <filter> }}` in a
+ * template (e.g. `{{$.env.NAV | title}}`). They let a single env value render in
+ * the various forms it takes across a page (a tab text "Contact" vs an href
+ * "/contact" vs a slug "some-tab") while a recorded selector keeps the
+ * placeholder instead of a frozen literal.
+ *
+ * Keep this set SMALL and deterministic: it is the single source of truth used
+ * both at replay (to render a value) and at record time (to recognize that an
+ * on-page literal is a transformed form of an env value). Each is a total
+ * `string -> string` function — no arguments, no side effects.
+ */
+export declare const ENV_VALUE_FILTERS: Record<string, (input: string) => string>;
+/**
+ * Split a template expression into its JSONPath part and any trailing
+ * `| filter | filter` chain. Splits only on top-level `|` — pipes inside
+ * brackets/parens or quotes (e.g. a JSONPath filter `[?(@.x == "a|b")]`) are left
+ * intact. The custom {@link queryJsonPath} dialect never uses `|`, so a top-level
+ * `|` is unambiguously a filter delimiter.
+ */
+export declare function parseFilteredExpression(content: string): {
+    path: string;
+    filters: string[];
+};
+/**
+ * Apply a chain of {@link ENV_VALUE_FILTERS} to a string, left to right. Throws
+ * on an unknown filter name so the caller (interpolation) leaves the original
+ * `{{...}}` placeholder in place rather than silently emitting a wrong value.
+ */
+export declare function applyEnvValueFilters(value: string, filters: string[]): string;
+/**
+ * The distinct forms an env value can take via the allow-listed filters — the
+ * identity form plus each filter applied. Used at record time to recognize that
+ * an on-page literal (e.g. "Contact") is a transformed form of an env value
+ * (e.g. "contact") so the recorded selector can keep `{{$.env.X | title}}`.
+ *
+ * Identity comes first; duplicate forms (a filter that doesn't change the value)
+ * are dropped, preferring the simplest (earliest) producer.
+ */
+export declare function envValueForms(value: string): Array<{
+    filter: string | null;
+    form: string;
+}>;
+/**
+ * Extract the env var NAMES referenced (via `{{$.env.NAME}}`, with or without a
+ * `| filter` suffix) anywhere in a template string. Centralizes the filter-aware
+ * parsing so callers don't re-derive names by naive substring math (which breaks
+ * once an expression carries a filter, e.g. `$.env.NAV | title`).
+ */
+export declare function extractEnvVarReferences(template: string): string[];
 /**
  * Resolve a JSONPath expression against the context
  * @param expression - The JSONPath expression to evaluate