@nuanu-ai/agentbrowse 0.2.46 → 0.2.48

package/dist/commands/fill-secret.js

@@ -1,39 +1,45 @@
 /**
- * browse fill-secret <fillRef> <intentId> — Fill protected fields from a cached one-time secret payload
- * using the persisted plan and deterministic browser execution.
+ * browse fill-secret <fillRef> <requestId> — Claim an already approved secret request and fill
+ * protected fields using deterministic browser execution.
  */
 import { outputFailure, outputJSON } from '../output.js';
-import { getFillableForm, getSecretIntentSnapshot, saveProtectedExposure, saveSecretIntentSnapshot, } from '../runtime-state.js';
-import { deleteCachedTransientSecret, getCachedTransientSecret, saveSession } from '../session.js';
+import { getFillableForm, getSecretRequestSnapshot, saveProtectedExposure, saveSecretRequestSnapshot, } from '../runtime-protected-state.js';
 import { connectPlaywright, disconnectPlaywright, resolvePageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { finishRunStep, startRunStep } from '../run-store.js';
+import { exportRunStepToOtlpHttpJsonBestEffort } from '../otel-exporter.js';
+import { appendCommandLifecycleEventBestEffort, captureStepSnapshotBestEffort, } from '../run-observability.js';
+import { saveSession } from '../session.js';
 import { tryResolveCatalogHost } from '../secrets/catalog-sync.js';
-import { describeSecretIntentStatus, serializeSecretIntentContext, } from '../secrets/intent-output.js';
+import { describeSecretRequestStatus, serializeSecretRequestContext, } from '../secrets/request-output.js';
 import { executeProtectedFill } from '../secrets/protected-fill.js';
-function persistIntentSnapshot(session, snapshot) {
-    const persisted = saveSecretIntentSnapshot(session, snapshot);
+import { getSecretBackend } from '../secrets/backend.js';
+import { AgentpayRequestError } from '../sessions-backend.js';
+function persistRequestSnapshot(session, snapshot) {
+    const persisted = saveSecretRequestSnapshot(session, snapshot);
     saveSession(session);
     return persisted;
 }
-function completeIntent(session, intentId) {
-    const current = getSecretIntentSnapshot(session, intentId);
+function markRequestClaimed(session, requestId, claimedAt) {
+    const current = getSecretRequestSnapshot(session, requestId);
     if (!current) {
-        throw new Error('secret_intent_not_found');
+        throw new Error('secret_request_not_found');
     }
-    if (current.status === 'completed') {
-        return current;
+    if (session.currentRequestId === requestId) {
+        session.currentRequestId = undefined;
+        session.lastKnownStatus = 'in_progress';
     }
-    return persistIntentSnapshot(session, {
+    return persistRequestSnapshot(session, {
         ...current,
-        status: 'completed',
-        completedAt: new Date().toISOString(),
+        claimedAt,
+        updatedAt: claimedAt,
     });
 }
-function activateProtectedExposure(session, fillableForm, intentId, reason) {
+function activateProtectedExposure(session, fillableForm, requestId, reason) {
     saveProtectedExposure(session, {
         pageRef: fillableForm.pageRef,
         scopeRef: fillableForm.scopeRef,
         fillRef: fillableForm.fillRef,
-        intentId,
+        requestId: requestId,
         activatedAt: new Date().toISOString(),
         reason,
     });
@@ -53,319 +59,498 @@ function restrictFormToCandidateFields(fillableForm, storedSecretCandidate) {
         fields: filteredFields,
     };
 }
-function nextActionForNonApprovedIntent(status) {
-    switch (status) {
-        case 'pending':
-        case 'checking':
-        case 'notify':
-        case 'confirmation':
-            return 'wait-for-approval';
-        case 'denied':
-            return 'ask-user';
-        case 'timed_out':
-        case 'completed':
-            return 'ask-user';
-        default:
-            return 'ask-user';
-    }
+function withFillableFormPresence(fillableForm, payload) {
+    return {
+        ...payload,
+        fillableFormPresence: fillableForm.presence ?? 'present',
+    };
 }
-function messageForNonApprovedIntent(status) {
-    switch (status) {
-        case 'pending':
-        case 'checking':
-        case 'notify':
-        case 'confirmation':
-            return 'Protected fill is waiting for user approval in AgentPay Cabinet.';
-        case 'denied':
-            return 'Protected fill is blocked because the user denied this intent in AgentPay Cabinet.';
-        case 'timed_out':
-        case 'completed':
-            return 'Protected fill requires a new intent because this intent is no longer usable.';
-        default:
-            return 'Protected fill cannot continue because the intent is not approved.';
+function finalizeFillSecretStepBestEffort(runId, stepId, options) {
+    if (!runId || !stepId) {
+        return;
     }
+    try {
+        finishRunStep({
+            runId,
+            stepId,
+            ...options,
+        });
+    }
+    catch {
+    }
+}
+async function emitFillSecretFailure(session, runId, stepId, payload, options = {}) {
+    const step = runId && stepId ? { runId, stepId, command: 'fill-secret' } : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step,
+        phase: 'point-in-time',
+        pageRef: options.pageRef ?? session.runtime?.currentPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step,
+        phase: 'failed',
+        attributes: {
+            outcomeType: typeof payload.outcomeType === 'string' ? payload.outcomeType : payload.error,
+            pageRef: options.pageRef,
+            fillRef: options.fillRef,
+            requestId: options.requestId,
+            reason: typeof payload.reason === 'string' ? payload.reason : payload.error,
+        },
+    });
+    finalizeFillSecretStepBestEffort(runId, stepId, {
+        success: false,
+        outcomeType: typeof payload.outcomeType === 'string' ? payload.outcomeType : payload.error,
+        message: typeof payload.message === 'string' ? payload.message : payload.error,
+        reason: typeof payload.reason === 'string' ? payload.reason : payload.error,
+    });
+    await exportRunStepToOtlpHttpJsonBestEffort(runId, stepId);
+    return outputFailure(payload);
 }
-function outcomeTypeForNonApprovedIntent(status) {
-    return describeSecretIntentStatus(status).outcomeType;
+async function emitFillSecretSuccess(session, runId, stepId, payload, options = {}) {
+    const step = runId && stepId ? { runId, stepId, command: 'fill-secret' } : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step,
+        phase: 'after',
+        pageRef: options.pageRef ?? session.runtime?.currentPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step,
+        phase: 'completed',
+        attributes: {
+            outcomeType: typeof payload.outcomeType === 'string' ? payload.outcomeType : 'protected_fill_completed',
+            pageRef: options.pageRef,
+            fillRef: options.fillRef,
+            requestId: options.requestId,
+        },
+    });
+    finalizeFillSecretStepBestEffort(runId, stepId, {
+        success: true,
+        outcomeType: typeof payload.outcomeType === 'string' ? payload.outcomeType : 'protected_fill_completed',
+        message: typeof payload.message === 'string' ? payload.message : 'Protected fill completed.',
+        reason: typeof payload.reason === 'string' ? payload.reason : undefined,
+    });
+    await exportRunStepToOtlpHttpJsonBestEffort(runId, stepId);
+    return outputJSON(payload);
+}
+function parseClaimFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('not approved yet') ||
+        message.includes('secret_request_not_fulfilled') ||
+        message.includes('does not have resolved secret values yet')) {
+        return 'not_fulfilled';
+    }
+    if (message.includes('already claimed') || message.includes('secret_request_already_claimed')) {
+        return 'already_claimed';
+    }
+    return 'other';
 }
-function reasonForNonApprovedIntent(status) {
-    return describeSecretIntentStatus(status).reason;
+function failureForUnfulfilledRequest(fillableForm, request, fillRef, requestId) {
+    const statusContract = describeSecretRequestStatus(request.status, request.requestType);
+    return withFillableFormPresence(fillableForm, {
+        error: 'secret_request_not_ready',
+        ...(statusContract.outcomeType ? { outcomeType: statusContract.outcomeType } : {}),
+        message: request.status === 'pending'
+            ? 'Protected fill is waiting for user approval in AgentPay.'
+            : statusContract.message,
+        reason: statusContract.reason,
+        fillRef,
+        requestId,
+        ...serializeSecretRequestContext(request),
+        requestStatus: request.status,
+        nextAction: statusContract.nextAction ?? 'poll-secret',
+    });
 }
-export async function fillSecret(session, fillRef, intentId) {
+export async function fillSecret(session, fillRef, requestId) {
+    const fillSecretStep = session.activeRunId
+        ? startRunStep({
+            runId: session.activeRunId,
+            command: 'fill-secret',
+            refs: {
+                fillRef,
+                requestId,
+            },
+            protectedStep: true,
+        })
+        : null;
+    const fillSecretStepHandle = session.activeRunId && fillSecretStep?.stepId
+        ? {
+            runId: session.activeRunId,
+            stepId: fillSecretStep.stepId,
+            command: 'fill-secret',
+        }
+        : null;
+    captureStepSnapshotBestEffort({
+        session,
+        step: fillSecretStepHandle,
+        phase: 'before',
+        pageRef: session.runtime?.currentPageRef,
+    });
+    appendCommandLifecycleEventBestEffort({
+        step: fillSecretStepHandle,
+        phase: 'started',
+        attributes: {
+            fillRef,
+            requestId,
+            pageRef: session.runtime?.currentPageRef,
+        },
+    });
+    if (!session.intentSessionId) {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, {
+            error: 'workflow_session_unavailable',
+            outcomeType: 'blocked',
+            message: 'Protected fill was not started because no active workflow session is bound to this browser.',
+            reason: 'Run start-session first so AgentBrowse has a workflow session for secret requests.',
+            fillRef,
+            requestId,
+        }, {
+            fillRef,
+            requestId,
+        });
+    }
     const fillableForm = getFillableForm(session, fillRef);
     if (!fillableForm) {
-        return outputFailure({
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, {
             error: 'unknown_fill_ref',
             outcomeType: 'blocked',
             message: 'Protected fill was not started because the requested fill reference is unknown.',
             reason: 'The provided fillRef does not match any currently observed protected fill target.',
             fillRef,
-            intentId,
+            requestId,
+        }, {
+            fillRef,
+            requestId,
         });
     }
-    const intent = getSecretIntentSnapshot(session, intentId);
-    if (!intent) {
-        return outputFailure({
-            error: 'secret_intent_not_found',
+    if (fillableForm.presence === 'absent') {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, withFillableFormPresence(fillableForm, {
+            error: 'fillable_form_absent',
             outcomeType: 'blocked',
-            message: 'Protected fill was not started because the requested intent does not exist.',
-            reason: 'The provided intentId was not found in AgentPay Cabinet.',
+            message: 'Protected fill was not started because the requested fill target is no longer present on the page.',
+            reason: 'AgentBrowse already observed this protected fill target as absent, so a new observe pass is required before protected fill can continue.',
+            fillRef,
+            requestId,
+        }), {
+            pageRef: fillableForm.pageRef,
             fillRef,
-            intentId,
+            requestId,
         });
     }
-    const latestIntent = persistIntentSnapshot(session, intent);
-    if (latestIntent.fillRef !== fillRef) {
-        return outputFailure({
-            error: 'secret_intent_fill_mismatch',
+    const request = getSecretRequestSnapshot(session, requestId);
+    if (!request) {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, {
+            error: 'secret_request_not_found',
             outcomeType: 'blocked',
-            message: 'Protected fill was blocked because the approved intent belongs to a different fill target.',
-            reason: `The approved intent belongs to fillRef ${latestIntent.fillRef}, not ${fillRef}.`,
+            message: 'Protected fill was not started because the requested secret request does not exist.',
+            reason: 'Run request-secret and poll-secret first so AgentBrowse has the latest request state.',
             fillRef,
-            intentId,
-            ...serializeSecretIntentContext(latestIntent),
-            intentFillRef: latestIntent.fillRef,
-            intentStatus: latestIntent.status,
-            nextAction: 'reobserve',
-        });
-    }
-    if (!(latestIntent.status === 'approved' || latestIntent.status === 'completed')) {
-        return outputFailure({
-            error: 'secret_intent_not_approved',
-            ...(outcomeTypeForNonApprovedIntent(latestIntent.status)
-                ? { outcomeType: outcomeTypeForNonApprovedIntent(latestIntent.status) }
-                : {}),
-            message: messageForNonApprovedIntent(latestIntent.status),
-            reason: reasonForNonApprovedIntent(latestIntent.status),
+            requestId,
+        }, {
+            pageRef: fillableForm.pageRef,
             fillRef,
-            intentId,
-            ...serializeSecretIntentContext(latestIntent),
-            intentStatus: latestIntent.status,
-            nextAction: nextActionForNonApprovedIntent(latestIntent.status),
+            requestId,
         });
     }
-    const cachedSecret = getCachedTransientSecret(session, intentId);
-    if (!cachedSecret) {
-        const missingCacheReason = latestIntent.status === 'completed'
-            ? 'This one-time intent has already delivered its protected payload, but the current session no longer has it cached.'
-            : 'Run poll-intent after approval so AgentBrowse can cache the transient protected values before fill-secret.';
-        const missingCacheNextAction = latestIntent.status === 'completed' ? 'ask-user' : 'poll-intent';
-        const missingCacheMessage = latestIntent.status === 'completed'
-            ? 'Protected fill could not continue because the one-time secret payload is no longer cached in the current session.'
-            : 'Protected fill could not continue because the approved secret payload is not cached in the current session.';
-        return outputFailure({
-            error: 'transient_secret_not_cached',
+    const latestRequest = persistRequestSnapshot(session, request);
+    if (latestRequest.fillRef !== fillRef) {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, withFillableFormPresence(fillableForm, {
+            error: 'secret_request_fill_mismatch',
             outcomeType: 'blocked',
-            message: missingCacheMessage,
-            reason: missingCacheReason,
+            message: 'Protected fill was blocked because the approved secret request belongs to a different fill target.',
+            reason: `The approved request belongs to fillRef ${latestRequest.fillRef}, not ${fillRef}.`,
+            fillRef,
+            requestId,
+            ...serializeSecretRequestContext(latestRequest),
+            requestFillRef: latestRequest.fillRef,
+            requestStatus: latestRequest.status,
+            nextAction: 'reobserve',
+        }), {
+            pageRef: fillableForm.pageRef,
             fillRef,
-            intentId,
-            ...serializeSecretIntentContext(latestIntent),
-            intentStatus: latestIntent.status,
-            nextAction: missingCacheNextAction,
+            requestId,
         });
     }
-    if (cachedSecret.fillRef !== fillRef ||
-        cachedSecret.storedSecretRef !== latestIntent.storedSecretRef) {
-        deleteCachedTransientSecret(session, intentId);
-        saveSession(session);
-        return outputFailure({
-            error: 'transient_secret_context_mismatch',
+    if (latestRequest.claimedAt) {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, withFillableFormPresence(fillableForm, {
+            error: 'secret_request_already_claimed',
             outcomeType: 'blocked',
-            message: 'Protected fill was blocked because the cached transient secret no longer matches this approved intent.',
-            reason: 'The cached transient payload belongs to a different fill target or stored secret reference.',
+            message: 'Protected fill could not continue because this one-time secret request was already claimed earlier.',
+            reason: 'Secret values can only be claimed once for this request, so AgentBrowse needs a new request before it can fill again.',
+            fillRef,
+            requestId,
+            ...serializeSecretRequestContext(latestRequest),
+            requestStatus: latestRequest.status,
+            nextAction: 'request-secret',
+        }), {
+            pageRef: fillableForm.pageRef,
             fillRef,
-            intentId,
-            ...serializeSecretIntentContext(latestIntent),
-            intentStatus: latestIntent.status,
-            nextAction: 'poll-intent',
+            requestId,
         });
     }
-    let browser = null;
-    try {
-        browser = await connectPlaywright(session.cdpUrl);
-    }
-    catch (error) {
-        deleteCachedTransientSecret(session, intentId);
-        saveSession(session);
-        return outputFailure({
-            error: 'browser_connection_failed',
-            message: 'Protected fill could not connect to the browser.',
+    if (latestRequest.status !== 'fulfilled') {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, failureForUnfulfilledRequest(fillableForm, latestRequest, fillRef, requestId), {
+            pageRef: fillableForm.pageRef,
             fillRef,
-            intentId,
-            ...serializeSecretIntentContext(latestIntent),
-            reason: error instanceof Error ? error.message : String(error),
+            requestId,
         });
     }
-    const connectedBrowser = browser;
+    let browser = null;
     let finalResult = null;
     try {
-        const page = await resolvePageByRef(connectedBrowser, session, fillableForm.pageRef);
+        browser = await connectPlaywright(session.cdpUrl);
+        const page = await resolvePageByRef(browser, session, fillableForm.pageRef);
         const syncedPage = await syncSessionPage(session, fillableForm.pageRef, page);
         const observedHost = tryResolveCatalogHost(syncedPage.url);
         const contextMismatchReasons = [];
-        if (latestIntent.host && observedHost && latestIntent.host !== observedHost) {
+        if (latestRequest.host && observedHost && latestRequest.host !== observedHost) {
             contextMismatchReasons.push('host');
         }
-        if (latestIntent.scopeRef && latestIntent.scopeRef !== fillableForm.scopeRef) {
+        if (latestRequest.scopeRef && latestRequest.scopeRef !== fillableForm.scopeRef) {
             contextMismatchReasons.push('scope');
         }
         if (contextMismatchReasons.length > 0) {
-            const completedIntent = completeIntent(session, intentId);
             finalResult = {
                 success: false,
-                payload: {
-                    error: 'secret_intent_context_mismatch',
+                payload: withFillableFormPresence(fillableForm, {
+                    error: 'secret_request_context_mismatch',
                     outcomeType: 'blocked',
-                    message: 'Protected fill was blocked because the page or protected surface no longer matches the approved intent context.',
-                    reason: 'The current page host or protected surface no longer matches the context that was approved for this intent.',
+                    message: 'Protected fill was blocked because the page or protected surface no longer matches the approved request context.',
+                    reason: 'The current page host or protected surface no longer matches the context that was approved for this request.',
                     fillRef,
-                    intentId,
-                    ...serializeSecretIntentContext(completedIntent),
-                    intentStatus: completedIntent.status,
+                    requestId,
+                    ...serializeSecretRequestContext(latestRequest),
+                    requestStatus: latestRequest.status,
                     nextAction: 'reobserve',
-                    intentReusable: false,
+                    requestReusable: true,
                     mismatchReasons: contextMismatchReasons,
-                    ...(latestIntent.host ? { expectedHost: latestIntent.host } : {}),
+                    ...(latestRequest.host ? { expectedHost: latestRequest.host } : {}),
                     ...(observedHost ? { observedHost } : {}),
-                    ...(latestIntent.scopeRef ? { expectedScopeRef: latestIntent.scopeRef } : {}),
+                    ...(latestRequest.scopeRef ? { expectedScopeRef: latestRequest.scopeRef } : {}),
                     ...(fillableForm.scopeRef ? { observedScopeRef: fillableForm.scopeRef } : {}),
-                },
+                }),
             };
         }
         else {
-            const protectedValues = { ...cachedSecret.values };
-            const storedSecretCandidate = fillableForm.storedSecretCandidates.find((candidate) => candidate.storedSecretRef === latestIntent.storedSecretRef);
-            const executableForm = restrictFormToCandidateFields(fillableForm, storedSecretCandidate);
+            let claimedAt = new Date().toISOString();
+            let claimStoredSecretRef = latestRequest.storedSecretRef;
+            let claimKind = latestRequest.kind;
+            let protectedValues = null;
             try {
-                const execution = await executeProtectedFill({
-                    session,
-                    page,
-                    fillableForm: executableForm,
-                    protectedValues,
-                    fieldPolicies: storedSecretCandidate?.fieldPolicies,
-                });
-                if (execution.kind === 'success') {
-                    const completedIntent = completeIntent(session, intentId);
-                    activateProtectedExposure(session, fillableForm, intentId, 'protected_fill_success');
+                const claim = await getSecretBackend().claimSecretRequest(session.intentSessionId, requestId, fillSecretStep?.stepId ?? `claim-${Date.now()}`);
+                claimedAt = claim.issuedAt;
+                claimStoredSecretRef = claim.secret.storedSecretRef ?? claimStoredSecretRef;
+                claimKind = claim.secret.kind ?? claimKind;
+                protectedValues = { ...claim.secret.values };
+            }
+            catch (error) {
+                const parsed = parseClaimFailure(error);
+                if (parsed === 'not_fulfilled') {
                     finalResult = {
-                        success: true,
-                        payload: {
-                            fillRef,
-                            intentId,
-                            ...serializeSecretIntentContext(completedIntent),
-                            filledFields: execution.filledFields,
-                            intentStatus: completedIntent.status,
-                            message: 'Protected fill completed successfully.',
-                            reason: 'AgentBrowse filled the protected fields using the one-time secret payload.',
-                        },
+                        success: false,
+                        payload: failureForUnfulfilledRequest(fillableForm, latestRequest, fillRef, requestId),
                     };
                 }
-                else if (execution.kind === 'binding_stale') {
-                    const completedIntent = completeIntent(session, intentId);
-                    activateProtectedExposure(session, fillableForm, intentId, 'protected_fill_binding_stale');
+                else if (parsed === 'already_claimed') {
                     finalResult = {
                         success: false,
-                        payload: {
-                            error: 'secret_fill_binding_stale',
-                            outcomeType: 'binding_stale',
-                            message: 'Protected fill was blocked because the stored field bindings are no longer valid on the page.',
+                        payload: withFillableFormPresence(fillableForm, {
+                            error: 'secret_request_already_claimed',
+                            outcomeType: 'blocked',
+                            message: 'Protected fill could not continue because this one-time secret request was already claimed earlier.',
+                            reason: 'Secret values can only be claimed once for this request, so AgentBrowse needs a new request before it can fill again.',
                             fillRef,
-                            intentId,
-                            ...serializeSecretIntentContext(completedIntent),
-                            intentStatus: completedIntent.status,
-                            nextAction: 'reobserve',
-                            targetRef: execution.targetRef,
-                            fieldKeys: execution.fieldKeys,
-                            reason: execution.reason,
-                            attempts: execution.attempts,
-                        },
+                            requestId,
+                            ...serializeSecretRequestContext(latestRequest),
+                            requestStatus: latestRequest.status,
+                            nextAction: 'request-secret',
+                        }),
                     };
                 }
-                else if (execution.kind === 'validation_failed') {
-                    const completedIntent = completeIntent(session, intentId);
-                    activateProtectedExposure(session, fillableForm, intentId, 'protected_fill_validation_failed');
+                else {
                     finalResult = {
                         success: false,
-                        payload: {
-                            error: 'secret_validation_failed',
+                        payload: withFillableFormPresence(fillableForm, {
+                            error: 'secret_claim_failed',
                             outcomeType: 'blocked',
-                            message: 'Protected fill stopped because the stored data did not pass client-side validation.',
-                            reason: 'Protected execution reported client-side validation errors for one or more filled fields.',
+                            message: 'Protected fill could not continue because AgentBrowse failed to claim the one-time secret payload.',
+                            reason: error instanceof Error ? error.message : String(error),
                             fillRef,
-                            intentId,
-                            ...serializeSecretIntentContext(completedIntent),
-                            intentStatus: completedIntent.status,
-                            executionResult: 'validation_failed',
-                            nextAction: 'ask-user',
-                            manualOverrideAllowed: true,
-                            filledFields: execution.filledFields,
-                            fieldErrors: execution.fieldErrors,
-                        },
+                            requestId,
+                            ...serializeSecretRequestContext(latestRequest),
+                            requestStatus: latestRequest.status,
+                            nextAction: error instanceof AgentpayRequestError && error.status === 404 ? 'poll-secret' : 'ask-user',
+                        }),
                     };
                 }
-                else {
-                    const completedIntent = completeIntent(session, intentId);
-                    activateProtectedExposure(session, fillableForm, intentId, 'protected_fill_unexpected_error');
+            }
+            if (!finalResult) {
+                if (!protectedValues) {
+                    throw new Error('claimed_secret_values_missing');
+                }
+                const claimedRequest = markRequestClaimed(session, requestId, claimedAt);
+                if (claimStoredSecretRef || claimKind) {
+                    persistRequestSnapshot(session, {
+                        ...claimedRequest,
+                        ...(claimStoredSecretRef ? { storedSecretRef: claimStoredSecretRef } : {}),
+                        ...(claimKind ? { kind: claimKind } : {}),
+                    });
+                }
+                const storedSecretCandidate = fillableForm.storedSecretCandidates.find((candidate) => candidate.storedSecretRef === (claimStoredSecretRef ?? latestRequest.storedSecretRef));
+                const executableForm = restrictFormToCandidateFields(fillableForm, storedSecretCandidate);
+                try {
+                    const execution = await executeProtectedFill({
+                        session,
+                        page,
+                        fillableForm: executableForm,
+                        protectedValues,
+                        fieldPolicies: storedSecretCandidate?.fieldPolicies,
+                    });
+                    if (execution.kind === 'success') {
+                        activateProtectedExposure(session, fillableForm, requestId, 'protected_fill_success');
+                        finalResult = {
+                            success: true,
+                            payload: withFillableFormPresence(fillableForm, {
+                                fillRef,
+                                requestId,
+                                ...serializeSecretRequestContext(getSecretRequestSnapshot(session, requestId)),
+                                filledFields: execution.filledFields,
+                                requestStatus: latestRequest.status,
+                                message: 'Protected fill completed successfully.',
+                                reason: 'AgentBrowse filled the protected fields using the claimed one-time secret payload.',
+                            }),
+                        };
+                    }
+                    else if (execution.kind === 'binding_stale') {
+                        activateProtectedExposure(session, fillableForm, requestId, 'protected_fill_binding_stale');
+                        finalResult = {
+                            success: false,
+                            payload: withFillableFormPresence(fillableForm, {
+                                error: 'secret_fill_binding_stale',
+                                outcomeType: 'binding_stale',
+                                message: 'Protected fill was blocked because the stored field bindings are no longer valid on the page.',
+                                fillRef,
+                                requestId,
+                                ...serializeSecretRequestContext(getSecretRequestSnapshot(session, requestId)),
+                                requestStatus: latestRequest.status,
+                                nextAction: 'reobserve',
+                                requestReusable: false,
+                                targetRef: execution.targetRef,
+                                fieldKeys: execution.fieldKeys,
+                                reason: execution.reason,
+                                attempts: execution.attempts,
+                            }),
+                        };
+                    }
+                    else if (execution.kind === 'validation_failed') {
+                        activateProtectedExposure(session, fillableForm, requestId, 'protected_fill_validation_failed');
+                        finalResult = {
+                            success: false,
+                            payload: withFillableFormPresence(fillableForm, {
+                                error: 'secret_validation_failed',
+                                outcomeType: 'blocked',
+                                message: 'Protected fill stopped because the stored data did not pass client-side validation.',
+                                reason: 'Protected execution reported client-side validation errors for one or more filled fields.',
+                                fillRef,
+                                requestId,
+                                ...serializeSecretRequestContext(getSecretRequestSnapshot(session, requestId)),
+                                requestStatus: latestRequest.status,
+                                executionResult: 'validation_failed',
+                                nextAction: 'ask-user',
+                                manualOverrideAllowed: true,
+                                requestReusable: false,
+                                filledFields: execution.filledFields,
+                                fieldErrors: execution.fieldErrors,
+                            }),
+                        };
+                    }
+                    else {
+                        activateProtectedExposure(session, fillableForm, requestId, 'protected_fill_unexpected_error');
+                        finalResult = {
+                            success: false,
+                            payload: withFillableFormPresence(fillableForm, {
+                                error: 'protected_fill_execution_failed',
+                                outcomeType: 'blocked',
+                                message: 'Protected fill failed during protected execution, so this claimed request must not be reused.',
+                                fillRef,
+                                requestId,
+                                ...serializeSecretRequestContext(getSecretRequestSnapshot(session, requestId)),
+                                requestStatus: latestRequest.status,
+                                requestReusable: false,
+                                nextAction: 'ask-user',
+                                reason: execution.reason,
+                            }),
+                        };
+                    }
+                }
+                catch (error) {
+                    activateProtectedExposure(session, fillableForm, requestId, 'protected_fill_unexpected_error');
                     finalResult = {
                         success: false,
-                        payload: {
+                        payload: withFillableFormPresence(fillableForm, {
                             error: 'protected_fill_execution_failed',
                             outcomeType: 'blocked',
-                            message: 'Protected fill failed during protected execution, so this approved intent must not be reused.',
+                            message: 'Protected fill failed during protected execution, so this claimed request must not be reused.',
                             fillRef,
-                            intentId,
-                            ...serializeSecretIntentContext(completedIntent),
-                            intentStatus: completedIntent.status,
+                            requestId,
+                            ...serializeSecretRequestContext(getSecretRequestSnapshot(session, requestId)),
+                            requestStatus: latestRequest.status,
+                            requestReusable: false,
                             nextAction: 'ask-user',
-                            reason: execution.reason,
-                        },
+                            reason: error instanceof Error ? error.message : String(error),
+                        }),
                     };
                 }
             }
-            catch (error) {
-                const completedIntent = completeIntent(session, intentId);
-                activateProtectedExposure(session, fillableForm, intentId, 'protected_fill_unexpected_error');
-                finalResult = {
-                    success: false,
-                    payload: {
-                        error: 'protected_fill_execution_failed',
-                        outcomeType: 'blocked',
-                        message: 'Protected fill failed during protected execution, so this approved intent must not be reused.',
-                        fillRef,
-                        intentId,
-                        ...serializeSecretIntentContext(completedIntent),
-                        intentStatus: completedIntent.status,
-                        nextAction: 'ask-user',
-                        reason: error instanceof Error ? error.message : String(error),
-                    },
-                };
-            }
         }
     }
+    catch (error) {
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, withFillableFormPresence(fillableForm, {
+            error: 'browser_connection_failed',
+            message: 'Protected fill could not connect to the browser.',
+            fillRef,
+            requestId,
+            ...serializeSecretRequestContext(latestRequest),
+            reason: error instanceof Error ? error.message : String(error),
+        }), {
+            pageRef: fillableForm.pageRef,
+            fillRef,
+            requestId,
+        });
+    }
     finally {
-        deleteCachedTransientSecret(session, intentId);
-        saveSession(session);
         if (browser) {
-            disconnectPlaywright(browser);
+            await disconnectPlaywright(browser);
         }
     }
     if (!finalResult) {
-        return outputFailure({
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, withFillableFormPresence(fillableForm, {
             error: 'protected_fill_execution_failed',
             outcomeType: 'blocked',
             message: 'Protected fill did not produce a final result.',
             reason: 'Protected execution finished without returning a terminal success or failure payload.',
             fillRef,
-            intentId,
-            ...serializeSecretIntentContext(latestIntent),
+            requestId,
+            ...serializeSecretRequestContext(latestRequest),
+        }), {
+            pageRef: fillableForm.pageRef,
+            fillRef,
+            requestId,
         });
     }
     if (!finalResult.success) {
-        return outputFailure(finalResult.payload);
+        return emitFillSecretFailure(session, session.activeRunId, fillSecretStep?.stepId, finalResult.payload, {
+            pageRef: fillableForm.pageRef,
+            fillRef,
+            requestId,
+        });
     }
-    return outputJSON({
+    return emitFillSecretSuccess(session, session.activeRunId, fillSecretStep?.stepId, {
         success: true,
         ...finalResult.payload,
+    }, {
+        pageRef: fillableForm.pageRef,
+        fillRef,
+        requestId,
     });
 }