Skip to main content

Contributing

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. CodeQL (.github/workflows/codeql.yml) analyzes JavaScript/TypeScript on pushes, pull requests, and a weekly schedule. 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/, single-vendor capability packages under capabilities/, 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/ (or legacy .openeve/)
  • 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 (and legacy examples/**/.openeve) directories after local build or deploy experiments.

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 build
node --test tests/openeve-compile.test.mjs
node --test tests/openeve-runtime.test.mjs
node --test tests/adapters.test.mjs
node --test tests/self-improvement.test.mjs

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:

  1. OPENEVE_TEST_DATABASE_URL — an existing server. The suite creates and drops a throwaway openeve_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.
  2. 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.
  3. A running Docker daemon — starts a disposable postgres:16 container (override the image with OPENEVE_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​

  1. Decide the owner: core definition, compiler extraction, runtime behavior, provider adapter, or example-only code.
  2. Add the smallest public API that fits the existing define* and adapter patterns.
  3. Add validation and manifest output when the capability is declared from files.
  4. Add runtime behavior only where the capability is executed.
  5. Add plugin package helpers only when they keep app code smaller without hiding important contracts.
  6. Add tests at the package or acceptance level.
  7. 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 pre-1.0, so bumping any one of them bumps all of them; example packages are ignored. On pushes to main, the release workflow (.github/workflows/release.yml) opens or updates a "Version Packages" PR that applies pending changesets. Merging that PR publishes to npm.

Publishing requires the NPM_TOKEN repository secret, which is a maintainer action.

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 pnpm --filter @assemblyline-agents/sdk pack --dry-run for the public meta package.
  • Run pnpm release:pack to produce local package tarballs under .release-packs/.
  • Run pnpm release:dry-run before publishing.

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.