@mercuryo-ai/agentbrowse 0.2.61 → 0.2.63

package/dist/match-resolve-fill.js

@@ -0,0 +1,700 @@
+import { actBrowser } from './commands/act.js';
+import { resolveObservedField, } from './secrets/observed-field-resolution.js';
+const INTERNAL_VALUE_ACCESSOR = Symbol('agentbrowse.internalValueAccessor');
+function hasResolveCapability(resolver) {
+    return (Boolean(resolver) &&
+        typeof resolver.resolve === 'function');
+}
+function hasGroupFillCapability(resolver) {
+    return (Boolean(resolver) &&
+        typeof resolver.fill === 'function');
+}
+function isMatchStore(value) {
+    return Boolean(value) && typeof value === 'object' && 'entries' in value && 'read' in value;
+}
+function isGroupMatchStore(value) {
+    return (Boolean(value) && typeof value === 'object' && 'entries' in value && 'readArtifact' in value);
+}
+function isGroupSubject(subject) {
+    return (subject !== null &&
+        typeof subject === 'object' &&
+        'fillRef' in subject &&
+        'fields' in subject &&
+        Array.isArray(subject.fields));
+}
+function createAccessor(resourcesByRef) {
+    return {
+        read(resourceRef) {
+            return resourcesByRef.get(resourceRef);
+        },
+    };
+}
+function createValueRef(candidateRef, seed) {
+    return `value:${candidateRef}:${seed}:${Math.abs(candidateRef.length)}`;
+}
+function createArtifactRef(candidateRef, seed) {
+    return `artifact:${candidateRef}:${seed}:${Math.abs(candidateRef.length)}`;
+}
+function createResolvedValueRef(candidateRef) {
+    return `value:${candidateRef}:resolved`;
+}
+function createResolvedArtifactRef(candidateRef) {
+    return `artifact:${candidateRef}:resolved`;
+}
+function inferValueType(fieldKey, value) {
+    if (typeof value === 'number') {
+        return 'number';
+    }
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim())) {
+        return 'email';
+    }
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value.trim())) {
+        return 'date';
+    }
+    if (/^https?:\/\//.test(value.trim())) {
+        return 'url';
+    }
+    const normalizedFieldKey = fieldKey.trim().toLowerCase();
+    if (normalizedFieldKey.includes('password') || normalizedFieldKey.includes('pan')) {
+        return 'secret';
+    }
+    if (normalizedFieldKey.includes('email')) {
+        return 'email';
+    }
+    if (normalizedFieldKey.includes('date') ||
+        normalizedFieldKey.includes('birth') ||
+        normalizedFieldKey.includes('dob')) {
+        return 'date';
+    }
+    return 'text';
+}
+function placeholderValueFor(type) {
+    switch (type) {
+        case 'email':
+            return 'agentbrowse@example.com';
+        case 'date':
+            return '2000-01-01';
+        case 'number':
+            return 1;
+        case 'url':
+            return 'https://agentbrowse.example';
+        default:
+            return 'agentbrowse-placeholder';
+    }
+}
+function matchCandidateType(type) {
+    return type === 'secret' ? 'text' : type;
+}
+function normalizeSource(source) {
+    const readyValues = new Map();
+    const candidateRefByValueRef = new Map();
+    const storeSource = isMatchStore(source) ? source : null;
+    const entries = isMatchStore(source)
+        ? [...source.entries()]
+        : Array.isArray(source)
+            ? source.filter((entry) => 'fieldKey' in entry)
+            : Object.entries(source).map(([fieldKey, value]) => ({
+                fieldKey,
+                value,
+            }));
+    const candidates = entries.map((entry, index) => {
+        const candidateRef = entry.candidateRef ?? `candidate:${entry.fieldKey}:${index}`;
+        const resolvedType = entry.type ?? inferValueType(entry.fieldKey, entry.value);
+        const valueRef = entry.value !== undefined || (storeSource !== null && !entry.resolve)
+            ? createValueRef(candidateRef, index)
+            : undefined;
+        if (valueRef && entry.value !== undefined) {
+            readyValues.set(valueRef, {
+                kind: 'value',
+                value: entry.value,
+            });
+        }
+        if (valueRef) {
+            candidateRefByValueRef.set(valueRef, candidateRef);
+        }
+        return {
+            candidateRef,
+            fieldKey: entry.fieldKey,
+            ...(resolvedType ? { type: resolvedType } : {}),
+            ...(entry.label ? { label: entry.label } : {}),
+            ...(entry.semanticTags ? { semanticTags: [...entry.semanticTags] } : {}),
+            ...(entry.applicability ? { applicability: { ...entry.applicability } } : {}),
+            ...(valueRef ? { valueRef } : {}),
+            ...(entry.resolve ? { resolve: { ...entry.resolve } } : {}),
+        };
+    });
+    const storeAccessor = storeSource
+        ? {
+            read(candidateRef) {
+                return storeSource.read(candidateRef);
+            },
+        }
+        : null;
+    return {
+        candidates,
+        accessor: {
+            read(valueRef) {
+                const inlineValue = readyValues.get(valueRef);
+                if (inlineValue !== undefined) {
+                    return inlineValue;
+                }
+                if (!storeAccessor) {
+                    return undefined;
+                }
+                const candidateRef = candidateRefByValueRef.get(valueRef);
+                if (!candidateRef) {
+                    return undefined;
+                }
+                const storedValue = storeAccessor.read(candidateRef);
+                return storedValue === undefined
+                    ? undefined
+                    : {
+                        kind: 'value',
+                        value: storedValue,
+                    };
+            },
+        },
+    };
+}
+function normalizeGroupSource(source) {
+    const readyArtifacts = new Map();
+    const candidateRefByArtifactRef = new Map();
+    const storeSource = isGroupMatchStore(source) ? source : null;
+    const entries = isGroupMatchStore(source)
+        ? source.entries()
+        : Array.isArray(source)
+            ? source.filter((entry) => 'fieldKeys' in entry)
+            : [];
+    const candidates = entries.map((entry, index) => {
+        const candidateRef = entry.candidateRef ?? `group-candidate:${index}`;
+        const artifactRef = entry.artifact !== undefined || (storeSource !== null && !entry.resolve)
+            ? createArtifactRef(candidateRef, index)
+            : undefined;
+        if (artifactRef && entry.artifact !== undefined) {
+            readyArtifacts.set(artifactRef, {
+                kind: 'artifact',
+                artifact: entry.artifact,
+                ...(entry.itemRef ? { itemRef: entry.itemRef } : {}),
+            });
+        }
+        if (artifactRef) {
+            candidateRefByArtifactRef.set(artifactRef, candidateRef);
+        }
+        return {
+            candidateRef,
+            ...(entry.itemRef ? { itemRef: entry.itemRef } : {}),
+            ...(entry.label ? { label: entry.label } : {}),
+            fieldKeys: [...entry.fieldKeys],
+            ...(entry.confidence ? { confidence: entry.confidence } : {}),
+            ...(entry.applicability ? { applicability: { ...entry.applicability } } : {}),
+            ...(artifactRef ? { artifactRef } : {}),
+            ...(entry.resolve ? { resolve: { ...entry.resolve } } : {}),
+            sortIndex: index,
+        };
+    });
+    return {
+        candidates,
+        accessor: {
+            read(artifactRef) {
+                const inlineArtifact = readyArtifacts.get(artifactRef);
+                if (inlineArtifact !== undefined) {
+                    return inlineArtifact;
+                }
+                if (!storeSource) {
+                    return undefined;
+                }
+                const candidateRef = candidateRefByArtifactRef.get(artifactRef);
+                if (!candidateRef) {
+                    return undefined;
+                }
+                const storedArtifact = storeSource.readArtifact(candidateRef);
+                return storedArtifact === undefined
+                    ? undefined
+                    : {
+                        kind: 'artifact',
+                        artifact: storedArtifact,
+                    };
+            },
+        },
+    };
+}
+function toObservedFieldCandidates(candidates, accessor) {
+    return candidates.map((candidate) => {
+        const matchingType = matchCandidateType(candidate.type);
+        const resource = candidate.valueRef !== undefined ? accessor.read(candidate.valueRef) : undefined;
+        const value = resource?.kind === 'value' ? resource.value : placeholderValueFor(matchingType);
+        return {
+            candidateRef: candidate.candidateRef,
+            fieldKey: candidate.fieldKey,
+            value,
+            source: 'profile_facts',
+            ...(matchingType ? { type: matchingType } : {}),
+            ...(candidate.label ? { label: candidate.label } : {}),
+            ...(candidate.semanticTags ? { semanticTags: [...candidate.semanticTags] } : {}),
+            ...(candidate.applicability ? { applicability: { ...candidate.applicability } } : {}),
+        };
+    });
+}
+function normalizeTarget(target) {
+    const availability = typeof target.availability === 'string'
+        ? { state: target.availability }
+        : (target.availability ?? { state: 'available' });
+    return {
+        ref: target.ref,
+        pageRef: target.pageRef ?? 'p0',
+        kind: target.kind ?? 'input',
+        label: target.label,
+        displayLabel: target.displayLabel,
+        placeholder: target.placeholder,
+        inputName: target.inputName,
+        inputType: target.inputType,
+        autocomplete: target.autocomplete,
+        selection: target.selection,
+        capability: target.capability ?? 'actionable',
+        lifecycle: target.lifecycle ?? 'live',
+        availability,
+        allowedActions: target.allowedActions ?? ['fill', 'type', 'select'],
+        locatorCandidates: [],
+        createdAt: 0,
+        ...(target.context && typeof target.context === 'object' ? { context: target.context } : {}),
+        ...(target.structure ? { structure: target.structure } : {}),
+    };
+}
+function attachAccessor(result, accessor) {
+    Object.defineProperty(result, INTERNAL_VALUE_ACCESSOR, {
+        value: accessor,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return result;
+}
+function missingValueFailure(targetRef) {
+    return {
+        success: false,
+        failureSurface: 'contract',
+        error: 'match_value_unavailable',
+        outcomeType: 'blocked',
+        message: 'The matched value is no longer available for deterministic fill.',
+        reason: 'AgentBrowse could not dereference the internal value ref for the selected match.',
+        targetRef,
+        action: 'fill',
+    };
+}
+function missingArtifactFailure(fillRef) {
+    return {
+        success: false,
+        failureSurface: 'contract',
+        error: 'match_artifact_unavailable',
+        outcomeType: 'blocked',
+        message: 'The matched artifact is no longer available for deterministic protected fill.',
+        reason: 'AgentBrowse could not dereference the internal artifact ref for the selected match.',
+        fillRef,
+        action: 'fill',
+    };
+}
+function groupedResolverRequiredFailure(fillRef) {
+    return {
+        success: false,
+        failureSurface: 'contract',
+        error: 'match_resolver_required',
+        outcomeType: 'unsupported',
+        message: 'This grouped match needs a resolver that can apply the resolved artifact before AgentBrowse can fill the form.',
+        reason: 'The selected match resolves to a grouped protected artifact, not a direct field value.',
+        fillRef,
+        action: 'fill',
+    };
+}
+function applicabilityMatches(applicability, host) {
+    if (!applicability || applicability.target === 'global') {
+        return true;
+    }
+    if (!host || !applicability.value) {
+        return false;
+    }
+    return applicability.value.trim().toLowerCase() === host.trim().toLowerCase();
+}
+function confidenceRank(confidence) {
+    if (confidence === 'high') {
+        return 2;
+    }
+    if (confidence === 'medium') {
+        return 1;
+    }
+    return 0;
+}
+function compareGroupCandidates(left, right) {
+    const overlapDelta = right.overlapCount - left.overlapCount;
+    if (overlapDelta !== 0) {
+        return overlapDelta;
+    }
+    const confidenceDelta = confidenceRank(right.confidence) - confidenceRank(left.confidence);
+    if (confidenceDelta !== 0) {
+        return confidenceDelta;
+    }
+    const labelDelta = (left.label ?? '').localeCompare(right.label ?? '');
+    if (labelDelta !== 0) {
+        return labelDelta;
+    }
+    const sortIndexDelta = left.sortIndex - right.sortIndex;
+    if (sortIndexDelta !== 0) {
+        return sortIndexDelta;
+    }
+    return left.candidateRef.localeCompare(right.candidateRef);
+}
+function matchGroup(subject, options) {
+    const { candidates, accessor } = normalizeGroupSource(options.from);
+    if (candidates.length === 0) {
+        return {
+            kind: 'no_match_group',
+            fillRef: subject.fillRef,
+            reason: 'no_candidate',
+        };
+    }
+    const scopeEligible = candidates.filter((candidate) => applicabilityMatches(candidate.applicability, options.host));
+    if (scopeEligible.length === 0) {
+        return {
+            kind: 'no_match_group',
+            fillRef: subject.fillRef,
+            reason: 'scope_ineligible',
+        };
+    }
+    const fieldKeys = subject.fields.map((field) => field.fieldKey);
+    const fieldKeySet = new Set(fieldKeys);
+    const ranked = scopeEligible
+        .map((candidate) => ({
+        ...candidate,
+        overlapCount: candidate.fieldKeys.filter((fieldKey) => fieldKeySet.has(fieldKey)).length,
+    }))
+        .filter((candidate) => candidate.overlapCount > 0)
+        .sort(compareGroupCandidates);
+    const selected = ranked[0];
+    if (!selected) {
+        return {
+            kind: 'no_match_group',
+            fillRef: subject.fillRef,
+            reason: 'incompatible_shape',
+        };
+    }
+    const confidence = selected.overlapCount === fieldKeySet.size ? 'high' : 'medium';
+    const ambiguousCandidates = ranked.filter((candidate) => candidate.overlapCount === selected.overlapCount &&
+        confidenceRank(candidate.confidence) === confidenceRank(selected.confidence));
+    if (ambiguousCandidates.length > 1) {
+        return {
+            kind: 'ambiguous_group',
+            fillRef: subject.fillRef,
+            candidates: ambiguousCandidates.map((candidate) => candidate.candidateRef),
+        };
+    }
+    if (selected.resolve) {
+        return {
+            kind: 'needs_resolution_group',
+            fillRef: subject.fillRef,
+            purpose: subject.purpose,
+            candidateRef: selected.candidateRef,
+            ...(selected.itemRef ? { itemRef: selected.itemRef } : {}),
+            fieldKeys,
+            confidence,
+            plan: {
+                fillRef: subject.fillRef,
+                pageRef: subject.pageRef,
+                ...(subject.scopeRef ? { scopeRef: subject.scopeRef } : {}),
+                purpose: subject.purpose,
+                candidateRef: selected.candidateRef,
+                ...(selected.itemRef ? { itemRef: selected.itemRef } : {}),
+                fieldKeys,
+                resolve: { ...selected.resolve },
+            },
+        };
+    }
+    if (!selected.artifactRef) {
+        return {
+            kind: 'no_match_group',
+            fillRef: subject.fillRef,
+            reason: 'no_candidate',
+        };
+    }
+    return attachAccessor({
+        kind: 'ready_group',
+        fillRef: subject.fillRef,
+        purpose: subject.purpose,
+        candidateRef: selected.candidateRef,
+        ...(selected.itemRef ? { itemRef: selected.itemRef } : {}),
+        fieldKeys,
+        artifactRef: selected.artifactRef,
+        confidence,
+    }, accessor);
+}
+export async function match(subject, options) {
+    if (isGroupSubject(subject)) {
+        return matchGroup(subject, options);
+    }
+    const normalizedTarget = normalizeTarget(subject);
+    const { candidates, accessor } = normalizeSource(options.from);
+    const resolution = resolveObservedField(normalizedTarget, toObservedFieldCandidates(candidates, accessor), {
+        host: options.host,
+        protectedTargetRefs: options.protectedTargetRefs,
+    });
+    if (resolution.status === 'ambiguous') {
+        return {
+            kind: 'ambiguous',
+            targetRef: resolution.targetRef,
+            candidates: resolution.candidates,
+        };
+    }
+    if (resolution.status === 'no_match') {
+        return {
+            kind: 'no_match',
+            targetRef: resolution.targetRef,
+            reason: resolution.reason,
+        };
+    }
+    const selected = candidates.find((candidate) => candidate.candidateRef === resolution.candidateRef);
+    if (!selected) {
+        return {
+            kind: 'no_match',
+            targetRef: resolution.targetRef,
+            reason: 'no_candidate',
+        };
+    }
+    const confidence = resolution.confidence;
+    if (selected.resolve) {
+        return {
+            kind: 'needs_resolution',
+            targetRef: resolution.targetRef,
+            fieldKey: resolution.fieldKey,
+            candidateRef: selected.candidateRef,
+            confidence,
+            plan: {
+                targetRef: resolution.targetRef,
+                candidateRef: selected.candidateRef,
+                fieldKey: resolution.fieldKey,
+                ...(selected.type ? { type: selected.type } : {}),
+                resolve: { ...selected.resolve },
+            },
+        };
+    }
+    if (!selected.valueRef) {
+        return {
+            kind: 'no_match',
+            targetRef: resolution.targetRef,
+            reason: 'no_candidate',
+        };
+    }
+    return attachAccessor({
+        kind: 'ready',
+        targetRef: resolution.targetRef,
+        fieldKey: resolution.fieldKey,
+        candidateRef: selected.candidateRef,
+        valueRef: selected.valueRef,
+        confidence,
+    }, accessor);
+}
+function resolveSingleResolvedMatch(plan, resolved) {
+    if (plan.kind === 'needs_resolution') {
+        if (resolved.kind !== 'value') {
+            throw new Error('AgentBrowse resolver returned an artifact for a field resolution plan.');
+        }
+        const valueRef = createResolvedValueRef(plan.candidateRef);
+        const accessor = createAccessor(new Map([[valueRef, resolved]]));
+        return attachAccessor({
+            kind: 'ready',
+            targetRef: plan.targetRef,
+            fieldKey: plan.fieldKey,
+            candidateRef: plan.candidateRef,
+            valueRef,
+            confidence: plan.confidence,
+        }, accessor);
+    }
+    if (resolved.kind !== 'artifact') {
+        throw new Error('AgentBrowse resolver returned a field value for a grouped resolution plan.');
+    }
+    const artifactRef = createResolvedArtifactRef(plan.candidateRef);
+    const accessor = createAccessor(new Map([[artifactRef, resolved]]));
+    return attachAccessor({
+        kind: 'ready_group',
+        fillRef: plan.fillRef,
+        purpose: plan.purpose,
+        candidateRef: plan.candidateRef,
+        ...(plan.itemRef ? { itemRef: plan.itemRef } : {}),
+        fieldKeys: [...plan.fieldKeys],
+        artifactRef,
+        confidence: plan.confidence,
+        ...(resolved.requestId ? { requestId: resolved.requestId } : {}),
+        ...(resolved.resolutionPath ? { resolutionPath: resolved.resolutionPath } : {}),
+        ...(resolved.claimedAt ? { claimedAt: resolved.claimedAt } : {}),
+    }, accessor);
+}
+export async function resolve(plan, options) {
+    if (!Array.isArray(plan)) {
+        const singlePlan = plan;
+        if (singlePlan.kind !== 'needs_resolution' && singlePlan.kind !== 'needs_resolution_group') {
+            return singlePlan;
+        }
+        if (!options.with.resolve) {
+            throw new Error('AgentBrowse resolve(...) was called with a plan that needs resolution, but the adapter does not implement `resolve`.');
+        }
+        const resolved = await options.with.resolve(singlePlan.plan);
+        return resolveSingleResolvedMatch(singlePlan, resolved);
+    }
+    const unresolvedEntries = plan
+        .map((entry, index) => ({ entry, index }))
+        .filter((item) => item.entry.kind === 'needs_resolution' || item.entry.kind === 'needs_resolution_group');
+    if (unresolvedEntries.length === 0) {
+        return [...plan];
+    }
+    const unresolvedPlans = unresolvedEntries.map(({ entry }) => entry.plan);
+    const singleResolve = options.with.resolve;
+    if (unresolvedPlans.length > 0 && !options.with.resolveBatch && !singleResolve) {
+        throw new Error('AgentBrowse resolve(...) received plans that need resolution, but the adapter does not implement `resolve` or `resolveBatch`.');
+    }
+    const resolvedResources = unresolvedPlans.length > 1 && options.with.resolveBatch
+        ? await options.with.resolveBatch(unresolvedPlans)
+        : await Promise.all(unresolvedPlans.map((entry) => singleResolve(entry)));
+    if (resolvedResources.length !== unresolvedEntries.length) {
+        throw new Error('AgentBrowse resolver returned an unexpected batch result length.');
+    }
+    const next = [...plan];
+    unresolvedEntries.forEach(({ entry, index }, resolvedIndex) => {
+        next[index] = resolveSingleResolvedMatch(entry, resolvedResources[resolvedIndex]);
+    });
+    return next;
+}
+export async function fill(session, subject, plan, options = {}) {
+    if (isGroupSubject(subject)) {
+        if (plan.kind === 'no_match_group') {
+            return {
+                success: false,
+                failureSurface: 'contract',
+                error: 'match_no_match',
+                outcomeType: 'blocked',
+                message: 'AgentBrowse could not find a deterministic grouped plan for this form.',
+                reason: plan.reason,
+                fillRef: subject.fillRef,
+                action: 'fill',
+            };
+        }
+        if (plan.kind === 'ambiguous_group') {
+            return {
+                success: false,
+                failureSurface: 'contract',
+                error: 'match_ambiguous',
+                outcomeType: 'blocked',
+                message: 'AgentBrowse found several competing grouped candidates for this form.',
+                reason: `Competing candidate refs: ${plan.candidates.join(', ')}`,
+                fillRef: subject.fillRef,
+                action: 'fill',
+            };
+        }
+        if (plan.kind === 'needs_resolution_group') {
+            if (!hasResolveCapability(options.resolver)) {
+                return {
+                    success: false,
+                    failureSurface: 'contract',
+                    error: 'match_resolver_required',
+                    outcomeType: 'unsupported',
+                    message: 'This grouped match needs an explicit resolver before AgentBrowse can fill the form.',
+                    reason: 'The selected grouped candidate does not carry a ready artifact ref.',
+                    fillRef: subject.fillRef,
+                    action: 'fill',
+                };
+            }
+            const [resolved] = (await resolve([plan], {
+                with: options.resolver,
+            }));
+            return fill(session, subject, resolved, options);
+        }
+        if (plan.kind === 'ready_group') {
+            if (!hasGroupFillCapability(options.resolver)) {
+                return groupedResolverRequiredFailure(subject.fillRef);
+            }
+            const accessor = plan[INTERNAL_VALUE_ACCESSOR];
+            const resolvedArtifact = accessor?.read(plan.artifactRef);
+            if (resolvedArtifact?.kind !== 'artifact') {
+                return missingArtifactFailure(subject.fillRef);
+            }
+            return options.resolver.fill(session, subject, {
+                candidateRef: plan.candidateRef,
+                itemRef: plan.itemRef ?? resolvedArtifact.itemRef,
+                fieldKeys: [...plan.fieldKeys],
+                artifact: resolvedArtifact.artifact,
+                requestId: plan.requestId ?? resolvedArtifact.requestId,
+                resolutionPath: plan.resolutionPath ?? resolvedArtifact.resolutionPath,
+                claimedAt: plan.claimedAt ?? resolvedArtifact.claimedAt,
+            });
+        }
+        return {
+            success: false,
+            failureSurface: 'contract',
+            error: 'match_no_match',
+            outcomeType: 'blocked',
+            message: 'The provided match result belongs to an individual field, not a grouped form.',
+            reason: 'AgentBrowse received a field-level match result for a grouped protected fill subject.',
+            fillRef: subject.fillRef,
+            action: 'fill',
+        };
+    }
+    if (plan.kind === 'no_match') {
+        return {
+            success: false,
+            failureSurface: 'contract',
+            error: 'match_no_match',
+            outcomeType: 'blocked',
+            message: 'AgentBrowse could not find a deterministic value for this target.',
+            reason: plan.reason,
+            targetRef: subject.ref,
+            action: 'fill',
+        };
+    }
+    if (plan.kind === 'no_match_group' ||
+        plan.kind === 'ambiguous_group' ||
+        plan.kind === 'needs_resolution_group' ||
+        plan.kind === 'ready_group') {
+        return {
+            success: false,
+            failureSurface: 'contract',
+            error: 'match_no_match',
+            outcomeType: 'blocked',
+            message: 'The provided match result belongs to a grouped form, not an individual field target.',
+            reason: 'AgentBrowse received a grouped match result for a single-target fill subject.',
+            targetRef: subject.ref,
+            action: 'fill',
+        };
+    }
+    if (plan.kind === 'ambiguous') {
+        return {
+            success: false,
+            failureSurface: 'contract',
+            error: 'match_ambiguous',
+            outcomeType: 'blocked',
+            message: 'AgentBrowse found several competing values for this target.',
+            reason: `Competing candidate refs: ${plan.candidates.join(', ')}`,
+            targetRef: subject.ref,
+            action: 'fill',
+        };
+    }
+    if (plan.kind === 'needs_resolution') {
+        if (!hasResolveCapability(options.resolver)) {
+            return {
+                success: false,
+                failureSurface: 'contract',
+                error: 'match_resolver_required',
+                outcomeType: 'unsupported',
+                message: 'This match needs an explicit resolver before AgentBrowse can fill the target.',
+                reason: 'The selected candidate does not carry a ready value ref.',
+                targetRef: subject.ref,
+                action: 'fill',
+            };
+        }
+        return fill(session, subject, await resolve(plan, { with: options.resolver }), options);
+    }
+    const accessor = plan[INTERNAL_VALUE_ACCESSOR];
+    const resolvedValue = accessor?.read(plan.valueRef);
+    if (resolvedValue?.kind !== 'value') {
+        return missingValueFailure(subject.ref);
+    }
+    return actBrowser(session, subject.ref, 'fill', String(resolvedValue.value));
+}