Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Running adapters

An adapter is a program that knows one source. It lists the source’s events, keys each one, fetches the raw material, and marks a capture that is its own excerpt. It writes no records, keeps no list of what it reported, cuts no excerpt, and reads no capture into signals (115). millpond does the rest, whichever adapter printed the lines.

Plugins and adapter parts

A plugin is the installable unit in every host. It holds parts, each of one kind:

HostKinds of part
Claude Codeskills, hooks, commands, MCP servers
herdractions, panes, events
Flywheeladapter, chat sink, runner, router, sign-in, unit type, elaboration type, deliverable producer, map vocabulary, template, scenario pack

Flywheel’s statement names the same unit a package, and a named set of parts a bundle (228, 284). millpond runs a Flywheel plugin’s adapter parts and nothing else of it.

An adapter part declares a command, the shape of its configuration and the secrets it needs (228). millpond reads the same declaration Flywheel reads, so a part written for one host runs on the other unchanged.

How millpond starts a part

millpond runs the part’s command as:

<command> --raw-dir <dir> [--cursor <c>]

The part’s configuration is in the file the CAPTURE_CONFIG environment variable names, and each declared secret is in the environment under its declared name. The adapter writes its raw files under the raw directory, prints its lines on standard output, and exits.

An adapter that signs in to its source keeps that sign-in itself. On millpond the user signs in once per host. On Flywheel the host places the secrets the plugin declares.

Two ways in

Two commands take the same lines.

the new cursor and the run's status, kept by millpond run millpond run <part> a fresh raw directory and the last cursor Adapter process reads its source, nothing else headwater capture a part of eddy's, per service millpond capture folder each prints the same lines lines raw files millpond land 1 checks each line 2 looks up its key 3 banks the raw files 4 writes the capture 5 writes its one signal 6 or marks it unread 7 records the run A program on its own a deployer, a script, a person … | millpond land
millpond run starts one adapter part with a fresh raw directory and its last cursor, lands what it prints, and keeps the new cursor and the run's status. Anything else pipes the same lines into millpond land. No adapter knows where its captures are kept.
  • millpond land is the intake. It takes lines on standard input from whoever pipes them, such as a deployer, a script or a person, and knows nothing of who made them.
  • millpond run <part> is the scheduled form. It makes a fresh raw directory, starts the part’s command with that directory and its last cursor, and lands what the command prints. It then keeps the new cursor and the run’s status: its exit, its failures and the tail of its standard error. Only a run knows which adapter ran, so only a run keeps a cursor or a status per part.

The tick

millpond tick runs every part of an inbox whose schedule is due, so one timer on a host serves every part there. A schedule is five-field cron. A run missed while the host slept is caught up once, and the key makes the catch-up write nothing twice (111, 231).

Flywheel’s tick takes the same schedules (231), and its capture endpoint takes the same lines (216, 217g). An adapter never knows which host ran it.