Skip to main content

Contributing

This page is for developers changing OpenEve itself.

Repo Setup​

pnpm install
pnpm build
pnpm check
pnpm test

There is no separate lint step yet; 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.

OpenEve is a TypeScript workspace:

packages/
  openeve/     public CLI/meta package
  core/        public definitions and manifest types
  compiler/    validation, compilation, manifests, artifacts, and deploy plans
  cli/         command-line developer path
  runtime/     durable lifecycle, context, tools, approvals, replay, and delivery
  pi/          canonical Pi model loop
  node/        Node HTTP runtime host
  codex/       Codex subagent harness
  claude-code/ Claude Code subagent harness
  postgres/    production state adapter and migrations
  s3/          S3-compatible blob adapter and R2 helper
  r2/          R2 compatibility wrapper
  otlp/        OTLP/HTTP telemetry sink
  railway/     Railway deploy adapter helper and publisher
  docker/      Docker deploy and sandbox adapters
  daytona/     Daytona sandbox adapter
  e2b/         E2B sandbox adapter
  modal/       Modal sandbox adapter
  fly/         Fly deploy adapter helper and publisher
  slack/       Slack channel adapter
  photon/      Photon/Spectrum channel adapter
  discord/     Discord channel adapter
  telegram/    Telegram channel adapter
  github/      GitHub App connection and preview repo-event webhook channel
  teams/       Microsoft Teams channel and connection helpers
capabilities/
  livekit/     LiveKit voice dispatch, SIP tools, and voice subagent harness
examples/
  minimal-agent/
  custom-context-agent/
  self-improving-agent/
docs/

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 @openeve/core contracts.
  • Treat generated build output as disposable.

Generated Files​

Do not commit:

  • .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/**/.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.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 provider 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 Provider Adapter​

Provider adapters 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 @openeve/core, helper exports in the provider package, compiler/runtime wiring if needed, tests, and docs.

Versioning And Releases​

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

pnpm changeset

All publishable packages (openeve and @openeve/*) 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​

OpenEve releases as one public openeve CLI/meta package plus scoped @openeve/* packages. The workspace root remains private and should never be published.

Before a package release:

  • Run pnpm build.
  • Run pnpm test.
  • Run pnpm --filter openeve 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.