Skip to main content

OpenEve Architecture And Auditability

This page maps the main framework modules so release reviewers can audit security-sensitive behavior without starting from a monolith.

Runtime Modules​

  • packages/runtime/src/index.ts: runtime orchestration, run lifecycle, channel dispatch, delivery coordination, resource projection, tool execution, and public runtime exports.
  • packages/runtime/src/state.ts: state contracts — RunStore, the optional facet stores, and the StateAdapter/StateStores types and guards.
  • packages/runtime/src/state-stores.ts: per-facet in-memory stores and StateStores composition/normalization with degraded-facet reporting.
  • packages/runtime/src/storage.ts: in-memory/file state adapters, local blob adapter, memory ranking, sandbox-sync record helpers, delivery retry timing, and shared storage utility functions.
  • packages/runtime/src/channel.ts: the ChannelModule contract, including ingressAuth and resolveAttachment.
  • packages/runtime/src/security.ts: core tool policy, ingress-security requirements/warnings, attachment trust checks, and constantTimeSecretEqual.
  • packages/runtime/src/delivery-queue.ts: durable delivery queue leasing, deferral, and settlement.
  • packages/runtime/src/run-recovery.ts: orphaned-run recovery sweep and background-worker startup.
  • packages/runtime/src/concurrency.ts: bounded run semaphore and RunCapacityError.
  • packages/runtime/src/http.ts: shared outbound HTTP client with timeouts, retries, Retry-After handling, and size caps.
  • packages/runtime/src/logging.ts: structured JSON runtime logger.
  • packages/runtime/src/local-sandbox.ts: local sandbox process, file, spawn, snapshot, and cleanup implementation.
  • packages/runtime/src/scheduler.ts: local, gateway, and Postgres scheduler adapter selection.
  • packages/runtime/src/telemetry.ts: telemetry sink contracts and OpenTelemetry exporter bridge.
  • packages/runtime/src/connections.ts: connection grant/session stores, principal keys, authorization continuation records, and runtime registry.
  • packages/runtime/src/self-improvement.ts: durable skills, dynamic schedules, dynamic connections, and their config resolution.
  • packages/runtime/src/attachments.ts: attachment materialization, file manifests, content-type handling, and safe zip extraction.
  • packages/runtime/src/source-loader.ts: artifact source-module loading.
  • packages/runtime/src/builtin-tools.ts: built-in runtime tool declarations.
  • packages/pi/src/pi-harness.ts: the default Pi model loop behind the engine-neutral AgentHarness contract.
  • packages/node/src/lifecycle.ts: graceful shutdown and signal handling.
  • packages/node/src/rate-limit.ts: token-bucket ingress rate limiting.
  • packages/node/src/provider-resolver.ts: generic openeveProvider package resolution for all adapter roles.

Compiler Modules​

  • packages/compiler/src/index.ts: file discovery, validation, manifest assembly, preflight, artifact generation, dependency planning, and deployment planning.
  • packages/compiler/src/config-ast.ts: static TypeScript config extraction for manifest-facing definitions. This module owns supported define*({ ... }), top-level constant, shorthand, as const, satisfies, and imported-helper alias semantics.

Adapter Boundary​

Provider packages own provider-specific helpers, live adapter behavior, and their own openeveProvider registration metadata. The CLI delegates deploy publishing to adapter-owned publishers for Railway, Docker, and Fly, and resolves other deploy targets through the same provider registry. The Node host resolves built-in kinds from first-party defaults and any other kind through the adapter definition's packageName, failing boot with a specific error when a provider package is missing or misshapen.

Security-Sensitive Flows​

  • Control-plane HTTP auth lives in packages/node/src/index.ts.
  • Connection credential-store secret resolution lives in packages/node/src/index.ts and deployment preflight in packages/compiler/src/index.ts.
  • Provider webhook authenticity remains channel-adapter-owned.
  • Delivery retry, file limits, sandbox-sync obligations, and memory search now live in packages/runtime/src/storage.ts or the focused runtime methods that call those helpers.

Size Gate​

Release-facing implementation files should normally stay under 1,500 lines. Files over that limit require a documented exception in this section and a ratchet issue before public release.

Current exceptions:

  • packages/runtime/src/index.ts: temporarily allowed up to 8,750 lines while recovery, delivery, resource projection, and model-tool execution continue to be extracted.
  • packages/compiler/src/index.ts: temporarily allowed up to 2,100 lines while file discovery, validation, preflight, artifact generation, and deployment planning are split from manifest assembly.