Skip to content
Troy

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
  1. Common behaviour
  2. Targets
  3. launch.mjs
  4. detect.mjs
  5. fill.mjs
  6. goto.mjs
  7. click.mjs
  8. read.mjs
  9. state.mjs
  10. test/run.sh

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, default http://127.0.0.1:9222. To use Troy, start it with --cdp-port=9333 and set APPLY_FILL_CDP=http://127.0.0.1:9333.
  • Target. --target <name> loads targets/<name>.json. The default is ycombinator.
  • 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 value or a bare --name for 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: allows apply.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:

  • name
  • allowedHosts: 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 and aria-hidden elements.
  • autosave: { "strategy": "blur", "settleMs": 900 }. settleMs is how long fill.mjs waits 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/Helium
  • chrome: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • chromium: /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, target
  • total, answered, unanswered
  • fields: each with index, 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, an input or 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, default networkidle.
  • --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. --text without --within is 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-text or --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.