@tangle-network/browser-agent-driver 0.36.1 → 0.36.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/README.md +72 -359
  2. package/dist/brain/action-parse.d.ts.map +1 -1
  3. package/dist/brain/action-parse.js +10 -2
  4. package/dist/brain/action-parse.js.map +1 -1
  5. package/dist/brain/decide.d.ts +3 -0
  6. package/dist/brain/decide.d.ts.map +1 -1
  7. package/dist/brain/decide.js +84 -17
  8. package/dist/brain/decide.js.map +1 -1
  9. package/dist/brain/gemini-cache.d.ts +40 -0
  10. package/dist/brain/gemini-cache.d.ts.map +1 -0
  11. package/dist/brain/gemini-cache.js +90 -0
  12. package/dist/brain/gemini-cache.js.map +1 -0
  13. package/dist/brain/history-compact.d.ts +23 -2
  14. package/dist/brain/history-compact.d.ts.map +1 -1
  15. package/dist/brain/history-compact.js +78 -5
  16. package/dist/brain/history-compact.js.map +1 -1
  17. package/dist/brain/index.d.ts +7 -1
  18. package/dist/brain/index.d.ts.map +1 -1
  19. package/dist/brain/index.js +9 -3
  20. package/dist/brain/index.js.map +1 -1
  21. package/dist/brain/model-client.d.ts.map +1 -1
  22. package/dist/brain/model-client.js +58 -1
  23. package/dist/brain/model-client.js.map +1 -1
  24. package/dist/brain/prompts.d.ts +3 -3
  25. package/dist/brain/prompts.d.ts.map +1 -1
  26. package/dist/brain/prompts.js +13 -8
  27. package/dist/brain/prompts.js.map +1 -1
  28. package/dist/brain/system-prompt.d.ts +8 -0
  29. package/dist/brain/system-prompt.d.ts.map +1 -1
  30. package/dist/brain/system-prompt.js +15 -1
  31. package/dist/brain/system-prompt.js.map +1 -1
  32. package/dist/brain/tasks/goal-verification.d.ts +7 -1
  33. package/dist/brain/tasks/goal-verification.d.ts.map +1 -1
  34. package/dist/brain/tasks/goal-verification.js +37 -12
  35. package/dist/brain/tasks/goal-verification.js.map +1 -1
  36. package/dist/cli/build-config.d.ts.map +1 -1
  37. package/dist/cli/build-config.js +9 -4
  38. package/dist/cli/build-config.js.map +1 -1
  39. package/dist/config.js +1 -1
  40. package/dist/design/audit/score-types.d.ts +2 -1
  41. package/dist/design/audit/score-types.d.ts.map +1 -1
  42. package/dist/design/audit/score-types.js +2 -1
  43. package/dist/design/audit/score-types.js.map +1 -1
  44. package/dist/drivers/cdp-snapshot.d.ts.map +1 -1
  45. package/dist/drivers/cdp-snapshot.js +39 -1
  46. package/dist/drivers/cdp-snapshot.js.map +1 -1
  47. package/dist/drivers/playwright.d.ts.map +1 -1
  48. package/dist/drivers/playwright.js +5 -3
  49. package/dist/drivers/playwright.js.map +1 -1
  50. package/dist/drivers/snapshot.d.ts +13 -0
  51. package/dist/drivers/snapshot.d.ts.map +1 -1
  52. package/dist/drivers/snapshot.js +96 -3
  53. package/dist/drivers/snapshot.js.map +1 -1
  54. package/dist/memory/store.d.ts +10 -0
  55. package/dist/memory/store.d.ts.map +1 -1
  56. package/dist/memory/store.js +36 -0
  57. package/dist/memory/store.js.map +1 -1
  58. package/dist/run-state.d.ts +8 -0
  59. package/dist/run-state.d.ts.map +1 -1
  60. package/dist/run-state.js +13 -0
  61. package/dist/run-state.js.map +1 -1
  62. package/dist/runner/completion-policy.d.ts +55 -0
  63. package/dist/runner/completion-policy.d.ts.map +1 -1
  64. package/dist/runner/completion-policy.js +132 -0
  65. package/dist/runner/completion-policy.js.map +1 -1
  66. package/dist/runner/events.d.ts +11 -1
  67. package/dist/runner/events.d.ts.map +1 -1
  68. package/dist/runner/events.js.map +1 -1
  69. package/dist/runner/page-analysis.js +1 -1
  70. package/dist/runner/page-analysis.js.map +1 -1
  71. package/dist/runner/replay/contracts.d.ts +11 -0
  72. package/dist/runner/replay/contracts.d.ts.map +1 -1
  73. package/dist/runner/replay/controller.d.ts.map +1 -1
  74. package/dist/runner/replay/controller.js +10 -0
  75. package/dist/runner/replay/controller.js.map +1 -1
  76. package/dist/runner/runner.d.ts +8 -0
  77. package/dist/runner/runner.d.ts.map +1 -1
  78. package/dist/runner/runner.js +152 -9
  79. package/dist/runner/runner.js.map +1 -1
  80. package/dist/runner/selector-guard.d.ts +27 -0
  81. package/dist/runner/selector-guard.d.ts.map +1 -0
  82. package/dist/runner/selector-guard.js +84 -0
  83. package/dist/runner/selector-guard.js.map +1 -0
  84. package/dist/runner/utils.d.ts +61 -0
  85. package/dist/runner/utils.d.ts.map +1 -1
  86. package/dist/runner/utils.js +92 -0
  87. package/dist/runner/utils.js.map +1 -1
  88. package/dist/test-runner.d.ts.map +1 -1
  89. package/dist/test-runner.js +2 -1
  90. package/dist/test-runner.js.map +1 -1
  91. package/dist/types/result.d.ts +16 -0
  92. package/dist/types/result.d.ts.map +1 -1
  93. package/dist/types/trajectory.d.ts +3 -0
  94. package/dist/types/trajectory.d.ts.map +1 -1
  95. package/package.json +8 -30
  96. package/skills/domain/amazon.com/SKILL.md +14 -0
  97. package/skills/domain/github.com/SKILL.md +15 -0
  98. package/skills/domain/linkedin.com/SKILL.md +14 -0
  99. package/skills/domain/stackoverflow.com/SKILL.md +13 -0
  100. package/skills/domain/wikipedia.org/SKILL.md +15 -0
  101. package/skills/macros/dismiss-cookie-banner.json +11 -0
  102. package/skills/macros/search-and-submit.json +13 -0
@@ -23,7 +23,7 @@ import { deriveWasteMetrics } from '../run-metrics.js';
23
23
  import { RunState, DEFAULT_TOKEN_BUDGET } from '../run-state.js';
24
24
  import { ContextBudget } from '../context-budget.js';
25
25
  import { runOverridePipeline } from '../override-pipeline.js';
26
- import { withRetry, findElementForRef, safeHostname, pushGoalVerificationEvidence } from './utils.js';
26
+ import { withRetry, findElementForRef, safeHostname, pushGoalVerificationEvidence, capFeedbackText, sanitizeRunScript, shouldRejectSurrender } from './utils.js';
27
27
  import { runExtractWithIndex, formatExtractWithIndexResult } from '../drivers/extract-with-index.js';
28
28
  import { buildSearchResultsGuidance, buildVisibleLinkRecommendation, getVisibleLinkRecommendation } from './search-guidance.js';
29
29
  import { buildGoalVerificationClaim, collectSearchWorkflowEvidence, shouldAcceptSearchWorkflowCompletion, shouldAcceptScriptBackedCompletion, detectCompletionContentTypeMismatch } from './goal-verification.js';
@@ -49,7 +49,8 @@ import { containsSelfContradictingCompletion } from './completion-language.js';
49
49
  import { detectBatchFillOpportunity } from './batch-fill.js';
50
50
  import { DEFAULT_MAX_TURNS, DEFAULT_RETRIES, DEFAULT_RETRY_DELAY_MS, DEFAULT_SUPERVISOR, EXTENSION_TURNS_GRANTED, } from './constants.js';
51
51
  import { DEFI_BRAIN_CONTEXT } from './prompt-snippets.js';
52
- import { hasPlaceholderPattern, isMeaningfulRunScriptOutput } from './completion-policy.js';
52
+ import { hasPlaceholderPattern, isMeaningfulRunScriptOutput, synthesizeFinalTurnCompletion, evidenceCorroboratesResult, goalLiteralsCorroborated } from './completion-policy.js';
53
+ import { validateObservedSelector } from './selector-guard.js';
53
54
  import { selectMicroPlanFollowUps } from './micro-plan.js';
54
55
  import { decideMaxTurnsExtension } from './max-turns-extension.js';
55
56
  // Re-export helpers that moved into sibling modules so existing import paths
@@ -227,6 +228,8 @@ export class BrowserAgent {
227
228
  phaseTimings,
228
229
  wasteMetrics: deriveWasteMetrics(turns, runState.verificationRejectionCount, runState.firstSufficientEvidenceTurn),
229
230
  };
231
+ if (replayMetrics && !agentResult.replay)
232
+ agentResult.replay = replayMetrics;
230
233
  this.saveMemory(scenario, agentResult, turns);
231
234
  // Complete run manifest
232
235
  const lastTurn = agentResult.turns[agentResult.turns.length - 1];
@@ -364,6 +367,7 @@ export class BrowserAgent {
364
367
  // the same `turns` array, so the unified timeline is preserved and the loop
365
368
  // offset (`plannerStartTurn`) is advanced past the replayed turns.
366
369
  let replayTurnsConsumed = 0;
370
+ let replayMetrics;
367
371
  if (this.config.replay?.enabled && this.replayPlan && scenario.startUrl) {
368
372
  const replayOutcome = await createReplayController().replay(this.replayPlan, {
369
373
  goal: scenario.goal,
@@ -375,6 +379,13 @@ export class BrowserAgent {
375
379
  ...(this.config.debug ? { debug: true } : {}),
376
380
  onEvent: (event) => this.handleReplayEvent(runId, event),
377
381
  });
382
+ replayMetrics = {
383
+ attempted: true,
384
+ outcome: replayOutcome.kind,
385
+ completedSteps: replayOutcome.completedSteps,
386
+ totalSteps: replayOutcome.totalSteps,
387
+ llmCallsUsed: replayOutcome.llmCallsUsed,
388
+ };
378
389
  for (const turn of replayOutcome.turns) {
379
390
  turns.push(turn);
380
391
  this.onTurn?.(turn);
@@ -1254,6 +1265,16 @@ export class BrowserAgent {
1254
1265
  durationMs: decideDurationMs,
1255
1266
  });
1256
1267
  }
1268
+ // Terminal-action guarantee: on the final turn, a non-terminal action
1269
+ // with script evidence already on the ledger completes from that
1270
+ // evidence instead of dying at max turns with the answer on the floor.
1271
+ const finalTurnCompletion = synthesizeFinalTurnCompletion(action, runState.goalVerificationEvidence, i >= maxTurns - 1);
1272
+ if (finalTurnCompletion.synthesized) {
1273
+ action = finalTurnCompletion.action;
1274
+ if (this.config.debug) {
1275
+ console.log(`[Runner] Final turn — auto-completing from script evidence instead of ${decision.action.action}`);
1276
+ }
1277
+ }
1257
1278
  // -- 4a. Narrate to the cursor overlay. Fire-and-forget.
1258
1279
  // Signals pushed to the page-context overlay:
1259
1280
  // 1. Reasoning panel (top-right) — the agent's own text
@@ -1407,22 +1428,34 @@ export class BrowserAgent {
1407
1428
  // -- 5c. Handle runScript action --
1408
1429
  if (action.action === 'runScript') {
1409
1430
  const page = this.driver.getPage?.();
1410
- if (page) {
1431
+ const sanitized = sanitizeRunScript(action.script);
1432
+ if (!sanitized.ok) {
1433
+ this.brain.injectFeedback(sanitized.error);
1434
+ this.noteExtractionMiss(runState, i);
1435
+ }
1436
+ else if (page) {
1411
1437
  try {
1412
- const scriptResult = await page.evaluate(action.script);
1438
+ const scriptResult = await page.evaluate(sanitized.script);
1413
1439
  const stringified = typeof scriptResult === 'string'
1414
1440
  ? scriptResult
1415
1441
  : JSON.stringify(scriptResult, null, 2);
1416
1442
  runState.firstSufficientEvidenceTurn ??= i;
1417
1443
  pushGoalVerificationEvidence(runState.goalVerificationEvidence, `SCRIPT RESULT:\n${stringified ?? '(undefined)'}`);
1444
+ if (isMeaningfulRunScriptOutput(stringified)) {
1445
+ runState.resetExtractionMisses();
1446
+ }
1447
+ else {
1448
+ this.noteExtractionMiss(runState, i);
1449
+ }
1418
1450
  if (typeof stringified === 'string' && stringified.length > 10) {
1419
1451
  runState.recordEvidence(`EXTRACTED (turn ${i}): ${stringified.slice(0, 500)}`);
1420
1452
  }
1421
- this.brain.injectFeedback(`SCRIPT RESULT:\n${stringified ?? '(undefined)'}`);
1453
+ this.brain.injectFeedback(capFeedbackText(`SCRIPT RESULT:\n${stringified ?? '(undefined)'}`));
1422
1454
  }
1423
1455
  catch (scriptErr) {
1424
1456
  const msg = scriptErr instanceof Error ? scriptErr.message : String(scriptErr);
1425
1457
  this.brain.injectFeedback(`SCRIPT ERROR: ${msg}`);
1458
+ this.noteExtractionMiss(runState, i);
1426
1459
  }
1427
1460
  }
1428
1461
  else {
@@ -1446,14 +1479,21 @@ export class BrowserAgent {
1446
1479
  const formatted = formatExtractWithIndexResult(matches, action.query, action.contains);
1447
1480
  runState.firstSufficientEvidenceTurn ??= i;
1448
1481
  pushGoalVerificationEvidence(runState.goalVerificationEvidence, `EXTRACT RESULT (${matches.length} matches):\n${formatted}`);
1482
+ if (matches.length > 0) {
1483
+ runState.resetExtractionMisses();
1484
+ }
1485
+ else {
1486
+ this.noteExtractionMiss(runState, i);
1487
+ }
1449
1488
  if (formatted.length > 10) {
1450
1489
  runState.recordEvidence(`EXTRACTED (turn ${i}): ${formatted.slice(0, 500)}`);
1451
1490
  }
1452
- this.brain.injectFeedback(`EXTRACT RESULT (${matches.length} matches for query "${action.query}"${action.contains ? ` containing "${action.contains}"` : ''}):\n${formatted}`);
1491
+ this.brain.injectFeedback(capFeedbackText(`EXTRACT RESULT (${matches.length} matches for query "${action.query}"${action.contains ? ` containing "${action.contains}"` : ''}):\n${formatted}`));
1453
1492
  }
1454
1493
  catch (extractErr) {
1455
1494
  const msg = extractErr instanceof Error ? extractErr.message : String(extractErr);
1456
1495
  this.brain.injectFeedback(`EXTRACT ERROR: ${msg}`);
1496
+ this.noteExtractionMiss(runState, i);
1457
1497
  }
1458
1498
  }
1459
1499
  else {
@@ -1541,7 +1581,35 @@ export class BrowserAgent {
1541
1581
  recentErrors === 0 &&
1542
1582
  hasScriptEvidence &&
1543
1583
  !selfContradicting;
1544
- if (fastPathEligible) {
1584
+ // Deterministic corroboration: the claimed JSON echoes SCRIPT
1585
+ // RESULT values field-for-field, OR every quoted literal in the
1586
+ // goal appears verbatim in the final observation/evidence —
1587
+ // hallucination is impossible by construction, so skip the
1588
+ // verifier LLM entirely (the wave-1 over-conservatism case:
1589
+ // correct JSON re-prompted 3x).
1590
+ const corroborated = !selfContradicting
1591
+ && (evidenceCorroboratesResult(agentResult, runState.goalVerificationEvidence)
1592
+ || goalLiteralsCorroborated(scenario.goal, state.snapshot, runState.goalVerificationEvidence, turns.map((t) => t.state.snapshot),
1593
+ // Form-control state evidence: payloads of actions that
1594
+ // executed without error (driver-confirmed fills/selects).
1595
+ turns
1596
+ .filter((t) => !t.error)
1597
+ .flatMap((t) => [JSON.stringify(t.action), ...(t.executedActions ?? []).map((a) => JSON.stringify(a))])));
1598
+ let verificationPath;
1599
+ if (corroborated) {
1600
+ verificationPath = 'corroborated';
1601
+ goalResult = {
1602
+ achieved: true,
1603
+ confidence: 0.9,
1604
+ evidence: ['Evidence-corroborated: every claimed result field matches a SCRIPT RESULT value exactly.'],
1605
+ missing: [],
1606
+ };
1607
+ if (this.config.debug) {
1608
+ console.log('[Runner] Goal verification: accepted via script-evidence corroboration (no LLM call)');
1609
+ }
1610
+ }
1611
+ else if (fastPathEligible) {
1612
+ verificationPath = 'fast-path';
1545
1613
  goalResult = {
1546
1614
  achieved: true,
1547
1615
  confidence: 0.9,
@@ -1556,14 +1624,34 @@ export class BrowserAgent {
1556
1624
  // Force LLM verification — the agent claims success but its
1557
1625
  // own text suggests failure. The LLM verifier reads the actual
1558
1626
  // content and makes the right call.
1627
+ verificationPath = hasScriptEvidence ? 'llm-slim' : 'llm';
1559
1628
  if (this.config.debug) {
1560
1629
  console.log('[Runner] Fast-path blocked: agent result contains self-contradicting language, forcing LLM verification');
1561
1630
  }
1562
- goalResult = await this.brain.verifyGoalCompletion(state, scenario.goal, buildGoalVerificationClaim(agentResult, verificationEvidence));
1631
+ goalResult = await this.brain.verifyGoalCompletion(state, scenario.goal, buildGoalVerificationClaim(agentResult, verificationEvidence), { skipPageState: hasScriptEvidence });
1563
1632
  }
1564
1633
  else {
1565
- goalResult = await this.brain.verifyGoalCompletion(state, scenario.goal, buildGoalVerificationClaim(agentResult, verificationEvidence));
1634
+ verificationPath = hasScriptEvidence ? 'llm-slim' : 'llm';
1635
+ goalResult = await this.brain.verifyGoalCompletion(state, scenario.goal, buildGoalVerificationClaim(agentResult, verificationEvidence), { skipPageState: hasScriptEvidence });
1566
1636
  }
1637
+ // Record the verifier call's own token usage into run metrics —
1638
+ // previously invisible in cost accounting (report.json totals and
1639
+ // events.jsonl). Deterministic paths carry no usage fields.
1640
+ if (goalResult && (goalResult.inputTokens !== undefined || goalResult.outputTokens !== undefined)) {
1641
+ turn.inputTokens = (turn.inputTokens ?? 0) + (goalResult.inputTokens ?? 0);
1642
+ turn.outputTokens = (turn.outputTokens ?? 0) + (goalResult.outputTokens ?? 0);
1643
+ turn.tokensUsed = (turn.tokensUsed ?? 0) + (goalResult.inputTokens ?? 0) + (goalResult.outputTokens ?? 0);
1644
+ }
1645
+ this.bus.emitNow({
1646
+ type: 'goal-verification-completed',
1647
+ runId,
1648
+ turn: i,
1649
+ achieved: goalResult?.achieved === true,
1650
+ path: verificationPath,
1651
+ ...(goalResult?.inputTokens !== undefined ? { inputTokens: goalResult.inputTokens } : {}),
1652
+ ...(goalResult?.outputTokens !== undefined ? { outputTokens: goalResult.outputTokens } : {}),
1653
+ ...(goalResult?.cacheReadInputTokens !== undefined ? { cacheReadInputTokens: goalResult.cacheReadInputTokens } : {}),
1654
+ });
1567
1655
  if (this.config.debug) {
1568
1656
  console.log(`[Runner] Goal verification: achieved=${goalResult.achieved}, confidence=${goalResult.confidence}`);
1569
1657
  }
@@ -1769,6 +1857,29 @@ export class BrowserAgent {
1769
1857
  goalVerification: goalResult,
1770
1858
  });
1771
1859
  }
1860
+ // Premature-surrender guard (fail-closed, same pattern as the
1861
+ // selector guard): an abort with ~zero executed actions and zero
1862
+ // extraction evidence on a reachable page is a confabulation, not a
1863
+ // verdict (the wave-5 dx weather window aborted at turn 1 with the
1864
+ // data visible). Reject it and re-prompt toward the observation.
1865
+ if (shouldRejectSurrender({
1866
+ actionType: action.action,
1867
+ executedTurns: turns.length,
1868
+ evidenceCount: runState.goalVerificationEvidence.length,
1869
+ state,
1870
+ })) {
1871
+ const elementCount = (state.snapshot.match(/\[ref=/g) ?? []).length;
1872
+ this.brain.injectFeedback(`SURRENDER REJECTED: you have not attempted a single action, and the current observation has ${elementCount} interactive elements plus page text. ` +
1873
+ `Invented constraints ("a previous run failed", "the data is not here") are not evidence — the page in front of you is. ` +
1874
+ `Work the goal from the ELEMENTS list and visible text now: extractWithIndex with a wide query or runScript pulls the data directly. ` +
1875
+ `Abort stays available after genuine attempts fail.`);
1876
+ turn.error = 'premature surrender rejected (no actions attempted)';
1877
+ turn.durationMs = Date.now() - turnStart;
1878
+ runState.recordError();
1879
+ turns.push(turn);
1880
+ this.onTurn?.(turn);
1881
+ continue;
1882
+ }
1772
1883
  if (action.action === 'abort') {
1773
1884
  turns.push(turn);
1774
1885
  this.onTurn?.(turn);
@@ -1789,6 +1900,20 @@ export class BrowserAgent {
1789
1900
  this.onTurn?.(turn);
1790
1901
  continue;
1791
1902
  }
1903
+ // Fail-closed on guessed CSS selectors: a selector that appears in
1904
+ // neither the observation nor the run's own evidence is a
1905
+ // hallucination — executing it burns the turn and invites the
1906
+ // blind-selector loop. Reject with the recovery path named.
1907
+ const guessedSelector = validateObservedSelector(action, state.snapshot, runState.goalVerificationEvidence);
1908
+ if (guessedSelector) {
1909
+ this.brain.injectFeedback(guessedSelector);
1910
+ turn.error = guessedSelector;
1911
+ turn.durationMs = Date.now() - turnStart;
1912
+ runState.recordError();
1913
+ turns.push(turn);
1914
+ this.onTurn?.(turn);
1915
+ continue;
1916
+ }
1792
1917
  // -- 7. Execute (with stale-ref auto-retry) --
1793
1918
  // Wall-clock cap: entire execute chain (including overlay recovery and retries)
1794
1919
  // gets a hard 45s cap. Prevents heavy JS sites from consuming
@@ -2076,6 +2201,24 @@ export class BrowserAgent {
2076
2201
  totalMs: Date.now() - startTime,
2077
2202
  });
2078
2203
  }
2204
+ /**
2205
+ * Track an unproductive extraction attempt and, at the threshold, tell the
2206
+ * model to stop digging. The counter deliberately does NOT reset when the
2207
+ * model alternates between runScript and extractWithIndex — the wave-4
2208
+ * 15-turn dashboard-extract loop was exactly that oscillation, and the
2209
+ * error-based abort ladder reset on every strategy switch.
2210
+ */
2211
+ noteExtractionMiss(runState, turn) {
2212
+ const misses = runState.recordExtractionMiss();
2213
+ if (misses === 4) {
2214
+ this.brain.injectFeedback(`STOP DIGGING: ${misses} consecutive extraction attempts have failed (rejected scripts, script errors, or empty results, across any strategy). ` +
2215
+ `Do NOT call runScript or extractWithIndex again. Review the data ALREADY in this conversation (page snapshots, earlier results) and either ` +
2216
+ `complete now with your best available answer, try ONE page navigation if the data is on a different page, or abort with the specific blocker.`);
2217
+ if (this.config.debug) {
2218
+ console.log(`[Runner] Extraction miss threshold hit at turn ${turn} — hard-stop feedback injected`);
2219
+ }
2220
+ }
2221
+ }
2079
2222
  selectFollowUpActions(primaryAction, nextActions) {
2080
2223
  return selectMicroPlanFollowUps(primaryAction, nextActions, this.config.microPlan);
2081
2224
  }