Open app

Get started

Share code between scripts

Scripts for one site often need the same logic: open the site and wait until it is ready, find a signed-out page, read a table row. Instead of a copy in each script, you keep that code in one file for the site. This file is the shared code of the site. Each script imports it.

You do not write it by hand. Your agent writes it with the read_library and create_library_version tools, when it sees that a second script for a site needs the same code.

  • The shared code holds what is true for the whole site: how to open it and know that it is ready, how to identify a block page or a signed-out page, how to read the shapes that come back on many pages.
  • The script holds what is specific to it: its inputs, its URL, its output.

Import it

A script that imports shared code uses import, as every script is a module with a default function. The function receives builtins, page, args and files, as one object.

// The library of news.ycombinator.com
import type { Page } from "playwright";

export async function openNewest(page: Page): Promise<void> {
  await page.goto("https://news.ycombinator.com/newest");
  await page.locator("tr.athing").first().waitFor();
}

// The script news.ycombinator.com/list_newest
import type { Scope } from "reduck:sandbox";
import type { Args, Output } from "reduck:contract";
import { openNewest } from "lib:news.ycombinator.com";

export default async ({ page }: Scope<Args>): Promise<Output> => {
  await openNewest(page);
  return { titles: await page.locator(".titleline > a").allTextContents() };
};
  • The import is lib:<site>. It loads the latest version of the shared code. An import that names a version, such as lib:news.ycombinator.com@3, fails.
  • A script imports the shared code of its own owner only, for any site: a script for amazon.fr can import lib:amazon.com.
  • Shared code does not see page or builtins. A function that needs them takes them as arguments, as openNewest(page) does above.
  • Shared code is TypeScript. It imports only types, from playwright and reduck:sandbox.
  • A function given to page.evaluate runs in the page, so it uses nothing outside its own body. Mark an exported one with /** @page */.

If the owner has no shared code for the site, the run fails with lib:<site>: the owner has no shared code for <site>.

The type check

A version of shared code passes the type check before it is created or promoted: the rules of a TypeScript script in core concepts, without the default export. The answer gives each error with its line and column. A version with errors is not created, and is not promoted.

A TypeScript script is checked with the latest version of the shared code it imports, and the errors of that shared code refuse the script too. So shared code with no types blocks the TypeScript scripts that import it until it has types.

A version of shared code is also checked against the current scripts of the owner that import it. A version that does not export a name one of these scripts imports, or that a TypeScript script does not pass the type check with, is not created and is not promoted. The answer gives the error at its line in that script. To remove or change an export, first change and promote the scripts that use it.

The answer also gives warnings: the code of the version that no current script uses, directly or through other code in it. A warning does not stop the version. When a script version stops using an export of shared code that no other current script uses, its promotion names that export in a warning too.

Versions

Each time the agent changes shared code, it creates the next version. A version never changes after it is created. Reduck adds no version when the text is the same as the newest version.

One version is the latest. Every script that imports the shared code runs the latest version, from its next run.

Tool What it does
create_library_version Creates the next version. The scripts continue to run the latest version until you promote the new one. The first version of shared code is the latest at once.
promote_library_version Makes a version the latest, for every script that imports the shared code. To roll back, promote the earlier version.
read_library Shows the latest version, each version with its note, the scripts that import the shared code, and the difference between two versions.

Test a version before you promote it

run_script and exec_code take libraries: the version of shared code to load for that one call, in place of the latest.

run_script({
  scripts: [/* each script that imports the shared code */],
  libraries: { "news.ycombinator.com": 4 },
});
exec_code({ sessionId, libraries: { "news.ycombinator.com": 4 }, code }); // code is a module

A run with libraries does not count in the success rate of the script: it tests the shared code, not the script. Each run records the version of the shared code that it loaded.

Who can read and change it

Shared code follows the scripts of its owner for that site. If the owner has a public script for the site, everyone can read its shared code. If not, only the owner can read it: the user, or the members of the project.

The source of an official script is for the members of its project only, and so is its shared code. Other users can run the official scripts, but only with the latest version of their shared code.

Only the owner, or a project member who may edit its scripts, can create or promote a version.

Ask your agent

Using Reduck MCP, read the shared code for news.ycombinator.com. If it has a function that opens the newest stories, use it in a new script that lists their titles.

The three tools:

  • read_library: host, handle (optional), version (optional, the latest if you leave it out) and diff (optional, another version to compare with).
  • create_library_version: host, handle (optional), and the code in one of two forms: content, the full TypeScript text, or edits, changes to the version from (optional, the latest if you leave it out). Also note (optional), what the version changes, in one line. It returns the version number, and the difference from the version it starts from.
  • promote_library_version: host, handle (optional) and version.

handle is the owner, as for other tools: @user for a user, a project handle without @ for a project. Leave it out for your own scripts.

Type to search the documentation.