Script runtime

​

The entry function

const asteroid = require('asteroid');

module.exports = async ({ page, browser, context, args }) => {
  // page     - the active Playwright Page, on the live browser session
  // browser  - the Playwright Browser
  // context  - the Playwright BrowserContext
  // args     - the node's resolved inputs (present when the node has an input schema)

  // Golden path: end with a handoff, which chooses the next node.
  return asteroid.handoff({ to: 'next_node', summary: 'Did the work.' });
};

• CommonJS is the norm: module.exports = async (...) => { ... }. export default works too, and an ESM file with top-level await is loaded as a module.
• A node with an input schema must destructure args. The async (page) => { ... } form does not receive args and fails validation when the node declares inputs.
• The return value decides output and routing. The golden path is to return asteroid.handoff(...), which chooses the next node and carries its data. An object instead becomes output variables, a string becomes script_output, and a throw is a failure. See Route to the next node yourself.

​

Timeouts

const asteroid = require('asteroid');

module.exports = async ({ page }) => {
  page.setDefaultTimeout(30000);          // all actions on this page
  page.setDefaultNavigationTimeout(60000); // navigations on this page

  await page.click('#slow-report', { timeout: 45000 }); // one call only
  return asteroid.handoff({ to: 'report_ready', summary: 'Report loaded.' });
};

​

The sandbox

• Node.js 22. Node built-in modules (node:fs, node:path, node:crypto, and the rest) are available.
• Playwright drives a headless Chromium over the live session. You get it through page, browser, and context, so you do not launch a browser yourself.
• python3 is present, with python3-yaml, reachable from the workflow’s Bash tool.
• No PDF or OCR libraries. To read a PDF or a print-only page, parse it in the browser page with pdf.js, not with a Node module. See the PDF pattern.

​

The filesystem

​

Requiring modules

• require('asteroid') is provided by the runtime. Its whole surface is handoff(...) and generateTotp(...). See Route to the next node yourself and Two-factor codes.
• Node built-ins resolve normally.
• Helper modules must be required by their absolute path under shared/, for example require('/home/agent/shared/file_claim/lib/dates.js'). A relative require('./dates.js') does not resolve, because the runtime runs your script from a private copy that holds no sibling files.
• Use absolute /home/agent/... paths. They work exactly as written from the entry script. Pass a required helper the paths it needs as arguments, rather than letting it compute its own, so it never depends on where the runtime placed your script.

const asteroid = require('asteroid');
const dates = require('/home/agent/shared/file_claim/lib/dates.js');

module.exports = async ({ page, args }) => {
  const dob = dates.toEhrFormat(args.date_of_birth);
  await page.fill('#dob', dob);
  return asteroid.handoff({ to: 'saved', summary: 'Filled the date of birth.' });
};

​

Secret tokens

​

Two-factor codes

const asteroid = require('asteroid');

module.exports = async ({ page }) => {
  await page.fill('#otp', asteroid.generateTotp('##MY_PORTAL.TOTP_SEED##'));
  await page.click('#verify');
  return asteroid.handoff({ to: 'dashboard', summary: 'Passed 2FA.' });
};

• A token the run does not fill throws, and the error names the token.
• An unusable seed throws a fixed message that never quotes the seed.
• Generate the code immediately before you submit it. If the site rejects it, generate a fresh code and retry once.

​

Related