Assembly Line Documentation

This page is for developers changing Assembly Line itself. The root CONTRIBUTING.md is the canonical short entrypoint; it links here for the full guide.

Repo Setup

pnpm install
pnpm build
pnpm check
pnpm test

There is no separate lint step; pnpm check (build plus typecheck) is the quality gate. CI runs pnpm check and pnpm test:coverage on Node 22.19 and 24, plus the Postgres durability suite against a postgres:16 service container. A separate weekly Smoke workflow (.github/workflows/smoke.yml) covers sandbox, channel, and deploy smokes, with credentialed steps gated on repository secrets.

Assembly Line is a TypeScript workspace: framework and plugin packages live under packages/, example agents under examples/, and documentation under docs/. The canonical package-by-package layout is the Repository Layout in the root README.

Working Principles

Keep framework packages product-neutral.
Prefer one small module per responsibility over large orchestration files.
Keep channel providers at the boundary: verify, normalize, preserve delivery metadata, and send replies.
Keep state, blob, sandbox, scheduling, approvals, and recovery in runtime or adapter contracts.
Keep provider helpers as sugar over stable @assemblyline-agents/core contracts.
Treat generated build output as disposable.

Generated Files

Do not commit:

.assembly-line/
package dist/ output from local builds
node_modules/
package manager caches
local env files
duplicated compiled tests

If a generated artifact is needed for evidence, document the command and the relevant output instead of checking in the artifact.

Use pnpm clean:artifacts to remove ignored examples/**/.assembly-line directories after local build or deploy experiments.

Acceptance tests use small release-mode fixtures by default and reserve full local dependency vendoring for packaging assertions. Full test commands clean their workspace-scoped temp root after the suite finishes. Use pnpm clean:tmp to remove marker-owned test directories left behind by an interrupted or targeted run.

Test Strategy

Run the full suite before broad changes:

pnpm test

Use pnpm test:coverage to run the same suite with Node's built-in coverage reporting, matching what CI runs.

Use targeted tests during development:

pnpm test:file tests/assembly-line-compile.test.mjs
pnpm test:file tests/assembly-line-runtime.test.mjs
pnpm test:file tests/adapters.test.mjs
pnpm test:file tests/self-improvement.test.mjs

test:file rebuilds workspace packages before Node loads their generated dist/ files, preventing targeted tests from passing or failing against stale compiled output. The opt-in pnpm test:live:slack contract test requires SLACK_BOT_TOKEN and SLACK_LIVE_TEST_CHANNEL; it uploads and sends a temporary file through Slack's external upload API, then deletes it. It has real external side effects and is never part of the ordinary suite.

Postgres Durability Suite

tests/postgres-durability.test.mjs exercises the production PostgresStateAdapter (migrations, skip-locked delivery/sync leasing, lease-token settling, idempotency reservation, and event sequencing) against a real database with two adapter instances acting as two replicas. It runs with the rest of pnpm test when a database can be provisioned and skips cleanly otherwise; CI additionally runs it in a dedicated job with a postgres:16 service container.

Run it locally with:

pnpm build
node --test tests/postgres-durability.test.mjs

The suite finds a database in this order:

ASSEMBLY_LINE_TEST_DATABASE_URL, an existing server. The suite creates and drops a throwaway assembly_line_test_<hex> database per run; if the role cannot create databases it uses the given database directly and resets its public schema, so never point this at a database you care about.
Local initdb/pg_ctl binaries (PATH, Homebrew postgresql* kegs, or Postgres.app), boots a temp data dir on a random port and removes it afterwards.
A running Docker daemon, starts a disposable postgres:16 container (override the image with ASSEMBLY_LINE_TEST_POSTGRES_IMAGE).

Without any of these the file skips cleanly with an explanatory message.

Changes should include tests when they alter:

Manifest shape or validation rules.
Runtime lifecycle, recovery, approvals, delivery, or persistence.
Adapter metadata, env preflight, deploy planning, or provider helper behavior.
Tool execution, sandbox hydration, memory/resource behavior, or model loop integration.
Public package exports.

Documentation Rule

Developer documentation must change with material code changes.

When a change affects setup, CLI commands, agent authoring, runtime behavior, adapter behavior, provider env, deployment, public APIs, examples, or package boundaries, update the relevant docs in the same change:

If a material code change does not require docs, note why in the PR or commit message. Small internal refactors with no developer-visible behavior usually do not need docs updates.

Adding A New Agent Capability

Decide the owner: core definition, compiler extraction, runtime behavior, provider adapter, or example-only code.
Add the smallest public API that fits the existing define* and adapter patterns.
Add validation and manifest output when the capability is declared from files.
Add runtime behavior only where the capability is executed.
Add plugin package helpers only when they keep app code smaller without hiding important contracts.
Add tests at the package or acceptance level.
Update the docs that teach the new behavior.

Adding A Plugin Provider

Plugin provider contributions should document and test:

Required and optional environment variables.
Authentication or signature verification.
Normalized input shape.
Idempotency keys and retry behavior.
Delivery behavior.
Preflight requirements.
Local test strategy.

Add provider metadata in @assemblyline-agents/core, helper exports in the plugin package, compiler/runtime wiring if needed, tests, and docs. Keep provider and adapter names precise inside the implementation while describing the installable package as a plugin in user-facing material.

Versioning And Releases

Assembly Line uses Changesets for versioning. Every PR with a user-visible change must include a changeset:

pnpm changeset

All publishable packages (@assemblyline-agents/sdk and the other @assemblyline-agents/* packages) version in lockstep; example packages are ignored. Run pnpm version-packages; it applies Changesets and keeps each official plugin.json version synchronized with its package version. Review the generated versions and changelogs, refresh any committed example plugins.lock files that pin official packages, and commit the release state. Releases run locally on the maintainer Mac with the npm publish token stored in Login Keychain. The Keychain item is:

service: npm-publish-token
account: jasonbadeaux

pnpm release reads that item through macOS security, places the value in the NPM_TOKEN environment variable only for the build and publish child processes, and uses a temporary npm config that is deleted afterward. The token is never stored in the repository or printed by the release script. The command verifies the token with npm whoami before building or publishing. The npm token must have publish access to every public @assemblyline-agents/* package and npm's 2FA-bypass permission enabled.

Release Notes

Assembly Line releases as one public @assemblyline-agents/sdk CLI/meta package plus the other scoped @assemblyline-agents/* packages. The workspace root remains private and should never be published.

Before a package release:

Run pnpm build.
Run pnpm test.
Run npm pack --dry-run from packages/sdk/ for the public meta package.
Run pnpm release:pack to produce local package tarballs under .release-packs/.
Run pnpm release:dry-run before publishing.
Run pnpm version-packages, review and commit the release state.
Refresh and review committed example plugins.lock files after versioning.
Run pnpm release on the maintainer Mac, then push the release commit and generated package tags with git push --follow-tags.

For each release-facing change, keep changes easy to audit:

Summarize developer-facing behavior in the PR or commit.
Mention migrations or required env changes explicitly.
Point to updated docs.
Include verification commands.

Contributing