Share code between scripts

Scripts for one site often need the same logic: read a table row, build a search URL, wait for a list to load. Instead of a copy in each script, you keep that code in one file for the site. We call it the common code of the site. Each script imports it.

You do not write this by hand. Your agent writes it with the read_host_common and set_host_common tools, when it sees that two scripts for the same site need the same helper.

Import it

A script that imports common code uses import and exports a default function. The function receives builtins, page, args and files, as one object.

import { parseRow, waitForTable } from "./news.ycombinator.com/common@3.js";

export default async ({ builtins, page, args }) => {
	await builtins.goto("https://news.ycombinator.com/newest");
	await waitForTable(page);
	return { rows: (await page.locator("tr.athing").all()).map(parseRow) };
};

The folder in the path is the site. A script for news.ycombinator.com can import only the common code of news.ycombinator.com, and only from its own owner. An import for another site fails.

Common code does not see page or builtins. A function that needs them takes them as arguments, as waitForTable(page) does above.

Versions

Each time the agent saves common code, it adds the next version. An earlier version never changes and is never deleted. Saving the text of the latest version again adds nothing.

Import	What it loads
./<site>/common@3.js	Version 3. It never changes.
./<site>/common.js	The latest version, at the moment of the run.

Use common.js while you test a draft, so a new edit shows at once. A script that is promoted must use common@<n>.js, so that it runs the same code tomorrow as today. Promote a script that imports common.js and Reduck refuses it with a 409 that names the import to pin:

This version imports ./news.ycombinator.com/common.js, which is the latest common code and
changes when a version is added. Pin it before promoting: import
./news.ycombinator.com/common@<n>.js — set_host_common returns the number, read_host_common
shows the latest.

A script that is already promoted is never refused for this, so you can still roll back to an older version.

A new version of the common code does not change a script that pins an older one. To use it, the agent saves a new version of the script that imports common@4.js, tests it, and promotes it.

Who can read it

Common code follows the scripts that import it. Anyone who can read the owner’s scripts for that site can read its common code: everyone when the owner has a public script for the site, and the owner’s project members otherwise. The source of an official script is for the members of its project only, and so is its common code. Only the owner, or a project member who may edit its scripts, can add a version.

Ask your agent

Using Reduck MCP, read the common code for news.ycombinator.com. If there is a helper
for reading a story row, use it in a new script that lists the newest stories.

The two tools:

• read_host_common: host, handle (optional), and version (optional, the latest if you leave it out).
• set_host_common: host, handle (optional), and content, the full JavaScript text. It returns the version number it saved.

handle is the owner, as for other tools: @user for a user, a project handle without @ for a project.

From your code

The same two actions are in the REST API as getHostCommon (GET /api/scripts/{handle}/{host}/common, with ?version= for one version) and setHostCommon (PUT, with content in the body).