CONTRIBUTING.md

Contributing to OpenAgentCore

This guide owns how to work in the repository: documentation ownership, the repository boundary, workflow and review, required checks and naming. Every other subject has one canonical owner, listed below.

Documentation ownership

Every subject has one owner. Most owners are the page whose title names the subject in the documentation sidebar, such as Configuration reference, Operations or Architecture. This table lists the owners a title does not reveal.

Subject	Canonical source
Design principles, public API fidelity, settings and data ownership, documentation rules	AGENTS.md
Protocol code and documents at each component boundary	Protocol map
Generated files (OpenAPI documents, Harness catalog reference, architecture diagram)	The source and generator named in Contract and schema rules and Branding; never edit the output by hand
Core service setup, tests and generation	Core service guide
Core implementation constraints beyond the public contracts	Implementation constraints
Built-in Harness identifiers and display names	internal/harnessconfig/<package>/declaration.go and its generated reference
Codex, Claude and MiniMax Runtime adapters and images	Codex, Claude, MiniMax
Claude private SDK bridge	Claude SDK adapter
E2B template construction	E2B template builder
E2B and microsandbox Provider helper implementation	E2B helper, microsandbox helper
Distribution builds, Runtime image builds, CI and publication	Build and release OpenAgentCore
Website: landing page, bilingual documentation maintenance, documentation site build and GitHub Pages publication	Website guide
Installer lifecycle, locking, generated state, managed HTTPS and downloads	Deployment and Node installer
Web page behavior and visual rules	Web product, Web design
Application example behavior and local operation	Application example

Repository boundary

This repository contains the Core API and database, Runtime daemon, Harness and Sandbox Provider adapters, shared protocol packages, Web administrator console and their build and test tools. Product applications stay outside that service boundary. Keep the external Parsar product's server/, apps/parsar/, CLI, plugins and deployment stack in its own repository; do not automatically sync or delete its Core copy. Go imports resolve through this repository's module.

Product and execution service separation

Core builds, deploys and runs independently of product services, frontends and databases. Applications follow the public API boundary and, when they share a PostgreSQL server with Core, use separate databases, credentials and migrations.

• Parsar owns users, workspaces, business authorization, Agent/Team definitions, capabilities, product conversations, IM/sharing, approval decisions and billing. It uses Core for execution.
• A product conversation may reference several execution Sessions. Core owns native engine session identities; an execution Session has its own lifetime, separate from a daemon connection, process or sandbox.
• Build application orchestration on the public Session and event contract in the Agents API guide. Product cursor replay must be an explicit product extension. Business Team orchestration belongs to the application; Core's pinned multi_agent and Subagent resources remain part of the public contract.

Optional application example

example/parsar/ is an optional Agent workbench in this repository. Its README owns its product behavior.

• It calls only public /v1 APIs. Its Project key stays server-side; it never holds a Core key or issues machine credentials. Self-hosted connection displays the public Session installation command unchanged; Core owns bootstrap authorization and machine credential issuance.
• It may keep a small product-owned SQLite database (Node's built-in module, Node 22.13+), outside the checkout and isolated by Core origin and Project key fingerprint. Provider keys never reach the browser.
• Core owns Skills and all execution and history state. The example stores only Session references and pending creation requests with stable idempotency keys.
• Product resources use /app/ and never become Core API or database conventions.
• It is excluded from Core distributions and cannot become a service dependency.

Workflow and review

Before you start

Follow the worktree rule. Do not edit or commit implementation directly on main.

If requirements are unresolved, object ownership is unclear, or a design would need parallel compatibility paths, raise it with a concrete recommendation and tradeoffs before implementing, and continue independent work meanwhile. Record unrelated findings without starting them. Scope compatibility claims to the operations and placements verified.

Implementation conventions

• Apply the simplicity and performance principles when adding structure or optimizing execution.
• Keep one formatter, parser, validator and error mapper per job, and one error mapper per API surface.
• Share frontend formatting and labels in apps/web/src/lib/.
• Use internal/obs/log for logs. Keep credentials out of source and logs. Harness profiles must not copy Runtime tool environment values; see the environment contract.
• Require absolute user-supplied working directories.
• Keep test artifacts under ~/.oac/.
• New or changed routes identify their caller and credential in API namespaces and credentials and link their detailed contract.

Review

Every change gets an independent review of the complete diff against its requirements, acceptance criteria and boundaries. The reviewer receives no implementation summary or earlier findings. Fix substantiated in-scope findings, validate and review again; if the cycle repeats, reassess design and scope instead of adding changes, and report an unresolved blocker instead of broadening the task.

Required checks

Toolchain setup and focused commands are in Develop OpenAgentCore. CI coverage, caches and release publication are owned by the maintainer guide.

Checks for a change

Validate the current diff and the behavior it directly affects, with the smallest checks that establish correctness. Include cross-component tests only when those behaviors change. A review, documentation edit or CI configuration change does not need a full repository test run. After a follow-up edit, rerun only the checks that edit affects, and record what passed and any limits.

The CI selection policy names affected groups. A narrower check is enough when it covers the change. make check is the full gate for an explicitly requested full validation and for releases. Live acceptance applies when native execution behavior changes.

Test database

Variable	Value
OAC_TEST_DATABASE_URL	A dedicated test database. The full gate fails when it is missing.
OAC_TEST_OFFICIAL_SDK_PYTHON	The pinned official SDK interpreter

The role needs CREATE DATABASE: tests of database-wide state, such as the execution lease and the provider identity, create and drop isolated oac_*_tests databases. They copy them from a migrated template, the test database's name with _template before _tests, which stays beside it. Tests must not bypass the production provider-switch guard.

Contract and schema rules

• Each internal/harnessconfig/<package>/declaration.go is the single authored declaration of one Harness, read by Core admission and the Runtime. make generate-harness-catalog generates the Go registrations, client identifiers/names and the reference, and projects the model-provider protocol names of internal/modelprovider/config.go to the client; make openapi derives the matching enums. make check-harness-catalog verifies freshness in the full gate. Native restrictions stay in the declaration; Runtime availability stays separate and discovery only narrows the declaration.
• make openapi regenerates the public Go types, the Agent request shapes, the route inventory and all three OpenAPI documents; run it after changing the pinned public schema, Go bindings, Core extensions or handler annotations, and commit the generated diffs. make check-openapi checks freshness and the generator, and also runs through make check-go.
• scripts/generate-public-api.py reads the checked-in, checksum-verified official source without network access. It selects Agents, Vaults, Files and Skills and follows their schema references, preserving union types, nullability, required fields and constraints. The request shapes in services/core/internal/api/official_shapes.gen.go project CreateAgentParams, UpdateAgentParams and SessionAgentConfigParam; Core checks request bodies against them before it reads an Agent configuration. Core's extension types in contracts/agents-api/v1/ stay authored in Go and are added to the public schema during generation.
• The standard fields are generated into v1/official.gen.go. go-bindings.json lists the types Core consumes and overrides only the Go representation or field order that existing storage or custom JSON encoding requires; shared shapes use one Go type. Selected discriminated unions also generate JSON serializers that keep required nullable fields for each variant. Go input projections exclude packages.system to preserve its explicit rejection. Other union serializers, Core's local limits, execution admission and state transitions remain implementation code.
• packages/agents-client/src/generated/public-api.ts generates the TypeScript client's types, enum values and field names from the resulting public schema. The same generator projects the /core/v1 document into core-api.ts, which imports the public types it references from public-api.ts. The internal /core/v1 and /api/v1 documents come from handler annotations: a response field Core always sends carries binding:"required", a nullable field carries extensions:"x-nullable", and a Core-owned closed set uses a named Go type with typed constants in its producing package, from which Swag derives one shared enum definition. Single-value discriminators keep enums: tags; fields mirroring official or Runtime-owned sets keep tags that contract tests check against their owners. The annotations only shape the documents, and the client rejects a response that breaks them.
• Contract tests verify that the public schema preserves the official definitions, extensions stay in x_agents_core, and all documents match registered routes. Official-client and raw HTTP tests verify behavior. Schema generation does not qualify an unimplemented feature; the known gaps in OpenAI compatibility still apply. Upstream upgrades update the OpenAPI and SDK pins together after comparison and compatibility tests.
• make sqlc-generate owns only services/core/internal/db/sqlc (sqlc v1.29.0).
• make check-runtime-contract is the focused Core–Runtime contract entry point; see Contract verification. It also runs through check-go and check-core.

Compatibility evidence

Use official SDKs and upstream types or schemas. Validate raw HTTP payloads and observable workflows alongside SDK behavior. API changes preserve the pinned contracts, OpenAI compatibility, official-client tests and Core's independent build. Verify the official-client workflow before application integration. An OpenAI endpoint is a test target only when the required capabilities and credentials are available.

Controlled fixtures and synthetic model responses qualify deterministic behavior. Live acceptance calls a real model API through Core, the daemon and the Harness adapter. Direct native probes establish feasibility only. Keep provider credentials in private test configuration, outside source, logs and task records.

For wire details the pinned SDK does not specify, probe resources you own and retain the request evidence. In the OpenAI compatibility, keep observed behavior distinct from guarantees, accepted profiles distinct from complete coverage, and provider connectivity distinct from deployment qualification.

Live acceptance

Native adapter changes require their build/check targets and live provider acceptance. Follow Qualify the adapter in the Harness protocol for native model execution. State which checks ran, which used fixtures and which lacked prerequisites. Changes to native package pins require the same qualification; build the MiniMax companion from this revision's pinned patched sources.

OpenAgentCore Runtime names

Surface	Current name
Runtime binary	oac-daemon
Filesystem and initialization helpers	oac-*
Runtime settings	OAC_RUNTIME_*
Reserved Environment env prefix	OAC_
Provider ownership labels	io.oac.*
E2B metadata	oac_*

Provider bootstrap, Runtime images and Harness adapters must agree on these names.

Branding

Use OpenAgentCore for public project branding. The canonical mark is docs/assets/openagentcore-logo.svg; Web uses its outline with cropped transparent margins, theme-aware favicon colors and dark-surface inversion. The README wordmark is docs/assets/openagentcore-wordmark-light.svg with a dark variant, and docs/assets/og-image.png is the social preview. The architecture diagram that README and the website show, docs/assets/architecture.svg and architecture-dark.svg, is generated by scripts/generate-architecture-diagram.py; change the script and run it again. The example/parsar/ workbench keeps its own name, logo and favicon. Preserve external repository URLs and data identifiers when changing display copy.