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(...), generateTotp(...) and emit(...). See Route to the next node yourself, Two-factor codes and Emit your own event.
• 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.

​

Emit your own event

const asteroid = require('asteroid');

module.exports = async ({ page, args }) => {
  await page.screenshot({ path: '/home/agent/downloads/referral.png' });
  await asteroid.emit('referral_result', {
    text: `Referral ${args.status} for member ${args.member_id}`,
    payload: { status: args.status, auth_number: args.auth_number },
    files: ['/home/agent/downloads/referral.png'],
  });
  return asteroid.handoff({ to: 'done', summary: 'Reported the result.' });
};

• Await the call. It resolves to { id }. Delivery to your endpoint happens after that, so a slow or failing endpoint never fails the script.
• A malformed call throws, and the error names the argument. So does the 101st emit of one execution.
• Do not send an event again after “did not confirm”. That error means the runtime gave no answer in time. The event can still arrive, and a second call is a second event with a new id.
• A secret never leaves the run. If text or payload contains the value of a secret from the profile, the runtime swaps it for its '##ITEM_KEY.FIELD##' placeholder before the event is sent, so the receiver sees the placeholder, not the value. A name or a file path that contains a secret value is refused. File contents are sent as written.
• A test-run in Astro sends nothing. It checks the call, logs the event, and resolves to { id: null, dryRun: true }.
• Do not use it for the final result. A run that fails, is cancelled or times out never reaches your emit. EXECUTION_COMPLETED, EXECUTION_FAILED and EXECUTION_CANCELLED always fire. Use emit for progress and for content the lifecycle events do not carry.

​

Related