@nuanu-ai/agentbrowse 0.2.7 → 0.2.8

package/dist/commands/extract.js

@@ -1,59 +1,276 @@
 /**
- * browse extract "<instruction>" [--schema '<json>'] — Extract structured data.
+ * browse extract '<schema-json>' [scopeRef] — Extract structured data from the page or a stored scope.
  */
 import { z } from 'zod';
-import { connectStagehand, getPageInfo } from '../stagehand.js';
-import { outputJSON, outputError } from '../output.js';
-/**
- * Build a Zod schema from a simple JSON type descriptor.
- * Supports: "string", "number", "boolean", and nested objects.
- *
- * Example: {"price": "number", "name": "string"} → z.object({price: z.number(), name: z.string()})
- */
+import { saveSession } from '../session.js';
+import { getSurface, getTarget, markSurfaceLifecycle, markTargetLifecycle, setCurrentPage, } from '../runtime-state.js';
+import { outputContractFailure, outputJSON } from '../output.js';
+import { connectPlaywright, disconnectPlaywright, resolvePageByRef as resolvePlaywrightPageByRef, syncSessionPage, } from '../playwright-runtime.js';
+import { normalizePageSignature } from './descriptor-validation.js';
+import { resolveScopedExtractContext } from './extract-scope-resolution.js';
+import { executeStagehandExtract } from './extract-stagehand-executor.js';
+function buildSchemaValue(descriptor) {
+    if (descriptor === 'string')
+        return z.string();
+    if (descriptor === 'number')
+        return z.number();
+    if (descriptor === 'boolean')
+        return z.boolean();
+    if (Array.isArray(descriptor)) {
+        const itemDescriptor = descriptor[0];
+        return z.array(itemDescriptor === undefined ? z.unknown() : buildSchemaValue(itemDescriptor));
+    }
+    if (typeof descriptor === 'object' && descriptor !== null) {
+        const shape = {};
+        for (const [key, value] of Object.entries(descriptor)) {
+            shape[key] = buildSchemaValue(value);
+        }
+        return z.object(shape);
+    }
+    return z.unknown();
+}
 function buildSchema(descriptor) {
-    const shape = {};
+    return buildSchemaValue(descriptor);
+}
+function describeSchema(descriptor, prefix) {
+    const lines = [];
     for (const [key, value] of Object.entries(descriptor)) {
-        if (value === 'string')
-            shape[key] = z.string();
-        else if (value === 'number')
-            shape[key] = z.number();
-        else if (value === 'boolean')
-            shape[key] = z.boolean();
-        else if (typeof value === 'object' && value !== null) {
-            shape[key] = buildSchema(value);
+        const fieldPath = prefix ? `${prefix}.${key}` : key;
+        if (value === 'string' || value === 'number' || value === 'boolean') {
+            lines.push(`${fieldPath}: ${value}`);
+            continue;
         }
-        else {
-            shape[key] = z.unknown();
+        if (Array.isArray(value)) {
+            const itemDescriptor = value[0];
+            if (itemDescriptor === 'string' || itemDescriptor === 'number' || itemDescriptor === 'boolean') {
+                lines.push(`${fieldPath}[]: ${itemDescriptor}`);
+            }
+            else if (typeof itemDescriptor === 'object' && itemDescriptor !== null && !Array.isArray(itemDescriptor)) {
+                lines.push(...describeSchema(itemDescriptor, `${fieldPath}[]`));
+            }
+            else {
+                lines.push(`${fieldPath}[]: unknown`);
+            }
+            continue;
         }
+        if (typeof value === 'object' && value !== null) {
+            lines.push(...describeSchema(value, fieldPath));
+            continue;
+        }
+        lines.push(`${fieldPath}: unknown`);
     }
-    return z.object(shape);
+    return lines;
+}
+function buildInstruction(schemaDescriptor, scopeRef) {
+    const fields = describeSchema(schemaDescriptor);
+    const scopeNote = scopeRef
+        ? 'Only inspect the provided scoped container, not the full page.'
+        : 'Inspect the current page.';
+    return [
+        'Extract structured data that is explicitly visible in the current DOM state.',
+        scopeNote,
+        'Return only the fields defined by the schema and do not infer missing values.',
+        `Fields: ${fields.join('; ') || 'none'}.`,
+    ].join(' ');
 }
-export async function extract(cdpUrl, instruction, schemaJson) {
-    let stagehand;
+function canUseTargetAsExtractScope(target) {
+    if (target.capability === 'informational') {
+        return false;
+    }
+    if (target.capability === 'scope') {
+        return true;
+    }
+    const kind = (target.kind ?? '').toLowerCase();
+    const role = (target.semantics?.role ?? '').toLowerCase();
+    const scopeLikeKinds = new Set([
+        'card',
+        'article',
+        'section',
+        'row',
+        'grid',
+        'gridcell',
+        'listitem',
+        'dialog',
+        'tabpanel',
+        'region',
+        'form',
+        'group',
+    ]);
+    const leafInteractiveKinds = new Set(['input', 'textarea', 'select', 'option', 'button', 'link', 'combobox']);
+    const leafInteractiveRoles = new Set(['textbox', 'combobox', 'option', 'menuitem', 'button', 'link']);
+    const iframeFieldLike = Boolean(target.framePath?.length) &&
+        (target.allowedActions.includes('fill') ||
+            target.allowedActions.includes('type') ||
+            target.allowedActions.includes('select') ||
+            ['input', 'textarea', 'select', 'combobox'].includes(kind) ||
+            ['textbox', 'combobox'].includes(role));
+    if (target.allowedActions.length === 0) {
+        return true;
+    }
+    if (iframeFieldLike) {
+        return true;
+    }
+    if (target.allowedActions.includes('fill') ||
+        target.allowedActions.includes('type') ||
+        target.allowedActions.includes('select')) {
+        return false;
+    }
+    if (leafInteractiveKinds.has(kind) || leafInteractiveRoles.has(role)) {
+        return false;
+    }
+    return Boolean(target.surfaceRef) || scopeLikeKinds.has(kind) || scopeLikeKinds.has(role);
+}
+export async function extract(session, schemaJson, scopeRef) {
+    let schemaDescriptor;
     try {
-        stagehand = await connectStagehand(cdpUrl);
+        schemaDescriptor = JSON.parse(schemaJson);
+    }
+    catch {
+        return outputContractFailure({
+            error: 'invalid_extract_schema',
+            outcomeType: 'blocked',
+            message: 'Extraction could not start because the schema JSON is invalid.',
+            reason: 'The provided schema argument is not valid JSON.',
+        });
+    }
+    const schema = buildSchema(schemaDescriptor);
+    const instruction = buildInstruction(schemaDescriptor, scopeRef);
+    const targetScope = scopeRef ? getTarget(session, scopeRef) : null;
+    const surfaceScope = !targetScope && scopeRef ? getSurface(session, scopeRef) : null;
+    const scopeTarget = targetScope ?? surfaceScope;
+    const pageRef = scopeTarget?.pageRef ?? session.runtime?.currentPageRef ?? 'p0';
+    if (scopeRef && !scopeTarget) {
+        return outputContractFailure({
+            error: 'unknown_scope_ref',
+            outcomeType: 'blocked',
+            message: 'Extraction could not start because the requested scopeRef is unknown.',
+            reason: `No live scope target matches scopeRef ${scopeRef}.`,
+            scopeRef,
+        });
+    }
+    if (scopeTarget && scopeTarget.lifecycle !== 'live') {
+        return outputContractFailure({
+            error: 'stale_extract_scope',
+            outcomeType: 'binding_stale',
+            message: 'Extraction could not start because the requested scope is no longer live.',
+            reason: `Scope ${scopeRef} is ${scopeTarget.lifecycle}${scopeTarget.lifecycleReason ? ` because ${scopeTarget.lifecycleReason}` : ''}.`,
+            scopeRef,
+        });
+    }
+    if (targetScope && !canUseTargetAsExtractScope(targetScope)) {
+        return outputContractFailure({
+            error: 'invalid_extract_scope',
+            outcomeType: 'unsupported',
+            message: 'Extraction cannot use the requested target as a scope.',
+            reason: `Target ${scopeRef} is a leaf control, not an extractable scope container.`,
+            scopeRef,
+        });
+    }
+    let browser = null;
+    let failureMessage = null;
+    let cleanupScopedExtract = null;
+    let staleScope = false;
+    let staleReason = null;
+    try {
+        browser = await connectPlaywright(session.cdpUrl);
     }
     catch (err) {
-        outputError(`Failed to connect to browser: ${err instanceof Error ? err.message : String(err)}`);
+        return outputContractFailure({
+            error: 'browser_connection_failed',
+            outcomeType: 'blocked',
+            message: 'Extraction could not start because AgentBrowse failed to connect to the browser.',
+            reason: err instanceof Error ? err.message : String(err),
+            scopeRef,
+            pageRef,
+        });
     }
     try {
-        if (schemaJson) {
-            const descriptor = JSON.parse(schemaJson);
-            const schema = buildSchema(descriptor);
-            const data = await stagehand.extract(instruction, schema);
-            const { url, title } = await getPageInfo(stagehand);
-            await stagehand.close();
-            outputJSON({ success: true, data, url, title });
+        const sourcePage = await resolvePlaywrightPageByRef(browser, session, pageRef);
+        let page = sourcePage;
+        let scopedResolution = null;
+        const { url, title } = await syncSessionPage(session, pageRef, sourcePage);
+        if (scopeTarget?.pageSignature && normalizePageSignature(url) !== scopeTarget.pageSignature) {
+            staleScope = true;
+            staleReason = 'page-signature-mismatch';
+            throw new Error('stale_scope_target_page_signature_changed');
         }
-        else {
-            const result = await stagehand.extract(instruction);
-            const { url, title } = await getPageInfo(stagehand);
-            await stagehand.close();
-            outputJSON({ success: true, extraction: result.extraction, url, title });
+        let effectiveSelector;
+        if (scopeTarget) {
+            try {
+                scopedResolution = await resolveScopedExtractContext({
+                    page: sourcePage,
+                    scopeTarget,
+                    validateDomSignature: Boolean(targetScope),
+                });
+                cleanupScopedExtract = scopedResolution.cleanup;
+                page = scopedResolution.page;
+                effectiveSelector = scopedResolution.selector;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message === 'stale_scope_target_dom_signature_changed') {
+                    staleScope = true;
+                    staleReason = 'dom-signature-mismatch';
+                }
+                throw error;
+            }
         }
+        setCurrentPage(session, pageRef);
+        const execution = await executeStagehandExtract({
+            session,
+            instruction,
+            schema,
+            page,
+            selector: effectiveSelector,
+            degradationReason: scopedResolution?.degraded
+                ? scopedResolution.degradationReason
+                : undefined,
+        });
+        saveSession(session);
+        outputJSON({
+            success: true,
+            ...execution,
+            pageRef,
+            scopeRef,
+            metrics: session.runtime?.metrics,
+            url,
+            title,
+        });
     }
     catch (err) {
-        await stagehand.close();
-        outputError(`Extract failed: ${err instanceof Error ? err.message : String(err)}`);
+        if (staleScope && scopeRef) {
+            if (targetScope) {
+                markTargetLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+            }
+            else if (surfaceScope) {
+                markSurfaceLifecycle(session, scopeRef, 'stale', staleReason ?? 'unknown');
+            }
+            saveSession(session);
+        }
+        failureMessage = `Extract failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    finally {
+        if (cleanupScopedExtract) {
+            await cleanupScopedExtract().catch(() => undefined);
+        }
+        if (browser) {
+            disconnectPlaywright(browser);
+        }
+    }
+    if (failureMessage) {
+        outputContractFailure({
+            error: staleScope ? 'stale_extract_scope' : 'extract_failed',
+            outcomeType: staleScope ? 'binding_stale' : 'blocked',
+            message: staleScope
+                ? 'Extraction failed because the requested scope became stale.'
+                : 'Extraction failed.',
+            reason: staleScope && scopeRef
+                ? `${failureMessage} (${scopeRef} marked stale: ${staleReason ?? 'stale'})`
+                : failureMessage.replace(/^Extract failed:\s*/, ''),
+            scopeRef,
+            pageRef,
+            staleScope,
+            staleReason: staleReason ?? undefined,
+        });
     }
 }

package/dist/commands/fill-secret.d.ts

@@ -0,0 +1,7 @@
+/**
+ * browse fill-secret <fillRef> <intentId> — Fill protected fields from a cached one-time secret payload
+ * using the persisted plan and deterministic browser execution.
+ */
+import type { BrowseSession } from '../session.js';
+export declare function fillSecret(session: BrowseSession, fillRef: string, intentId: string): Promise<void>;
+//# sourceMappingURL=fill-secret.d.ts.map

package/dist/commands/fill-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fill-secret.d.ts","sourceRoot":"","sources":["../../src/commands/fill-secret.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA8InD,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAmUf"}