Troy / Reference
Action scripts
Reference for the verified action scripts in scripts/: launch, detect, fill, goto and click, with their flags, host allowlist targets and exit codes.
On this page
The scripts/ folder holds Node.js scripts that act on a page over the Chrome DevTools Protocol (CDP) with safety checks: a host allowlist, refusal of submit controls, and a check after each action that it changed the page. They came from the apply-fill workflow and attach to any Chromium with a CDP port, including Troy.
Each check answers a specific way an agent goes wrong in a real browser. The allowlist stops it typing into the wrong site. The submit guard leaves the irreversible step to a person. The after-action check stops it reporting a click that did nothing as done.
The project plans to port them to TypeScript as a troy command (see Roadmap). Today they are run with node from the repository root, after npm install.
Common behaviour
- Browser. Scripts attach to
APPLY_FILL_CDP, defaulthttp://127.0.0.1:9222. To use Troy, start it with--cdp-port=9333and setAPPLY_FILL_CDP=http://127.0.0.1:9333. - Target.
--target <name>loadstargets/<name>.json. The default isycombinator. - Allowed hosts. A page is eligible only if its host equals an allowed host or is a subdomain of it. Substring matches do not count.
- Tab choice. If more than one tab matches, the script refuses to guess and lists them. Narrow it with
--url <substring>. - Output. JavaScript Object Notation (JSON) on stdout. Errors go to stderr prefixed with
apply-fill:and exit with code 1. - Detaching. Scripts exit without closing the browser.
- Flags.
--name valueor a bare--namefor true. - Selectors. Plain Cascading Style Sheets (CSS) selectors, passed to
document.querySelector. Selectors from the read pipeline that cross a shadow root (they contain>>>) are not supported.
Targets
Two targets ship in targets/:
ycombinator: allowsapply.ycombinator.com.generic: allows no host. Every run needs--allow-host <hostname>, so a mistyped command cannot type into an unrelated tab.
A target file has these keys:
nameallowedHosts: array of host names.fieldSelector: CSS selector for fields to detect.skipSelector: CSS selector for fields to ignore. Both shipped targets skip hidden, submit, button, checkbox, radio, file and password inputs, and read-only, disabled andaria-hiddenelements.autosave:{ "strategy": "blur", "settleMs": 900 }.settleMsis how longfill.mjswaits after blur.notes: free text.
Add a target by copying targets/generic.json and filling in allowedHosts.
--allow-host <hostname> adds one host for a single run, with any target.
launch.mjs
node scripts/launch.mjs [--url <url>] [--headless] [--browser helium|chrome|chromium] [--force]
Starts a separate automation browser with remote debugging on the port from APPLY_FILL_CDP and a dedicated profile from APPLY_FILL_PROFILE. The browser binary comes from --browser (one of the names below, or a path), then APPLY_FILL_BROWSER, then Helium. Known macOS paths:
helium:/Applications/Helium.app/Contents/MacOS/Heliumchrome:/Applications/Google Chrome.app/Contents/MacOS/Google Chromechromium:/Applications/Chromium.app/Contents/MacOS/Chromium
It is idempotent. If a browser already answers and can be attached to, it reports alreadyRunning and exits 0. If one answers over Hypertext Transfer Protocol (HTTP) but cannot be attached to, which happens to a stale process after the browser auto-updates, it stops unless you pass --force, which kills the process using that profile and starts a new one.
This script starts a separate browser. It does not start Troy.
detect.mjs
node scripts/detect.mjs --target ycombinator [--url <substring>]
Lists every visible field that matches fieldSelector and not skipSelector. It does not change the page. Output:
url,title,targettotal,answered,unansweredfields: each withindex,selector,tag,type,name,question,maxLength,currentValue,currentLength,answered
The question is taken from a label, aria-label, aria-labelledby, or the nearest preceding text.
fill.mjs
printf '%s' "$ANSWER" | node scripts/fill.mjs --target ycombinator --selector '#q3' [--dry-run]
Fills one field, then reads it back. The answer must arrive on stdin, never as an argument, so quotes and newlines survive.
It refuses:
- an empty answer, or one containing an em dash or en dash
- an answer longer than the field’s
maxlength - buttons, submit, button and image inputs, and anything whose text or name looks like a submit control
- password fields
- anything that is not a
textarea, aninputor a content-editable element
--dry-run reports the field and what would be written, without writing.
After writing it blurs the field, waits autosave.settleMs, and compares. Output includes before, after and ok. Exit code 0 when the value landed, 2 on a mismatch.
goto.mjs
node scripts/goto.mjs --target generic --allow-host 127.0.0.1 --to http://127.0.0.1:8100/form.html
Navigates within the allowlist. --to (or --url) is the destination; only http and https are accepted, and the destination host must be allowed.
Other flags:
--match <substring>: use the tab whose address contains this.--until <state>: Playwright wait state, defaultnetworkidle.--timeout <ms>: default 30000.--dry-run: report the plan only.
Without --match it uses a tab already on an allowed host, then a blank tab, then opens a new tab. It never takes over a tab showing something else.
The output reports from, requested, landed, status, redirected, stillAllowed, title and fields. If a redirect lands off the allowlist it warns not to act on the page. Exit code 0 only when there was a response with a status below 400 and the page is still on an allowed host; otherwise 2. A navigation error exits 1.
click.mjs
node scripts/click.mjs --target ycombinator --within "#q-entity" --text "No"
node scripts/click.mjs --target generic --allow-host 127.0.0.1 \
--within "#q-using" --text "Yes" --expect-visible "#usercount"
Clicks one control and checks that something changed.
--selector <css>: target by selector, optionally inside--within.--text <text>with--within <css>: target by exact text inside a scope.--textwithout--withinis refused, because repeated labels such as Yes and No appear once per question on a single-page form.--settle <ms>: wait after clicking, default 500.--dry-run: report what would be clicked.- One expectation, checked for up to 4 seconds:
--expect-selector,--expect-visible,--expect-textor--expect-gone.
It refuses when nothing matches, when more than one element matches, and when the element’s text or name looks like a commit control (submit, send application, finalise, confirm and send, delete, pay now).
Without an expectation, success means a snapshot diff of the scope found a change: the address, the count of visible fields, a field value, or a selected, checked or expanded state. A click that changed nothing is reported as NOT VERIFIED. Exit code 0 when verified, 2 otherwise.
read.mjs
Not an action script: it reads a page and changes nothing, and it finds Troy through agent-endpoint.json rather than APPLY_FILL_CDP. On main only. See How Troy reads a page and Command line and environment.
state.mjs
A module, not a command. snapshot, diff and expect are what click.mjs and goto.mjs use to decide whether an action happened.
test/run.sh
A shell test for these scripts. It serves test/fixture/form.html with Python on port 8100 (PORT overrides it) and runs goto.mjs and click.mjs against it, checking allowlist refusals, the scoped click, no-op detection, the submit guard and ambiguity refusal. It expects a browser answering on port 9222. It is not part of npm test.