CONTRIBUTING.md
Rama main · réplica de lectura del repositorio original.
# Contributing to OpenAgentCore
This guide owns how to work in the repository: documentation ownership, the repository boundary, workflow and review, required checks and naming.
## Documentation ownership
Every subject has one owner. Most owners are the page whose title names the subject in the [documentation sidebar](docs.json), 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](AGENTS.md) |
| Protocol code and documents at each component boundary | [Protocol map](AGENTS.md#protocols-at-every-boundary) |
| Generated files (OpenAPI documents, Harness catalog reference, architecture diagram) | The source and generator named in [Contract and schema rules](#contract-and-schema-rules) and [Branding](#branding); never edit the output by hand |
| Core service setup, tests and generation | [Core service guide](services/core/README.md) |
| Core implementation constraints beyond the public contracts | [Implementation constraints](services/core/IMPLEMENTATION.md) |
| Built-in Harness identifiers and display names | `internal/harnessconfig/<package>/declaration.go` and its [generated reference](contracts/agents-api/harness-catalog.md) |
| Codex, Claude and MiniMax Runtime adapters and images | [Codex](services/core/deploy/codex/README.md), [Claude](services/core/deploy/claude/README.md), [MiniMax](services/core/deploy/mcode/README.md) |
| Claude private SDK bridge | [Claude SDK adapter](packages/claude-sdk-adapter/README.md) |
| E2B template construction | [E2B template builder](services/core/deploy/e2b/README.md) |
| OpenSandbox Runtime image and adapter | [OpenSandbox adapter guide](services/core/deploy/opensandbox/README.md) |
| E2B and microsandbox Provider helper implementation | [E2B helper](services/core/tools/e2b-provider/README.md), [microsandbox helper](services/core/tools/microsandbox-provider/README.md) |
| Distribution builds, Runtime image builds, CI and publication | [Build and release OpenAgentCore](docs/maintainers.md) |
| Website: landing page, bilingual documentation maintenance, documentation site build and GitHub Pages publication | [Website guide](website/README.md) |
| Installer lifecycle, locking, generated state and downloads | [Deployment](deploy/README.md) and [Node installer](deploy/node/README.md) |
| Web page behavior and visual rules | [Web product](apps/web/PRODUCT.md), [Web design](apps/web/DESIGN.md) |
| Application example behavior and local operation | [Parsar](example/parsar/README.md), [RL evaluation](example/rl-eval/README.md) |
## 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.
Core builds, deploys and runs independently of product services, frontends and databases; applications follow the [public API boundary](AGENTS.md#public-api).
### Optional application example
`example/parsar/` is an optional conversation workspace in this repository. Its [README](example/parsar/README.md) 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. The example uses only Core-managed hosted environments; its environment templates prepare packages, initialization commands, variables and initial files through the public Session contract.
- 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.
- Product resources use `/app/` and never become Core API or database conventions.
- It is excluded from Core distributions and cannot become a service dependency.
`example/rl-eval/` is an optional script that runs batch rollouts for RL and evaluation. Its [README](example/rl-eval/README.md) owns its behavior. It calls only public `/v1` APIs, holds only a Project key, uses only Core-managed hosted environments and writes results only to a local JSONL file.
## Workflow and review
### Before you start
Follow the [worktree rule](AGENTS.md#working-in-this-repository). 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
- 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](contracts/agents-api/environments.md#explicit-local-tool-environment).
- 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](docs/api/index.md) 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](docs/development.md#set-up-a-checkout). CI coverage, caches and release publication are owned by the [maintainer guide](docs/maintainers.md#publish-a-version).
### 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](docs/maintainers.md#continuous-integration) 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](#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
- [Declare the Harness](contracts/agents-api/harness-onboarding.md#declare-the-harness) owns what `make generate-harness-catalog` generates from each declaration and what `make check-harness-catalog` checks. The same generator also projects the model-provider protocol names of `internal/modelprovider/config.go` to the client.
- `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](contracts/agents-api/index.md#known-gaps) 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](docs/runtime-protocol.md#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](contracts/agents-api/index.md), 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.
For wire details the pinned SDK does not specify, probe resources you own and retain the request evidence. In the [OpenAI compatibility](contracts/agents-api/index.md), 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](contracts/agents-api/harness-onboarding.md#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 | 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 banner is `docs/assets/openagentcore-banner.webp`, 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/` example keeps its own name, logo and favicon.