localagentbrowser-cleanroom 1.67__py3-none-any.whl

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.
agent_browser.py ADDED
@@ -0,0 +1,24 @@
1
+ """LocalAgentBrowser: an autonomous web agent driven by a local language model.
2
+
3
+ Run: python agent_browser.py (or `localagentbrowser` once installed; it asks for the objective)
4
+
5
+ The code lives in the localagentbrowser package (see its __init__.py for how it is organized). This file keeps
6
+ `python agent_browser.py` working from a clone, and `import agent_browser` working for the tests and tools: it
7
+ gives access to every name in the package. To replace a part of the agent in a test, patch the module that
8
+ uses it (for example localagentbrowser.agent.AsyncOpenAI), not this file.
9
+ """
10
+ from localagentbrowser.config import * # noqa: F403
11
+ from localagentbrowser.prompts import * # noqa: F403
12
+ from localagentbrowser.text import * # noqa: F403
13
+ from localagentbrowser.pages import * # noqa: F403
14
+ from localagentbrowser.grounding import * # noqa: F403
15
+ from localagentbrowser.dates import * # noqa: F403
16
+ from localagentbrowser.checklist import * # noqa: F403
17
+ from localagentbrowser.coverage import * # noqa: F403
18
+ from localagentbrowser.checks import * # noqa: F403
19
+ from localagentbrowser.report import * # noqa: F403
20
+ from localagentbrowser.agent import * # noqa: F403
21
+ from localagentbrowser.agent import main, run # noqa: F401
22
+
23
+ if __name__ == "__main__":
24
+ run()
@@ -0,0 +1,26 @@
1
+ """LocalAgentBrowser: an autonomous web agent driven by a local language model.
2
+
3
+ A model served by LM Studio decides, one JSON action at a time, whether to SEARCH, NAVIGATE, READ_MORE,
4
+ DISCOVER or FINISH; Playwright carries the actions out in a visible Chromium window. Everything the
5
+ agent does and finds is written to research_log.txt.
6
+
7
+ Run: python agent_browser.py (or `localagentbrowser` once installed; it asks for the objective)
8
+
9
+ Settings (environment variables):
10
+ LMSTUDIO_BASE_URL OpenAI-compatible server address (default http://localhost:1234/v1)
11
+ LMSTUDIO_MODEL model identifier (default qwen2.5-7b-instruct)
12
+ LMSTUDIO_API_KEY API key, if the server needs one (default lm-studio)
13
+ LMSTUDIO_CONTEXT_LENGTH context length the model is loaded with (default 8192)
14
+
15
+ The package, one file per job; each imports only from the ones listed before it:
16
+ config settings and every limit and threshold
17
+ prompts every fixed text the model reads
18
+ text small word helpers the checks share
19
+ pages search results, page parts, the outline and its pointer, links
20
+ grounding whether a finding is really on the page shown, or already recorded
21
+ checklist the objective split into a fixed checklist; findings linked to its items
22
+ coverage the coverage check before finishing, verified in code
23
+ checks decisions refused or confirmed before they are carried out
24
+ report the journal, research log, final result and report file
25
+ agent the loop: each turn's conversation with the model, and main()
26
+ """
@@ -0,0 +1,558 @@
1
+ """The agent loop: each turn's conversation with the model, the fresh prompt, in-turn retries, and main()."""
2
+ import asyncio
3
+ import ipaddress
4
+ import json
5
+ import re
6
+ import socket
7
+ import urllib.parse
8
+ from openai import APIConnectionError, APITimeoutError, AsyncOpenAI, BadRequestError, InternalServerError
9
+ from playwright.async_api import async_playwright
10
+ from .config import API_KEY, BASE_URL, CHROMIUM_ARGS, MAX_CHEAP_RETRIES, MAX_CONVERSATION_TOKENS, MAX_DISCOVERY_PROMPT_CHARS, MAX_FOLLOWUPS, MAX_JSON_RETRIES, MAX_QUERY_WORDS, MAX_VISITS_PER_URL, MODEL, MODEL_RETRY_WAITS, MODEL_TIMEOUT_SECONDS, TURN_MAX_TOKENS, OBJECTIVE_CHECK_EVERY, REPORT_FILE, STALL_TURNS, TURN_PAUSE_SECONDS
11
+ from .prompts import CUT_OFF, FINAL_RESULT, FIRST_TURN_INSTRUCTION, GIVE_UP_RULE, READ_FIRST, RESPONSE_FORMAT, SYSTEM_PROMPT, TURN_INSTRUCTIONS
12
+ from .text import extract_message_content, was_cut_off
13
+ from .pages import build_environment, count_search_results, determine_url, is_search_page, load_page, normalize_url, read_more_target, render_part, search_query, section_heading, where_you_are, with_inner_headings, mark_refusing, site_of, site_refusal
14
+ from .checklist import after_discovery_advice, check_parts, checklist_lines, link_discovery, split_objective
15
+ from .coverage import amounts_not_found, coverage_refusal, not_found_items, record_install_line, remember_install_lines
16
+ from .checks import check_decision, escalation_message, numbered_discoveries, numbered_lines, refusal_correction, source_note
17
+ from . import windows
18
+ from .report import compact_journal, compose_final_result, visited_summary, write_report, write_research_log
19
+
20
+ def new_conversation():
21
+ return {"messages": None, "followups": 0, "tokens": 0, "note": None, "note_url": None, "shown_links": set()}
22
+
23
+ def set_note(conversation, note, current_url):
24
+ # A note is only used if the agent is still on the page it describes when the next turn starts
25
+ conversation.update(note=note, note_url=normalize_url(current_url) if current_url else None)
26
+
27
+ async def run_agent_turn(client, page, objective, journal, current_url, tried, page_state, conversation, loop_warning=None):
28
+ warning_prompt = f"\n\n⚠️ LOOP DETECTION WARNING: {loop_warning}" if loop_warning else ""
29
+
30
+ # Turns continue the previous conversation: LM Studio has already processed all of it, so only the
31
+ # note about what changed (a result, a new page part, or a whole new page) is new. Too many
32
+ # follow-ups, or a conversation nearing the context limit, starts over with a full prompt.
33
+ note = conversation["note"]
34
+ estimated_tokens = conversation["tokens"] + len(note or "") // 3
35
+ if (conversation["messages"] and note and current_url
36
+ and conversation["note_url"] == normalize_url(current_url)
37
+ and conversation["followups"] < MAX_FOLLOWUPS
38
+ and estimated_tokens < MAX_CONVERSATION_TOKENS):
39
+ conversation["followups"] += 1
40
+ print(f"⚡ Continuing the conversation (follow-up {conversation['followups']}/{MAX_FOLLOWUPS}, ~{estimated_tokens} tokens)")
41
+ messages = conversation["messages"] + [{"role": "user", "content": f"{note}{warning_prompt}\n\n{TURN_INSTRUCTIONS}"}]
42
+ else:
43
+ conversation.update(followups=0, shown_links=set())
44
+ messages = await build_full_prompt(page, objective, journal, current_url, tried, page_state, warning_prompt, conversation["shown_links"])
45
+ conversation["note"] = None
46
+
47
+ decision, refused, messages, tokens = await request_decision(client, messages, journal, tried, page_state, current_url)
48
+ conversation.update(messages=messages, tokens=tokens)
49
+ return decision, refused
50
+
51
+ async def build_full_prompt(page, objective, journal, current_url, tried, page_state, warning_prompt, shown_links=None):
52
+ print("🔍 Scraping and preparing current environment text layout...")
53
+ environment = await build_environment(page, current_url, page_state, {normalize_url(u) for u in tried["urls"]}, shown_links)
54
+
55
+ # Shortened in the prompt (the full text is in the log and the report, and duplicates are checked against
56
+ # it in code): the growing discoveries list had become a quarter of every fresh prompt
57
+ discoveries = "\n".join(numbered_lines(journal, MAX_DISCOVERY_PROMPT_CHARS)) or "[None yet]"
58
+ recent_journal = compact_journal(journal)
59
+
60
+ # LM Studio only reuses the part of the prompt that is identical to the previous turn's, up to the
61
+ # first change. Sections are ordered from least to most often changed, carry no counters, and the
62
+ # journal only grows at its end, so each turn mostly adds text instead of changing earlier text.
63
+ # The page content goes last, where small models pay the most attention.
64
+ user_payload = f"""### HIGH-LEVEL OBJECTIVE
65
+ {objective}
66
+
67
+ ### DISCOVERIES SO FAR
68
+ {discoveries}
69
+
70
+ ### OBJECTIVE CHECKLIST (every part of the objective, with the discoveries recorded for each)
71
+ {checklist_lines(tried.get("checklist")) or "[None]"}
72
+
73
+ ### RECENT RESEARCH JOURNAL
74
+ {recent_journal}
75
+
76
+ ### ALREADY TRIED
77
+ Queries (do not repeat): {json.dumps(tried["queries"]) if tried["queries"] else "[None]"}
78
+ URLs visited (you may return to one that still has information you need, at most {MAX_VISITS_PER_URL} visits each): {visited_summary(tried["urls"])}
79
+
80
+ ### CURRENT ENVIRONMENT
81
+ Active URL: {current_url if current_url else "None (Loop Initializing)"}
82
+ {environment}{warning_prompt}
83
+
84
+ {"" if journal else FIRST_TURN_INSTRUCTION}{TURN_INSTRUCTIONS}"""
85
+ return [
86
+ {"role": "system", "content": SYSTEM_PROMPT},
87
+ {"role": "user", "content": user_payload}
88
+ ]
89
+
90
+ PATH_ESCAPES = {"\t": "\\t", "\r": "\\r", "\b": "\\b", "\f": "\\f"}
91
+
92
+ def restore_path_escapes(text):
93
+ """Undoes JSON escapes the model did not mean: recording the Windows command "python -m venv
94
+ C:\\path\\to\\new\\virtual\\environment", it wrote single backslashes, and its \\t, \\n and \\r became a tab, a
95
+ newline and a carriage return. A tab, carriage return, backspace or form feed right before a letter is
96
+ treated as such a path; a newline is only restored where it sits between word characters (as in "to\\new").
97
+ Only text that also has a backslash or a drive letter is touched: page tables are read with real tabs."""
98
+ if not re.search(r"[\t\r\b\f][A-Za-z]", text) or not re.search(r"\\|\b[A-Za-z]:[\\\"\t\r\b\f\n]", text):
99
+ return text
100
+ text = re.sub(r"(?<=\w)\n(?=[a-z])", r"\\n", text)
101
+ return re.sub(r"[\t\r\b\f](?=[A-Za-z])", lambda m: PATH_ESCAPES[m.group()], text)
102
+
103
+ def cut_decision(raw, on_search_page=False):
104
+ """The SEARCH, NAVIGATE or READ_MORE in a reply cut off inside its parameter, the parameter ending where it
105
+ starts to repeat itself; None when the cut came earlier, or for a DISCOVER or FINISH, whose cut text is never
106
+ sound (every cut DISCOVER in the 3B's runs was its own looping words, and one of them got recorded). On the
107
+ results page a DISCOVER is kept: it is always refused there, and the refusal says to open a result, which the
108
+ plain cut-off note did not (three cut DISCOVERs there lost a turn)."""
109
+ found = re.match(r'\s*\{\s*"thought_process"\s*:\s*"((?:[^"\\]|\\.)*)"\s*,\s*"action"\s*:\s*"([A-Z_]+)"\s*,'
110
+ r'\s*"parameter"\s*:\s*"((?:[^"\\]|\\.)*)', raw)
111
+ if not found or found.group(2) not in ("SEARCH", "NAVIGATE", "READ_MORE", *(("DISCOVER",) if on_search_page else ())):
112
+ return None
113
+ thought, action, parameter = (json.loads(f'"{text.rstrip(chr(92))}"') for text in found.groups())
114
+ words = parameter.split()
115
+ # The cut parameters looped ("...comprehensive guide for beginners professionals cold brew coffee making..."
116
+ # again and again): the first six words seen twice mark where the loop began
117
+ seen = set()
118
+ for i in range(len(words) - 5):
119
+ run = tuple(w.lower() for w in words[i:i + 6])
120
+ if run in seen:
121
+ words = words[:i]
122
+ break
123
+ seen.add(run)
124
+ if action == "SEARCH":
125
+ words = words[:MAX_QUERY_WORDS]
126
+ return {"thought_process": thought, "action": action, "parameter": " ".join(words), "checklist_items": []} if words else None
127
+
128
+ async def request_decision(client, messages, journal, tried, page_state, current_url):
129
+ # Cheap retries: a reply that is invalid or would be refused is answered with a short correction
130
+ # appended to the same conversation. Everything before the correction is identical to what LM Studio
131
+ # just processed, so it only reads the correction instead of the whole prompt again. Resending the
132
+ # prompt unchanged would not help: the same prompt returns the same answer.
133
+ messages = list(messages)
134
+ refused = []
135
+ json_failures = 0
136
+ while True:
137
+ response = await client.chat.completions.create(
138
+ model=MODEL,
139
+ messages=messages,
140
+ temperature=0.2,
141
+ max_tokens=TURN_MAX_TOKENS,
142
+ response_format=RESPONSE_FORMAT
143
+ )
144
+ original_content = extract_message_content(response)
145
+ raw_content = original_content
146
+
147
+ if raw_content.startswith("```"):
148
+ raw_content = re.sub(r'^```json\s*|^```\s*|```$', '', raw_content, flags=re.MULTILINE).strip()
149
+
150
+ try:
151
+ action_decision = json.loads(raw_content)
152
+ if not isinstance(action_decision, dict):
153
+ raise ValueError("the reply was JSON but not an object")
154
+ for key in ("parameter", "thought_process"):
155
+ if isinstance(action_decision.get(key), str):
156
+ action_decision[key] = restore_path_escapes(action_decision[key])
157
+ except (json.JSONDecodeError, ValueError) as parse_err:
158
+ # A 3B model's search queries looped through the same words until the cap, three times in a row; their
159
+ # start is a usable decision, which the checks below judge like any other
160
+ action_decision = cut_decision(raw_content, is_search_page(current_url)) if was_cut_off(response) else None
161
+ if action_decision:
162
+ print(f"✂️ The reply was cut off inside its parameter; going on with its start: [{action_decision['action']}] {action_decision['parameter'][:120]}")
163
+ else:
164
+ json_failures += 1
165
+ print(f"⚠️ Model returned invalid JSON (attempt {json_failures}/{MAX_JSON_RETRIES}): {raw_content[:200]}")
166
+ if json_failures >= MAX_JSON_RETRIES:
167
+ raise ValueError(f"No valid JSON decision after {MAX_JSON_RETRIES} attempts.") from parse_err
168
+ if was_cut_off(response):
169
+ # A 3B model's replies ran past the cap in 25 replies of one suite; asked only for valid JSON, it
170
+ # wrote the same long reply again, and 8 turns were lost. The cut reply is left out, so the model
171
+ # is not shown a long reply to continue.
172
+ messages += [{"role": "user", "content": CUT_OFF.format(limit=TURN_MAX_TOKENS)}]
173
+ continue
174
+ messages += [{"role": "assistant", "content": original_content},
175
+ {"role": "user", "content": f"That reply was not a valid JSON object ({parse_err}). Reply with only the JSON object in the mandatory format."}]
176
+ continue
177
+
178
+ action = str(action_decision.get("action", "FINISH")).upper()
179
+ parameter = str(action_decision.get("parameter", "")).strip()
180
+ refusal = check_decision(action, parameter, journal, tried, page_state, current_url,
181
+ action_decision.get("thought_process", ""))
182
+ if not refusal or len(refused) >= MAX_CHEAP_RETRIES:
183
+ usage = getattr(response, "usage", None)
184
+ tokens = (getattr(usage, "prompt_tokens", 0) or 0) + (getattr(usage, "completion_tokens", 0) or 0)
185
+ return action_decision, refused, messages + [{"role": "assistant", "content": original_content}], tokens
186
+
187
+ refused.append({"action": action, "parameter": parameter, "journal_action": refusal[0], "reason": refusal[1]})
188
+ print(f"♻️ Cheap retry {len(refused)}/{MAX_CHEAP_RETRIES}: [{action}] refused. {refusal[1]}")
189
+ correction = refusal_correction(action, refusal[1], page_state, current_url)
190
+ if refusal[0].startswith("CONFIRM_"):
191
+ # Not a true refusal: repeating the action is an allowed answer, so no "do not repeat" wording
192
+ correction = f"CHECK: {refusal[1]} Reply with only the JSON object."
193
+ elif refusal[0] in ("BLOCKED_NOT_ON_PAGE", "BLOCKED_CODE_NOT_ON_PAGE") and len(refused) < 2:
194
+ # The refusal says what to do instead (DISCOVER the quoted sentence or read on); with the usual "Do NOT
195
+ # choose DISCOVER ... choose a different action" around it, the model read on 3 times out of 3 past the
196
+ # sentence it was shown
197
+ correction = f"REFUSED: {refusal[1]} Reply with only the JSON object."
198
+ elif len(refused) >= 2:
199
+ correction = escalation_message(len(refused), action, refusal[1], page_state, current_url) + "\nReply with only the JSON object."
200
+ messages += [{"role": "assistant", "content": original_content}, {"role": "user", "content": correction}]
201
+
202
+
203
+ def is_local_server():
204
+ return bool(re.match(r"https?://(localhost|127\.0\.0\.1|\[::1\])(:|/|$)", BASE_URL))
205
+
206
+ def on_this_pc_or_network(url):
207
+ """Whether a server address is on this PC or the local network: every address its name stands for is a
208
+ loopback, private (home or office network) or link-local one. A name that cannot be looked up is not."""
209
+ host = urllib.parse.urlsplit(url).hostname
210
+ if not host:
211
+ return False
212
+ try:
213
+ addresses = {info[4][0] for info in socket.getaddrinfo(host, None)}
214
+ except (OSError, UnicodeError):
215
+ return False
216
+ for address in addresses:
217
+ ip = ipaddress.ip_address(address.split("%")[0])
218
+ if not (ip.is_loopback or ip.is_private or ip.is_link_local):
219
+ return False
220
+ return bool(addresses)
221
+
222
+ def server_allowed():
223
+ """Whether the run may use the model server it is set to. The Clean Room edition (a private edition) only talks
224
+ to a model server on this PC or the local network, whatever LMSTUDIO_BASE_URL says; the full edition takes any."""
225
+ return on_this_pc_or_network(BASE_URL)
226
+
227
+
228
+ def failure_advice(err):
229
+ """What a failed model call means and what to do, for the server the run actually uses."""
230
+ return f"Check that LM Studio is running at {BASE_URL} and model '{MODEL}' is loaded."
231
+
232
+
233
+
234
+ def with_retries(client):
235
+ """The client, with each model call tried again when the server fails it (no connection, or a server error).
236
+
237
+ A failed call used to end the run at once. LM Studio's server loads a model by itself when a request names one
238
+ that is not loaded (it unloads idle ones too), so waiting and trying again carries a run through an unloaded
239
+ model or a restarted app. Only failures of the server are retried: a reply that cannot be used is handled where
240
+ it is read, as before. A model unloaded in the middle of a call does not drop the connection: LM Studio answers
241
+ that call with "400 - Model unloaded by user or API request", so that refusal is retried too. A timeout is not
242
+ retried: the server is up but the model has not finished, and a 3B model that kept writing for 10 minutes kept
243
+ writing when the same request was sent again.
244
+ """
245
+ create = client.chat.completions.create
246
+
247
+ async def create_with_retries(*args, **kwargs):
248
+ server_waits = iter(MODEL_RETRY_WAITS)
249
+ while True:
250
+ try:
251
+ response = await create(*args, **kwargs)
252
+ except (APIConnectionError, InternalServerError, BadRequestError) as err:
253
+ retried = isinstance(err, BadRequestError) and re.search(r"\b(unloaded|not loaded)\b", str(err), re.I)
254
+ wait = next(server_waits, None)
255
+ if wait is None or isinstance(err, APITimeoutError) or (isinstance(err, BadRequestError) and not retried):
256
+ raise
257
+ hint = "LM Studio loads the model again by itself if it was unloaded."
258
+ print(f"⚠️ The model server failed the call ({type(err).__name__}: {err}). Trying again in {wait} s; {hint}")
259
+ await asyncio.sleep(wait)
260
+ continue
261
+ return response
262
+
263
+ client.chat.completions.create = create_with_retries
264
+ return client
265
+
266
+ async def main():
267
+ if not server_allowed():
268
+ print(f"❌ The model server {BASE_URL} is not on this PC or your local network, and this edition only uses one "
269
+ "that is. Set LMSTUDIO_BASE_URL to LM Studio's address (default http://localhost:1234/v1).")
270
+ return
271
+ # The client's own silent retries are off (its default retried a timed-out runaway reply twice); with_retries
272
+ # decides what is tried again
273
+ client = with_retries(AsyncOpenAI(
274
+ base_url=BASE_URL,
275
+ api_key=API_KEY,
276
+ max_retries=0,
277
+ timeout=MODEL_TIMEOUT_SECONDS,
278
+ ))
279
+
280
+ # A person's run (not a test run): the console full size until the browser opens beside it
281
+ windows.maximize_console()
282
+ print("🤖 ==================================================== 🤖")
283
+ print("🚀 Initializing Autonomous Discovery Agent Setup...")
284
+ objective = input("🎯 Define the Agent's High-Level Objective: ").strip()
285
+ if not objective:
286
+ print("⚠️ Objective cannot be empty.")
287
+ return
288
+
289
+ journal = []
290
+ current_url = None
291
+ turn_counter = 1
292
+ max_turns = 100
293
+ tried = {"queries": [], "urls": [], "objective": objective}
294
+ # The first model call reads the whole prompt with nothing cached yet: on a CPU it takes a minute or two, and a
295
+ # silent console looked frozen to a first-time user
296
+ print("📋 Splitting the objective into a checklist... (the first step takes a minute or two on a CPU)")
297
+ tried["checklist"] = await split_objective(client, objective)
298
+ print("📋 Objective checklist:\n" + checklist_lines(tried["checklist"]))
299
+ page_state = {"url": None, "parts": [], "index": 0}
300
+ conversation = new_conversation()
301
+ loop_msg = None
302
+ consecutive_refusals = 0
303
+ turns_without_discovery = 0
304
+ turns_since_objective_check = 0
305
+ stop_reason = None
306
+
307
+ async with async_playwright() as p:
308
+ # Side by side for a person watching: the browser on the right half and the console on the left, with the
309
+ # page zoomed out so it is laid out about as wide as in a test run (windows.py); test runs are unchanged
310
+ side_by_side = windows.browser_args()
311
+ browser = await p.chromium.launch(headless=False, args=[*side_by_side, *CHROMIUM_ARGS])
312
+ # No user_agent override: headed Chromium already reports a real, version-matched Chrome UA
313
+ context = await browser.new_context(
314
+ java_script_enabled=True,
315
+ **({"no_viewport": True} if side_by_side else {"viewport": {"width": 1280, "height": 720}})
316
+ )
317
+ page = await context.new_page()
318
+
319
+ try:
320
+ while turn_counter <= max_turns:
321
+ print(f"\n🧠 [TURN {turn_counter}/{max_turns}] Active reasoning cycle executing...")
322
+ tried["finish_confirmed"] = False # The finish check runs once per turn
323
+ remember_install_lines(tried, page_state)
324
+
325
+ try:
326
+ decision, refused = await run_agent_turn(client, page, objective, journal, current_url, tried, page_state, conversation, loop_warning=loop_msg)
327
+ thought = decision.get("thought_process", "No reasoning recorded.")
328
+ action = str(decision.get("action", "FINISH")).upper()
329
+ parameter = str(decision.get("parameter", "")).strip()
330
+ loop_msg = None
331
+ except ValueError as parse_err:
332
+ print(f"⚠️ {parse_err} Skipping turn.")
333
+ journal.append({"turn": turn_counter, "action": "INVALID_OUTPUT", "error": str(parse_err)})
334
+ turn_counter += 1
335
+ continue
336
+ except Exception as err:
337
+ print(f"❌ The model call failed: {err}")
338
+ print(f"💡 {failure_advice(err)}")
339
+ stop_reason = f"the model call failed ({str(err)[:300]})"
340
+ break
341
+
342
+ # Replies refused and retried within this turn stay in the journal so the model sees what failed;
343
+ # "check" names the check that refused them, for counting in the regression runs (not shown to the model)
344
+ for r in refused:
345
+ journal.append({"turn": turn_counter, "action": "REFUSED_IN_TURN", "requested": f"{r['action']} {r['parameter'][:120]}", "reason": r["reason"],
346
+ "check": r["journal_action"]})
347
+
348
+ print(f"💡 Agent Thoughts: {thought}")
349
+ print(f"🎬 Chosen Action: [{action}] -> Parameter: {parameter}")
350
+
351
+ refusal = check_decision(action, parameter, journal, tried, page_state, current_url, thought)
352
+ if not refusal and action == "FINISH":
353
+ refusal = await coverage_refusal(client, objective, tried, journal)
354
+ if refusal:
355
+ # Only reached once this turn's cheap retries are used up
356
+ print(f"⚠️ Action refused: {refusal[1]}")
357
+ journal.append({"turn": turn_counter, "thought": thought, "action": refusal[0], "requested": parameter, "reason": refusal[1]})
358
+ loop_msg = f"Your {action} was refused. {refusal[1]}"
359
+ set_note(conversation, f"RESULT: Nothing changed. {where_you_are(page_state, current_url)}", current_url)
360
+ if refusal[0] == "BLOCKED_COVERAGE":
361
+ # The coverage prompts pushed the conversation out of LM Studio's cache, and re-reading it took
362
+ # 626-651 s; a fresh prompt is shorter and starts with the system prompt they left cached
363
+ conversation["messages"] = None
364
+
365
+ elif action == "FINISH":
366
+ print("\n🎯 Agent has signaled mission complete. Writing the final result...")
367
+ # "writing" is cleared only once the final result is written: stopped during the checks before it
368
+ # (a 14B model ran into the test's time limit there), the report said "finished" over the model's
369
+ # unchecked FINISH text
370
+ finish_entry = {"turn": turn_counter, "thought": thought, "action": "FINISH", "finding": parameter,
371
+ "writing": True}
372
+ remember_install_lines(tried, page_state)
373
+ added = record_install_line(tried, journal, turn_counter)
374
+ if added:
375
+ print(f"📝 Recorded by the code: the install command the page gives ({added['source']}): "
376
+ f"{added['extracted_data'][:120]}")
377
+ journal.append(finish_entry)
378
+ try:
379
+ missing, unproven = await not_found_items(client, objective, tried, journal)
380
+ no_amounts = amounts_not_found(tried.get("checklist"), journal, skip=missing)
381
+ final = await compose_final_result(client, objective, journal, tried.get("checklist"), missing,
382
+ unproven, no_amounts, tried.get("evidence"),
383
+ tried.get("short_counts"))
384
+ if final:
385
+ finish_entry.update(draft=parameter, finding=final)
386
+ except Exception as err:
387
+ print(f"⚠️ Could not write the final result separately ({err}); keeping the agent's FINISH text.")
388
+ finish_entry.pop("writing", None)
389
+ break
390
+
391
+ elif action in ["SEARCH", "NAVIGATE"]:
392
+ target_url = determine_url(action, parameter)
393
+ print(f"🌐 Driving Playwright to cross-domain target: {target_url}")
394
+ try:
395
+ response = await load_page(page, target_url)
396
+ current_url = page.url
397
+ status = getattr(response, "status", None) or 0
398
+
399
+ if action == "SEARCH":
400
+ # The search engine sometimes returns an error page; reload once before giving up
401
+ if await count_search_results(page) == 0:
402
+ print("⚠️ Search returned no results. Retrying once...")
403
+ await asyncio.sleep(3)
404
+ await load_page(page)
405
+ current_url = page.url
406
+ if await count_search_results(page) == 0:
407
+ print("❌ Search still returned no results.")
408
+ journal.append({"turn": turn_counter, "thought": thought, "action": "FAILED_SEARCH", "requested": parameter,
409
+ "error": "No results (search engine error or no matches). This query may be tried again."})
410
+ else:
411
+ tried["queries"].append(search_query(parameter))
412
+ journal.append({"turn": turn_counter, "thought": thought, "action": action, "requested": parameter, "destination": current_url})
413
+ else:
414
+ tried["urls"].append(target_url)
415
+ if normalize_url(current_url) != normalize_url(target_url):
416
+ tried["urls"].append(current_url) # Also remember where redirects landed
417
+ refused = await site_refusal(page, status)
418
+ if refused:
419
+ # The site turned the browser away (403, 429 or a "verify you are human" page): every
420
+ # later visit to it is refused in code and it leaves the search results. Gemma 3 4B
421
+ # went back to alternativeto.net six times after its first 403, each a lost turn
422
+ mark_refusing(current_url, refused)
423
+ mark_refusing(target_url, refused)
424
+ print(f"⛔ {site_of(target_url)} refused the visit ({refused}); it is blocked for the rest of this run.")
425
+ journal.append({"turn": turn_counter, "thought": thought, "action": "FAILED_NAVIGATE", "requested": parameter,
426
+ "error": f"The site refused the visit ({refused}). It will refuse again, so "
427
+ f"{site_of(target_url)} is blocked for the rest of this run: use another site."})
428
+ elif status >= 400:
429
+ # Often a guessed URL; reported as a failure so the model does not treat the
430
+ # error page as content (and is not asked to record something from it)
431
+ print(f"❌ The page returned HTTP {status}.")
432
+ journal.append({"turn": turn_counter, "thought": thought, "action": "FAILED_NAVIGATE", "requested": parameter,
433
+ "error": f"The page returned HTTP {status} (for example 404: not found). "
434
+ "Use a link shown on a page or in search results instead of guessing URLs."})
435
+ else:
436
+ journal.append({"turn": turn_counter, "thought": thought, "action": action, "requested": parameter, "destination": current_url})
437
+ except Exception as b_err:
438
+ print(f"❌ Failed to reach target destination: {b_err}")
439
+ if action == "NAVIGATE":
440
+ tried["urls"].append(target_url)
441
+ journal.append({"turn": turn_counter, "thought": thought, "action": f"FAILED_{action}", "requested": parameter, "error": str(b_err)})
442
+
443
+ # The new page joins the running conversation instead of forcing a full prompt rebuild
444
+ outcome = journal[-1]
445
+ if "error" in outcome:
446
+ result = f"RESULT: {outcome['action']} '{parameter}' failed: {outcome['error'][:200]}"
447
+ else:
448
+ added = search_query(parameter) if action == "SEARCH" else target_url
449
+ result = f"RESULT: {action} '{parameter}' done. ALREADY TRIED now also includes: {added}"
450
+ if action == "NAVIGATE":
451
+ visits = [normalize_url(u) for u in tried["urls"]].count(normalize_url(target_url))
452
+ result = f"RESULT: NAVIGATE '{parameter}' done (visit {visits} of {MAX_VISITS_PER_URL} allowed for this URL)."
453
+ environment = await build_environment(page, current_url, page_state, {normalize_url(u) for u in tried["urls"]}, conversation["shown_links"])
454
+ if "error" in outcome and page_state["url"] == normalize_url(current_url):
455
+ page_state["leave_confirmed"] = True # Nothing to record on an error page
456
+ set_note(conversation, f"{result}\n\n### CURRENT ENVIRONMENT (replaces the earlier one)\n"
457
+ f"Active URL: {current_url}\n{environment}", current_url)
458
+
459
+ elif action == "READ_MORE":
460
+ target = read_more_target(parameter, page_state)
461
+ page_state["index"] = target
462
+ page_state.setdefault("seen_parts", {0}).add(target)
463
+ print(f"📖 Showing part {target + 1} of {len(page_state['parts'])} of the current page.")
464
+ journal.append({"turn": turn_counter, "thought": thought, "action": "READ_MORE", "part": f"{target + 1} of {len(page_state['parts'])}"})
465
+ set_note(conversation, f"RESULT: READ_MORE done. {where_you_are(page_state, current_url)} "
466
+ f"The CURRENT ENVIRONMENT now shows:\n{render_part(page_state)}\n"
467
+ f"The links listed earlier for this page still apply.", current_url)
468
+
469
+ elif action == "DISCOVER":
470
+ print(f"📝 Logging critical discovery element: {parameter}")
471
+ number = sum(1 for e in journal if e.get("action") == "DISCOVER") + 1
472
+ linked = link_discovery(tried["checklist"], decision.get("checklist_items"), number)
473
+ # Recorded with its section's heading when the copied text does not name it (the heading is page
474
+ # text too): every later check and the final result then see what the lines are about
475
+ heading = section_heading(page_state, parameter)
476
+ inner = with_inner_headings(page_state, parameter)
477
+ recorded = f'(Under the heading "{heading}") {inner}' if heading else inner
478
+ journal.append({"turn": turn_counter, "thought": thought, "action": "DISCOVER", "source": current_url,
479
+ "extracted_data": recorded, "checklist_items": linked})
480
+ page_state["visit_discoveries"] = page_state.get("visit_discoveries", 0) + 1
481
+ page_state.setdefault("recorded_parts", set()).add(page_state["index"])
482
+ # A discovery is when the objective can become complete; on a one-answer question the model
483
+ # recorded the full answer, said "the objective has been met", then kept reading for
484
+ # "interesting" details, so completion is checked right here. On an explanation task it recorded
485
+ # the Calvin cycle step by step while the light reactions were still missing, so the note also
486
+ # points to the parts not yet covered, and the checklist with its discoveries shows which ones are open
487
+ linked_note = (f" for checklist item {', '.join(map(str, linked))}" if linked else
488
+ " (linked to no checklist item)")
489
+ set_note(conversation, f"RESULT: Your DISCOVER was recorded as discovery [{number}]{linked_note}. "
490
+ f"{where_you_are(page_state, current_url)} The page is unchanged.\n"
491
+ f"OBJECTIVE CHECKLIST now:\n{checklist_lines(tried['checklist'])}\n"
492
+ f"Do not record the same information again. {after_discovery_advice(tried['checklist'])}",
493
+ current_url)
494
+
495
+ # A single refusal gets a short warning; repeated refusals get an explicit list of other options
496
+ last_entry = journal[-1]["action"] if journal else ""
497
+ if last_entry.startswith(("BLOCKED_", "UNKNOWN_")) or last_entry == "DUPLICATE_DISCOVER":
498
+ consecutive_refusals += 1
499
+ if consecutive_refusals >= 2:
500
+ print(f"⚠️ {consecutive_refusals} refused actions in a row. Escalating loop warning.")
501
+ loop_msg = escalation_message(consecutive_refusals, action, journal[-1].get("reason", ""), page_state, current_url)
502
+ else:
503
+ consecutive_refusals = 0
504
+
505
+ # Without a nudge the model keeps browsing after it already has enough; after several turns
506
+ # with no new discovery it is asked to weigh its discoveries against the objective
507
+ if action == "DISCOVER" and last_entry == "DISCOVER":
508
+ turns_without_discovery = 0
509
+ else:
510
+ turns_without_discovery += 1
511
+ # Fires every STALL_TURNS stalled turns rather than every turn: repeated each turn it crowded out
512
+ # the current page and pushed the model to navigate away without reading what was in front of it
513
+ if turns_without_discovery and turns_without_discovery % STALL_TURNS == 0:
514
+ print(f"⚠️ No new discoveries in {turns_without_discovery} turns. Adding progress check.")
515
+ progress = (f"PROGRESS CHECK: no new discoveries in the last {turns_without_discovery} turns."
516
+ f"{numbered_discoveries(journal)} {READ_FIRST} "
517
+ f"Then {check_parts(tried)} If every part is covered, choose FINISH with {FINAL_RESULT} in the "
518
+ "parameter. If not, state in thought_process exactly what is still missing, then go and find "
519
+ f"that specific thing. {GIVE_UP_RULE}")
520
+ loop_msg = f"{loop_msg}\n{progress}" if loop_msg else progress
521
+ turns_since_objective_check = 0
522
+ else:
523
+ # Discoveries on loosely related topics keep resetting the stall count, so the objective is
524
+ # also re-checked on a fixed schedule to stop the model drifting away from it
525
+ turns_since_objective_check += 1
526
+ if turns_since_objective_check >= OBJECTIVE_CHECK_EVERY:
527
+ turns_since_objective_check = 0
528
+ count = sum(1 for e in journal if e.get("action") == "DISCOVER")
529
+ print(f"🧭 Objective check after {turn_counter} turns ({count} discoveries).")
530
+ check = (f"OBJECTIVE CHECK: you have recorded {count} discoveries in {turn_counter} turns."
531
+ f"{numbered_discoveries(journal)} "
532
+ f"{source_note(journal)} {READ_FIRST} "
533
+ f"Then {check_parts(tried)} If every part is covered, choose FINISH with {FINAL_RESULT} in the "
534
+ "parameter. If not, state in thought_process exactly what is still missing and go directly for it; "
535
+ f"do not spend turns on topics outside the objective. {GIVE_UP_RULE}")
536
+ loop_msg = f"{loop_msg}\n{check}" if loop_msg else check
537
+
538
+ # Saved every turn as well, so a crash or a killed process still leaves a current report
539
+ write_research_log(objective, journal, tried.get("checklist"))
540
+ write_report(objective, journal, tried.get("checklist"))
541
+
542
+ turn_counter += 1
543
+ print("\n⏱️ Cycle pacing check complete. Refreshing navigation loop pipeline...")
544
+ await asyncio.sleep(TURN_PAUSE_SECONDS)
545
+ finally:
546
+ # Always saved, however the run ends: FINISH, the turn limit, Ctrl+C or an outside time limit
547
+ write_research_log(objective, journal, tried.get("checklist"))
548
+ write_report(objective, journal, tried.get("checklist"), stop_reason)
549
+
550
+ print(f"\n🔒 Shutting down browser instance. Report: {REPORT_FILE}; full journal: research_log.txt.")
551
+ await browser.close()
552
+
553
+ def run():
554
+ """Command-line entry point (installed as `localagentbrowser`)."""
555
+ try:
556
+ asyncio.run(main())
557
+ except KeyboardInterrupt:
558
+ print("\n⏹️ Stopped. Findings so far are in research_log.txt.")