navego 0.0.0-stage → 1.7.5
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.
- package/README.md +149 -2
- package/action-strategy.js +15 -0
- package/advice.js +153 -0
- package/agent-guide.js +201 -0
- package/bin/kemudi.js +60 -0
- package/bin/opera-chrome.cmd +15 -0
- package/bin/opera-local-dev.js +62 -0
- package/bin/opera-local.js +188 -0
- package/bing-serp.js +174 -0
- package/bridge-token.js +43 -0
- package/bridge-ws.js +718 -0
- package/bridge.js +322 -0
- package/browsers.js +144 -0
- package/burst.js +413 -0
- package/canvas.js +248 -0
- package/captcha-solver.js +73 -0
- package/caret-guard.js +68 -0
- package/cdp.js +95 -0
- package/cloud.js +139 -0
- package/decks.js +115 -0
- package/dev-shim.js +253 -0
- package/dialog.js +198 -0
- package/doctor.js +92 -0
- package/documents.js +408 -0
- package/driver.js +73 -0
- package/focus-guard.js +87 -0
- package/gates.js +299 -0
- package/input.js +237 -0
- package/install.js +201 -0
- package/leases.js +59 -0
- package/lib/endpoints.js +34 -0
- package/lib/socket-protocol.js +144 -0
- package/mcp-server.js +1001 -0
- package/menu-tree.js +298 -0
- package/oauth.js +212 -0
- package/observe.js +363 -0
- package/office/docx.js +159 -0
- package/office/palette.js +17 -0
- package/office/pptx.js +154 -0
- package/office/xlsx.js +201 -0
- package/office/xml.js +31 -0
- package/office/zip.js +111 -0
- package/package.json +94 -4
- package/page-expressions.js +780 -0
- package/pointer.js +213 -0
- package/postinstall.js +27 -0
- package/primitives-file.js +394 -0
- package/primitives.js +149 -0
- package/read-strategy.js +58 -0
- package/registry.js +88 -0
- package/reports.js +309 -0
- package/sessions.js +131 -0
- package/spreadsheets.js +93 -0
- package/statements.js +221 -0
- package/surface-profile.js +241 -0
- package/tidy.js +72 -0
- package/tools.js +494 -0
- package/transport.js +200 -0
- package/waits.js +178 -0
- package/wallet-client.js +95 -0
- package/window-focus.js +338 -0
- package/ws-server.js +263 -0
package/README.md
CHANGED
|
@@ -1,3 +1,150 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Navego
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Drive your own browser from an MCP client, with no dependencies. Installed as `opera-agent-mcp`; commands are `navego`, `opera-agent-mcp` and `kemudi`:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm i -g opera-agent-mcp
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
| mode | what drives | what it needs |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `navego local` | the everyday profile on this machine, over the loopback bridge | Node 20+, the extension, a paired device |
|
|
12
|
+
| `navego cloud` | the paired device's browser, through the hosted server | an account, an OAuth login, a paired device |
|
|
13
|
+
| `navego auth` | sign in once, keep the token beside this install | a browser, or `OPERA_AGENT_MCP_TOKEN` |
|
|
14
|
+
| `navego doctor` | print what is connected and what the plan allows | nothing but this install |
|
|
15
|
+
|
|
16
|
+
`npx -y opera-agent-mcp` is the published form of the package.
|
|
17
|
+
|
|
18
|
+
## Why this exists
|
|
19
|
+
|
|
20
|
+
The same action measured two ways on one machine:
|
|
21
|
+
|
|
22
|
+
| | round trip |
|
|
23
|
+
|---|---|
|
|
24
|
+
| through a cloud MCP function | ~380 ms |
|
|
25
|
+
| through this driver | under 1 ms |
|
|
26
|
+
|
|
27
|
+
It exists because Google Docs, Sheets and Slides all render to canvas. There is no
|
|
28
|
+
element to write to and no text to read back, so every action has to go through
|
|
29
|
+
browser-level input — and every action the editor silently ignores looks exactly
|
|
30
|
+
like one that worked. The recipes at the bottom are what was learned by driving,
|
|
31
|
+
not by reading documentation.
|
|
32
|
+
|
|
33
|
+
## Requirements
|
|
34
|
+
|
|
35
|
+
Node 20 or newer, the Navego extension on the everyday browser, and a paired
|
|
36
|
+
device for the meter. The bridge — not a debugging port — is the road: Chrome
|
|
37
|
+
refuses a debugging port on the Default profile, the extension cannot be driven
|
|
38
|
+
from a headless harness, and the everyday window is the one people actually use.
|
|
39
|
+
|
|
40
|
+
Load the extension from `extension/` (chrome://extensions, developer mode, load
|
|
41
|
+
unpacked; it persists in the profile) or install the signed CRX from the
|
|
42
|
+
download page. Pair the browser in the dashboard: the meter needs a paired
|
|
43
|
+
device to name whose allowance the session spends.
|
|
44
|
+
|
|
45
|
+
Then:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
navego doctor
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
is the one command to reach for. It prints the bridge, the device, the
|
|
52
|
+
extension version, the plan, the quota, and the fix when something is degraded —
|
|
53
|
+
`ready` when everything is wired. `OPERA_BRIDGE_PORT` (default `9451`) names
|
|
54
|
+
the loopback port; `OPERA_AGENT_HOME` names the paired device file's folder.
|
|
55
|
+
A dedicated, separate test profile with the extension pre-loaded is
|
|
56
|
+
`local\bin\opera-chrome.cmd` — on macOS and Linux the equivalent is one
|
|
57
|
+
Chrome invocation with `--load-extension`.
|
|
58
|
+
|
|
59
|
+
## The meter
|
|
60
|
+
|
|
61
|
+
The local drive is metered where it happens. At the start of a session the
|
|
62
|
+
bridge asks the cloud once (`session_open`, with the device credentials the
|
|
63
|
+
hello carries), then enforces the returned allowance locally: one command past
|
|
64
|
+
it answers `PLAN_LIMIT_REACHED` with the plan named. When the session ends, the
|
|
65
|
+
usage is reported once and folded into the same daily count the hosted surface
|
|
66
|
+
reads, so `plan.pilot` carries 200 commands per day and 50 per session, and
|
|
67
|
+
`plan.firm` carries 5000 and 500. Cloud unreachable means the local drive
|
|
68
|
+
stops, with the reason named — an unmetered drive is not offered. The gate
|
|
69
|
+
lives in the bridge and in the hosted MCP, never in readable client code.
|
|
70
|
+
|
|
71
|
+
Trust boundary, stated plainly: the loopback socket admits this machine's
|
|
72
|
+
processes (any of them) as well as the extension — the CRX signature is the
|
|
73
|
+
only identity the origin check conveys, and local automation was always
|
|
74
|
+
possible on a local machine. What the meter bounds is the account's spend,
|
|
75
|
+
not who drives.
|
|
76
|
+
|
|
77
|
+
## Tools
|
|
78
|
+
|
|
79
|
+
The server advertises 45 tools, named for what they do and grouped by what they touch:
|
|
80
|
+
|
|
81
|
+
`browser_status`, `browser_focus_window`, `browser_focus_tab`, `browser_select_browser`,
|
|
82
|
+
`browser_list_tabs`, `browser_open_url`, `browser_close_tab`, `browser_read_page`,
|
|
83
|
+
`browser_search_web`, `browser_find_text`, `browser_find_element`, `browser_click`,
|
|
84
|
+
`browser_hover`, `browser_press_key`, `browser_type_text`, `browser_scroll`,
|
|
85
|
+
`browser_run_steps_steps`, `browser_wait_until`, `browser_upload_file`, `browser_drop_file`,
|
|
86
|
+
`browser_intercept_picker`, `browser_download_file`, `browser_list_menu`, `browser_walk_menu`,
|
|
87
|
+
`browser_get_guide`, `browser_screenshot`, `browser_read_dialog`, `browser_type_into_dialog`,
|
|
88
|
+
`browser_press_dialog_button`, `browser_check_gate`, `browser_login`, `browser_solve_captcha`.
|
|
89
|
+
|
|
90
|
+
`delivery_plan`, `delivery_record`.
|
|
91
|
+
|
|
92
|
+
`artifact_build_report`, `artifact_build_workbook`, `artifact_build_slides`, `artifact_build_document`.
|
|
93
|
+
|
|
94
|
+
`wallet_pair_device`, `wallet_get_balance`, `wallet_get_price`, `wallet_add_funds`,
|
|
95
|
+
`wallet_hold_price`, `wallet_charge`, `wallet_refund`.
|
|
96
|
+
|
|
97
|
+
`browser_status` names the paired browsers and `browser_select_browser` pins tab-less calls
|
|
98
|
+
(`browser_open_url` is the one that matters) to one of them until another switch says
|
|
99
|
+
otherwise; pass a slot number, a device name, or `any` to follow the first ready
|
|
100
|
+
browser again. Tab-scoped calls keep routing by their tab id either way.
|
|
101
|
+
|
|
102
|
+
`browser_run_steps` runs 1-8 dependent steps on one tab in a single call and reads the page
|
|
103
|
+
once at the end; the first failure stops the burst and keeps the steps that finished.
|
|
104
|
+
`browser_open_url` always opens its own tab, so a drive never navigates a page someone is
|
|
105
|
+
already reading. `browser_screenshot` is clipped to the viewport at one pixel per
|
|
106
|
+
clickable coordinate, so a coordinate read off a screenshot can be clicked as-is.
|
|
107
|
+
Actions answer with where the page stands and the rows that changed; `browser_find_element`
|
|
108
|
+
is the deliberate look at every row for a role.
|
|
109
|
+
|
|
110
|
+
Every answer is one flat document: `{ ok: true, ...facts }`, with the cost of the
|
|
111
|
+
call under `elapsedMs`. A refused tool answers the same way - `{ ok: false, error:
|
|
112
|
+
{ code, message } }` - with the next move in the message, so the local road reads
|
|
113
|
+
exactly like the hosted one.
|
|
114
|
+
|
|
115
|
+
`browser_download_file` writes a file to the folder the caller names and proves it by the file on
|
|
116
|
+
disk — a `.crdownload` is not a result, and two files landing at once is not a
|
|
117
|
+
result either: the newest of an ambiguous pair is somebody else's download, so the
|
|
118
|
+
answer names both and moves neither. Over the extension the browser's own folder is
|
|
119
|
+
watched instead of an armed one, because `chrome.debugger` refuses browser-level
|
|
120
|
+
commands there. The last two tools are the statement job: a
|
|
121
|
+
card that names the file before the drive, and a delivery that verifies it and adds the
|
|
122
|
+
client-month to a manifest. See the statement job in the price list migration under `hosted/migrations/`.
|
|
123
|
+
|
|
124
|
+
## Recipes, measured
|
|
125
|
+
|
|
126
|
+
These are the rules that the three Google editors actually honour. Each one returns
|
|
127
|
+
success while doing nothing if you get it wrong, so there is no error to notice.
|
|
128
|
+
|
|
129
|
+
**Paragraph breaks are newlines inside the text, never a dispatched Enter.** The
|
|
130
|
+
editor ignores the key event entirely and merges every paragraph into one.
|
|
131
|
+
|
|
132
|
+
**Structure is applied before content.** A style applied to a paragraph that
|
|
133
|
+
already holds its text does not take; the same chord applied to an empty paragraph
|
|
134
|
+
does, and the heading appears in the outline.
|
|
135
|
+
|
|
136
|
+
**The first key event after a write is swallowed.** Send one harmless key before
|
|
137
|
+
the real one, or the real one is the one that disappears.
|
|
138
|
+
|
|
139
|
+
**A cell ignores inserted text until a character key opens it**, and the opening
|
|
140
|
+
character joins the value. Press a letter, press Backspace, then insert.
|
|
141
|
+
|
|
142
|
+
**Clearing removes text but not formatting.** The next paragraph inherits the old
|
|
143
|
+
bullets. Clear, toggle once, then write.
|
|
144
|
+
|
|
145
|
+
**A submenu opens on hover.** Move the pointer and settle there; a press closes the
|
|
146
|
+
menu instead.
|
|
147
|
+
|
|
148
|
+
## Licence
|
|
149
|
+
|
|
150
|
+
MIT
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// @last-edited: 2026-10-27 UTC+7.
|
|
2
|
+
// @title: action-strategy — whether an action is grounded on an element or on a coordinate, decided from evidence.
|
|
3
|
+
// @state: the two grounding strategies and one pure function that orders them for a surface.
|
|
4
|
+
// @dependencies: none.
|
|
5
|
+
// WHY A CANVAS SURFACE LEADS WITH COORDINATES.
|
|
6
|
+
// A canvas page exposes no DOM worth querying, but Blink computes an accessibility tree for every rendered page and every node in it resolves to a box.
|
|
7
|
+
// So a coordinate on a canvas page is grounded on a measured box rather than guessed, which is the opposite of a coordinate on a page that does have elements.
|
|
8
|
+
export const ACTION_DOM = 'dom';
|
|
9
|
+
export const ACTION_COORDINATE = 'coordinate';
|
|
10
|
+
export function actionLadder(profile = {}) {
|
|
11
|
+
const canvas = profile.canvas === true;
|
|
12
|
+
const dom = { strategy: ACTION_DOM, why: 'the page holds the element, so it can be found and clicked by name' };
|
|
13
|
+
const coordinate = { strategy: ACTION_COORDINATE, why: 'the page draws the control, so it is grounded on the box the accessibility tree reports' };
|
|
14
|
+
return canvas === true ? [coordinate, dom] : [dom, coordinate];
|
|
15
|
+
}
|
package/advice.js
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
// @last-edited: 2026-10-15 UTC+7.
|
|
2
|
+
// @title: advice — what to do next when a call could not do what it was asked.
|
|
3
|
+
// @state: rules keyed by what went wrong, each with a move that is known to work.
|
|
4
|
+
// @dependencies: none.
|
|
5
|
+
// WHY THIS FILE EXISTS
|
|
6
|
+
// A failure that names the problem sends an agent looking for the problem again.
|
|
7
|
+
// Measured on this product's own author: "no menuitem matching \"Image\"" said exactly what was missing and nothing about what to do, and the next move was always the same two or three — open the menu that holds it, read the menu tree, wait for it to appear.
|
|
8
|
+
// Those moves are written down here once, so the failure carries them and the agent does not have to rediscover them while a menu is closing underneath it.
|
|
9
|
+
// WHY ADVICE IS DATA AND NOT SENTENCES APPENDED TO ERRORS.
|
|
10
|
+
// An error that grows a paragraph of advice becomes unreadable, and the advice drifts from what the product can actually do.
|
|
11
|
+
// Here a rule matches what went wrong and names the call to make; a rule that names a call nobody has is caught by a test, the same way the guide's recipes are.
|
|
12
|
+
// WHY EVERY MOVE IS ONE CALL.
|
|
13
|
+
// An advice line that needed three calls is a plan, and a plan inside an error message is read once and forgotten.
|
|
14
|
+
// Each move below is a single tool call that answers the question the failure raised.
|
|
15
|
+
const MENU_ROLES = ['menuitem', 'menuitemcheckbox', 'menuitemradio'];
|
|
16
|
+
const trim = (text, at = 60) => {
|
|
17
|
+
const one = String(text ?? '').replace(/\s+/g, ' ').trim();
|
|
18
|
+
return one.length > at ? `${one.slice(0, at)}...` : one;
|
|
19
|
+
};
|
|
20
|
+
// WHY THE NEAREST NAME IS OFFERED WHEN NOTHING MATCHED.
|
|
21
|
+
// The caller asked for one thing and the page offers another that starts the same way — "Upload" against "Upload from computer".
|
|
22
|
+
// An agent that sees the difference spelled out does not have to guess whether its own spelling was wrong or the page's.
|
|
23
|
+
const rowAdvice = (role, name, rows) => {
|
|
24
|
+
const wanted = String(name ?? '').toLowerCase();
|
|
25
|
+
const sameRole = rows.filter((row) => row.role === role);
|
|
26
|
+
const begins = sameRole.find((row) => String(row.name ?? '').toLowerCase().startsWith(wanted));
|
|
27
|
+
const looks = [...new Set(sameRole.map((row) => row.name))]
|
|
28
|
+
.filter((text) => wanted !== '' && (String(text).toLowerCase().includes(wanted.slice(0, 6)) || wanted.includes(String(text).toLowerCase().slice(0, 6))))
|
|
29
|
+
.slice(0, 3);
|
|
30
|
+
if (begins)
|
|
31
|
+
return [`the page has "${trim(begins.name)}" — browser_click({role: "${role}", name: "${trim(begins.name, 40)}"})`];
|
|
32
|
+
if (looks.length)
|
|
33
|
+
return [`the page has: ${looks.map((text) => `"${trim(text, 34)}"`).join(', ')}`];
|
|
34
|
+
if (MENU_ROLES.includes(String(role))) {
|
|
35
|
+
return [
|
|
36
|
+
'browser_list_menu({}) to see what this application can do',
|
|
37
|
+
'browser_walk_menu({path: [...]}) to walk into the menu that holds it',
|
|
38
|
+
`browser_wait_until({until: "row", role: "${role}", name: "..."}) if it has not appeared yet`
|
|
39
|
+
];
|
|
40
|
+
}
|
|
41
|
+
return [`browser_find_element({role: "${role}"}) to see what is on the page now`];
|
|
42
|
+
};
|
|
43
|
+
const HANDLE_GONE = [
|
|
44
|
+
'browser_find_element({role: "element-role", name: "element-name"}) again — the element it named is gone, and the row may now be somewhere else',
|
|
45
|
+
'browser_find_element({role: "element-role"}) to find the row under its new name or place'
|
|
46
|
+
];
|
|
47
|
+
const NOT_A_HANDLE = [
|
|
48
|
+
'a handle comes from browser_find_element and looks like "opera-1234"',
|
|
49
|
+
'browser_click({x, y}) for a point, browser_click({handle}) for an element'
|
|
50
|
+
];
|
|
51
|
+
const BRIDGE_GONE = [
|
|
52
|
+
'the extension has to be connected: reload it in chrome://extensions, then browser_status() to confirm',
|
|
53
|
+
'nothing that touches a page can succeed until this is fixed'
|
|
54
|
+
];
|
|
55
|
+
const WRONG_PIPE = [
|
|
56
|
+
'this is the debug-port road, not the real profile: start the local driver and reload the extension so the bridge is used'
|
|
57
|
+
];
|
|
58
|
+
const NO_TARGET = [
|
|
59
|
+
'browser_list_tabs() for the ids that exist now',
|
|
60
|
+
'browser_open_url() if the page is not open yet'
|
|
61
|
+
];
|
|
62
|
+
// WHY A CLICK OFF THE PAGE GETS ITS OWN MOVES.
|
|
63
|
+
// Measured live: a click on a row below the fold answered with a click at y -139 - success, on a coordinate no pixel holds.
|
|
64
|
+
// The only roads that change the outcome are scrolling the thing into view and clicking it again, and each is one call.
|
|
65
|
+
const CLICK_OFF_PAGE = [
|
|
66
|
+
'browser_scroll({text}) or browser_scroll({y}) to bring it into the viewport, then click again',
|
|
67
|
+
'browser_click({role, name}) answers coordinates — a row above the fold is clickable as it is, one below it is not'
|
|
68
|
+
];
|
|
69
|
+
const EMPTY_FILE_INPUT = [
|
|
70
|
+
'the page has no file input to fill — browser_drop_file({x, y, filename, path}) instead, which is the road into a picker with no input behind it',
|
|
71
|
+
'browser_screenshot() after the drop to see whether the page took it'
|
|
72
|
+
];
|
|
73
|
+
// WHY TEXT THAT WENT NOWHERE GETS ITS OWN MOVES.
|
|
74
|
+
// Measured live: five characters were typed into a document that had lost its caret, and the call answered with the number of characters it had inserted.
|
|
75
|
+
// The next move is always the same two - put a caret in the page, then type again - and both are one call each.
|
|
76
|
+
const EDIT_GONE = [
|
|
77
|
+
'the failure names the element that had focus: if it is not a field, browser_click({role, name}) that field and type again',
|
|
78
|
+
'if a dialog or overlay is over the page, browser_press_key({key: \u201cEscape\u201d}) or click its dismiss button first - measured live, a cookie wall sat over a search box and swallowed the click',
|
|
79
|
+
'browser_find_element({role: "menuitem", name: "..."}) to see where the caret is, or browser_read_page() to see what the page holds',
|
|
80
|
+
'browser_read_page() before typing again on a canvas page - the text may have landed after the check, and retyping duplicates it'
|
|
81
|
+
];
|
|
82
|
+
// WHY AN EXTENSION PAGE GETS ITS OWN MOVES.
|
|
83
|
+
// Measured live: a drive named the Extensions tab and the bridge refused it with "Cannot access a chrome:// URL".
|
|
84
|
+
// That is a wall, not a failure - no move on that tab can ever succeed - so the moves point at the tabs that can be driven instead of at the one that cannot.
|
|
85
|
+
const EXTENSION_PAGE = [
|
|
86
|
+
'browser_list_tabs() for the tabs that can be driven - a chrome:// page refuses every move',
|
|
87
|
+
'browser_open_url() if the page belongs in a new tab instead'
|
|
88
|
+
];
|
|
89
|
+
// WHY THE FIRST RULE THAT FITS WINS.
|
|
90
|
+
// A refusal and a missing row can both be true at once — a page that refuses the method it was asked for is also "no such thing" — and a caller is better served by the most specific thing that is wrong, which is the first rule in this order.
|
|
91
|
+
export const RULES = Object.freeze([
|
|
92
|
+
{
|
|
93
|
+
when: (text) => /was still in flight when the device disconnected|extension is not connected/.test(text),
|
|
94
|
+
next: BRIDGE_GONE
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
when: (text) => /is not reachable: fetch failed/.test(text),
|
|
98
|
+
next: BRIDGE_GONE
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
when: (text) => /not reachable: fetch failed|debugging port/.test(text),
|
|
102
|
+
next: WRONG_PIPE
|
|
103
|
+
},
|
|
104
|
+
{
|
|
105
|
+
when: (text) => /No page target/.test(text),
|
|
106
|
+
next: NO_TARGET
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
when: (text) => /chrome:\/\//.test(text),
|
|
110
|
+
next: EXTENSION_PAGE
|
|
111
|
+
},
|
|
112
|
+
{
|
|
113
|
+
when: (text) => /click refused: .* is outside the /.test(text),
|
|
114
|
+
next: CLICK_OFF_PAGE
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
when: (text) => /is not an element handle/.test(text),
|
|
118
|
+
next: NOT_A_HANDLE
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
when: (text) => /no longer in the page/.test(text),
|
|
122
|
+
next: HANDLE_GONE
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
when: (text) => /inputFound|found no file input/.test(text),
|
|
126
|
+
next: EMPTY_FILE_INPUT
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
when: (text) => /nothing on the page changed|holds no text and no field/.test(text),
|
|
130
|
+
next: EDIT_GONE
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
when: (text) => /^no \w+ matching/.test(text),
|
|
134
|
+
next: (text, context) => {
|
|
135
|
+
const asked = /^no (\w+) matching "([^"]*)"/.exec(text);
|
|
136
|
+
const role = asked?.[1] ?? 'row';
|
|
137
|
+
const name = asked?.[2] ?? '';
|
|
138
|
+
return rowAdvice(role, name, context.rows ?? []);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
]);
|
|
142
|
+
// WHY THE FIRST WORD IS KEPT.
|
|
143
|
+
// "no menuitem matching" says what was looked for and what class of thing it was, and an agent that reads only the first line still knows whether to look for a menu, a button or a text field.
|
|
144
|
+
export function withAdvice(error, context = {}) {
|
|
145
|
+
const text = String(error?.message ?? error ?? '');
|
|
146
|
+
if (!text)
|
|
147
|
+
return text;
|
|
148
|
+
const rule = RULES.find((entry) => entry.when(text));
|
|
149
|
+
if (!rule)
|
|
150
|
+
return text;
|
|
151
|
+
const moves = typeof rule.next === 'function' ? rule.next(text, context) : rule.next;
|
|
152
|
+
return `${text}\nNext: ${moves.join('\n ')}`;
|
|
153
|
+
}
|
package/agent-guide.js
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
// @last-edited: 2026-10-25 UTC+7.
|
|
2
|
+
// @title: agent-guide — what an agent can do here, written as tasks instead of a tool list.
|
|
3
|
+
// @state: recipes, side effects, honesty locks between them and the tools.
|
|
4
|
+
// @dependencies: none.
|
|
5
|
+
// WHY THIS FILE EXISTS
|
|
6
|
+
// An agent arriving cold does not know what to call first.
|
|
7
|
+
// Every tool description answers "what does this do" and never answer "I want to attach a file, what do I do" — so an agent reads all of them, in order, every session, and picks.
|
|
8
|
+
// Measured on this product's own author: an image upload took a dozen calls and a submenu twenty seconds of polling because the road was never written down anywhere the agent could read it.
|
|
9
|
+
// WHY THE RECIPES ARE DATA AND THE CHECKS ARE TESTS.
|
|
10
|
+
// A guide that drifts from the product is worse than none: an agent follows a route to a tool that was renamed and learns to distrust the guide.
|
|
11
|
+
// So the recipes name tools and the test fails the moment a name stops existing, the moment a tool has no declared side effect, and the moment a recipe points at a tool that is not on the list.
|
|
12
|
+
// Rot is a build failure, not a surprise in production.
|
|
13
|
+
// WHY SIDE EFFECTS ARE DECLARED AND NOT IMPLIED.
|
|
14
|
+
// Half of what an agent loses today is not a missing tool but an unannounced one: reading a Google Doc moves the caret, so the next click lands somewhere the agent had already visited.
|
|
15
|
+
// A tool that quietly moves something should say so in the tool list, where the agent reads before calling, not in a document it reads after being surprised.
|
|
16
|
+
// WHY A DOCUMENT OUTLINE IS NOT A MENU.
|
|
17
|
+
// Google Docs renders the document's own headings as role=menuitem, so a walk that trusts roles alone descends into the document — measured live: a menu probe on an open Docs menu returned "BAB I PENDAHULUAN" and every paragraph as menu items.
|
|
18
|
+
// The walk therefore treats a menu as a menu only while it hangs off a menubar or a menu that a manu item owns, and a whole branch that grows into document text is refused by name rather than walked to the end of the document.
|
|
19
|
+
export const RECIPES = Object.freeze([
|
|
20
|
+
{
|
|
21
|
+
task: 'See what is on the page',
|
|
22
|
+
do: ['browser_read_page'],
|
|
23
|
+
note: 'On a Google Doc this reads the document itself, not the toolbar around it.'
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
task: 'See what can be clicked, with role and name',
|
|
27
|
+
do: ['browser_find_element'],
|
|
28
|
+
note: 'Pass role (menuitem, button, option, link) without a name to list every row of that role; with a name to find the one row.'
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
task: 'Find one row by what it is called',
|
|
32
|
+
do: ['browser_find_element'],
|
|
33
|
+
note: 'role + name returns the one row, exact name first then substring, with a handle for later clicks.'
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
task: 'Click a row by what it is called',
|
|
37
|
+
do: ['browser_click'],
|
|
38
|
+
note: 'Pass role and name instead of x and y: the row is resolved and clicked centred in one call — no stale coordinates.'
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
task: 'Open a menu and walk into a submenu',
|
|
42
|
+
do: ['browser_hover', 'browser_wait_until'],
|
|
43
|
+
note: 'Submenus need the pointer to leave and come back. Wait for the row, never for a guessed number of milliseconds.'
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
task: 'Walk a menu by path, not by guessing',
|
|
47
|
+
do: ['browser_walk_menu'],
|
|
48
|
+
note: 'browser_walk_menu({path: ["Insert","Image"]}) opens each level and stops; branches are hovered, never clicked into blindly.'
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
task: 'Do several dependent moves in one call',
|
|
52
|
+
do: ['browser_run_steps'],
|
|
53
|
+
note: 'Up to eight steps on one tab, in order. The first failure stops the burst and keeps the steps that finished; the page is settled and read once at the end instead of after every move. A refFromStep carries a handle from an earlier step into a later click.'
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
task: 'Wait for something to arrive or to go',
|
|
57
|
+
do: ['browser_wait_until'],
|
|
58
|
+
note: 'until=text looks for a text; until=row with absent:true looks for a row to leave. Returns found:false with the page rather than hanging.'
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
task: 'Wait until a navigation has happened',
|
|
62
|
+
do: ['browser_wait_until'],
|
|
63
|
+
note: 'Follows a submit or a sign-in with until=url (contains or matches) instead of polling the text. A text wait cannot see a url move.'
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
task: 'Wait until the page has stopped moving',
|
|
67
|
+
do: ['browser_wait_until'],
|
|
68
|
+
note: 'until=stable, for anything that moves on its own: a menu animating, a save running, an upload landing.'
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
task: 'Put a file into a page that has a file input',
|
|
72
|
+
do: ['browser_intercept_picker', 'browser_click', 'browser_upload_file', 'browser_intercept_picker'],
|
|
73
|
+
note: 'Enable interception first, click the chooser (or the input), call upload with the path or the bytes, then disable it. If upload reports inputFound:false, the site has no input — use the drop below.'
|
|
74
|
+
},
|
|
75
|
+
{
|
|
76
|
+
task: 'Put a file into a page whose chooser has no input',
|
|
77
|
+
do: ['browser_drop_file'],
|
|
78
|
+
note: 'A drop needs no dialog at all: the page takes the file on the drop it already listens for. If the chooser is already open - Google Docs opens it through the File System Access API - answer it with browser_type_into_dialog, which reaches it from the machine.'
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
task: 'Take a file out of a page',
|
|
82
|
+
do: ['browser_find_element', 'browser_download_file'],
|
|
83
|
+
note: 'Resolve the control that starts the download, then hand its handle to browser_download_file with the folder you want. The file landing and stopping growing is the proof; a still-writing file, a viewer that opened instead, and a click that produced nothing each come back downloaded:false with the reason.'
|
|
84
|
+
},
|
|
85
|
+
{
|
|
86
|
+
task: 'Deliver a client statement',
|
|
87
|
+
do: ['delivery_plan', 'browser_open_url', 'browser_read_page', 'browser_find_element', 'browser_download_file', 'delivery_record'],
|
|
88
|
+
note: 'One client, one portal, one month. The card names the file and the folder before anything is clicked; the drive gets the file; delivered checks it on disk and adds the client-month to the manifest. Never type a password: if the portal asks to sign in, the person signs in in their own browser and the same tab is used again. The answer is the proof another agent can hand to its own user: bytes, the kind of file sniffed from its bytes, the page count, and the closing balance as the portal printed it with the page named as its source. A balance that was not read is reported missing, never invented.'
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
task: 'Build a report from an exported sheet',
|
|
92
|
+
do: ['artifact_build_report'],
|
|
93
|
+
note: 'CSV in, a checked report out, written beside the source. No browser is touched: month-end reports must not depend on a tab being open. Every figure names the column and the exact rows it came from, and the plan is rechecked against those rows before the file exists.'
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
task: 'Build a paper from JSON tables, images, and graphs',
|
|
97
|
+
do: ['artifact_build_document'],
|
|
98
|
+
note: 'JSON in, a .docx out in one call: the checked plan (written beside the source) and the Word file built from it. Every graph names its table and columns, and the graph is recomputed from those rows before the file exists - a graph without a source, or one whose number disagrees with the table, stops the paper instead of reaching a reader.'
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
task: 'Turn an exported sheet into an Excel workbook',
|
|
102
|
+
do: ['artifact_build_workbook'],
|
|
103
|
+
note: 'CSV in, an .xlsx out: the report lines, the source rows, and the ledger of which rows produced each figure. The totals are numbers, so the customer can use them in another sheet. The plan is rechecked against those rows before the file exists, and the plan is written beside the workbook for the next artifact that needs the same figures.'
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
task: 'Turn a written plan into slides',
|
|
107
|
+
do: ['artifact_build_slides'],
|
|
108
|
+
note: 'JSON in, a .pptx out. A slide names a figure from the checked report and carries its value; a name the report does not hold stops the deck. The provenance of every figure is written beside the presentation, so the author can answer "where did this number come from" without opening the slide.'
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
task: 'Sign in to a portal',
|
|
112
|
+
do: ['browser_check_gate', 'browser_login', 'browser_check_gate'],
|
|
113
|
+
note: "One read says whether the page wants a password, a one-time code, or a captcha. login fills the fields from a credential file the person wrote, matched by the page's own domain, and never returns the secret. A one-time code is never answered: portal waits while the person signs in in their own browser, and the same tab is used again. Without a credentials file the default stands - the person signs in and portal waits for them."
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
task: 'Solve a captcha',
|
|
117
|
+
do: ['browser_check_gate', 'browser_solve_captcha', 'browser_check_gate'],
|
|
118
|
+
note: 'portal names the captcha and which kind it is. captcha is opt-in: it reads the image through the solver the person configured, only on a host they allowlisted, and types the answer. A token widget cannot be solved this way - let the person click it and use portal. With no solver configured, captcha refuses and types nothing.'
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
task: 'Prove it worked',
|
|
122
|
+
do: ['browser_screenshot', 'browser_read_page'],
|
|
123
|
+
note: 'A picture and the text, compared against what you expected. A tool saying it succeeded is not proof; the page saying so is.'
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
task: 'Bring a window forward',
|
|
127
|
+
do: ['browser_status', 'browser_focus_window'],
|
|
128
|
+
note: 'status names the browser in front and whether it is ours; front takes a piece of the window title. With no match, front answers the state without moving anything — pass a piece of the title to bring one forward. Never an empty match: that used to bring an arbitrary window forward.'
|
|
129
|
+
}
|
|
130
|
+
]);
|
|
131
|
+
// WHY NO RECIPE FOR "FIND A FILE INPUT" ANYMORE.
|
|
132
|
+
// It was here for a day, written while it was the only road, and every step of it was a guess: poll, retry, hope.
|
|
133
|
+
// The two roads that replaced it are above, and a recipe that teaches guessing is worse than no recipe.
|
|
134
|
+
export const SIDE_EFFECTS = Object.freeze({
|
|
135
|
+
wallet_pair_device: ['writes a device token to this machine\'s disk, which is the whole authority of the machine over the wallet'],
|
|
136
|
+
wallet_get_balance: [],
|
|
137
|
+
wallet_get_price: [],
|
|
138
|
+
wallet_add_funds: ['opens a payable invoice at the provider, which costs nothing until the person pays it'],
|
|
139
|
+
wallet_hold_price: ['arms a hold of the quoted price, which the next settle or refund will close'],
|
|
140
|
+
wallet_charge: ['takes the held price from the wallet, once, for a job that was reported finished'],
|
|
141
|
+
wallet_refund: ['returns the whole held price to the wallet, once, for a job that did not finish'],
|
|
142
|
+
browser_status: [],
|
|
143
|
+
browser_focus_window: ['brings a browser window to the front of the machine, which takes the keyboard away from whatever was in front'],
|
|
144
|
+
browser_focus_tab: ['brings the window holding one named tab to the front, instead of guessing by window title'],
|
|
145
|
+
browser_read_dialog: ['reads the dialog\'s title, buttons and field text outside the browser — changes nothing'],
|
|
146
|
+
browser_type_into_dialog: ['writes text into an operating system dialog outside the browser and reads the field back'],
|
|
147
|
+
browser_press_dialog_button: ['presses a button on an operating system dialog outside the browser'],
|
|
148
|
+
browser_get_guide: [],
|
|
149
|
+
browser_list_menu: ['reads the menu markup and answers — never clicks'],
|
|
150
|
+
browser_walk_menu: ['opens menus by hovering and clicking levels on the way to the path you gave'],
|
|
151
|
+
browser_select_browser: ['pins tab-less commands to the named browser until another switch says otherwise; moves no tab by itself and steers no running drive'],
|
|
152
|
+
browser_list_tabs: [],
|
|
153
|
+
browser_open_url: ['opens a new tab in the same browser'],
|
|
154
|
+
browser_close_tab: ['closes a tab the caller may still be holding'],
|
|
155
|
+
browser_search_web: ['opens one background tab on the Bing results on the bridged path (the direct CDP fallback opens it in the foreground) and closes it before the answer returns - nothing is left on the browser, and the machine\'s own window is never brought forward'],
|
|
156
|
+
browser_read_page: ['with allowCaretMove, borrows the selection on a canvas editor to read the text through it, and answers caretRestored as what was measured rather than what was hoped', 'without it, that step is skipped and the reason is reported, because a canvas caret is not in the DOM and cannot be promised back'],
|
|
157
|
+
browser_find_text: [],
|
|
158
|
+
browser_find_element: [],
|
|
159
|
+
browser_click: ['moves the pointer and presses'],
|
|
160
|
+
browser_hover: ['moves the pointer'],
|
|
161
|
+
browser_press_key: ['sends a key to whatever is focused'],
|
|
162
|
+
browser_type_text: ['inserts text into whatever is focused', 'atEnd: moves the caret to the end before inserting, so text lands at the end instead of wherever the caret was left'],
|
|
163
|
+
browser_scroll: ['moves the view, which can load more of a lazy page and move the page out from under coordinates you already hold'],
|
|
164
|
+
browser_run_steps: ['runs every step in order and stops at the first failure', 'settles and reads the page once at the end, not after each step'],
|
|
165
|
+
browser_wait_until: ['waits until text appears, a row matches, a url matches, or the page stops changing — whatever until= says'],
|
|
166
|
+
browser_upload_file: ['fills a file input, which fires the change the page listens for'],
|
|
167
|
+
browser_drop_file: ['brings the tab to front and drops a file on it'],
|
|
168
|
+
browser_intercept_picker: ['changes whether the native file picker appears on this tab'],
|
|
169
|
+
browser_download_file: ['brings the tab to front, clicks, and writes a file into the download folder it names'],
|
|
170
|
+
delivery_plan: [],
|
|
171
|
+
delivery_record: ['writes the client-month into the manifest on disk, replacing the record only when asked'],
|
|
172
|
+
artifact_build_report: ['writes a checked report file beside the source; no page is touched'],
|
|
173
|
+
artifact_build_document: ['writes a checked document plan and the Word file built from it beside the source; no page is touched'],
|
|
174
|
+
artifact_build_workbook: ['writes an Excel workbook and a checked report plan beside the source; no page is touched'],
|
|
175
|
+
artifact_build_slides: ['writes a PowerPoint presentation and the provenance of its figures beside the source; no page is touched'],
|
|
176
|
+
browser_check_gate: ['reads the gate on the page and names it — sign-in, one-time code, captcha, or nothing; types nothing', 'waits for the person to clear the gate in their own browser, then answers with the page as it stands'],
|
|
177
|
+
browser_login: ['fills the username and password fields from the credential file and submits; the secret never returns in the answer'],
|
|
178
|
+
browser_solve_captcha: ['reads a captcha image through the configured solver, which spends the person\'s money at that service, then types the answer into the captcha field'],
|
|
179
|
+
browser_screenshot: []
|
|
180
|
+
});
|
|
181
|
+
// WHY THE GUIDE ANSWERS ONE QUESTION AND NOT SEVERAL.
|
|
182
|
+
// A caller with a topic gets the roads for that task; a caller with none gets every road and every side effect, which is the whole surface in one read.
|
|
183
|
+
// Anything else is a filter that hides something and names nothing.
|
|
184
|
+
export function guide(topic) {
|
|
185
|
+
const asked = String(topic ?? '').trim().toLowerCase();
|
|
186
|
+
const recipes = asked
|
|
187
|
+
? RECIPES.filter((recipe) => `${recipe.task} ${recipe.note}`.toLowerCase().includes(asked))
|
|
188
|
+
: RECIPES;
|
|
189
|
+
return {
|
|
190
|
+
recipes,
|
|
191
|
+
sideEffects: Object.entries(SIDE_EFFECTS).map(([tool, effects]) => ({ tool, effects })),
|
|
192
|
+
refusals: [
|
|
193
|
+
'A native operating-system dialog cannot be opened, closed or filled from here — try browser_type_into_dialog or browser_press_dialog_button instead, which reach the dialog from the machine.',
|
|
194
|
+
'There is no raw CDP escape hatch — anything that can change the page is a named tool, by design.',
|
|
195
|
+
'A tool that reports success is not proof. The page saying so is.',
|
|
196
|
+
'A page cannot see whether the window in front of it is the one the machine has in front. Clicks and keys go nowhere while status says the window is not focused.',
|
|
197
|
+
'front with no match answers the state without moving anything — pass a piece of the window title. An empty match used to bring an arbitrary window forward.',
|
|
198
|
+
'A complex document or report is built as a plan on disk (report, doc, sheet, deck) before it reaches a page, not by driving cells one by one.'
|
|
199
|
+
]
|
|
200
|
+
};
|
|
201
|
+
}
|
package/bin/kemudi.js
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// @last-edited: 2026-11-08 UTC+7.
|
|
3
|
+
// @title: navego - the installed entry point: one command, two modes.
|
|
4
|
+
// @state: the mode comes from the first argument; each mode starts the server it names.
|
|
5
|
+
// @dependencies: ./opera-local.js for the local mode.
|
|
6
|
+
// WHY THE MODE IS AN ARGUMENT AND NOT A FLAG.
|
|
7
|
+
// A caller that has to remember a flag has two ways to get it wrong; a caller that names the mode cannot.
|
|
8
|
+
// The modes share every tool name and every answer shape, so the choice is only about who drives the browser.
|
|
9
|
+
const USAGE = `navego <mode>
|
|
10
|
+
|
|
11
|
+
local drive the everyday browser on this machine, over the loopback bridge
|
|
12
|
+
cloud drive it through the hosted Navego server
|
|
13
|
+
auth sign in with a browser and keep the token beside this install
|
|
14
|
+
doctor print what is connected, the plan, and what the plan allows
|
|
15
|
+
install detect this machine's browsers, register the extension, keep a verified CRX backup
|
|
16
|
+
uninstall remove the extension's policy entries, the OperaAgent folder, and this package; prints what it cannot remove
|
|
17
|
+
|
|
18
|
+
--help print this
|
|
19
|
+
`;
|
|
20
|
+
const requested = process.argv[2] || 'local';
|
|
21
|
+
const mode = requested.startsWith('--mode=') ? requested.slice('--mode='.length) : requested;
|
|
22
|
+
if (mode === 'help' || process.argv.includes('--help')) {
|
|
23
|
+
process.stdout.write(USAGE);
|
|
24
|
+
process.exit(0);
|
|
25
|
+
}
|
|
26
|
+
if (mode === 'doctor') {
|
|
27
|
+
const { doctor } = await import('../doctor.js');
|
|
28
|
+
process.exitCode = await doctor();
|
|
29
|
+
}
|
|
30
|
+
else if (mode === 'local') {
|
|
31
|
+
await import('./opera-local.js');
|
|
32
|
+
}
|
|
33
|
+
else if (mode === 'cloud') {
|
|
34
|
+
const { serveCloud } = await import('../cloud.js');
|
|
35
|
+
process.exitCode = await serveCloud();
|
|
36
|
+
}
|
|
37
|
+
else if (mode === 'auth') {
|
|
38
|
+
const { login } = await import('../oauth.js');
|
|
39
|
+
try {
|
|
40
|
+
const answer = await login();
|
|
41
|
+
process.stdout.write('Signed in. The token is stored in ' + answer.file + '\n');
|
|
42
|
+
}
|
|
43
|
+
catch (error) {
|
|
44
|
+
process.stderr.write('Sign-in did not finish: ' + String(error?.message || error) + '\n');
|
|
45
|
+
process.exitCode = 4;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
else if (mode === 'install') {
|
|
49
|
+
const { installFromCli } = await import('../install.js');
|
|
50
|
+
process.exitCode = await installFromCli();
|
|
51
|
+
}
|
|
52
|
+
else if (mode === 'uninstall') {
|
|
53
|
+
const { uninstallFromCli } = await import('../install.js');
|
|
54
|
+
process.exitCode = await uninstallFromCli();
|
|
55
|
+
}
|
|
56
|
+
else {
|
|
57
|
+
process.stderr.write(`Unknown mode: ${mode}\n${USAGE}`);
|
|
58
|
+
process.exit(2);
|
|
59
|
+
}
|
|
60
|
+
export {};
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
@echo off
|
|
2
|
+
|
|
3
|
+
REM @last-edited: 2026-10-21 UTC+7.
|
|
4
|
+
REM @title: opera-chrome — the dedicated Chrome this product drives, with the extension always loaded.
|
|
5
|
+
REM @state: the profile, the debugging port and the extension path, and nothing else.
|
|
6
|
+
REM @dependencies: none.
|
|
7
|
+
REM Navego dedicated Chrome: persistent profile, debugging port, extension always loaded.
|
|
8
|
+
REM Run this instead of opening Chrome normally.
|
|
9
|
+
REM Sign in to Google once; the profile keeps the login and the flag keeps the extension across restarts.
|
|
10
|
+
|
|
11
|
+
setlocal
|
|
12
|
+
set PROFILE=%LOCALAPPDATA%\OperaAgent\ChromeProfile
|
|
13
|
+
set EXTDIR=%~dp0..\..\extension
|
|
14
|
+
if not exist "%PROFILE%" mkdir "%PROFILE%" 2>nul
|
|
15
|
+
start "Navego Chrome" "C:\Program Files\Google\Chrome\Application\chrome.exe" --user-data-dir="%PROFILE%" --remote-debugging-port=9450 --load-extension="%EXTDIR%" --no-first-run --no-default-browser-check about:blank
|