@nuanu-ai/agentbrowse 0.2.29 → 0.2.30

package/README.md

@@ -165,6 +165,9 @@ overrides.
 Human-readable progress is written to `stderr`. Command results are written to
 `stdout`.
 
+When `launch` detects a newer npm release, it prints the reminder to `stderr`
+without changing the JSON result written to `stdout`.
+
 `observe()` and `extract()` responses expose where runtime work came from:
 
 - top-level `source` shows the winning execution source, for example `dom` or `stagehand`

package/dist/commands/semantic-observe.d.ts

@@ -20,6 +20,9 @@ type ObserveInventoryTarget = {
     framePath?: string[];
     frameUrl?: string;
     formSelector?: string;
+    pageSignature?: string;
+    goalInventoryType?: 'target' | 'scope';
+    goalSurfaceId?: string;
 };
 export declare function rerankDomTargetsForGoal<T extends ObserveInventoryTarget>(instruction: string, targets: ReadonlyArray<T>): Promise<T[]>;
 export {};

package/dist/commands/semantic-observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-observe.d.ts","sourceRoot":"","sources":["../../src/commands/semantic-observe.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B,KAAK,sBAAsB,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACvC,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA6UF,wBAAsB,uBAAuB,CAAC,CAAC,SAAS,sBAAsB,EAC5E,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd"}
+{"version":3,"file":"semantic-observe.d.ts","sourceRoot":"","sources":["../../src/commands/semantic-observe.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B,KAAK,sBAAsB,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACvC,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA+3BF,wBAAsB,uBAAuB,CAAC,CAAC,SAAS,sBAAsB,EAC5E,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,EAAE,CAAC,CA6Dd"}

package/dist/commands/semantic-observe.js

@@ -9,6 +9,7 @@ const rerankSchema = z.object({
         .max(8),
 });
 const RERANK_CANDIDATE_LIMIT = 120;
+const GOAL_RETRIEVAL_ENTITY_LIMIT = 64;
 const FORM_BUCKET_RESERVE_LIMIT = 48;
 const FORM_BUCKET_RESERVE_PER_BUCKET = 8;
 const SCOPE_BUCKET_RESERVE_LIMIT = 24;
@@ -27,12 +28,60 @@ const HIGH_SIGNAL_SCOPE_KINDS = new Set([
     'card',
     'form',
 ]);
+const GOAL_TEXT_STOPWORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'at',
+    'for',
+    'from',
+    'in',
+    'of',
+    'on',
+    'or',
+    'the',
+    'to',
+    'with',
+    'в',
+    'для',
+    'и',
+    'или',
+    'на',
+    'найти',
+]);
 function isFieldLikeTarget(target) {
     const kind = (target.kind ?? '').trim().toLowerCase();
     const role = (target.role ?? '').trim().toLowerCase();
     return (['input', 'textarea', 'select', 'combobox'].includes(kind) ||
         ['textbox', 'combobox'].includes(role));
 }
+function isScopeLikeCandidate(target) {
+    return ((target.goalInventoryType ?? '').trim().toLowerCase() === 'scope' ||
+        (target.capability ?? '').trim().toLowerCase() === 'scope');
+}
+function isActionLikeTargetCandidate(target) {
+    if (isScopeLikeCandidate(target) || isFieldLikeTarget(target)) {
+        return false;
+    }
+    const kind = (target.kind ?? '').trim().toLowerCase();
+    const role = (target.role ?? '').trim().toLowerCase();
+    return (target.allowedActions?.includes('click') ||
+        target.allowedActions?.includes('press') ||
+        kind === 'button' ||
+        role === 'button' ||
+        kind === 'link' ||
+        role === 'link');
+}
+function normalizeRetrievalText(value) {
+    const normalized = value?.replace(/\s+/g, ' ').trim().toLowerCase();
+    return normalized ? normalized : undefined;
+}
+function tokenizeRetrievalText(value) {
+    if (!value) {
+        return [];
+    }
+    return (value.match(/[\p{L}\p{N}]+/gu) ?? []).map((token) => token.toLowerCase());
+}
 function semanticFormContextKey(context) {
     for (const node of [context?.landmark, context?.container, context?.group, context?.item]) {
         const kind = (node?.kind ?? '').trim().toLowerCase();
@@ -58,6 +107,17 @@ function candidateBucketKey(target, options = {}) {
     const surfaceKey = (options.preferFormBucket ? formKey : undefined) ?? target.surfaceRef ?? formKey ?? 'page-root';
     return `${frameKey}|${surfaceKey}`;
 }
+function surfaceIdentityOf(target) {
+    const explicitSurfaceId = target.goalSurfaceId?.trim();
+    if (explicitSurfaceId) {
+        return explicitSurfaceId;
+    }
+    const surfaceRef = target.surfaceRef?.trim();
+    if (!surfaceRef) {
+        return undefined;
+    }
+    return surfaceRef.startsWith('scope:') ? surfaceRef.slice('scope:'.length) : surfaceRef;
+}
 function isPrimaryFormControlTarget(target) {
     const kind = (target.kind ?? '').trim().toLowerCase();
     const role = (target.role ?? '').trim().toLowerCase();
@@ -102,6 +162,31 @@ function isHighSignalScopeCandidate(target) {
     const kind = (target.kind ?? '').trim().toLowerCase();
     return HIGH_SIGNAL_SCOPE_KINDS.has(kind);
 }
+function contentItemBucketKey(target) {
+    if (isScopeLikeCandidate(target) ||
+        !isActionLikeTargetCandidate(target) ||
+        Boolean(formBucketKey(target)) ||
+        isPrimaryFormControlTarget(target)) {
+        return undefined;
+    }
+    const surfaceKind = (target.surfaceKind ?? '').trim().toLowerCase();
+    if (['form', 'dialog', 'listbox', 'menu', 'popover', 'dropdown', 'datepicker'].includes(surfaceKind)) {
+        return undefined;
+    }
+    const surfaceIdentity = surfaceIdentityOf(target);
+    if (surfaceIdentity) {
+        return `surface:${surfaceIdentity}`;
+    }
+    const itemKey = normalizeRetrievalText(target.context?.item?.label ?? target.context?.item?.text);
+    if (itemKey) {
+        return `item:${itemKey}`;
+    }
+    const containerKey = normalizeRetrievalText(target.context?.container?.label ?? target.context?.container?.text);
+    if (containerKey) {
+        return `container:${containerKey}`;
+    }
+    return undefined;
+}
 function scopeCandidatePriority(target) {
     const kind = (target.kind ?? '').trim().toLowerCase();
     if (kind === 'dialog' || kind === 'listbox' || kind === 'menu') {
@@ -118,6 +203,343 @@ function scopeCandidatePriority(target) {
     }
     return 4;
 }
+function representativeCandidateScore(target) {
+    const normalizedLabel = normalizeRetrievalText(target.label);
+    const kind = (target.kind ?? '').trim().toLowerCase();
+    const role = (target.role ?? '').trim().toLowerCase();
+    let score = (target.surfacePriority ?? 0) * 10;
+    if (isPrimaryFormControlTarget(target)) {
+        score += 1_500 - primaryFormTargetPriority(target) * 100;
+    }
+    else if (isFieldLikeTarget(target)) {
+        score += 1_250;
+    }
+    else if (isActionLikeTargetCandidate(target)) {
+        score += 1_000;
+    }
+    else if (isScopeLikeCandidate(target)) {
+        score += 700;
+    }
+    if (target.allowedActions?.includes('fill') || target.allowedActions?.includes('select')) {
+        score += 120;
+    }
+    if (target.allowedActions?.includes('click') || target.allowedActions?.includes('press')) {
+        score += 80;
+    }
+    if (target.acceptancePolicy === 'submit') {
+        score += 120;
+    }
+    if (target.acceptancePolicy === 'navigation') {
+        score += 60;
+    }
+    if (kind === 'link' || role === 'link') {
+        score += 40;
+    }
+    if (normalizedLabel) {
+        score += Math.min(normalizedLabel.length, 100);
+        if (normalizedLabel === 'button' || normalizedLabel === 'link') {
+            score -= 300;
+        }
+        if (normalizedLabel.includes('opens in new window')) {
+            score -= 120;
+        }
+        if (normalizedLabel.includes('save this item')) {
+            score -= 80;
+        }
+    }
+    return score;
+}
+function entityMemberPriority(entityKind, target) {
+    if (entityKind === 'form' && isPrimaryFormControlTarget(target)) {
+        return 5_000 - primaryFormTargetPriority(target) * 100;
+    }
+    if (entityKind === 'scope' && isScopeLikeCandidate(target)) {
+        return representativeCandidateScore(target) - 200;
+    }
+    return representativeCandidateScore(target);
+}
+function compareEntityMembers(entityKind, left, right) {
+    const scoreDelta = entityMemberPriority(entityKind, right.target) - entityMemberPriority(entityKind, left.target);
+    if (scoreDelta !== 0) {
+        return scoreDelta;
+    }
+    return left.index - right.index;
+}
+function pickEntityLabel(entityKind, representative) {
+    if (entityKind === 'form') {
+        return (representative.context?.landmark?.label ??
+            representative.context?.container?.label ??
+            representative.context?.group?.label ??
+            representative.surfaceLabel ??
+            representative.label);
+    }
+    return (representative.label ??
+        representative.context?.container?.label ??
+        representative.context?.item?.label ??
+        representative.surfaceLabel ??
+        representative.context?.group?.label ??
+        representative.context?.landmark?.label);
+}
+function collectRepresentativeLabels(targets) {
+    const labels = [];
+    for (const target of targets) {
+        const label = target.label?.replace(/\s+/g, ' ').trim();
+        if (!label || label === 'Button' || label === 'Link' || labels.includes(label)) {
+            continue;
+        }
+        labels.push(label);
+        if (labels.length >= 4) {
+            break;
+        }
+    }
+    return labels;
+}
+function buildEntitySearchText(entityLabel, representative, representativeLabels) {
+    return [
+        entityLabel,
+        representative.label,
+        ...representativeLabels,
+        representative.surfaceLabel,
+        representative.context?.item?.label,
+        representative.context?.item?.text,
+        representative.context?.group?.label,
+        representative.context?.group?.text,
+        representative.context?.container?.label,
+        representative.context?.container?.text,
+        representative.context?.landmark?.label,
+        representative.context?.landmark?.text,
+        representative.context?.hintText,
+    ]
+        .map((value) => normalizeRetrievalText(value))
+        .filter((value) => Boolean(value))
+        .join(' ');
+}
+function buildGoalRetrievalEntity(entityKind, entityKey, memberIndexes, targets) {
+    const orderedMembers = [...memberIndexes]
+        .map((index) => ({ index, target: targets[index] }))
+        .sort((left, right) => compareEntityMembers(entityKind, left, right));
+    const representative = orderedMembers[0].target;
+    const representativeLabels = collectRepresentativeLabels(orderedMembers.map((entry) => entry.target));
+    const label = pickEntityLabel(entityKind, representative);
+    return {
+        entityKind,
+        entityKey,
+        firstIndex: Math.min(...memberIndexes),
+        memberIndexes: orderedMembers.map((entry) => entry.index),
+        representative,
+        label,
+        kind: entityKind === 'form'
+            ? 'form'
+            : entityKind === 'item'
+                ? representative.surfaceKind ?? representative.kind
+                : representative.kind,
+        surfaceKind: representative.surfaceKind,
+        surfaceLabel: representative.surfaceLabel,
+        surfacePriority: representative.surfacePriority,
+        framePath: representative.framePath,
+        frameUrl: representative.frameUrl,
+        context: representative.context,
+        structure: representative.structure,
+        representativeLabels,
+        searchText: buildEntitySearchText(label, representative, representativeLabels),
+    };
+}
+function buildGoalRetrievalEntities(targets) {
+    const entities = [];
+    const groupedTargetIndexes = new Set();
+    const nonScopeTargetsBySurface = new Map();
+    for (const [index, target] of targets.entries()) {
+        if (isScopeLikeCandidate(target)) {
+            continue;
+        }
+        const surfaceIdentity = surfaceIdentityOf(target);
+        if (!surfaceIdentity) {
+            continue;
+        }
+        const linked = nonScopeTargetsBySurface.get(surfaceIdentity) ?? [];
+        linked.push(index);
+        nonScopeTargetsBySurface.set(surfaceIdentity, linked);
+    }
+    const formGroups = new Map();
+    for (const [index, target] of targets.entries()) {
+        if (isScopeLikeCandidate(target)) {
+            continue;
+        }
+        const bucketKey = formBucketKey(target);
+        if (!bucketKey) {
+            continue;
+        }
+        const members = formGroups.get(bucketKey) ?? [];
+        members.push(index);
+        formGroups.set(bucketKey, members);
+    }
+    for (const [key, memberIndexes] of formGroups.entries()) {
+        entities.push(buildGoalRetrievalEntity('form', `form:${key}`, memberIndexes, targets));
+        memberIndexes.forEach((index) => groupedTargetIndexes.add(index));
+    }
+    const itemGroups = new Map();
+    for (const [index, target] of targets.entries()) {
+        const bucketKey = contentItemBucketKey(target);
+        if (!bucketKey) {
+            continue;
+        }
+        const members = itemGroups.get(bucketKey) ?? [];
+        members.push(index);
+        itemGroups.set(bucketKey, members);
+    }
+    for (const [key, memberIndexes] of itemGroups.entries()) {
+        entities.push(buildGoalRetrievalEntity('item', `item:${key}`, memberIndexes, targets));
+        memberIndexes.forEach((index) => groupedTargetIndexes.add(index));
+    }
+    for (const [index, target] of targets.entries()) {
+        if (!isHighSignalScopeCandidate(target)) {
+            continue;
+        }
+        const kind = (target.kind ?? '').trim().toLowerCase();
+        const surfaceIdentity = surfaceIdentityOf(target);
+        if (!surfaceIdentity) {
+            continue;
+        }
+        if (kind === 'form') {
+            continue;
+        }
+        if (kind === 'card' && itemGroups.has(`surface:${surfaceIdentity}`)) {
+            continue;
+        }
+        const linkedTargets = nonScopeTargetsBySurface.get(surfaceIdentity) ?? [];
+        const memberIndexes = [index, ...linkedTargets];
+        entities.push(buildGoalRetrievalEntity('scope', `scope:${surfaceIdentity}`, memberIndexes, targets));
+        linkedTargets.forEach((targetIndex) => groupedTargetIndexes.add(targetIndex));
+    }
+    for (const [index, target] of targets.entries()) {
+        if (isScopeLikeCandidate(target) || groupedTargetIndexes.has(index)) {
+            continue;
+        }
+        if (!isActionLikeTargetCandidate(target) &&
+            !isFieldLikeTarget(target) &&
+            !isPrimaryFormControlTarget(target)) {
+            continue;
+        }
+        entities.push(buildGoalRetrievalEntity('standalone', `target:${index}`, [index], targets));
+    }
+    return entities.sort((left, right) => left.firstIndex - right.firstIndex);
+}
+function retrievalEntityPriority(entity) {
+    let score = (entity.surfacePriority ?? 0) * 10;
+    switch (entity.entityKind) {
+        case 'form':
+            score += 900;
+            break;
+        case 'item':
+            score += 820;
+            break;
+        case 'scope':
+            score += 720;
+            break;
+        case 'standalone':
+            score += 600;
+            break;
+    }
+    score += Math.min(entity.memberIndexes.length, 6) * 25;
+    score += representativeCandidateScore(entity.representative);
+    return score;
+}
+function scoreRetrievalEntityAgainstGoal(goal, entity) {
+    const normalizedGoal = normalizeRetrievalText(goal);
+    if (!normalizedGoal) {
+        return 0;
+    }
+    const entityText = entity.searchText;
+    if (!entityText) {
+        return 0;
+    }
+    let score = 0;
+    const goalTokens = tokenizeRetrievalText(normalizedGoal).filter((token) => token.length >= 2 && !GOAL_TEXT_STOPWORDS.has(token));
+    const entityTokens = new Set(tokenizeRetrievalText(entityText));
+    if (entityText.includes(normalizedGoal)) {
+        score += 220;
+    }
+    const entityLabel = normalizeRetrievalText(entity.label);
+    if (entityLabel) {
+        if (normalizedGoal.includes(entityLabel)) {
+            score += 180;
+        }
+        if (entityLabel.includes(normalizedGoal)) {
+            score += 140;
+        }
+    }
+    let matchedTokenCount = 0;
+    for (const token of goalTokens) {
+        if (entityTokens.has(token)) {
+            matchedTokenCount += 1;
+            score += 8 + Math.min(token.length, 12);
+        }
+    }
+    if (goalTokens.length > 0) {
+        const coverage = matchedTokenCount / goalTokens.length;
+        if (coverage === 1) {
+            score += 120;
+        }
+        else if (coverage >= 0.75) {
+            score += 70;
+        }
+        else if (coverage >= 0.5) {
+            score += 35;
+        }
+    }
+    return score;
+}
+function preselectRetrievalEntities(goal, entities) {
+    if (entities.length <= GOAL_RETRIEVAL_ENTITY_LIMIT) {
+        return [...entities];
+    }
+    const scored = entities.map((entity) => ({
+        entity,
+        lexicalScore: scoreRetrievalEntityAgainstGoal(goal, entity),
+        priority: retrievalEntityPriority(entity),
+    }));
+    const selected = [];
+    const seenKeys = new Set();
+    for (const entry of scored
+        .filter((candidate) => candidate.lexicalScore > 0)
+        .sort((left, right) => right.lexicalScore - left.lexicalScore ||
+        right.priority - left.priority ||
+        left.entity.firstIndex - right.entity.firstIndex)) {
+        if (seenKeys.has(entry.entity.entityKey)) {
+            continue;
+        }
+        seenKeys.add(entry.entity.entityKey);
+        selected.push(entry.entity);
+        if (selected.length >= GOAL_RETRIEVAL_ENTITY_LIMIT) {
+            return selected;
+        }
+    }
+    for (const entry of scored.sort((left, right) => right.priority - left.priority || left.entity.firstIndex - right.entity.firstIndex)) {
+        if (seenKeys.has(entry.entity.entityKey)) {
+            continue;
+        }
+        seenKeys.add(entry.entity.entityKey);
+        selected.push(entry.entity);
+        if (selected.length >= GOAL_RETRIEVAL_ENTITY_LIMIT) {
+            break;
+        }
+    }
+    return selected;
+}
+function expandRetrievalEntitiesToCandidates(targets, entities) {
+    const orderedIndexes = [];
+    const seenIndexes = new Set();
+    for (const entity of entities) {
+        for (const index of entity.memberIndexes) {
+            if (seenIndexes.has(index)) {
+                continue;
+            }
+            seenIndexes.add(index);
+            orderedIndexes.push(index);
+        }
+    }
+    return orderedIndexes.map((index) => targets[index]).filter(Boolean);
+}
 function collectBucketedCandidateIndexes(targets, options) {
     const bucketEntries = new Map();
     for (const [index, target] of targets.entries()) {
@@ -305,9 +727,14 @@ export async function rerankDomTargetsForGoal(instruction, targets) {
     }
     const gateway = resolveAgentpayGatewayConfig();
     const client = new AgentpayStagehandLlmClient(gateway);
-    const candidates = diversifyCandidates(targets);
+    const retrievalEntities = buildGoalRetrievalEntities(targets);
+    const retrievedCandidates = targets.length > RERANK_CANDIDATE_LIMIT
+        ? expandRetrievalEntitiesToCandidates(targets, preselectRetrievalEntities(instruction, retrievalEntities))
+        : [...targets];
+    const candidates = diversifyCandidates(retrievedCandidates.length > 0 ? retrievedCandidates : [...targets]);
     const prompt = [
         'You are choosing from already discovered visible actionable candidates on a webpage.',
+        'Candidates already come from the most relevant retrieved page regions/items for this goal.',
         'Select only the candidate IDs that directly satisfy the user goal.',
         'Use container/landmark/layout/state information to disambiguate similar labels.',
         'Prefer candidates whose surrounding container clearly corroborates the goal.',

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA0QA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgKhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA0QA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqKhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}

package/dist/index.js

@@ -238,14 +238,21 @@ async function main(argv = process.argv) {
         }
         case 'launch': {
             const { launch } = await import('./commands/launch.js');
+            const { checkForLaunchUpdate } = await import('./update-check.js');
             const launchArgs = parseLaunchArgs(args);
-            outputJSON(await launch(launchArgs.url, {
+            const updateNoticePromise = checkForLaunchUpdate().catch(() => null);
+            const launchResult = await launch(launchArgs.url, {
                 compact: launchArgs.compact,
                 profile: launchArgs.profile,
                 headless: launchArgs.headless,
                 proxy: launchArgs.proxy,
                 noProxy: launchArgs.noProxy,
-            }));
+            });
+            const updateNotice = await updateNoticePromise;
+            if (updateNotice) {
+                info(updateNotice.message);
+            }
+            outputJSON(launchResult);
             break;
         }
         case 'navigate': {

package/dist/update-check.d.ts

@@ -0,0 +1,14 @@
+export type LaunchUpdateNotice = {
+    currentVersion: string;
+    latestVersion: string;
+    message: string;
+};
+export type LaunchUpdateCheckOptions = {
+    fetchImpl?: typeof fetch;
+    now?: Date;
+    timeoutMs?: number;
+    ttlMs?: number;
+};
+export declare function compareVersions(left: string, right: string): number;
+export declare function checkForLaunchUpdate(options?: LaunchUpdateCheckOptions): Promise<LaunchUpdateNotice | null>;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA8DnE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA2BpC"}

package/dist/update-check.js

@@ -0,0 +1,182 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSolverDir } from './solver/config.js';
+const PACKAGE_NAME = '@nuanu-ai/agentbrowse';
+const PACKAGE_JSON_URL = new URL('../package.json', import.meta.url);
+const REGISTRY_METADATA_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`;
+const DEFAULT_UPDATE_CHECK_TIMEOUT_MS = 1500;
+const DEFAULT_UPDATE_TTL_MS = 12 * 60 * 60 * 1000;
+export function compareVersions(left, right) {
+    const parsedLeft = parseVersion(left);
+    const parsedRight = parseVersion(right);
+    if (!parsedLeft || !parsedRight) {
+        return left.localeCompare(right, undefined, {
+            numeric: true,
+            sensitivity: 'base',
+        });
+    }
+    for (let i = 0; i < 3; i += 1) {
+        const diff = parsedLeft.core[i] - parsedRight.core[i];
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    if (!parsedLeft.prerelease && !parsedRight.prerelease) {
+        return 0;
+    }
+    if (!parsedLeft.prerelease) {
+        return 1;
+    }
+    if (!parsedRight.prerelease) {
+        return -1;
+    }
+    const length = Math.max(parsedLeft.prerelease.length, parsedRight.prerelease.length);
+    for (let i = 0; i < length; i += 1) {
+        const leftPart = parsedLeft.prerelease[i];
+        const rightPart = parsedRight.prerelease[i];
+        if (leftPart === undefined) {
+            return -1;
+        }
+        if (rightPart === undefined) {
+            return 1;
+        }
+        if (typeof leftPart === 'number' && typeof rightPart === 'number') {
+            const diff = leftPart - rightPart;
+            if (diff !== 0) {
+                return diff;
+            }
+            continue;
+        }
+        if (typeof leftPart === 'number') {
+            return -1;
+        }
+        if (typeof rightPart === 'number') {
+            return 1;
+        }
+        const diff = leftPart.localeCompare(rightPart);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+export async function checkForLaunchUpdate(options = {}) {
+    const currentVersion = readCurrentPackageVersion();
+    const now = options.now ?? new Date();
+    const ttlMs = options.ttlMs ?? DEFAULT_UPDATE_TTL_MS;
+    const cachedState = readUpdateState();
+    const cachedNotice = buildLaunchUpdateNotice(currentVersion, cachedState?.latestVersion);
+    if (cachedState && !isCacheStale(cachedState.lastCheckedAt, now, ttlMs)) {
+        return cachedNotice;
+    }
+    const latestVersion = await fetchLatestVersion({
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs ?? DEFAULT_UPDATE_CHECK_TIMEOUT_MS,
+    }).catch(() => null);
+    if (!latestVersion) {
+        return cachedNotice;
+    }
+    writeUpdateState({
+        packageName: PACKAGE_NAME,
+        latestVersion,
+        lastCheckedAt: now.toISOString(),
+    });
+    return buildLaunchUpdateNotice(currentVersion, latestVersion);
+}
+function parseVersion(version) {
+    const match = version
+        .trim()
+        .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+.*)?$/);
+    if (!match) {
+        return null;
+    }
+    const prerelease = match[4]
+        ? match[4].split('.').map((part) => (/^\d+$/.test(part) ? Number(part) : part))
+        : null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease,
+    };
+}
+function buildLaunchUpdateNotice(currentVersion, latestVersion) {
+    if (!latestVersion || compareVersions(latestVersion, currentVersion) <= 0) {
+        return null;
+    }
+    return {
+        currentVersion,
+        latestVersion,
+        message: `A newer agentbrowse version is available: ${latestVersion} (current: ${currentVersion}). Update with: npm i -g ${PACKAGE_NAME}@latest`,
+    };
+}
+function readCurrentPackageVersion() {
+    const raw = JSON.parse(readFileSync(PACKAGE_JSON_URL, 'utf-8'));
+    if (!raw.version || typeof raw.version !== 'string') {
+        throw new Error('Package version is missing from package.json.');
+    }
+    return raw.version;
+}
+function readUpdateState() {
+    const updateStatePath = getUpdateStatePath();
+    if (!existsSync(updateStatePath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(updateStatePath, 'utf-8'));
+        if (raw.packageName !== PACKAGE_NAME ||
+            typeof raw.latestVersion !== 'string' ||
+            typeof raw.lastCheckedAt !== 'string') {
+            return null;
+        }
+        return {
+            packageName: raw.packageName,
+            latestVersion: raw.latestVersion,
+            lastCheckedAt: raw.lastCheckedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeUpdateState(state) {
+    const solverDir = getSolverDir();
+    mkdirSync(solverDir, { recursive: true });
+    writeFileSync(getUpdateStatePath(), JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+function isCacheStale(lastCheckedAt, now, ttlMs) {
+    const lastCheckedAtMs = new Date(lastCheckedAt).getTime();
+    if (!Number.isFinite(lastCheckedAtMs)) {
+        return true;
+    }
+    return now.getTime() - lastCheckedAtMs >= ttlMs;
+}
+async function fetchLatestVersion(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('Global fetch is not available.');
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetchImpl(REGISTRY_METADATA_URL, {
+            headers: {
+                Accept: 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`Registry responded with ${response.status}.`);
+        }
+        const metadata = (await response.json());
+        const latestVersion = metadata['dist-tags']?.latest;
+        if (!latestVersion || typeof latestVersion !== 'string') {
+            throw new Error('Registry metadata does not include dist-tags.latest.');
+        }
+        return latestVersion;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function getUpdateStatePath() {
+    return join(getSolverDir(), 'update-state.json');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentbrowse",
-  "version": "0.2.29",
+  "version": "0.2.30",
   "type": "module",
   "description": "Browser automation CLI for AI agents: control a CDP browser, observe UI surfaces, act on refs, extract data, capture screenshots, complete protected fills, and solve captchas",
   "keywords": [