Skip to content
The AI Agent Factory

14.1 Modules and packages

Approved by
Panaversity ·
15 min read

In everyday life. A recipe book does not write out its tomato sauce in every recipe. The sauce is on page 12, and the pizza recipe says "use the tomato sauce from page 12". If page 12 has too much salt, so does every dish that uses it. And a sauce from someone else's book goes into your dishes too, though you never made it.

What you will learn. How one file uses code from another, and what that tells you: which files to read first, and which code is not yours.

Why it matters. The files that every other file uses are where one change reaches everything. And code someone else wrote can do anything your account can do.

How does one file use code from another?

In 13.11, a test took dueDate from the due-date file. Here are both files, from the practice folder: one offers a name, and the other takes it.

The money file is the page with the sauce. It has one function, usd, which turns cents into dollars. You do not need to follow the lines inside it.

// money.ts
// export: other files may use usd
export function usd(cents: number): string {
  const dollars = Math.trunc(cents / 100);
  const rest = String(cents % 100).padStart(2, "0");
  return `$${dollars.toLocaleString("en-US")}.${rest}`;
}

The try file is the pizza recipe. Its first lines say which names it uses, and from which file. Predict what it prints.

// try.ts
// from the money file, use usd
import { usd } from "./money.ts";
// from the due-date file,
// use dueDate
import { dueDate } from "./due-date.ts";

console.log(usd(1922953), dueDate("2026-10-07", "Net 30"));

Both print:

$19,229.53 2026-11-06

Each file is a module: one file, one job. A name a module offers to other files is an export, like the sauce on page 12. A line that takes a name from another file is an import, like "use the tomato sauce from page 12". The two languages differ on what a file offers.

LanguageWhich names another file may import
TypeScriptOnly a name marked export. Every other name stays inside its file.
PythonAny name at the top of a file, outside every function and class.

Is this code mine, or someone else's?

Code someone else wrote comes as a package: modules that someone published, which an install command copies into your project. The import line tells you which kind you are looking at.

LanguageA file in this projectA package
TypeScriptA path that starts with ./, which means "in this folder", or ../, the folder above: "./money.ts"A name with no path, such as "zod". A name that starts with node: comes with Node itself.
PythonThe file's name without .py, such as moneyA name that no file in the project has, such as pydantic. Some, such as datetime, come with Python itself.

Which files do I read first?

An agent can split one long script into many files. To find your way, draw each file as a box, with an arrow to each file it imports. That picture is an import graph. Mark two kinds of file on it, and read them in this order.

  1. Edges first: the files where data comes in from outside, such as a file that reads a CSV export. To find them, ask the agent: "Which files read data from outside this project?"
  2. Foundations next: the files that many others import, like the sauce on page 12. A change there reaches everywhere, so test them hardest.

A file that nothing imports is either an entry point, the file a command starts, or dead code, which nothing uses.

At work. Figure 14.1 is Ana's map of brightline-ap, as it is at the end of this chapter. She does not start with the longest file. She marks the edges first: load-invoices reads the CSV export and checks each row, and ap-client asks a service on the web for vendors and open invoices. Seven files import csv, and six import due-date. Those are the foundations, so she reads them next.

Figure 14.1. A reading map of brightline-ap in four layers: shared helpers and libraries (due-date, csv, money and zod), records and validation (schemas, vendor and invoice), workflow helpers (load-invoices and invoice-book), and commands (list-vendors, ap-client, export-json, reconcile, due-by-friday and scripts/ap-api). Mark the edges first: load-invoices and ap-client are outlined in red. Then read the shared helpers and the code that uses them. due-date is imported by six files and csv by seven. Two import paths are traced: export-json to load-invoices to schemas, and due-by-friday to invoice-book to invoice.

Figure 14.1. Ana's reading map. Arrows point from a file to what it imports. Red outlines mark the two edges. After the edges, read the shared files at the bottom.

Should I let the agent add a package?

Only after three questions. A package is someone else's code, and it can do anything your account can do on this computer.

  1. Is the name spelled exactly right?
  2. Is it the real, well-known package, and not a made-up or look-alike name?
  3. Is it needed at all?

To find out, ask the agent to show you each package's page on npmjs.com or pypi.org, and to say what this project uses it for. A real, well-known package has years of history and many downloads. Attackers publish packages one letter away from popular names, and agents sometimes suggest a package for a job three lines of code would do.

Each package the project needs is a dependency, one entry in a file at the top of the project. Here are the practice folder's. The name is the package, and the rest says which versions the project accepts. These are the names you check, letter by letter.

"dependencies": {
  "zod": "^4.1.12"
}

An install also writes a lock file: the exact version of every dependency, and of the packages they use. It goes into every commit with the code, so a clean copy of the project next month installs exactly what you tested today.

LanguageThe dependenciesThe lock fileInstalls from the lock file
TypeScriptpackage.jsonpackage-lock.jsonnpm ci
Pythonpyproject.tomluv.lockuv sync

How do I set up to try this?

Once, for the whole chapter.

  1. Download brightline-practice-ch14.zip, and unzip it.
  2. Open the brightline-practice-ch14 folder in your agent, in the mode that asks before it acts, as in Chapter 13.
  3. Its AGENTS.md says TypeScript. If you chose Python, send: "Set my language in AGENTS.md to Python."
  4. Open package.json and pyproject.toml in a text editor, and write down the packages they name. Answer the three questions for each. Then send: "Install this folder's packages from its lock files, with npm ci and uv sync. Before each command, tell me which packages it will install." Compare the names with your list before you approve.

Try it

Run. Send: "Run the file in 14-1 and show me what it prints. Don't explain it yet."

Modify. Send: "Also import TERMS_DAYS from the due-date module in the file, and print it on a new last line. Don't run it yet." Open the due-date file in 14-1 in a text editor, find TERMS_DAYS, and use the export rule above to write down what will happen. Then ask the agent to run it.

Investigate. Ask about anything you got wrong.

Make. Send: "Make a module in 14-1 called fees, with one function that adds a $25.00 fee to an amount in cents, and a new file called mine that imports it and prints one answer. Don't run it yet." Find the import line, say what it will print, and then ask the agent to run it.

What you should see. TypeScript stops with a SyntaxError, Node's error for importing a name that is not exported. It prints nothing else, because Node loads every import before it runs any line. Python prints the usual line, then the terms and their days.

The operating rule: read the import graph before the functions. Mark where data comes in, read the foundations next, and approve a package only after you check its exact name and need.

Next. 14.2 writes down which values those files may pass to each other.

Check yourself

Question 1 / 6

0 answered

An agent split a report into two files, and Node stops on the import with Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../cents'.// cents.ts export function cents(dollars: number): number { return Math.round(dollars * 100) } // report.ts import { cents } from "./cents" console.log(cents(912.5))What is the cause?

Owner
Panaversity